com.latencybusters.lbm
Class LBMReceiver

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

All Implemented Interfaces:

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

Direct Known Subclasses:

LBMHotFailoverReceiver

public class LBMReceiver
extends java.util.Properties

LBM Receiver class. This class can be subclassed in order to override the default onReceive() method used to deliver received data or an LBMReceiverCallback interface may be specified for handling the received message callback.

Warning: It is not safe to instantiate this class from a context thread callback.

See Also:

Serialized Form

Field Summary

Fields inherited from class java.util.Properties

defaults

Constructor Summary

protected	LBMReceiver(LBMContext lbmctx, LBMTopic lbmtopic) Instantiate an LBM Receiver object associated with a given context and topic.
protected	LBMReceiver(LBMContext lbmctx, LBMTopic lbmtopic, LBMEventQueue lbmevq) Instantiate an LBM Receiver object associated with a given context, topic, and event queue.
	LBMReceiver(LBMContext lbmctx, LBMTopic lbmtopic, LBMReceiverCallback cb, java.lang.Object cbArg) Instantiate an LBM Receiver object associated with a given context and topic.
	LBMReceiver(LBMContext lbmctx, LBMTopic lbmtopic, LBMReceiverCallback cb, java.lang.Object cbArg, LBMEventQueue lbmevq) Instantiate an LBM Receiver object associated with a given context, topic, and event queue.

Method Summary

void	addReceiver(LBMReceiverCallback cb) Register a receiver callback
void	addReceiver(LBMReceiverCallback cb, java.lang.Object cbArg) Register a receiver callback (and callback token)
java.util.List<LBMMessage>	browseQueueMessages(java.lang.String queue, int max, long timeoutMS) Not currently supported.
void	close() Close this receiver.
void	deregister() Deregister from all UMQ queues.
void	deregister(java.lang.String queue) Deregister from a queue.
LBMConfigOption[]	dumpAttributeList() Returns an array of LBMConfigOptions
protected void	finalize()
java.lang.String	getAttributeValue(java.lang.String attributeName) Returns the value of a receiver-related attribute for this receiver.
LBMReceiverStatistics	getStatistics(int maxStats) Return the current set of receiver transport statistics for all sources.
LBMReceiverStatistics	getStatistics(java.lang.String source) Return the current set of receiver transport statistics for a particular source.
void	indexRelease(java.lang.String queue, UMQIndexInfo index) Instruct the given UMQ queue(s) to release the given UMQ index that is assigned to the given receiver.
void	indexStartAssignment(java.lang.String queue) Starts this receiver's eligibility for new index assignments from a queue.
void	indexStopAssignment(java.lang.String queue) Stops this receiver's eligibility for new index assignments from a queue.
void	load(java.io.InputStream inStream) Reads a property (attribute) list (key and element pairs) from the input stream.
protected int	onChannelReceive(LBMMessage lbmmsg, LBMReceiverCallback cb, java.lang.Object cbArg)
protected int	onReceive(LBMMessage lbmmsg) Default received message callback.
void	queueMessageList(java.lang.String queue, LBMAsyncOperationCallback asyncOpCb) Returns a list of currently-enqueued messages from the specified queue (which the receiver must be registered with).
void	queueMessageList(java.lang.String queue, LBMAsyncOperationCallback asyncOpCb, java.lang.Object cbArg) Returns a list of currently-enqueued messages from the specified queue (which the receiver must be registered with).
void	queueMessageList(java.lang.String queue, LBMAsyncOperationCallback asyncOpCb, java.lang.Object cbArg, java.lang.String msgSelector) Returns a list of currently-enqueued messages from the specified queue (which the receiver must be registered with).
void	queueMessageRetrieve(java.lang.String queue, java.util.List<UMQMessageId> messageIDs, LBMAsyncOperationCallback asyncOpCb) Retrieves the given list of UMQ messages (specified by UMQMessageId) and their associated status information from the specified queue.
void	queueMessageRetrieve(java.lang.String queue, java.util.List<UMQMessageId> messageIDs, LBMAsyncOperationCallback asyncOpCb, java.lang.Object cbArg) Retrieves the given list of UMQ messages (specified by UMQMessageId) and their associated status information from the specified queue.
int	receiverCount() Returns the number of receiver callbacks registered to this receiver
void	removeReceiver(LBMReceiverCallback cb) Deregister a receiver callback
void	removeReceiver(LBMReceiverCallback cb, java.lang.Object cbArg) Deregister a receiver callback (and callback token)
void	resetStatistics() Reset the receiver transport statistics for all sources.
void	resetStatistics(java.lang.String source) Reset the receiver transport statistics for a particular source.
void	setAttributeValue(java.lang.String attributeName, java.lang.String attributeValue) Set the value of a receiver-related attribute for this receiver.
java.lang.Object	setProperty(java.lang.String attributeName, java.lang.String attributeValue) Set the value of a receiver-related attribute for this receiver.
void	setSourceClientObject(java.lang.String source, java.lang.Object newClientObject) Set (or change) this receiver's per-source client object for the source with source string matching "source".
void	subscribeChannel(long channelNumber, LBMReceiverCallback cb, java.lang.Object cbArg) Subscribe to a given channel
void	umederegister() Deregister from all UME Store.
void	umewrcvderegister() Deregister Wildcard receiver from all UME Store.
void	unsubscribeChannel(long channelNumber) Cancel an existing subscription

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

Constructor Detail

LBMReceiver

protected LBMReceiver(LBMContext lbmctx,
                      LBMTopic lbmtopic)
               throws LBMException

Instantiate an LBM Receiver object associated with a given context and topic. ATTENTION: An application _must_ have at least one receiver callback registered per receiver object. Use of this constructor in a class that does not override the onReceive method creates a window after receiver creation and before adding a callback in which messages may be lost. Using this constructor in a class that overrides the onReceive method yields the best performance, and is recommended. If multiple callbacks support is needed, or if overriding the onReceive method is not desirable, use a constructor that specifies at least one initial callback.

Warning: It is not safe to call this constructor from a context thread callback.

Parameters:

lbmctx - Context with which to associate the receiver.

lbmtopic - LBMTopic used to initialize the receiver.

Throws:

LBMException - if an error occurs creating the receiver.

LBMReceiver

protected LBMReceiver(LBMContext lbmctx,
                      LBMTopic lbmtopic,
                      LBMEventQueue lbmevq)
               throws LBMException

Instantiate an LBM Receiver object associated with a given context, topic, and event queue. ATTENTION: An application _must_ have at least one receiver callback registered per receiver object. Use of this constructor in a class that does not override the onReceive method creates a window after receiver creation and before adding a callback in which messages may be lost. Using this constructor in a class that overrides the onReceive method yields the best performance, and is recommended. If multiple callbacks support is needed, or if overriding the onReceive method is not desirable, use a constructor that specifies at least one initial callback.

Warning: It is not safe to call this constructor from a context thread callback.

Parameters:

lbmctx - Context with which to associate the receiver.

lbmtopic - LBMTopic used to initialize the receiver.

lbmevq - Event queue with which to associate the receiver (all receiver events will be posted to this event queue).

Throws:

LBMException - if an error occurs creating the receiver.

LBMReceiver

public LBMReceiver(LBMContext lbmctx,
                   LBMTopic lbmtopic,
                   LBMReceiverCallback cb,
                   java.lang.Object cbArg)
            throws LBMException

Instantiate an LBM Receiver object associated with a given context and topic.

Warning: It is not safe to call this constructor from a context thread callback.

Parameters:

lbmctx - Context with which to associate the receiver.

lbmtopic - LBMTopic used to initialize the receiver.

cb - An object implementing the LBMReceiverCallback interface

cbArg - Callback object passed as token to callback interface

Throws:

LBMException - if an error occurs creating the receiver.

LBMReceiver

public LBMReceiver(LBMContext lbmctx,
                   LBMTopic lbmtopic,
                   LBMReceiverCallback cb,
                   java.lang.Object cbArg,
                   LBMEventQueue lbmevq)
            throws LBMException

Instantiate an LBM Receiver object associated with a given context, topic, and event queue.

Warning: It is not safe to call this constructor from a context thread callback.

Parameters:

lbmctx - Context with which to associate the receiver.

lbmtopic - LBMTopic used to initialize the receiver.

cb - An object implementing the LBMReceiverCallback interface

cbArg - Callback object passed as token to callback interface

lbmevq - Event queue with which to associate the receiver (all receiver events will be posted to this event queue).

Throws:

LBMException - if an error occurs creating the receiver.

Method Detail

finalize

protected void finalize()
                 throws LBMException

Throws:

LBMException

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 a receiver-related attribute for this receiver.

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 a receiver-related attribute for this receiver. 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 a receiver-related attribute for this receiver.

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.

getStatistics

public LBMReceiverStatistics getStatistics(java.lang.String source)
                                    throws LBMException

Return the current set of receiver transport statistics for a particular source.

Parameters:

source - Source string (as returned by LBMMesage source()) that specifies the set of statistics to return.

Returns:

LBMReceiverStatistics object containing the statistics corresponding to the specified source.

Throws:

LBMException - if any error occurred retrieving receiver statistics.

resetStatistics

public void resetStatistics(java.lang.String source)
                     throws LBMException

Reset the receiver transport statistics for a particular source.

Parameters:

source - The string version of the source to reset statistics for.

Throws:

LBMException - if any error occurred resetting statistics.

getStatistics

public LBMReceiverStatistics getStatistics(int maxStats)
                                    throws LBMException

Return the current set of receiver transport statistics for all sources.

Parameters:

maxStats - Maximum number of sources

Returns:

LBMReceiverStatistics object containing the statistics corresponding to the specified number of sources

Throws:

LBMException - if any error occurred retrieving receiver statistics.

resetStatistics

public void resetStatistics()
                     throws LBMException

Reset the receiver transport statistics for all sources.

Throws:

LBMException - if any error occurred resetting statistics.

subscribeChannel

public void subscribeChannel(long channelNumber,
                             LBMReceiverCallback cb,
                             java.lang.Object cbArg)
                      throws LBMException

Subscribe to a given channel

Throws:

LBMException

unsubscribeChannel

public void unsubscribeChannel(long channelNumber)
                        throws LBMException

Cancel an existing subscription

Throws:

LBMException

close

public final void close()
                 throws LBMException

Close this receiver.

Warning: It is not safe to call this method from a context thread callback.

Throws:

LBMException

receiverCount

public int receiverCount()

Returns the number of receiver callbacks registered to this receiver

addReceiver

public void addReceiver(LBMReceiverCallback cb)

Register a receiver callback

Parameters:

cb - Object implementing the LBMReceiverCallback interface

See Also:

LBMReceiverCallback, removeReceiver(com.latencybusters.lbm.LBMReceiverCallback)

addReceiver

public void addReceiver(LBMReceiverCallback cb,
                        java.lang.Object cbArg)

Register a receiver callback (and callback token)

Parameters:

cb - Object implementing the LBMReceiverCallback interface

cbArg - Callback token object

See Also:

LBMReceiverCallback, removeReceiver(com.latencybusters.lbm.LBMReceiverCallback)

removeReceiver

public void removeReceiver(LBMReceiverCallback cb)

Deregister a receiver callback

Parameters:

cb - Previously registered object implementing the LBMReceiverCallback interface

See Also:

LBMReceiverCallback, addReceiver(com.latencybusters.lbm.LBMReceiverCallback)

removeReceiver

public void removeReceiver(LBMReceiverCallback cb,
                           java.lang.Object cbArg)

Deregister a receiver callback (and callback token)

Parameters:

cb - Previously registered object implementing the LBMReceiverCallback interface

cbArg - Callback token for previously registered object

See Also:

LBMReceiverCallback, addReceiver(com.latencybusters.lbm.LBMReceiverCallback)

onReceive

protected int onReceive(LBMMessage lbmmsg)

Default received message callback. This method may be overridden by subclassing the LBMReceiverBase class (or one of the classes derived from LBMReceiverBase). Alternatively, a callback may be registered (deregistered) using the addReceiver() (removeReceiver()) methods.

Parameters:

lbmmsg - LBMMessage object containing the received data

See Also:

addReceiver(com.latencybusters.lbm.LBMReceiverCallback), removeReceiver(com.latencybusters.lbm.LBMReceiverCallback)

onChannelReceive

protected int onChannelReceive(LBMMessage lbmmsg,
                               LBMReceiverCallback cb,
                               java.lang.Object cbArg)

setSourceClientObject

public void setSourceClientObject(java.lang.String source,
                                  java.lang.Object newClientObject)
                           throws LBMEInvalException

Set (or change) this receiver's per-source client object for the source with source string matching "source".

Parameters:

source - Source string of source to look for.

newClientObject - The new per-source client object to use with this source.

Throws:

LBMEInvalException - if the source was not found.

umederegister

public void umederegister()
                   throws LBMException

Deregister from all UME Store.

Throws:

LBMEOPException - if an error occurs while attempting to deregister.

LBMException

umewrcvderegister

public void umewrcvderegister()
                       throws LBMException

Deregister Wildcard receiver from all UME Store.

Throws:

LBMEOPException - if an error occurs while attempting to deregister.

LBMException

deregister

public void deregister()
                throws LBMException

Deregister from all UMQ queues.

Throws:

LBMEOPException - if an error occurs while attempting to deregister.

LBMException

deregister

public void deregister(java.lang.String queue)
                throws LBMException

Deregister from a queue.

Parameters:

queue - The name of the queue to deregister from.

Throws:

LBMEOPException - if an error occurs while attempting to deregister.

LBMException

indexStopAssignment

public void indexStopAssignment(java.lang.String queue)
                         throws LBMException

Stops this receiver's eligibility for new index assignments from a queue.

Parameters:

queue - The name of the queue to stop new index assignment from, or null for all queues.

Throws:

LBMException - if an error occurs while attempting to stop index assignment.

Since:

UMQ 1.2

indexStartAssignment

public void indexStartAssignment(java.lang.String queue)
                          throws LBMException

Starts this receiver's eligibility for new index assignments from a queue.

Parameters:

queue - The name of the queue to start new index assignment from, or null for all queues.

Throws:

LBMException - if an error occurs while attempting to start index assignment.

Since:

UMQ 1.2

indexRelease

public void indexRelease(java.lang.String queue,
                         UMQIndexInfo index)
                  throws LBMException

Instruct the given UMQ queue(s) to release the given UMQ index that is assigned to the given receiver.

Parameters:

queue - Name of the queue at which to release the index, or null for all queues.

index - The index to release, or null for all indices.

Throws:

LBMException - if any error occurs.

Since:

UMQ 1.2

browseQueueMessages

public java.util.List<LBMMessage> browseQueueMessages(java.lang.String queue,
                                                      int max,
                                                      long timeoutMS)
                                               throws LBMException

Not currently supported. When implemented, it will browse messages on the given UMQ queue.

Parameters:

queue - Name of the queue at which to browse.

max - The max number of messages to return

Throws:

LBMException - if any error occurs.

queueMessageList

public void queueMessageList(java.lang.String queue,
                             LBMAsyncOperationCallback asyncOpCb)
                      throws LBMException

Returns a list of currently-enqueued messages from the specified queue (which the receiver must be registered with).

Parameters:

queue - Name of the queue to retrieve the list of messages from.

asyncOpCb - Object implementing the LBMAsyncOperationCallback interface that will receive updates and results for the asynchronous operation.

Throws:

LBMException - if queue or asyncObCb parameters are invalid, or if an error occurs.

queueMessageList

public void queueMessageList(java.lang.String queue,
                             LBMAsyncOperationCallback asyncOpCb,
                             java.lang.Object cbArg)
                      throws LBMException

Returns a list of currently-enqueued messages from the specified queue (which the receiver must be registered with).

Parameters:

queue - Name of the queue to retrieve the list of messages from.

asyncOpCb - Object implementing the LBMAsyncOperationCallback interface that will receive updates and results for the asynchronous operation.

cbArg - User-supplied callback object which will be passed back when asyncOpCb's onAsyncOperation method is called.

Throws:

LBMException - if queue or asyncObCb parameters are invalid, or if an error occurs.

queueMessageList

public void queueMessageList(java.lang.String queue,
                             LBMAsyncOperationCallback asyncOpCb,
                             java.lang.Object cbArg,
                             java.lang.String msgSelector)
                      throws LBMException

Returns a list of currently-enqueued messages from the specified queue (which the receiver must be registered with).

Parameters:

queue - Name of the queue to retrieve the list of messages from.

asyncOpCb - Object implementing the LBMAsyncOperationCallback interface that will receive updates and results for the asynchronous operation.

cbArg - User-supplied callback object which will be passed back when asyncOpCb's onAsyncOperation method is called.

msgSelector - User-supplied message selector string.

Throws:

LBMException - if queue or asyncObCb parameters are invalid, or if an error occurs.

queueMessageRetrieve

public void queueMessageRetrieve(java.lang.String queue,
                                 java.util.List<UMQMessageId> messageIDs,
                                 LBMAsyncOperationCallback asyncOpCb)
                          throws LBMException

Retrieves the given list of UMQ messages (specified by UMQMessageId) and their associated status information from the specified queue.

Parameters:

queue - Name of the queue to retrieve the messages from.

messageIDs - A list of the UMQ message IDs of the messages desired.

asyncOpCb - Object implementing the LBMAsyncOperationCallback interface that will receive updates and results for the asynchronous operation.

Throws:

LBMException - if queue, asyncObCb, or messageIDs parameters are invalid, or if an error occurs.

queueMessageRetrieve

public void queueMessageRetrieve(java.lang.String queue,
                                 java.util.List<UMQMessageId> messageIDs,
                                 LBMAsyncOperationCallback asyncOpCb,
                                 java.lang.Object cbArg)
                          throws LBMException

Retrieves the given list of UMQ messages (specified by UMQMessageId) and their associated status information from the specified queue.

Parameters:

queue - Name of the queue to retrieve the messages from.

messageIDs - A list of the UMQ message IDs of the messages desired.

asyncOpCb - Object implementing the LBMAsyncOperationCallback interface that will receive updates and results for the asynchronous operation.

cbArg - User-supplied callback object which will be passed back when asyncOpCb's onAsyncOperation method is called.

Throws:

LBMException - if queue, asyncObCb, or messageIDs parameters are invalid, or if an error occurs.