xmlBlaster 2.2.0 client API

org.xmlBlaster.util.queue
Interface I_Queue

All Superinterfaces:
I_Storage, I_StorageProblemNotifier
All Known Implementing Classes:
CacheQueueInterceptorPlugin, JdbcQueue, 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 embeddedQueueObjectsToXml(java.io.OutputStream out, java.util.Properties props)
          NOTE: rename from embeddedObjectsToXml to embeddedQueueObjectsToXml as it used the map lookup and lost priority info Dump all entries of this queue to the given output stream.
 java.util.List<I_Entry> 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.List<I_Entry> 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.List<I_Entry> peekLowest(int numOfEntries, long numOfBytes, I_QueueEntry limitEntry, boolean leaveOne)
          Same as takeLowest but it does not remove the entries.
 java.util.List<I_Entry> 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.List<I_Entry> peekStartAt(int numOfEntries, long numOfBytes, I_QueueEntry firstEntryExlusive)
          Returns maximum the first num element in the queue but does not remove it from that queue (leaves it untouched).
 java.util.List<I_Entry> peekWithLimitEntry(I_QueueEntry limitEntry)
          Deprecated. you should use directly removeWithLimitEntry
 java.util.List<I_Entry> 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 removeHead(I_QueueEntry toEntry)
          removes the head of the queue until (but not included) the entry specified as the argument.
 long removeNum(long numOfEntries)
          Removes max num messages.
 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.List<I_Entry> takeLowest(int numOfEntries, long numOfBytes, I_QueueEntry limitEntry, boolean leaveOne)
          Takes entries from the back of the queue.
 java.util.List<I_Entry> 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

static final boolean IGNORE_PUT_INTERCEPTOR
See Also:
Constant Field Values

USE_PUT_INTERCEPTOR

static final boolean USE_PUT_INTERCEPTOR
See Also:
Constant Field Values
Method Detail

initialize

void initialize(StorageId storageId,
                java.lang.Object userData)
                throws XmlBlasterException
Is called after the instance is created.

Parameters:
uniqueQueueId - A unique name, allowing to create a unique name for a persistent store (e.g. file name) "update:/node/heron/client/joe/2", "history:", "client:joe/2"
userData - For example a Properties object or a String[] args object passing the configuration data
Throws:
XmlBlasterException

setProperties

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

java.lang.Object getProperties()
Access the current queue configuration


setNotifiedAboutAddOrRemove

void setNotifiedAboutAddOrRemove(boolean notify)
Parameters:
true - The I_QueueEntry.addedToQueue() and removedFromQueue() are invoked
false The entries are not informed

isNotifiedAboutAddOrRemove

boolean isNotifiedAboutAddOrRemove()
Defaults to false.

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

addPutListener

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

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

Parameters:
The - given listener is currently ignored

getEntryReferences

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

java.util.List<I_Entry> 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

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:
msgQueueEntry - the queue entry to put into the queue.
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

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:
msgQueueEntries - the queue entry to put into the queue.
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[])

takeWithPriority

java.util.List<I_Entry> 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

java.util.List<I_Entry> 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)
entry -
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

java.util.List<I_Entry> 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

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

java.util.List<I_Entry> 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.

peekStartAt

java.util.List<I_Entry> peekStartAt(int numOfEntries,
                                    long numOfBytes,
                                    I_QueueEntry firstEntryExlusive)
                                    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

java.util.List<I_Entry> 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

java.util.List<I_Entry> 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

java.util.List<I_Entry> 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

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

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.

removeNum

long removeNum(long numOfEntries)
               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

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

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

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

long getMaxNumOfBytes()
Access the configured capacity (maximum bytes) for this queue

Returns:
The maximum capacity for the queue in bytes

removeRandom

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

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

long clear()
Remove all queue entries.

Returns:
The number of entries erased

shutdown

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


removeHead

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

java.lang.String usage()
Returns:
a human readable usage help string

toXml

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

embeddedQueueObjectsToXml

long embeddedQueueObjectsToXml(java.io.OutputStream out,
                               java.util.Properties props)
                               throws java.lang.Exception
NOTE: rename from embeddedObjectsToXml to embeddedQueueObjectsToXml as it used the map lookup and lost priority info 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

xmlBlaster 2.2.0 client API

Copyright © 1999-2014 The xmlBlaster.org contributers.