org.xmlBlaster.util.admin
Interface I_AdminQueue

All Superinterfaces:

I_AdminPlugin, I_AdminUsage

All Known Subinterfaces:

CacheQueueInterceptorPluginMBean

All Known Implementing Classes:

CacheQueueInterceptorPlugin

public interface I_AdminQueue

extends I_AdminPlugin

Declares available methods of a queue implementation for administration.

SNMP or telnet tools can access only the here declared properties.
This interface is implemented by I_Queue.java implementations delivering the meat.

Don't invoke any operations on this interface, it will certainly destroy your running application!

Since:

1.0.4

Author:

xmlBlaster@marcelruff.info

See Also:

I_Queue

Method Summary

long	clear() Remove all queue entries.
java.lang.String	dumpEmbeddedObjectsToFile(java.lang.String fileName) Dump all entries of this queue to a file.
long[]	getEntryReferences() Gets the references of the entries in the queue.
long	getMaxNumOfBytes() Access the configured capacity (maximum bytes) for this queue
long	getMaxNumOfEntries() Returns the maximum number of elements for this queue
long	getNumOfBytes() Returns the amount of bytes currently in the queue.
long	getNumOfEntries() Returns the number of elements in 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.String	getPropertyStr() Access the current queue configuration
java.lang.String	getQueueName() Returns the unique ID of this queue as found in the database XB_ENTRIES.queueName column.
boolean	isNotifiedAboutAddOrRemove() Defaults to false.
boolean	isShutdown() Check status of queue.
boolean	isTransient()
java.lang.String[]	peekEntries(int numOfEntries) Returns maximum the first num element in the queue but does not remove it from that queue (leaves it untouched).
java.lang.String	peekStr() Returns the first element in the queue but does not remove it from that queue (leaves it untouched).
int	remove() Removes the first element in the queue.
long	remove(long numOfEntries, long numOfBytes) Removes max num messages.
int	removeTransient() Removes all the transient entries (the ones which have the flag 'persistent' set to false.
long	removeWithPriority(long numOfEntries, long numOfBytes, int minPriority, int maxPriority) Removes max numOfEntries messages (or less depending on the numOfBytes).
void	shutdown() Shutdown the implementation, sync with data store, free resources.
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() Dump state to XML string.

Methods inherited from interface org.xmlBlaster.util.admin.I_AdminPlugin

getType, getVersion

Methods inherited from interface org.xmlBlaster.util.admin.I_AdminUsage

getUsageUrl, setUsageUrl, usage

Method Detail

getPropertyStr

public java.lang.String getPropertyStr()

Access the current queue configuration

isNotifiedAboutAddOrRemove

public boolean isNotifiedAboutAddOrRemove()

Defaults to false.

Returns:

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

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.

Returns:

Array with reference numbers

Throws:

XmlBlasterException

getQueueName

public java.lang.String getQueueName()

Returns the unique ID of this queue as found in the database XB_ENTRIES.queueName column.

Returns:

For example "history_heronhello"

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.

peekStr

public java.lang.String peekStr()
                         throws java.lang.Exception

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:

java.lang.Exception - if the underlying implementation gets an exception.

peekEntries

public java.lang.String[] peekEntries(int numOfEntries)
                               throws java.lang.Exception

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

Returns:

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

Throws:

java.lang.Exception - if the underlying implementation gets an exception.

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.

getNumOfEntries

public long getNumOfEntries()

Returns the number of elements 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

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

getMaxNumOfEntries

public long getMaxNumOfEntries()

Returns the maximum number of elements for this queue

Returns:

The maximum number of elements in the queue

getNumOfBytes

public long getNumOfBytes()

Returns the amount of bytes currently 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

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

removeTransient

public int removeTransient()
                    throws XmlBlasterException

Removes all the transient entries (the ones which have the flag 'persistent' set to false.

Throws:

XmlBlasterException

isTransient

public boolean isTransient()

Returns:

true for RAM based queue, false for other types like CACHE and JDBC queues

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.

Specified by:

shutdown in interface I_AdminPlugin

isShutdown

public boolean isShutdown()

Check status of queue.

Specified by:

isShutdown in interface I_AdminPlugin

Returns:

true if queue is not available anymore

toXml

public java.lang.String toXml()

Dump state to XML string.

Returns:

An xml encoded dump

dumpEmbeddedObjectsToFile

public java.lang.String dumpEmbeddedObjectsToFile(java.lang.String fileName)
                                           throws java.lang.Exception

Dump all entries of this queue to a file. The messages are XML formatted.

Parameters:

fileName - The file name to dump, may contain a path.

Returns:

Status string

Throws:

java.lang.Exception