org.xmlBlaster.util.queue
Interface I_Queue

All Superinterfaces:

I_Storage, I_StorageProblemNotifier

All Known Implementing Classes:

CacheQueueInterceptorPlugin, JdbcQueueCommonTablePlugin, RamQueuePlugin

public interface I_Queue

extends I_Storage, I_StorageProblemNotifier

The Interface which all queues (persistent queues and cache queues) must implement. Note on shared store (or single point of persistence). In most cases the storage of the raw data for the queues is done centrally, for example in a database or on a file system or on the Ram. We call this space which is shared by all queues a 'shared store' or in case of persistent queues 'single point of persistence'. On this space each queue is represented by a 'persistent queue entity' (which in case of a DB could be a Table). In such a design it is theoretically possible to have two queues (two java objects on the same- or on different JVM) which point to the same persistent queue entity. It should be avoided to have that happen simultaneously since wether the persistent queue entity, nor the two objects have knowledge of each other. This could lead to unexpected and undesired results in case the queues store part of the information on cache.

As an example for sorting see org.xmlBlaster.util.queuemsg.MsgQueueEntry#compare(I_QueueEntry)

All methods are reentrant and thread safe

Author:

michele@laghi.eu, xmlBlaster@marcelruff.info

Field Summary

static boolean	IGNORE_PUT_INTERCEPTOR
static boolean	USE_PUT_INTERCEPTOR

Method Summary

void	addPutListener(I_QueuePutListener l) Register a listener which wants to be informed on put() events.
long	clear() Remove all queue entries.
long	embeddedObjectsToXml(java.io.OutputStream out, java.util.Properties props) Dump all entries of this queue to the given output stream.
java.util.ArrayList	getEntries(I_EntryFilter entryFilter) Gets a copy of the entries (e.g the messages) in the queue.
long[]	getEntryReferences() Gets the references of the entries in the queue.
long	getMaxNumOfBytes() Access the configured capacity (maximum bytes) for this queue
long	getNumOfPersistentBytes() Returns the amount of bytes used by the persistent entries in the queue If the implementation of this interface is not able to return the correct number of entries (for example if the implementation must make a remote call to a DB which is temporarly not available) it will return -1.
long	getNumOfPersistentEntries() Returns the number of elements having the persistent flag set in this queue.
java.lang.Object	getProperties() Access the current queue configuration
void	initialize(StorageId storageId, java.lang.Object userData) Is called after the instance is created.
boolean	isNotifiedAboutAddOrRemove() Defaults to false.
I_QueueEntry	peek() Returns the first element in the queue but does not remove it from that queue (leaves it untouched).
java.util.ArrayList	peek(int numOfEntries, long numOfBytes) Returns maximum the first num element in the queue but does not remove it from that queue (leaves it untouched).
java.util.ArrayList	peekLowest(int numOfEntries, long numOfBytes, I_QueueEntry limitEntry, boolean leaveOne) Same as takeLowest but it does not remove the entries.
java.util.ArrayList	peekSamePriority(int numOfEntries, long numOfBytes) Returns maximum the first num element in the queue of highest priority but does not remove it from that queue (leaves it untouched).
java.util.ArrayList	peekWithLimitEntry(I_QueueEntry limitEntry) Deprecated. you should use directly removeWithLimitEntry
java.util.ArrayList	peekWithPriority(int numOfEntries, long numOfBytes, int minPriority, int maxPriority) Returns maximum given number of entries from the queue (none blocking).
void	put(I_QueueEntry[] queueEntries, boolean ignorePutInterceptor) Puts one queue entry on top of the queue.
void	put(I_QueueEntry queueEntry, boolean ignorePutInterceptor) Puts one queue entry on top of the queue.
int	remove() Removes the first element in the queue.
long	remove(long numOfEntries, long numOfBytes) Removes max num messages.
long	removeHead(I_QueueEntry toEntry) removes the head of the queue until (but not included) the entry specified as the argument.
void	removePutListener(I_QueuePutListener l) Remove the listener which wanted to be informed on put() events.
int	removeRandom(I_Entry entry) Removes the given entry.
boolean[]	removeRandom(I_Entry[] queueEntries) Removes the given entries.
long	removeWithLimitEntry(I_QueueEntry limitEntry, boolean inclusive) It removes the entries which are higher than the entry specified in the argument list.
long	removeWithPriority(long numOfEntries, long numOfBytes, int minPriority, int maxPriority) Removes max numOfEntries messages (or less depending on the numOfBytes).
void	setNotifiedAboutAddOrRemove(boolean notify)
void	setProperties(java.lang.Object userData) Allows to overwrite properties which where passed on initialize() The properties which support hot configuration are depending on the used implementation
void	shutdown() Shutdown the implementation, sync with data store, free resources.
java.util.ArrayList	takeLowest(int numOfEntries, long numOfBytes, I_QueueEntry limitEntry, boolean leaveOne) Takes entries from the back of the queue.
java.util.ArrayList	takeWithPriority(int numOfEntries, long numOfBytes, int minPriority, int maxPriority) Takes given number of entries out of the queue.
java.lang.String	toXml(java.lang.String extraOffset) Dump state to XML string.
java.lang.String	usage()

Methods inherited from interface org.xmlBlaster.util.queue.I_Storage

addStorageSizeListener, getMaxNumOfEntries, getNumOfBytes, getNumOfEntries, getStorageId, getStorageSizeListeners, hasStorageSizeListener, isShutdown, isTransient, removeStorageSizeListener

Methods inherited from interface org.xmlBlaster.util.queue.I_StorageProblemNotifier

registerStorageProblemListener, unRegisterStorageProblemListener

Field Detail

IGNORE_PUT_INTERCEPTOR

public static final boolean IGNORE_PUT_INTERCEPTOR

See Also:

Constant Field Values

USE_PUT_INTERCEPTOR

public static final boolean USE_PUT_INTERCEPTOR

See Also:

Constant Field Values

Method Detail

initialize

public void initialize(StorageId storageId,
                       java.lang.Object userData)
                throws XmlBlasterException

Is called after the instance is created.

Parameters:

userData - For example a Properties object or a String[] args object passing the configuration data

Throws:

XmlBlasterException

setProperties

public void setProperties(java.lang.Object userData)
                   throws XmlBlasterException

Allows to overwrite properties which where passed on initialize() The properties which support hot configuration are depending on the used implementation

Throws:

XmlBlasterException

getProperties

public java.lang.Object getProperties()

Access the current queue configuration

setNotifiedAboutAddOrRemove

public void setNotifiedAboutAddOrRemove(boolean notify)

isNotifiedAboutAddOrRemove

public boolean isNotifiedAboutAddOrRemove()

Defaults to false.

Returns:

true The I_QueueEntry.addedToQueue() and removedFromQueue() are invoked
false The entries are not informed

addPutListener

public void addPutListener(I_QueuePutListener l)

Register a listener which wants to be informed on put() events.

Only one listener is currently supported.

Throws:

java.lang.IllegalArgumentException - If a listener is registered already

removePutListener

public void removePutListener(I_QueuePutListener l)

Remove the listener which wanted to be informed on put() events.

The currently registered listener is removed. If no listener is registered, this call is silently ignored

getEntryReferences

public long[] getEntryReferences()
                          throws XmlBlasterException

Gets the references of the entries in the queue. Note that the data which is referenced here may be changed by other threads. The entries are not removed.

Returns:

Array with reference numbers

Throws:

XmlBlasterException

getEntries

public java.util.ArrayList getEntries(I_EntryFilter entryFilter)
                               throws XmlBlasterException

Gets a copy of the entries (e.g the messages) in the queue. If the queue is modified, this copy will not be affected. This method is useful for client browsing, the entries are not removed

Parameters:

entryFilter - if not null the you can control which entries to return with the callback entryFilter.intercept(I_Entry).

Returns:

The found entries

Throws:

XmlBlasterException

put

public void put(I_QueueEntry queueEntry,
                boolean ignorePutInterceptor)
         throws XmlBlasterException

Puts one queue entry on top of the queue. See the other put() for a detailed description.

Parameters:

ignorePutInterceptor - if set to 'IGNORE_PUT_INTERCEPTOR=true' the put will not inform the QueuePutListener that a put occurred.

Throws:

XmlBlasterException - in case an error occurs. Possible causes of error can be a communication exception of the underlying implementation (jdbc, file system etc).

See Also:

I_QueuePutListener.putPre(I_QueueEntry), I_QueuePutListener.putPost(I_QueueEntry), put(I_QueueEntry[], boolean)

put

public void put(I_QueueEntry[] queueEntries,
                boolean ignorePutInterceptor)
         throws XmlBlasterException

Puts one queue entry on top of the queue. It does not wait. If the queue is ALREADY full at the time of the invocation, it will throw an exception. Full means here that the maximum number of entries OR the maximum size in bytes has been exceeded. This means that the queue can be overloaded once.

The implementation must assure that identical entries which are put twice are only once in the store. The behavior if the new entry overwrites the old entry is undefined.

Parameters:

ignorePutInterceptor - if set to 'IGNORE_PUT_INTERCEPTOR=true' the put will not inform the QueuePutListener that a put occurred.

Returns:

An ACK object for each queueEntry (ackObject.length == queueEntries.length) or null

Throws:

XmlBlasterException - in case an error occurs. Possible causes of error can be a communication exception of the underlying implementation (jdbc, file system etc).

See Also:

I_QueuePutListener.putPre(I_QueueEntry[]), I_QueuePutListener.putPost(I_QueueEntry[])

takeWithPriority

public java.util.ArrayList takeWithPriority(int numOfEntries,
                                            long numOfBytes,
                                            int minPriority,
                                            int maxPriority)
                                     throws XmlBlasterException

Takes given number of entries out of the queue. The ordering is first priority and secondly timestamp. This method blocks until at least one entry is found

Parameters:

numOfEntries - Take numOfEntries entries, if -1 take all entries currently found

numOfBytes - so many entries are returned as not to exceed the amount specified. If the first entry is bigger than this amount, it is returned anyway.

minPriority - The lower priority (inclusive), usually 0 lowest, 9 highest

maxPriority - The higher priority (inclusive), usually 0 lowest, 9 highest

Returns:

list with I_QueueEntry, the least elements with respect to the given ordering, or size()==0

Throws:

XmlBlasterException - in case the underlying implementation gets an exception while retrieving the element.

takeLowest

public java.util.ArrayList takeLowest(int numOfEntries,
                                      long numOfBytes,
                                      I_QueueEntry limitEntry,
                                      boolean leaveOne)
                               throws XmlBlasterException

Takes entries from the back of the queue. It takes so many entries as the LESS restrictive of the limits specified in the argument list. If you invoke this method as: takeLowest(10, 50000L, someEntry); It will take either 10 entries or as much entries which together do not exceed 50 kB (all entries together) whichever is higher. Note that numOfEntries is exclusive. If there is no entry of lower order (lower priority and higher uniqueId) than the one specified, an empty array list is returned. A further restriction is the following: if 'leaveOne' is 'true', then at least one entry must be left on the queue. A little example: suppose the size of every entry is 100 bytes and you invoke the following: takeLowest(3, 750, null, false); then it will give back 8 entries because: numEntries would give back 3 entries. 750 bytes / 100 bytes/entry gives 7.5 entries so it would round it up to 8. Since it gives back the less restrictive it will give back 8 entries.

Parameters:

numOfEntries - inclusive, zero up to numOfEntries, if -1 up to the whole queue

numOfBytes - inclusive, and minimum one is returned (but not if limitEntry suppress it)

leaveOne - Usually set to false. (true for cache queue to never flush transient queue totally)

Returns:

the list containing all 'I_QueueEntry' entries which fit into the constrains, never null.

Throws:

XmlBlasterException

peekLowest

public java.util.ArrayList peekLowest(int numOfEntries,
                                      long numOfBytes,
                                      I_QueueEntry limitEntry,
                                      boolean leaveOne)
                               throws XmlBlasterException

Same as takeLowest but it does not remove the entries.

Throws:

XmlBlasterException

peek

public I_QueueEntry peek()
                  throws XmlBlasterException

Returns the first element in the queue but does not remove it from that queue (leaves it untouched). This method does not block.

Returns:

I_QueueEntry the least element with respect to the given ordering or null if the queue is empty.

Throws:

XmlBlasterException - if the underlying implementation gets an exception.

peek

public java.util.ArrayList peek(int numOfEntries,
                                long numOfBytes)
                         throws XmlBlasterException

Returns maximum the first num element in the queue but does not remove it from that queue (leaves it untouched). This method does not block.

Parameters:

numOfEntries - Access num entries, if -1 access all entries currently found

numOfBytes - is the maximum size in bytes of the array to return, -1 is unlimited .

Returns:

list with I_QueueEntry, the least elements with respect to the given ordering, or size()==0

Throws:

XmlBlasterException - if the underlying implementation gets an exception.

peekSamePriority

public java.util.ArrayList peekSamePriority(int numOfEntries,
                                            long numOfBytes)
                                     throws XmlBlasterException

Returns maximum the first num element in the queue of highest priority but does not remove it from that queue (leaves it untouched). This method does not block.

Parameters:

numOfEntries - Access num entries, if -1 access all entries currently found

numOfBytes - so many entries are returned as not to exceed the amount specified. If the first entry is bigger than this amount, it is returned anyway. -1 is unlimited.

Returns:

list with I_QueueEntry, the least elements with respect to the given ordering, or size()==0

Throws:

XmlBlasterException - if the underlying implementation gets an exception.

peekWithPriority

public java.util.ArrayList peekWithPriority(int numOfEntries,
                                            long numOfBytes,
                                            int minPriority,
                                            int maxPriority)
                                     throws XmlBlasterException

Returns maximum given number of entries from the queue (none blocking).

Parameters:

numOfEntries - Access num entries, if -1 take all entries currently found

numOfBytes - so many entries are returned as not to exceed the amount specified. If the first entry is bigger than this amount, it is returned anyway.

minPriority - The lower priority (inclusive), usually 0 lowest, 9 highest, <0 is not allowed

maxPriority - The higher priority (inclusive), usually 0 lowest, 9 highest, <0 is not allowed

Returns:

list with I_QueueEntry, the least elements with respect to the given ordering, or size()==0

Throws:

XmlBlasterException - in case the underlying implementation gets an exception while retrieving the element.

peekWithLimitEntry

public java.util.ArrayList peekWithLimitEntry(I_QueueEntry limitEntry)
                                       throws XmlBlasterException

Deprecated. you should use directly removeWithLimitEntry

It returns the entries which are higher than the entry specified in the argument list.

Parameters:

limitEntry - the entry which limits the peek. Only entries of higher order, i.e. entries having a higher priority, or same priority and lower uniqueId are returned. If entryLimit is null or no entries are higher than entryLimit, an empty list is returned. Note: The limitEntry does not need to be in the queue.

Throws:

XmlBlasterException

removeWithLimitEntry

public long removeWithLimitEntry(I_QueueEntry limitEntry,
                                 boolean inclusive)
                          throws XmlBlasterException

It removes the entries which are higher than the entry specified in the argument list.

Parameters:

limitEntry - the entry which limits the remove. Only entries of higher order, i.e. entries having a higher priority, or same priority and lower uniqueId are deleted. If entryLimit is null or no entries are higher than entryLimit, an empty list is returned.

inclusive - if 'true', then also the entry specified will be removed (if it exists). If false the remove is exclusive, i.e. the specified entry is left in the queue. Note: The limitEntry does not need to be in the queue.

Throws:

XmlBlasterException

remove

public int remove()
           throws XmlBlasterException

Removes the first element in the queue. This method does not block.

Returns:

the size in bytes of the removed elements

Throws:

XmlBlasterException - if the underlying implementation gets an exception.

remove

public long remove(long numOfEntries,
                   long numOfBytes)
            throws XmlBlasterException

Removes max num messages. This method does not block.

Parameters:

numOfEntries - Erase num entries or less if less entries are available, -1 erases everything

numOfBytes - so many entries are returned as not to exceed the amount specified. If the first entry is bigger than this amount, it is removed anyway.

Returns:

Number of entries erased

Throws:

XmlBlasterException - if the underlying implementation gets an exception.

removeWithPriority

public long removeWithPriority(long numOfEntries,
                               long numOfBytes,
                               int minPriority,
                               int maxPriority)
                        throws XmlBlasterException

Removes max numOfEntries messages (or less depending on the numOfBytes). This method does not block.

Parameters:

numOfEntries - Erase num entries or less if less entries are available, -1 erases everything

numOfBytes - so many entries are returned as not to exceed the amout specified. If the first entry is bigger than this amount, it is returned anyway.

minPriority - The lower priority (inclusive), usually 0 lowest, 9 highest

maxPriority - The higher priority (inclusive), usually 0 lowest, 9 highest

Returns:

Number of entries erased

Throws:

XmlBlasterException - in case the underlying implementation gets an exception while retrieving the element.

getNumOfPersistentEntries

public long getNumOfPersistentEntries()

Returns the number of elements having the persistent flag set in this queue. If the implementation of this interface is not able to return the correct number of entries (for example if the implementation must make a remote call to a DB which is temporarly not available) it will return -1.

Returns:

int the number of elements currently in the queue

getNumOfPersistentBytes

public long getNumOfPersistentBytes()

Returns the amount of bytes used by the persistent entries in the queue If the implementation of this interface is not able to return the correct number of entries (for example if the implementation must make a remote call to a DB which is temporarly not available) it will return -1.

Returns:

The amount of bytes currently in the queue

getMaxNumOfBytes

public long getMaxNumOfBytes()

Access the configured capacity (maximum bytes) for this queue

Returns:

The maximum capacity for the queue in bytes

removeRandom

public boolean[] removeRandom(I_Entry[] queueEntries)
                       throws XmlBlasterException

Removes the given entries.

Parameters:

queueEntries - the entries to erase.

Returns:

a boolean array of the same size as the queueEntries array. If an entry is true it means it could be removed, if false it means it could not be removed (probably already removed)

Throws:

XmlBlasterException

removeRandom

public int removeRandom(I_Entry entry)
                 throws XmlBlasterException

Removes the given entry.

Parameters:

entry - The entry to erase.

Returns:

the number of elements erased.

Throws:

XmlBlasterException

clear

public long clear()

Remove all queue entries.

Returns:

The number of entries erased

shutdown

public void shutdown()

Shutdown the implementation, sync with data store, free resources. Persistent entries will NOT be deleted.

removeHead

public long removeHead(I_QueueEntry toEntry)
                throws XmlBlasterException

removes the head of the queue until (but not included) the entry specified as the argument.

Parameters:

toEntry - the entry until to remove.

Returns:

long the number of entries deleted.

Throws:

XmlBlasterException

usage

public java.lang.String usage()

Returns:

a human readable usage help string

toXml

public java.lang.String toXml(java.lang.String extraOffset)

Dump state to XML string.

Parameters:

extraOffset - Indent the dump with given ASCII blanks

Returns:

An xml encoded dump

embeddedObjectsToXml

public long embeddedObjectsToXml(java.io.OutputStream out,
                                 java.util.Properties props)
                          throws java.lang.Exception

Dump all entries of this queue to the given output stream. The messages are XML formatted.

Parameters:

out - The output stream to dump the entries

props - Configuration properties, not yet specified, just pass null

Returns:

Number of entries dumped

Throws:

java.lang.Exception