public abstract class Queue extends Object implements 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 | Field and Description |
|---|---|
static Pattern |
DirectoryRegexp |
static Pattern |
ElementRegexp |
| Constructor and Description |
|---|
Queue() |
| Modifier and Type | Method and Description |
|---|---|
abstract String |
add(byte[] data)
Add data as byte array to the queue.
|
abstract String |
add(String data)
Add data as a string to the queue.
|
abstract 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.
|
abstract int |
count()
Return the number of elements in the queue, locked or not
(but not temporary).
|
abstract String |
get(String name)
Get locked element as a string.
|
abstract byte[] |
getAsByteArray(String name)
Get locked element as a byte array.
|
String |
getId() |
String |
getPath() |
abstract String |
getPath(String name)
Return the path given the name of the element.
|
abstract Iterator<String> |
iterator()
Return the queue iterator.
|
boolean |
lock(String name)
Lock an element in permissive mode.
|
abstract 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(int 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.
|
abstract void |
purge(int maxTemp,
int 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(Map<String,Integer> options)
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.
|
abstract void |
remove(String name)
Remove a locked element from the queue.
|
boolean |
unlock(String name)
Unlock an element in non-permissive mode.
|
abstract boolean |
unlock(String name,
boolean permissive)
Unlock an element.
|
public static final Pattern DirectoryRegexp
public static final Pattern ElementRegexp
public String getId()
public String getPath()
public abstract String add(String data) throws QueueException
data - data to be added to the queueQueueExceptionpublic abstract String add(byte[] data) throws QueueException
data - data to be added to the queueQueueExceptionpublic abstract String addPath(String path) throws QueueException
path - the path of the file to be addedQueueExceptionpublic abstract String get(String name) throws Exception
name - the name of the element to be returnedExceptionpublic abstract byte[] getAsByteArray(String name) throws Exception
name - the name of the element to be returnedExceptionpublic abstract String getPath(String name) throws Exception
name - the name of the elementExceptionpublic boolean lock(String name) throws Exception
name - name of the element to be lockedtrue on success, false if
the element could not be lockedExceptionpublic abstract boolean lock(String name, boolean permissive) throws Exception
name - name of the element to be lockedpermissive - work in permissive modetrue on success, false if
the element could not be lockedExceptionpublic boolean unlock(String name) throws Exception
name - name of the element to be lockedtrue on success, false if
the element could not be unlockedExceptionpublic abstract boolean unlock(String name, boolean permissive) throws Exception
name - name of the element to be lockedpermissive - work in permissive modetrue on success, false if
the element could not be unlockedExceptionpublic abstract void remove(String name) throws Exception
name - name of the element to be removedExceptionpublic abstract int count()
public void purge()
throws QueueException
It uses default value for maxTemp and maxLock
QueueExceptionpublic void purge(Map<String,Integer> options) throws QueueException
options - map containing purge options, only maxLock
and maxTemp values are used, the others are ignoredQueueExceptionpublic void purge(int maxLock)
throws QueueException
maxLock - maximum time for a locked element
(in seconds, default 600);
if set to 0, locked elements will not be unlockedQueueExceptionpublic abstract void purge(int maxTemp,
int maxLock)
throws QueueException
maxTemp - maximum time for a temporary element
(in seconds, default 300);
if set to 0, temporary elements will not be removedmaxLock - maximum time for a locked element
(in seconds, default 600);
if set to 0, locked elements will not be unlockedQueueExceptionCopyright © 2012. All Rights Reserved.