com.latencybusters.lbm
Class LBMEventQueue

java.lang.Object
  java.util.Dictionary<K,V>
      java.util.Hashtable<java.lang.Object,java.lang.Object>
          java.util.Properties
              com.latencybusters.lbm.LBMEventQueue

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, java.util.Map<java.lang.Object,java.lang.Object>

public class LBMEventQueue
extends java.util.Properties

LBM Event Queue class. This class may be subclassed to override the default event queue monitoring method or an LBMEventQueueCallback interface may be specified to handle the monitor callback.

See Also:

Serialized Form

Field Summary

int	maxIterationRunTime Maximum time (in milliseconds) the event queue will run for at one time.

Fields inherited from class java.util.Properties

defaults

Constructor Summary

LBMEventQueue()
Instantiate an LBM Event Queue object using default attributes.

LBMEventQueue(LBMEventQueueAttributes lbmevqattr)
Instantiate an LBM Event Queue object using the given attributes.

LBMEventQueue(LBMEventQueueAttributes lbmevqattr, LBMEventQueueCallback cb, java.lang.Object cbArg)
Instantiate an LBM Event Queue object using the given attributes.

LBMEventQueue(LBMEventQueueCallback cb, java.lang.Object cbArg)
Instantiate an LBM Event Queue object using default attributes.

Method Summary

void	addMonitor(LBMEventQueueCallback cb) Register a monitor callback
void	addMonitor(LBMEventQueueCallback cb, java.lang.Object cbArg) Register a monitor callback (and callback token)
void	close() Close this event queue.
LBMConfigOption[]	dumpAttributeList() Returns an array of LBMConfigOptions.
protected void	finalize()
java.lang.String	getAttributeValue(java.lang.String attributeName) Returns the value of an event queue-related attribute for this event queue.
LBMEventQueueStatistics	getStatistics() Return the current set of statistics for this event queue.
void	load(java.io.InputStream inStream) Reads a property (attribute) list (key and element pairs) from the input stream.
protected void	monitor(int eventType, int eventQueueSize, long eventQueueDelay) Default event queue monitoring callback.
int	propertySize() Deprecated. In LBM4.0. This API existed because there was an LBMEventQueue.size() API which conflicted with java.util.Properties. This has been removed so propertySize() is no longer required. Use Hashtable.size()
int	queueSize() Determine the number of queued events in the event queue.
void	removeMonitor(LBMEventQueueCallback cb) Deregister a monitor callback
void	removeMonitor(LBMEventQueueCallback cb, java.lang.Object cbArg) Deregister a monitor callback (and callback token)
void	resetStatistics() Reset the event queue statistics.
void	run(long milliseconds) Dispatch waiting events to the appropriate callback methods.
void	setAttributeValue(java.lang.String attributeName, java.lang.String attributeValue) Set the value of an event queue-related attribute for this event queue.
java.lang.Object	setProperty(java.lang.String attributeName, java.lang.String attributeValue) Set the value of an event queue-related attribute for this event queue.
int	shutdown() Shutdown the event queue by purging any pending events and not allowing additional events to be added to the queue.
void	stop() Signal any threads dispatching the event queue to return as soon as possible.

Methods inherited from class java.util.Properties

getProperty, getProperty, list, list, load, loadFromXML, propertyNames, save, store, store, storeToXML, storeToXML, stringPropertyNames

Methods inherited from class java.util.Hashtable

clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

maxIterationRunTime

public int maxIterationRunTime

Maximum time (in milliseconds) the event queue will run for at one time.

Constructor Detail

LBMEventQueue

public LBMEventQueue()
              throws LBMException

Instantiate an LBM Event Queue object using default attributes.

Throws:

LBMException - if there was an error creating the event queue.

LBMEventQueue

public LBMEventQueue(LBMEventQueueAttributes lbmevqattr)
              throws LBMException

Instantiate an LBM Event Queue object using the given attributes.

Parameters:

lbmevqattr - LBMEventQueueAttributes used to initialize the event queue.

Throws:

LBMException - if any error occurs creating the event queue.

LBMEventQueue

public LBMEventQueue(LBMEventQueueCallback cb,
                     java.lang.Object cbArg)
              throws LBMException

Instantiate an LBM Event Queue object using default attributes.

Parameters:

cb - An object implementing the LBMEventQueueCallback interface

cbArg - Callback object passed as token to callback interface

Throws:

LBMException - if any error occurs creating the event queue.

LBMEventQueue

public LBMEventQueue(LBMEventQueueAttributes lbmevqattr,
                     LBMEventQueueCallback cb,
                     java.lang.Object cbArg)
              throws LBMException

Instantiate an LBM Event Queue object using the given attributes.

Parameters:

lbmevqattr - LBMEventQueueAttributes used to initialize the event queue.

cb - An object implementing the LBMEventQueueCallback interface

cbArg - Callback object passed as token to callback interface

Throws:

LBMException - if any error occurs creating the event queue.

Method Detail

finalize

protected void finalize()

Overrides:

finalize in class java.lang.Object

close

public void close()

Close this event queue. Since this method deletes the underlying LBM event queue object, it should not be called prior to closing or canceling of its dependent objects (e.g., LBMSource, LBMReceiver, LBMRequest, LBMTimer).

queueSize

public int queueSize()
              throws LBMException

Determine the number of queued events in the event queue. This method is only supported when the queue_size_warning config variable is set. If not set, then this function will throw an exception with an error number == LBM.EINVAL.

Returns:

Number of queued events on the event queue

Throws:

LBMException - if any error occurs.

propertySize

public int propertySize()

Deprecated. In LBM4.0. This API existed because there was an LBMEventQueue.size() API which conflicted with java.util.Properties. This has been removed so propertySize() is no longer required. Use Hashtable.size()

A wrapper for the size() method in java.util.Properties due to an unfortunate name choice.

Returns:

Number of keys in the property list.

shutdown

public int shutdown()
             throws LBMException

Shutdown the event queue by purging any pending events and not allowing additional events to be added to the queue.

Returns:

Always returns 0 although an exception may be thrown in the event of an error.

Throws:

LBMException - if any error occurs shutting down the event queue.

dumpAttributeList

public LBMConfigOption[] dumpAttributeList()

Returns an array of LBMConfigOptions.

Returns:

Array of LBMConfigOption

getAttributeValue

public java.lang.String getAttributeValue(java.lang.String attributeName)
                                   throws LBMException

Returns the value of an event queue-related attribute for this event queue.

Parameters:

attributeName - Name of the attribute to retrieve

Returns:

Value corresponding to the specified attribute name

Throws:

LBMException - if attributeName is not a valid attribute.

setAttributeValue

public void setAttributeValue(java.lang.String attributeName,
                              java.lang.String attributeValue)
                       throws LBMException

Set the value of an event queue-related attribute for this event queue. Note that this method bypasses the property list. As such no attributes configured using this method will appear in the property list.

Parameters:

attributeName - Name of the attribute to set

attributeValue - New attribute value

Throws:

LBMException - if attributeName is not a valid attribute, or attributeValue is not a valid value for attributeName.

See Also:

setProperty(java.lang.String, java.lang.String)

setProperty

public java.lang.Object setProperty(java.lang.String attributeName,
                                    java.lang.String attributeValue)

Set the value of an event queue-related attribute for this event queue.

Overrides:

setProperty in class java.util.Properties

Parameters:

attributeName - Name of the attribute to set

attributeValue - New attribute value

Throws:

LBMRuntimeException - if attributeName is not a valid attribute, or attributeValue is not a valid value for attributeName.

load

public void load(java.io.InputStream inStream)
          throws java.io.IOException

Reads a property (attribute) list (key and element pairs) from the input stream.

Overrides:

load in class java.util.Properties

Parameters:

inStream - Input stream of bytes

Throws:

java.io.IOException - if any I/O error occurs.

LBMRuntimeException - if any invalid attribute is detected in inStream.

run

public void run(long milliseconds)

Dispatch waiting events to the appropriate callback methods.

Parameters:

milliseconds - Number of milliseconds to block before returning.

stop

public void stop()

Signal any threads dispatching the event queue to return as soon as possible.

See Also:

run(long)

getStatistics

public LBMEventQueueStatistics getStatistics()
                                      throws LBMException

Return the current set of statistics for this event queue.

Returns:

LBMEventQueueStatistics object containing the statistics corresponding to this event queue.

Throws:

LBMException - if any error occurred retrieving statistics.

resetStatistics

public void resetStatistics()
                     throws LBMException

Reset the event queue statistics.

Throws:

LBMException - if any error occurs resetting the statistics.

addMonitor

public void addMonitor(LBMEventQueueCallback cb)

Register a monitor callback

Parameters:

cb - Object implementing the LBMEventQueueCallback interface

See Also:

LBMEventQueueCallback, removeMonitor(com.latencybusters.lbm.LBMEventQueueCallback)

addMonitor

public void addMonitor(LBMEventQueueCallback cb,
                       java.lang.Object cbArg)

Register a monitor callback (and callback token)

Parameters:

cb - Object implementing the LBMEventQueueCallback interface

cbArg - Callback token object

See Also:

LBMEventQueueCallback, removeMonitor(com.latencybusters.lbm.LBMEventQueueCallback)

removeMonitor

public void removeMonitor(LBMEventQueueCallback cb)

Deregister a monitor callback

Parameters:

cb - Previously registered object implementing the LBMEventQueueCallback interface

See Also:

LBMEventQueueCallback, addMonitor(com.latencybusters.lbm.LBMEventQueueCallback)

removeMonitor

public void removeMonitor(LBMEventQueueCallback cb,
                          java.lang.Object cbArg)

Deregister a monitor callback (and callback token)

Parameters:

cb - Previously registered object implementing the LBMEventQueueCallback interface

cbArg - Callback token for previously registered object

See Also:

LBMEventQueueCallback, addMonitor(com.latencybusters.lbm.LBMEventQueueCallback)

monitor

protected void monitor(int eventType,
                       int eventQueueSize,
                       long eventQueueDelay)

Default event queue monitoring callback. This method may be overridden by subclassing the LBMEventQueue class. Alternatively, the callback may be registered (deregistered) using the addMonitor() (removeMonitor()) methods.

Parameters:

eventType - monitoring event type

eventQueueSize - current event queue size (when monitor fires due

eventQueueDelay - current event queue delay in microseconds (when monitor fires due to excessive queue delay)

See Also:

addMonitor(com.latencybusters.lbm.LBMEventQueueCallback), removeMonitor(com.latencybusters.lbm.LBMEventQueueCallback)