|
xmlBlaster 2.2.0 client API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface I_Queue
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
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 |
---|
static final boolean IGNORE_PUT_INTERCEPTOR
static final boolean USE_PUT_INTERCEPTOR
Method Detail |
---|
void initialize(StorageId storageId, java.lang.Object userData) throws XmlBlasterException
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:userData
- For example a Properties object or a String[] args object passing the configuration data
XmlBlasterException
void setProperties(java.lang.Object userData) throws XmlBlasterException
XmlBlasterException
java.lang.Object getProperties()
void setNotifiedAboutAddOrRemove(boolean notify)
true
- The I_QueueEntry.addedToQueue() and removedFromQueue() are invokedboolean isNotifiedAboutAddOrRemove()
void addPutListener(I_QueuePutListener l)
java.lang.IllegalArgumentException
- If a listener is registered alreadyvoid removePutListener(I_QueuePutListener l)
The
- given listener is currently ignoredlong[] getEntryReferences() throws XmlBlasterException
XmlBlasterException
java.util.List<I_Entry> getEntries(I_EntryFilter entryFilter) throws XmlBlasterException
entryFilter
- if not null the you can control which entries to return
with the callback entryFilter.intercept(I_Entry).
XmlBlasterException
void put(I_QueueEntry queueEntry, boolean ignorePutInterceptor) throws XmlBlasterException
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.
XmlBlasterException
- in case an error occurs. Possible causes of
error can be a communication exception of the underlying implementation (jdbc, file system etc).I_QueuePutListener.putPre(I_QueueEntry)
,
I_QueuePutListener.putPost(I_QueueEntry)
,
put(I_QueueEntry[], boolean)
void put(I_QueueEntry[] queueEntries, boolean ignorePutInterceptor) throws XmlBlasterException
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.
XmlBlasterException
- in case an error occurs. Possible causes of
error can be a communication exception of the underlying implementation (jdbc, file system etc).I_QueuePutListener.putPre(I_QueueEntry[])
,
I_QueuePutListener.putPost(I_QueueEntry[])
java.util.List<I_Entry> takeWithPriority(int numOfEntries, long numOfBytes, int minPriority, int maxPriority) throws XmlBlasterException
numOfEntries
- Take numOfEntries entries, if -1 take all entries currently foundnumOfBytes
- 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 highestmaxPriority
- The higher priority (inclusive), usually 0 lowest, 9 highest
XmlBlasterException
- in case the underlying implementation gets an exception while retrieving the element.java.util.List<I_Entry> takeLowest(int numOfEntries, long numOfBytes, I_QueueEntry limitEntry, boolean leaveOne) throws XmlBlasterException
numOfEntries
- inclusive, zero up to numOfEntries, if -1 up to the whole queuenumOfBytes
- 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)
XmlBlasterException
java.util.List<I_Entry> peekLowest(int numOfEntries, long numOfBytes, I_QueueEntry limitEntry, boolean leaveOne) throws XmlBlasterException
XmlBlasterException
I_QueueEntry peek() throws XmlBlasterException
XmlBlasterException
- if the underlying implementation gets an exception.java.util.List<I_Entry> peek(int numOfEntries, long numOfBytes) throws XmlBlasterException
numOfEntries
- Access num entries, if -1 access all entries currently foundnumOfBytes
- is the maximum size in bytes of the array to return, -1 is unlimited .
XmlBlasterException
- if the underlying implementation gets an exception.java.util.List<I_Entry> peekStartAt(int numOfEntries, long numOfBytes, I_QueueEntry firstEntryExlusive) throws XmlBlasterException
numOfEntries
- Access num entries, if -1 access all entries currently foundnumOfBytes
- is the maximum size in bytes of the array to return, -1 is unlimited .
XmlBlasterException
- if the underlying implementation gets an exception.java.util.List<I_Entry> peekSamePriority(int numOfEntries, long numOfBytes) throws XmlBlasterException
numOfEntries
- Access num entries, if -1 access all entries currently foundnumOfBytes
- 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.
XmlBlasterException
- if the underlying implementation gets an exception.java.util.List<I_Entry> peekWithPriority(int numOfEntries, long numOfBytes, int minPriority, int maxPriority) throws XmlBlasterException
numOfEntries
- Access num entries, if -1 take all entries currently foundnumOfBytes
- 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 allowedmaxPriority
- The higher priority (inclusive), usually 0 lowest, 9 highest, <0 is not allowed
XmlBlasterException
- in case the underlying implementation gets an exception while retrieving the element.java.util.List<I_Entry> peekWithLimitEntry(I_QueueEntry limitEntry) throws XmlBlasterException
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.
XmlBlasterException
long removeWithLimitEntry(I_QueueEntry limitEntry, boolean inclusive) throws XmlBlasterException
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.
XmlBlasterException
int remove() throws XmlBlasterException
XmlBlasterException
- if the underlying implementation gets an exception.long removeNum(long numOfEntries) throws XmlBlasterException
numOfEntries
- Erase num entries or less if less entries are available, -1 erases everythingnumOfBytes
- 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.
XmlBlasterException
- if the underlying implementation gets an exception.long removeWithPriority(long numOfEntries, long numOfBytes, int minPriority, int maxPriority) throws XmlBlasterException
numOfEntries
- Erase num entries or less if less entries are available, -1 erases everythingnumOfBytes
- 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 highestmaxPriority
- The higher priority (inclusive), usually 0 lowest, 9 highest
XmlBlasterException
- in case the underlying implementation gets an exception while retrieving the element.long getNumOfPersistentEntries()
long getNumOfPersistentBytes()
long getMaxNumOfBytes()
boolean[] removeRandom(I_Entry[] queueEntries) throws XmlBlasterException
queueEntries
- the entries to erase.
XmlBlasterException
int removeRandom(I_Entry entry) throws XmlBlasterException
entry
- The entry to erase.
XmlBlasterException
long clear()
void shutdown()
long removeHead(I_QueueEntry toEntry) throws XmlBlasterException
toEntry
- the entry until to remove.
XmlBlasterException
java.lang.String usage()
java.lang.String toXml(java.lang.String extraOffset)
extraOffset
- Indent the dump with given ASCII blanks
long embeddedQueueObjectsToXml(java.io.OutputStream out, java.util.Properties props) throws java.lang.Exception
out
- The output stream to dump the entriesprops
- Configuration properties, not yet specified, just pass null
java.lang.Exception
|
xmlBlaster 2.2.0 client API | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |