com.latencybusters.lbm
Class LBMWildcardReceiver

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

All Implemented Interfaces:

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

public class LBMWildcardReceiver
extends java.util.Properties

LBM Wildcard 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

LBMWildcardReceiver(LBMContext lbmctx, java.lang.String pattern, LBMReceiverAttributes lbmrcvattr, LBMWildcardReceiverAttributes lbmwrcvattr)
Instantiate an LBM Wildcard Receiver object that will receive messages sent to any topic matching the given pattern.

LBMWildcardReceiver(LBMContext lbmctx, java.lang.String pattern, LBMReceiverAttributes lbmrcvattr, LBMWildcardReceiverAttributes lbmwrcvattr, LBMEventQueue lbmevq)
Instantiate an LBM Wildcard Receiver object (associated with a specified event queue) that will receive messages sent to any topic matching the given pattern.

LBMWildcardReceiver(LBMContext lbmctx, java.lang.String pattern, LBMReceiverAttributes lbmrcvattr, LBMWildcardReceiverAttributes lbmwrcvattr, LBMReceiverCallback cb, java.lang.Object cbArg)
Instantiate an LBM Wildcard Receiver object that will receive messages sent to any topic matching the given pattern.

LBMWildcardReceiver(LBMContext lbmctx, java.lang.String pattern, LBMReceiverAttributes lbmrcvattr, LBMWildcardReceiverAttributes lbmwrcvattr, LBMReceiverCallback cb, java.lang.Object cbArg, LBMEventQueue lbmevq)
Instantiate an LBM Wildcard Receiver object (associated with a specified event queue) that will receive messages sent to any topic matching the given pattern.

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.
protected int	comparePattern(java.lang.String topic) Default wildcard pattern comparison method.
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 wildcard receiver-related attribute for this wildcard receiver.
void	indexRelease(java.lang.String queue, UMQIndexInfo index) Instruct the given UMQ queue(s) to release the given UMQ index that is assigned to this wildcard receiver.
void	indexStartAssignment(java.lang.String queue) Starts this wildcard receiver's eligibility for new index assignments from a queue.
void	indexStopAssignment(java.lang.String queue) Stops this wildcard receiver's eligibility for new index assignments from a queue.
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	setAttributeValue(java.lang.String attributeName, java.lang.String attributeValue) Set the value of a wildcard receiver-related attribute for this wildcard 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, load, loadFromXML, propertyNames, save, setProperty, 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

LBMWildcardReceiver

public LBMWildcardReceiver(LBMContext lbmctx,
                           java.lang.String pattern,
                           LBMReceiverAttributes lbmrcvattr,
                           LBMWildcardReceiverAttributes lbmwrcvattr)
                    throws LBMException

Instantiate an LBM Wildcard Receiver object that will receive messages sent to any topic matching the given pattern. 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 wildcard receiver.

pattern - Pattern used to match topic strings

lbmrcvattr - LBMReceiverAttributes to be associated with this wildcard receiver

lbmwrcvattr - LBMWildcardReceiverAttributes to be associated with this wildcard receiver

Throws:

LBMException - if the wildcard receiver creation fails.

LBMWildcardReceiver

public LBMWildcardReceiver(LBMContext lbmctx,
                           java.lang.String pattern,
                           LBMReceiverAttributes lbmrcvattr,
                           LBMWildcardReceiverAttributes lbmwrcvattr,
                           LBMEventQueue lbmevq)
                    throws LBMException

Instantiate an LBM Wildcard Receiver object (associated with a specified event queue) that will receive messages sent to any topic matching the given pattern. 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 wildcard receiver.

pattern - Pattern used to match topic strings

lbmrcvattr - LBMReceiverAttributes to be associated with this wildcard receiver

lbmwrcvattr - LBMWildcardReceiverAttributes to be associated with this wildcard receiver

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

Throws:

LBMException - if the wildcard receiver creation fails.

LBMWildcardReceiver

public LBMWildcardReceiver(LBMContext lbmctx,
                           java.lang.String pattern,
                           LBMReceiverAttributes lbmrcvattr,
                           LBMWildcardReceiverAttributes lbmwrcvattr,
                           LBMReceiverCallback cb,
                           java.lang.Object cbArg)
                    throws LBMException

Instantiate an LBM Wildcard Receiver object that will receive messages sent to any topic matching the given pattern.

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

Parameters:

lbmctx - Context with which to associate the wildcard receiver.

pattern - Pattern used to match topic strings

lbmrcvattr - LBMReceiverAttributes to be associated with this wildcard receiver

lbmwrcvattr - LBMWildcardReceiverAttributes to be associated with this wildcard receiver

cb - An object implementing the LBMReceiverCallback interface

cbArg - Callback object passed as token to callback interface

Throws:

LBMException - if the wildcard receiver creation fails.

LBMWildcardReceiver

public LBMWildcardReceiver(LBMContext lbmctx,
                           java.lang.String pattern,
                           LBMReceiverAttributes lbmrcvattr,
                           LBMWildcardReceiverAttributes lbmwrcvattr,
                           LBMReceiverCallback cb,
                           java.lang.Object cbArg,
                           LBMEventQueue lbmevq)
                    throws LBMException

Instantiate an LBM Wildcard Receiver object (associated with a specified event queue) that will receive messages sent to any topic matching the given pattern.

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

Parameters:

lbmctx - Context with which to associate the wildcard receiver.

pattern - Pattern used to match topic strings

lbmrcvattr - LBMReceiverAttributes to be associated with this wildcard receiver

lbmwrcvattr - LBMWildcardReceiverAttributes to be associated with this wildcard 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 the wildcard receiver creation fails.

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 wildcard receiver-related attribute for this wildcard 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 wildcard receiver-related attribute for this wildcard 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:

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

comparePattern

protected int comparePattern(java.lang.String topic)

Default wildcard pattern comparison method. This method is called when a pattern match is desired for a topic discovered for a wildcard receiver (if the pattern type attribute is set to "appcb").

Parameters:

topic - Topic string to evaluate

Returns:

0 - indicates that the given topic should be considered part of the wildcard, 1 or more - indicates that the topic should not be considered matching the wildcard.

See Also:

LBMWildcardReceiverAttributes.setPatternCallback(com.latencybusters.lbm.LBMWildcardPatternCallback, java.lang.Object)

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

umederegister

public void umederegister()
                   throws LBMException

Deregister 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 wildcard 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 wildcard 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 this wildcard 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

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.

umewrcvderegister

public void umewrcvderegister()
                       throws LBMException

Deregister Wildcard receiver from all UME Store.

Throws:

LBMEOPException - if an error occurs while attempting to deregister.

LBMException

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.