xmlBlaster 2.2.0 API

org.xmlBlaster.util.queue.jdbc
Class JdbcQueueCommonTablePlugin

java.lang.Object
  extended by org.xmlBlaster.util.queue.jdbc.JdbcQueueCommonTablePlugin
All Implemented Interfaces:
I_Map, I_Plugin, I_Queue, I_Storage, I_StoragePlugin, I_StorageProblemNotifier

public final class JdbcQueueCommonTablePlugin
extends java.lang.Object
implements I_Queue, I_StoragePlugin, I_Map

Persistence queue implementation on a DB based on JDBC.

Loaded via xmlBlaster.properties, there are three implementation.

org.xmlBlaster.util.queue.jdbc.JdbcQueueCommonTablePlugin
was the operational variant up to v1.6.2+ (2008-10) using one XB_ENTRIES table

org.xmlBlaster.util.queue.jdbc.JdbcQueue
is the new implementation since v1.6.3 using three tables XBSTORE, XBREF, XBMEAT

Example:
 JdbcStorage[postgres]=org.xmlBlaster.util.queue.jdbc.JdbcQueue,\
                      url=jdbc:postgresql://localhost:5432/test,\
                      user=postgres,\
                      password=,\
                      connectionPoolSize=1,\
                      connectionBusyTimeout=90000,\
                      maxWaitingThreads=300,\
                      tableNamePrefix=XB_,\
                      entriesTableName=ENTRIES,\
                      dbAdmin=true
 

Author:
michele@laghi.eu, xmlBlaster@marcelruff.info
See Also:
The queue.jdbc.commontable requirement, JdbcQueue

Field Summary
private  boolean debug
           
private  int entryCounter
           
private  Global glob
           
(package private)  boolean isDown
           
private static boolean isWarned
           
private static java.util.logging.Logger log
           
private  CommonTableDatabaseAccessor manager
           
private  java.lang.String ME
           
private  java.lang.Object modificationMonitor
          Monitor object used to synchronize the count of sizes
private  boolean notifiedAboutAddOrRemove
           
private  long numOfBytes
           
private  long numOfEntries
           
private  long numOfPersistentBytes
           
private  long numOfPersistentEntries
           
private  PluginInfo pluginInfo
           
private  QueuePropertyBase property
           
private  I_QueuePutListener putListener
           
private  StorageId storageId
           
private  StorageSizeListenerHelper storageSizeListenerHelper
           
 
Fields inherited from interface org.xmlBlaster.util.queue.I_Queue
IGNORE_PUT_INTERCEPTOR, USE_PUT_INTERCEPTOR
 
Constructor Summary
JdbcQueueCommonTablePlugin()
           
 
Method Summary
 void addPutListener(I_QueuePutListener l)
          Register a listener which wants to be informed on put() events.
 void addStorageSizeListener(I_StorageSizeListener listener)
          Adds a storage size listener to the storage.
 I_MapEntry change(I_MapEntry entry, I_ChangeCallback callback)
           
 I_MapEntry change(long uniqueId, I_ChangeCallback callback)
          This method is threadsafe because it makes a lookup for the updated entry within the synchronization point.
 long clear()
          Clears everything and removes the queue (i.e.
 void destroy()
          Cleans up the current queue (it deletes all the entries and frees the table used and cleans up all tables in the database).
 long embeddedObjectsToXml(java.io.OutputStream out, java.util.Properties props)
          Dump all entries of this map to the given output stream.
 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.
 I_MapEntry get(long uniqueId)
          Lookup entry without removing.
 I_MapEntry[] getAll(I_EntryFilter entryFilter)
          Retrieve all entries in the storage, please take care on memory consumption.
 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.
 PluginInfo getInfo()
          Enforced by I_StoragePlugin
protected  CommonTableDatabaseAccessor getJdbcQueueManagerCommonTable(PluginInfo pluginInfo)
          Returns a JdbcManagerCommonTable for a specific queue.
 CommonTableDatabaseAccessor getManager()
           
 long getMaxNumOfBytes()
          returns the capacity (maximum bytes) for this queue
 long getMaxNumOfEntries()
          Returns the maximum number of elements for this queue
private  long getNumOfBytes_()
          It returns the size of the queue.
 long getNumOfBytes()
          It returns the size of the queue.
private  long getNumOfEntries_()
          It returns the size of the queue.
 long getNumOfEntries()
          It returns the size of the queue.
private  long getNumOfPersistentBytes_(boolean verbose)
          It returns the number of persistent entries in the queue.
 long getNumOfPersistentBytes()
          It returns the number of persistent entries in the queue.
private  long getNumOfPersistentEntries_(boolean verbose)
          It returns the number of persistent entries in the queue.
 long getNumOfPersistentEntries()
          It returns the number of persistent entries in the queue.
 java.lang.Object getProperties()
          Access the current queue configuration
 StorageId getStorageId()
          Returns the unique ID of this queue
 I_StorageSizeListener[] getStorageSizeListeners()
           
 java.lang.String getType()
          Enforced by I_Plugin
 java.lang.String getVersion()
          Enforced by I_Plugin
 boolean hasStorageSizeListener(I_StorageSizeListener listener)
          Checks wether the specified listener is registered.
 void init(Global glob, PluginInfo pluginInfo)
          Enforced by I_Plugin
 void initialize(StorageId uniqueQueueId, java.lang.Object userData)
          Is called after the instance is created.
 boolean isNotifiedAboutAddOrRemove()
          Defaults to false.
 boolean isShutdown()
          Performs what has to be done when the Map Plugin shuts down.
 boolean isTransient()
           
 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 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.ArrayList peekWithLimitEntry(I_QueueEntry limitEntry)
          Deprecated.  
 java.util.ArrayList peekWithPriority(int numOfEntries, long numOfBytes, int minPriority, int maxPriority)
          Returns maximum given number of entries from the queue (none blocking).
private  boolean put(I_Entry entry)
          Internally used for I_MapEntry and I_QueueEntry
 int put(I_MapEntry mapEntry)
          Adds one entry and automatically increments the reference counter.
 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.
 boolean registerStorageProblemListener(I_StorageProblemListener listener)
          registers a new listener to be notified.
 int remove()
          Removes the first element in the queue This method does not block.
 int remove(I_MapEntry mapEntry)
           
 int remove(long uniqueId)
           
 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 numOfEntries messages.
 I_MapEntry removeOldest()
          Remove the oldest entry.
 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.
 int removeRandom(long dataId)
          Removes the given entry.
 boolean[] removeRandom(long[] dataIdArray)
          Removes the given entries.
 void removeStorageSizeListener(I_StorageSizeListener listener)
          Removes the specified listener from the queue.
 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).
private  void resetCounters()
          This method resets all cached sizes and counters.
private  void setEntryCount(EntryCount entryCount)
           
 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
private  java.lang.String spaceLeft(long numOfEntries, long sizeInBytes)
          Check is storage is big enough for entry
 I_QueueEntry take()
          Currently not supported by I_Queue.
 java.util.ArrayList take(int numOfEntries, long numOfBytes)
          Currently not supported by I_Queue.
 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.
 boolean unRegisterStorageProblemListener(I_StorageProblemListener listener)
          unregisters a listener.
 int update(I_QueueEntry queueEntry)
          Updates the given message queue entry with a new value.
 void updateCounters(I_MapEntry entry)
           
 java.lang.String usage()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ME

private java.lang.String ME

storageId

private StorageId storageId

notifiedAboutAddOrRemove

private boolean notifiedAboutAddOrRemove

glob

private Global glob

log

private static java.util.logging.Logger log

property

private QueuePropertyBase property

manager

private CommonTableDatabaseAccessor manager

putListener

private I_QueuePutListener putListener

numOfEntries

private long numOfEntries

numOfPersistentEntries

private long numOfPersistentEntries

numOfPersistentBytes

private long numOfPersistentBytes

numOfBytes

private long numOfBytes

isDown

boolean isDown

modificationMonitor

private java.lang.Object modificationMonitor
Monitor object used to synchronize the count of sizes


pluginInfo

private PluginInfo pluginInfo

debug

private boolean debug

entryCounter

private int entryCounter

isWarned

private static boolean isWarned

storageSizeListenerHelper

private StorageSizeListenerHelper storageSizeListenerHelper
Constructor Detail

JdbcQueueCommonTablePlugin

public JdbcQueueCommonTablePlugin()
Method Detail

isTransient

public boolean isTransient()
Specified by:
isTransient in interface I_Storage
Returns:
true for RAM based queue, false for other types like CACHE and JDBC queues

resetCounters

private final void resetCounters()
This method resets all cached sizes and counters. While testing it could be invoked before each public invocation to see which method fails ...


spaceLeft

private java.lang.String spaceLeft(long numOfEntries,
                                   long sizeInBytes)
Check is storage is big enough for entry

Parameters:
mapEntry - may not be null
Returns:
null There is space (otherwise the error text is returned)

getJdbcQueueManagerCommonTable

protected CommonTableDatabaseAccessor getJdbcQueueManagerCommonTable(PluginInfo pluginInfo)
                                                              throws XmlBlasterException
Returns a JdbcManagerCommonTable for a specific queue. It strips the queueId to find out to which manager it belongs. If such a manager does not exist yet, it is created and initialized. A queueId must be of the kind: cb:some/id/or/someother where the important requirement here is that it contains a ':' character. text on the left side of the separator (in this case 'cb') tells which kind of queue it is: for example a callback queue (cb) or a client queue.

Throws:
XmlBlasterException

initialize

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

Specified by:
initialize in interface I_Map
Specified by:
initialize in interface I_Queue
Parameters:
uniqueQueueId - A unique name, allowing to create a unique name for a persistent store (e.g. file name)
userData - For example a Properties object or a String[] args object passing the configuration data
Throws:
XmlBlasterException
See Also:
I_Queue.initialize(StorageId, Object)

setProperties

public void setProperties(java.lang.Object userData)
                   throws XmlBlasterException
Description copied from interface: I_Map
Allows to overwrite properties which where passed on initialize() The properties which support hot configuration are depending on the used implementation

Specified by:
setProperties in interface I_Map
Specified by:
setProperties in interface I_Queue
Throws:
XmlBlasterException
See Also:
I_Queue.setProperties(Object)

getProperties

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

Specified by:
getProperties in interface I_Map
Specified by:
getProperties in interface I_Queue

setNotifiedAboutAddOrRemove

public void setNotifiedAboutAddOrRemove(boolean notify)
Specified by:
setNotifiedAboutAddOrRemove in interface I_Queue

isNotifiedAboutAddOrRemove

public boolean isNotifiedAboutAddOrRemove()
Description copied from interface: I_Queue
Defaults to false.

Specified by:
isNotifiedAboutAddOrRemove in interface I_Queue
Returns:
true The I_QueueEntry.addedToQueue() and removedFromQueue() are invoked
false The entries are not informed

addPutListener

public void addPutListener(I_QueuePutListener l)
Description copied from interface: I_Queue
Register a listener which wants to be informed on put() events.

Only one listener is currently supported.

Specified by:
addPutListener in interface I_Queue
See Also:
I_Queue.addPutListener(I_QueuePutListener)

removePutListener

public void removePutListener(I_QueuePutListener l)
Description copied from interface: I_Queue
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

Specified by:
removePutListener in interface I_Queue
See Also:
I_Queue.removePutListener(I_QueuePutListener)

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.

Specified by:
getEntryReferences in interface I_Queue
Returns:
Array with reference numbers
Throws:
XmlBlasterException

getEntries

public java.util.ArrayList getEntries(I_EntryFilter entryFilter)
                               throws XmlBlasterException
Description copied from interface: I_Queue
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

Specified by:
getEntries in interface I_Queue
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
See Also:
I_Queue.getEntries(I_EntryFilter)

put

public void put(I_QueueEntry queueEntry,
                boolean ignorePutInterceptor)
         throws XmlBlasterException
Description copied from interface: I_Queue
Puts one queue entry on top of the queue. See the other put() for a detailed description.

Specified by:
put in interface I_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_Queue.put(I_QueueEntry, boolean)

put

private boolean put(I_Entry entry)
             throws XmlBlasterException
Internally used for I_MapEntry and I_QueueEntry

Returns:
true on success
Throws:
XmlBlasterException

put

public void put(I_QueueEntry[] queueEntries,
                boolean ignorePutInterceptor)
         throws XmlBlasterException
Description copied from interface: I_Queue
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.

Specified by:
put in interface I_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_Queue.put(I_QueueEntry[], boolean)

getStorageId

public StorageId getStorageId()
Returns the unique ID of this queue

Specified by:
getStorageId in interface I_Storage
Returns:
For example "history_heronhello"

take

public I_QueueEntry take()
                  throws XmlBlasterException
Currently not supported by I_Queue.

Throws:
XmlBlasterException

takeWithPriority

public java.util.ArrayList takeWithPriority(int numOfEntries,
                                            long numOfBytes,
                                            int minPriority,
                                            int maxPriority)
                                     throws XmlBlasterException
Description copied from interface: I_Queue
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

Specified by:
takeWithPriority in interface I_Queue
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.
See Also:
I_Queue.takeWithPriority(int,long,int,int)

take

public java.util.ArrayList take(int numOfEntries,
                                long numOfBytes)
                         throws XmlBlasterException
Currently not supported by I_Queue.

Throws:
XmlBlasterException

takeLowest

public java.util.ArrayList takeLowest(int numOfEntries,
                                      long numOfBytes,
                                      I_QueueEntry limitEntry,
                                      boolean leaveOne)
                               throws XmlBlasterException
Description copied from interface: I_Queue
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.

Specified by:
takeLowest in interface I_Queue
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
See Also:
I_Queue.takeLowest(int, long, I_QueueEntry, boolean)

peekLowest

public java.util.ArrayList peekLowest(int numOfEntries,
                                      long numOfBytes,
                                      I_QueueEntry limitEntry,
                                      boolean leaveOne)
                               throws XmlBlasterException
Description copied from interface: I_Queue
Same as takeLowest but it does not remove the entries.

Specified by:
peekLowest in interface I_Queue
Throws:
XmlBlasterException
See Also:
I_Queue.peekLowest(int, long, I_QueueEntry, boolean)

peek

public I_QueueEntry peek()
                  throws XmlBlasterException
Description copied from interface: I_Queue
Returns the first element in the queue but does not remove it from that queue (leaves it untouched). This method does not block.

Specified by:
peek in interface I_Queue
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.
See Also:
I_Queue.peek()

peek

public java.util.ArrayList peek(int numOfEntries,
                                long numOfBytes)
                         throws XmlBlasterException
Description copied from interface: I_Queue
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.

Specified by:
peek in interface I_Queue
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.
See Also:
I_Queue.peek(int,long)

peekStartAt

public java.util.ArrayList peekStartAt(int numOfEntries,
                                       long numOfBytes,
                                       I_QueueEntry firstEntryExlusive)
                                throws XmlBlasterException
Description copied from interface: I_Queue
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.

Specified by:
peekStartAt in interface I_Queue
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
Description copied from interface: I_Queue
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.

Specified by:
peekSamePriority in interface I_Queue
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.
See Also:
I_Queue.peekSamePriority(int, long)

peekWithPriority

public java.util.ArrayList peekWithPriority(int numOfEntries,
                                            long numOfBytes,
                                            int minPriority,
                                            int maxPriority)
                                     throws XmlBlasterException
Description copied from interface: I_Queue
Returns maximum given number of entries from the queue (none blocking).

Specified by:
peekWithPriority in interface I_Queue
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.
See Also:
I_Queue.peekWithPriority(int, long, int, int)

peekWithLimitEntry

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

Description copied from interface: I_Queue
It returns the entries which are higher than the entry specified in the argument list.

Specified by:
peekWithLimitEntry in interface I_Queue
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
See Also:
I_Queue.peekWithLimitEntry(I_QueueEntry)

removeWithLimitEntry

public long removeWithLimitEntry(I_QueueEntry limitEntry,
                                 boolean inclusive)
                          throws XmlBlasterException
Description copied from interface: I_Queue
It removes the entries which are higher than the entry specified in the argument list.

Specified by:
removeWithLimitEntry in interface I_Queue
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
See Also:
I_Queue.removeWithLimitEntry(I_QueueEntry, boolean)

remove

public int remove()
           throws XmlBlasterException
Removes the first element in the queue This method does not block.

Specified by:
remove in interface I_Queue
Returns:
Number of messages erased (0 or 1)
Throws:
XmlBlasterException - if the underlying implementation gets an exception.

removeNum

public long removeNum(long numOfEntries)
               throws XmlBlasterException
Removes max numOfEntries messages. This method does not block.

Specified by:
removeNum in interface I_Queue
Parameters:
numOfEntries - Erase num entries or less if less entries are available, -1 erases everything
Returns:
Number of entries erased
Throws:
XmlBlasterException - if the underlying implementation gets an exception.

removeRandom

public int removeRandom(long dataId)
                 throws XmlBlasterException
Removes the given entry.

Parameters:
dataId - the unique id. It must be unique within the storage area of the implementing queue. In other words, if the underlying implementation is on RAM, then the storage area is the JVM, that is the queue must be unique in the same JVM. If the queue is a jdbc, the dataId is unique in the DB used.
Throws:
XmlBlasterException

removeRandom

public boolean[] removeRandom(long[] dataIdArray)
                       throws XmlBlasterException
Removes the given entries.

Parameters:
msgQueueEntry - the entry to erase.
Throws:
XmlBlasterException

removeRandom

public int removeRandom(I_Entry entry)
                 throws XmlBlasterException
Description copied from interface: I_Queue
Removes the given entry.

Specified by:
removeRandom in interface I_Queue
Parameters:
entry - The entry to erase.
Returns:
the number of elements erased.
Throws:
XmlBlasterException
See Also:
I_Queue.removeRandom(I_Entry)

removeRandom

public boolean[] removeRandom(I_Entry[] queueEntries)
                       throws XmlBlasterException
Description copied from interface: I_Queue
Removes the given entries.

Specified by:
removeRandom in interface I_Queue
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
See Also:
I_Queue.removeRandom(I_Entry[])

removeWithPriority

public long removeWithPriority(long numOfEntries,
                               long numOfBytes,
                               int minPriority,
                               int maxPriority)
                        throws XmlBlasterException
Description copied from interface: I_Queue
Removes max numOfEntries messages (or less depending on the numOfBytes). This method does not block.

Specified by:
removeWithPriority in interface I_Queue
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.
See Also:
I_Queue.removeWithPriority(long, long, int, int)

setEntryCount

private void setEntryCount(EntryCount entryCount)

getNumOfEntries_

private final long getNumOfEntries_()
                             throws XmlBlasterException
It returns the size of the queue. Note that this call will return the size stored in cache. In case this value is negative (which means a previous attempt to read from the DB failed) it will synchronize against the DB by making a call to the DB. If that fails it will return -1L. If the log DUMP is set to true, then a refresh of the cache is done by every invocation and if the cached value is different from the real value an error is written.

Throws:
XmlBlasterException - if number is not retrievable
See Also:
I_Storage.getNumOfEntries()

getNumOfEntries

public long getNumOfEntries()
It returns the size of the queue. Note that this call will return the size stored in cache. In case this value is -1L (which means a previous attempt to read from the DB failed) it will synchronize against the DB by making a call to the DB. If that fails it will return -1L.

Specified by:
getNumOfEntries in interface I_Storage
Returns:
int the number of elements
See Also:
I_Storage.getNumOfEntries()

getNumOfPersistentEntries_

private long getNumOfPersistentEntries_(boolean verbose)
                                 throws XmlBlasterException
It returns the number of persistent entries in the queue. In case this value is -1L (which means a previous attempt to read from the DB failed) it will synchronize against the DB by making a call to the DB. If that fails it will return -1L.

Parameters:
verbose - If true we throw an exception on errors, if false we ignore the error silently
Throws:
XmlBlasterException
See Also:
I_Queue.getNumOfPersistentEntries()

getNumOfPersistentEntries

public long getNumOfPersistentEntries()
It returns the number of persistent entries in the queue. In case this value is -1L (which means a previous attempt to read from the DB failed) it will synchronize against the DB by making a call to the DB. If that fails it will return -1L.

Specified by:
getNumOfPersistentEntries in interface I_Map
Specified by:
getNumOfPersistentEntries in interface I_Queue
Returns:
int the number of elements currently in the queue
See Also:
I_Queue.getNumOfPersistentEntries()

getMaxNumOfEntries

public long getMaxNumOfEntries()
Description copied from interface: I_Storage
Returns the maximum number of elements for this queue

Specified by:
getMaxNumOfEntries in interface I_Storage
Returns:
The maximum number of elements in the queue
See Also:
I_Storage.getMaxNumOfEntries()

getNumOfBytes_

private long getNumOfBytes_()
                     throws XmlBlasterException
It returns the size of the queue. Note that this call will return the size stored in cache. In case this value is -1L (which means a previous attempt to read from the DB failed) it will synchronize against the DB by making a call to the DB. If that fails it will return -1L.

Throws:
XmlBlasterException
See Also:
I_Storage.getNumOfBytes()

getNumOfBytes

public long getNumOfBytes()
It returns the size of the queue. Note that this call will return the size stored in cache. In case this value is -1L (which means a previous attempt to read from the DB failed) it will synchronize against the DB by making a call to the DB. If that fails it will return -1L.

Specified by:
getNumOfBytes in interface I_Storage
Returns:
The number of elements currently in the queue
See Also:
I_Storage.getNumOfBytes()

getNumOfPersistentBytes_

private long getNumOfPersistentBytes_(boolean verbose)
                               throws XmlBlasterException
It returns the number of persistent entries in the queue. In case this value is -1L (which means a previous attempt to read from the DB failed) it will synchronize against the DB by making a call to the DB. If that fails it will return -1L.

Parameters:
verbose - If true we throw an exception on errors, if false we ignore the error silently
Throws:
XmlBlasterException
See Also:
I_Queue.getNumOfPersistentBytes()

getNumOfPersistentBytes

public long getNumOfPersistentBytes()
It returns the number of persistent entries in the queue. In case this value is -1L (which means a previous attempt to read from the DB failed) it will synchronize against the DB by making a call to the DB. If that fails it will return -1L.

Specified by:
getNumOfPersistentBytes in interface I_Map
Specified by:
getNumOfPersistentBytes in interface I_Queue
Returns:
int the number of elements currently in the queue
See Also:
I_Queue.getNumOfPersistentBytes()

getMaxNumOfBytes

public long getMaxNumOfBytes()
Description copied from interface: I_Map
returns the capacity (maximum bytes) for this queue

Specified by:
getMaxNumOfBytes in interface I_Map
Specified by:
getMaxNumOfBytes in interface I_Queue
Returns:
int the maximum number of elements in the queue
See Also:
I_Queue.getMaxNumOfBytes()

update

public int update(I_QueueEntry queueEntry)
           throws XmlBlasterException
Updates the given message queue entry with a new value. Note that this can be used if an entry with the unique id already exists. ?? Does this really make sense here since we need to store history ?? ?? Should we define a switch which can deactivate storage of history ??

Throws:
XmlBlasterException

getManager

public CommonTableDatabaseAccessor getManager()

clear

public long clear()
Clears everything and removes the queue (i.e. frees the associated table)

Specified by:
clear in interface I_Map
Specified by:
clear in interface I_Queue
Returns:
Number of entries removed

removeHead

public long removeHead(I_QueueEntry toEntry)
                throws XmlBlasterException
Description copied from interface: I_Queue
removes the head of the queue until (but not included) the entry specified as the argument.

Specified by:
removeHead in interface I_Queue
Parameters:
toEntry - the entry until to remove.
Returns:
long the number of entries deleted.
Throws:
XmlBlasterException
See Also:
I_Queue.removeHead(I_QueueEntry)

shutdown

public void shutdown()
Shutdown the implementation, sync with data store

Specified by:
shutdown in interface I_Map
Specified by:
shutdown in interface I_Plugin
Specified by:
shutdown in interface I_Queue

isShutdown

public boolean isShutdown()
Description copied from interface: I_Storage
Performs what has to be done when the Map Plugin shuts down.

Specified by:
isShutdown in interface I_Storage

usage

public java.lang.String usage()
Specified by:
usage in interface I_Map
Specified by:
usage in interface I_Queue
Returns:
a human readable usage help string

toXml

public final java.lang.String toXml(java.lang.String extraOffset)
Description copied from interface: I_Queue
Dump state to XML string.

Specified by:
toXml in interface I_Map
Specified by:
toXml in interface I_Queue
Parameters:
extraOffset - Indent the dump with given ASCII blanks
Returns:
Internal state as an XML ASCII string

init

public void init(Global glob,
                 PluginInfo pluginInfo)
Enforced by I_Plugin

Specified by:
init in interface I_Plugin
See Also:
I_Plugin.init(org.xmlBlaster.util.Global, PluginInfo)

getType

public java.lang.String getType()
Enforced by I_Plugin

Specified by:
getType in interface I_Plugin
Returns:
"JDBC"

getVersion

public java.lang.String getVersion()
Enforced by I_Plugin

Specified by:
getVersion in interface I_Plugin
Returns:
"1.0"

getInfo

public PluginInfo getInfo()
Enforced by I_StoragePlugin

Specified by:
getInfo in interface I_StoragePlugin
Returns:
the pluginInfo object.

destroy

public void destroy()
             throws XmlBlasterException
Cleans up the current queue (it deletes all the entries and frees the table used and cleans up all tables in the database). This method should never be called, only for testing purposes or to clean up the entire database.

Specified by:
destroy in interface I_Map
Throws:
XmlBlasterException

get

public I_MapEntry get(long uniqueId)
               throws XmlBlasterException
Description copied from interface: I_Map
Lookup entry without removing.

Specified by:
get in interface I_Map
Returns:
null if not found
Throws:
XmlBlasterException

getAll

public I_MapEntry[] getAll(I_EntryFilter entryFilter)
                    throws XmlBlasterException
Description copied from interface: I_Map
Retrieve all entries in the storage, please take care on memory consumption.

Specified by:
getAll in interface I_Map
Parameters:
entryFilter - null to get everything. If specified you can filter by this callback the wanted entries.
Returns:
A current snapshot of all entries
Throws:
XmlBlasterException
See Also:
I_Map#getAll()

put

public int put(I_MapEntry mapEntry)
        throws XmlBlasterException
Description copied from interface: I_Map
Adds one entry and automatically increments the reference counter. Note: If an entry existed already (0 is returned), it is NOT updated in storage

Specified by:
put in interface I_Map
Returns:
Number of new entries added: 0 if entry existed, 1 if new entry added
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_Map.put(I_MapEntry)

remove

public int remove(I_MapEntry mapEntry)
           throws XmlBlasterException
Specified by:
remove in interface I_Map
Returns:
the number of elements erased.
Throws:
XmlBlasterException

remove

public int remove(long uniqueId)
           throws XmlBlasterException
Specified by:
remove in interface I_Map
Returns:
the number of elements erased.
Throws:
XmlBlasterException

removeOldest

public I_MapEntry removeOldest()
                        throws XmlBlasterException
Description copied from interface: I_Map
Remove the oldest entry. 'Oldest' is defined in the context of the implementation to support an efficient cache, typically it is the LRU (last recent used) entry.

Specified by:
removeOldest in interface I_Map
Returns:
the removed entry
Throws:
XmlBlasterException
See Also:
I_Map.removeOldest()

registerStorageProblemListener

public boolean registerStorageProblemListener(I_StorageProblemListener listener)
Description copied from interface: I_StorageProblemNotifier
registers a new listener to be notified. If the registration was not done (for example if the implementation only allows one listener and there is already one), then a 'false' is returned, otherwise 'true' is returned.

Specified by:
registerStorageProblemListener in interface I_StorageProblemNotifier
See Also:
I_StorageProblemNotifier.registerStorageProblemListener(I_StorageProblemListener)

unRegisterStorageProblemListener

public boolean unRegisterStorageProblemListener(I_StorageProblemListener listener)
Description copied from interface: I_StorageProblemNotifier
unregisters a listener. If there is no such listener 'false' is returned, otherwise 'true' is returned.

Specified by:
unRegisterStorageProblemListener in interface I_StorageProblemNotifier
See Also:
I_StorageProblemNotifier.unRegisterStorageProblemListener(I_StorageProblemListener)

change

public I_MapEntry change(I_MapEntry entry,
                         I_ChangeCallback callback)
                  throws XmlBlasterException
Specified by:
change in interface I_Map
Parameters:
entry - the entry to change. This is the old entry, i.e. the entry on which the modification has to take place by callback. Or it is the new entry and you can pass null for callback. IMPORTANT: This method is not threadsafe since it does not make a lookup to get the actual entry. The specified entry could be a dirty read, in which case the current entry would be overwritten with this dirty value. If you want to work threadsafe you should invoke change(long, callback). That method makes a lookup within the same synchronization point.
callback - the object on which the callback method 'changeEntry' is invoked. The modification of the object is done in that method. If you pass null, then the changeEntry is not invoked and the processing continues with entry.
Returns:
I_MapEntry the modified entry.
Throws:
XmlBlasterException - if something goes wrong when making the change (for example if the entry is not in the map) or if the callback throws an exception.
See Also:
I_Map.change(I_MapEntry, I_ChangeCallback)

updateCounters

public void updateCounters(I_MapEntry entry)
                    throws XmlBlasterException
Specified by:
updateCounters in interface I_Map
Parameters:
entry - the entry to change. This is the old entry, i.e. the entry on which the modification has to take place by callback. Or it is the new entry and you can pass null for callback. IMPORTANT: This method is not threadsafe since it does not make a lookup to get the actual entry. The specified entry could be a dirty read, in which case the current entry would be overwritten with this dirty value. If you want to work threadsafe you should invoke change(long, callback). That method makes a lookup within the same synchronization point.
Throws:
XmlBlasterException - if something goes wrong when making the change (for example if the entry is not in the map) or if the callback throws an exception.
See Also:
I_Map.change(I_MapEntry, I_ChangeCallback)

change

public I_MapEntry change(long uniqueId,
                         I_ChangeCallback callback)
                  throws XmlBlasterException
Description copied from interface: I_Map
This method is threadsafe because it makes a lookup for the updated entry within the synchronization point.

Specified by:
change in interface I_Map
Parameters:
uniqueId - the uniqueId of the entry to change. This is the old entry, i.e. the entry on which the modification has to take place.
callback - the object on which the callback method 'changeEntry' is invoked. The modification of the object is done in that method. If you pass null, then the changeEntry is not invoked and the processing continues with entry.
Returns:
I_Entry the modified entry.
Throws:
XmlBlasterException - if something goes wrong when making the change (for example if the entry is not in the map) or if the callback throws an exception.
See Also:
I_Map.change(long, I_ChangeCallback)

addStorageSizeListener

public void addStorageSizeListener(I_StorageSizeListener listener)
Description copied from interface: I_Storage
Adds a storage size listener to the storage. Every time the number of storage entries changes we will fire a changed() event.

The changed() invocation is guaranteed to NOT be in any Queue specific synchronize

You can use this for example to add a threshold warning system.

Specified by:
addStorageSizeListener in interface I_Storage
Parameters:
listener - the listener to be added, adding the same listener multiple times will only remember one and fire once
See Also:
I_Storage.addStorageSizeListener(I_StorageSizeListener)

removeStorageSizeListener

public void removeStorageSizeListener(I_StorageSizeListener listener)
Description copied from interface: I_Storage
Removes the specified listener from the queue.

Specified by:
removeStorageSizeListener in interface I_Storage
Parameters:
listener - the listener to be removed. Currently only one. If you pass null, all queueSizeListeners are removed.
See Also:
I_Storage.removeStorageSizeListener(I_StorageSizeListener)

hasStorageSizeListener

public boolean hasStorageSizeListener(I_StorageSizeListener listener)
Description copied from interface: I_Storage
Checks wether the specified listener is registered.

Specified by:
hasStorageSizeListener in interface I_Storage
Parameters:
listener - the listener to check against. If you pass null it checks if at least one listener exists.
Returns:
true if the specified listener exists, false otherwise. If you passed null in the argument list it returns true if a listener exists.
See Also:
I_Storage.hasStorageSizeListener(I_StorageSizeListener)

getStorageSizeListeners

public I_StorageSizeListener[] getStorageSizeListeners()
Specified by:
getStorageSizeListeners in interface I_Storage
Returns:
the array of storage size listeners for this storage. It never returns null.
See Also:
I_Storage.getStorageSizeListeners()

embeddedQueueObjectsToXml

public long embeddedQueueObjectsToXml(java.io.OutputStream out,
                                      java.util.Properties props)
                               throws java.lang.Exception
Description copied from interface: I_Queue
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.

Specified by:
embeddedQueueObjectsToXml in interface I_Queue
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

embeddedObjectsToXml

public long embeddedObjectsToXml(java.io.OutputStream out,
                                 java.util.Properties props)
                          throws java.lang.Exception
Description copied from interface: I_Map
Dump all entries of this map to the given output stream. The messages are XML formatted.

Specified by:
embeddedObjectsToXml in interface I_Map
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
See Also:
I_Map.embeddedObjectsToXml(OutputStream, Properties)

xmlBlaster 2.2.0 API

Copyright © 1999-2014 The xmlBlaster.org contributers.