public interface Queue extends Iterable<String>
This module allows multiple concurrent readers and writers to interact with the same queue.
Different implementations are available so readers and writers can be written in different programming languages:
There is no knowledge of priority within a queue. If multiple priorities are needed, multiple queues should be used.
QueueSimple
queues, an element can only contain one
binary string.
A queue is a "best effort" FIFO (First In - First Out) collection of elements.
It is very hard to guarantee pure FIFO behavior with multiple writers using the same queue. Consider for instance:
For simplicity, this implementation provides only "best effort" FIFO, i.e. there is a very high probability that elements are processed in FIFO order but this is not guaranteed. This is achieved by using a high-resolution timer and having elements sorted by the time their final directory gets created.
In order to support multiple reader processes interacting with the same queue, advisory locking is used. Processes should first lock an element before working with it. In fact, the get() and remove() methods report a fatal error if they are called on unlocked elements.
If the process that created the lock dies without unlocking the element, we end up with a staled lock. The purge() method can be used to remove these staled locks.
An element can basically be in only one of two states: locked or unlocked.
A newly created element is unlocked as a writer usually does not need to do anything more with it.
Iterators return all the elements, regardless of their states.
There is no method to get an element state as this information is usually useless since it may change at any time. Instead, programs should directly try to lock elements to make sure they are indeed locked.
The elements are stored as plain files and directories. The filesystem security features (owner, group, permissions, ACLs...) should be used to adequately protect the data.
By default, the process' umask is respected. See the class constructor documentation if you want an other behavior. If multiple readers and writers with different uids are expected, the easiest solution is to have all the files and directories inside the toplevel directory world-writable (i.e. umask=0). Then, the permissions of the toplevel directory itself (e.g. group-writable) are enough to control who can access the queue.Modifier and Type | Method and Description |
---|---|
String |
add(byte[] data)
Add data as byte array to the queue.
|
String |
add(String data)
Add data as a string to the queue.
|
String |
addPath(String path)
Add the given file (identified by its path) to the queue and return the
corresponding element name, the file must be on the same filesystem and
will be moved to the queue.
|
int |
count()
Return the number of elements in the queue, locked or not (but not
temporary).
|
String |
get(String name)
Get locked element as a string.
|
byte[] |
getAsByteArray(String name)
Get locked element as a byte array.
|
String |
getId()
Return the queue id.
|
String |
getPath(String name)
Return the path given the name of the element.
|
boolean |
lock(String name)
Lock an element in permissive mode.
|
boolean |
lock(String name,
boolean permissive)
Lock an element.
|
void |
purge()
Purge the queue by removing unused intermediate directories, removing too
old temporary elements and unlocking too old locked elements (aka staled
locks); note: this can take a long time on queues with many elements.
|
void |
purge(Integer maxLock)
Purge the queue by removing unused intermediate directories, removing too
old temporary elements and unlocking too old locked elements (aka staled
locks); note: this can take a long time on queues with many elements.
|
void |
purge(Integer maxLock,
Integer maxTemp)
Purge the queue by removing unused intermediate directories, removing too
old temporary elements and unlocking too old locked elements (aka staled
locks); note: this can take a long time on queues with many elements.
|
void |
remove(String name)
Remove a locked element from the queue.
|
boolean |
unlock(String name)
Unlock an element in non-permissive mode.
|
boolean |
unlock(String name,
boolean permissive)
Unlock an element.
|
forEach, iterator, spliterator
String getId()
String add(String data) throws IOException
data
- data to be added to the queueIOException
- if any file operation failString add(byte[] data) throws IOException
data
- data to be added to the queueIOException
- if any file operation failString addPath(String path) throws IOException
path
- the path of the file to be addedIOException
- if any file operation failString get(String name)
name
- the name of the element to be returnedbyte[] getAsByteArray(String name)
name
- the name of the element to be returnedString getPath(String name)
name
- the name of the elementboolean lock(String name) throws IOException
name
- name of the element to be lockedtrue
on success, false
if the element
could not be lockedIOException
- if any file operation failboolean lock(String name, boolean permissive) throws IOException
name
- name of the element to be lockedpermissive
- work in permissive modetrue
on success, false
if the element
could not be lockedIOException
- if any file operation failboolean unlock(String name) throws IOException
name
- name of the element to be lockedtrue
on success, false
if the element
could not be unlockedIOException
- if any file operation failboolean unlock(String name, boolean permissive) throws IOException
name
- name of the element to be lockedpermissive
- work in permissive modetrue
on success, false
if the element
could not be unlockedIOException
- if any file operation failvoid remove(String name)
name
- name of the element to be removedint count()
void purge() throws IOException
IOException
- if any file operation failvoid purge(Integer maxLock) throws IOException
maxLock
- maximum time for a locked element (in seconds);
if set to 0, locked elements will not be unlocked;
if set to null, the object's default value will be usedIOException
- if any file operation failvoid purge(Integer maxLock, Integer maxTemp) throws IOException
maxLock
- maximum time for a locked element (in seconds);
if set to 0, locked elements will not be unlocked;
if set to null, the object's default value will be usedmaxTemp
- maximum time for a temporary element (in seconds);
if set to 0, temporary elements will not be removed
if set to null, the object's default value will be usedIOException
- if any file operation failCopyright © 2015. All rights reserved.