org.osesb.connectors.jms
Class JMSTopicReceiver

java.lang.Object
  org.osesb.connectors.jms.JMSConsumerBase
      org.osesb.connectors.jms.JMSTopicReceiver

All Implemented Interfaces:

java.lang.Runnable, javax.jms.ExceptionListener, javax.jms.MessageListener

public class JMSTopicReceiver
extends JMSConsumerBase

This descendant of JMSConsumerBase is a blocking, Topic receiver.

An instance of a JMSTopicReceiver is associated with a particular JMS Destination. The JMS Session object is cached (but can be reset) and JMSTopicReceiver(s) can be pooled. See the org.osesb.objectpools package for JMS producer and consumer pools.

Instances of JMSTopicReceiver are constructed with a org.osesb.configuration.JMSClientConfiguration, which contains properties for creating a JMS connection.

JMSTopicReceiver implements Topic-specific methods for JMS message consumers.

• startJMS(): Queue and Topic consumers implement this method to initialize their JMS environment. JMS receivers initialize their JMS environment from a XML configuration file, which is parsed into a JMSClientConfiguration object that is passed to this class's constructor.
• close(): Releases JMS resources.
• receiveJMSMessage(): blocking receivers implement this method to receive a message from the configured Destination object (Topic or Queue). Non- blocking receivers implement the MessageListener interface (i.e. onMessage()).

JMSQueueReceiver(s) can be pooled. See org.osesb.objectpools.JMSClientKeyedPoolFactory.

Since:

Version .9

Field Summary

protected javax.jms.Topic	topic The Topic for this JMS client.
protected javax.jms.TopicConnection	topicConnection The TopicConnection for this JMS client.
protected javax.jms.TopicSession	topicSession The TopicSession for this JMS client.

Fields inherited from class org.osesb.connectors.jms.JMSConsumerBase

connectionStarted, dateTimeOfLastMessage, dateTimeServiceStarted, heartbeatInterval, jmsClientConfiguration, jmsMessage, log, messageID, messageText, MIN_HEARTBEAT_INTERVAL, numberOfMessagesReceived, session, thisClassName

Constructor Summary

JMSTopicReceiver(JMSClientConfiguration jmsClientConfiguration)
Creates a new instance of JMSTopicReceiver and starts JMS.

JMSTopicReceiver(JMSClientConfiguration jmsClientConfiguration, javax.jms.Topic topic)
Creates a new instance of JMSTopicReceiver and starts JMS using the specified Topic.

Method Summary

protected void	checkSession() Checks the TopicSession and restarts JMS connection, if required.
void	close() Release JMS resources.
void	createDurableSubscription() Uses the <durableSubscriptionID>, <clientID>, <generateUniqueClientID>, and <deleteSubscriptionOnClose> JMSClientConfiguration elements to create a durable subscription, as follows: <durableSubscriptionID> is required. Either <clientID> or <generateUniqueClientID> must be configured. If <clientID> is set, then it's value is used as the JMS ClientID for the connection.
javax.jms.Connection	getConnection() Returns the JMS Connection for this JMS client.
javax.jms.Destination	getDestination() Returns the JMS Destination for this JMS client.
java.lang.String	getDestinationName() Returns the name of the JMS Destination for this JMS client.
protected void	logConsumerStartupMessage() Logs a JMS startup message for JMS consumers.
protected void	logMessage(java.lang.String logMessage) Log the message.
static void	main(java.lang.String[] args) main() -- for testing
javax.jms.Message	receiveJMSMessage() Receive a JMS Message using the configured Topic; waits for a message indefinitely.
javax.jms.Message	receiveJMSMessage(long receiveTimeoutMilliseconds, java.lang.String messageSelector) Receive a JMS Message using the configured Topic.
void	removeDurableSubscription()
protected javax.jms.Message	retryReceiveJMSMessage(long receiveTimeoutMilliseconds, java.lang.String messageSelector) Retry receiving a message using the configured Topic.
void	startJMS() Initialize JMS objects according to JMSClientConfiguration and start the connection.

Methods inherited from class org.osesb.connectors.jms.JMSConsumerBase

checkJMSConnection, consumerStartupMessage, finalize, getDateTimeOfLastMessage, getDateTimeServiceStarted, getHeartbeatInterval, getJMSClientConfiguration, getNumberOfMessagesReceived, getSession, isConnectionStarted, onException, onMessage, run, setNumberOfMessagesReceived, setSession

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

topicConnection

protected javax.jms.TopicConnection topicConnection

The TopicConnection for this JMS client.

topicSession

protected javax.jms.TopicSession topicSession

The TopicSession for this JMS client.

topic

protected javax.jms.Topic topic

The Topic for this JMS client.

Constructor Detail

JMSTopicReceiver

public JMSTopicReceiver(JMSClientConfiguration jmsClientConfiguration)
                 throws java.lang.Exception

Creates a new instance of JMSTopicReceiver and starts JMS.

Parameters:

jmsClientConfiguration - The JMSClientConfiguration object to use for this JMS client.

Throws:

java.lang.Exception - if constructed with a null JMSClientConfiguration.

JMSTopicReceiver

public JMSTopicReceiver(JMSClientConfiguration jmsClientConfiguration,
                        javax.jms.Topic topic)
                 throws java.lang.Exception

Creates a new instance of JMSTopicReceiver and starts JMS using the specified Topic. This constructor is used by synchronous senders, where the replyTo Destination is configured in the portion of the JMSClientConfiguration.

Parameters:

jmsClientConfiguration - The JMSClientConfiguration object to use for this JMS client.

topic - The Topic to start the JMS connection for.

Throws:

java.lang.Exception - if constructed with a null JMSClientConfiguration.

Method Detail

createDurableSubscription

public void createDurableSubscription()
                               throws java.lang.Exception

Uses the <durableSubscriptionID>, <clientID>, <generateUniqueClientID>, and <deleteSubscriptionOnClose> JMSClientConfiguration elements to create a durable subscription, as follows:

• <durableSubscriptionID> is required.
• Either <clientID> or <generateUniqueClientID> must be configured.
• If <clientID> is set, then it's value is used as the JMS ClientID for the connection. <clientID> takes precedence over <generateUniqueClientID>.
• If <generateUniqueClientID> is true and <clientID> is not set, then a unique JMS ClientID is set for the connection. If a unique JMS ClientID is configured for the connection, then the subscription is automatically removed (deleted) when the connection is closed.

createDurableSubscription() is provided to account for situations where a durable subscription needs to be created prior to to invoking receiveJMSMessage(); that is under circumstances where messages are published to the configured Topic before a TopicSubscriber is created by receiveJMSMessage(). For example, consider the situation where messages are published to a Topic and receiveJMSMessage() will be invoked with a 'messageSelector' set to the JMSCorrelationID of the published message. If this, or a similar situation is not the case, then there is no need to invoke createDurableSubscription() prior to calling receiveJMSMessage().

Throws:

java.lang.Exception - if a durable subscription cannot be created.

removeDurableSubscription

public void removeDurableSubscription()
                               throws java.lang.Exception

Throws:

java.lang.Exception - if a durable subscription cannot be removed.

receiveJMSMessage

public javax.jms.Message receiveJMSMessage()
                                    throws java.lang.Exception

Receive a JMS Message using the configured Topic; waits for a message indefinitely.

Specified by:

receiveJMSMessage in class JMSConsumerBase

Returns:

the Message that was received.

Throws:

java.lang.Exception - if a general is error encountered.

receiveJMSMessage

public javax.jms.Message receiveJMSMessage(long receiveTimeoutMilliseconds,
                                           java.lang.String messageSelector)
                                    throws java.lang.Exception

Receive a JMS Message using the configured Topic.

Specified by:

receiveJMSMessage in class JMSConsumerBase

Parameters:

receiveTimeoutMilliseconds - receive timeout in milliseconds. If receiveTimeout > 0, then the receiver waits for a message for the specified amount of time, otherwise, the receiver waits for a message indefinitely.

messageSelector - The JMS messageSelector.

Returns:

the Message that was received.

Throws:

java.lang.Exception - if a general is error encountered.

retryReceiveJMSMessage

protected javax.jms.Message retryReceiveJMSMessage(long receiveTimeoutMilliseconds,
                                                   java.lang.String messageSelector)
                                            throws java.lang.Exception

Retry receiving a message using the configured Topic.

Parameters:

receiveTimeoutMilliseconds - receive timeout in milliseconds. If receiveTimeout > 0, then the receiver waits for a message for the specified amount of time, otherwise, the receiver waits for a message indefinitely.

messageSelector - The JMS messageSelector.

Returns:

the Message that was received.

Throws:

java.lang.Exception - if a general is error encountered.

getDestinationName

public java.lang.String getDestinationName()

Returns the name of the JMS Destination for this JMS client.

Specified by:

getDestinationName in class JMSConsumerBase

Returns:

the name of the JMS Destination for this JMS client.

getConnection

public javax.jms.Connection getConnection()

Returns the JMS Connection for this JMS client.

Specified by:

getConnection in class JMSConsumerBase

Returns:

the JMS Connection for this JMS client.

getDestination

public javax.jms.Destination getDestination()

Returns the JMS Destination for this JMS client.

Specified by:

getDestination in class JMSConsumerBase

Returns:

the JMS Destination for this JMS client.

logMessage

protected void logMessage(java.lang.String logMessage)

Log the message. Override this method to log differently.

Overrides:

logMessage in class JMSConsumerBase

Parameters:

logMessage - The message to log.

startJMS

public void startJMS()

Initialize JMS objects according to JMSClientConfiguration and start the connection.

Specified by:

startJMS in class JMSConsumerBase

logConsumerStartupMessage

protected void logConsumerStartupMessage()

Logs a JMS startup message for JMS consumers.

checkSession

protected void checkSession()
                     throws java.lang.Exception

Checks the TopicSession and restarts JMS connection, if required.

Specified by:

checkSession in class JMSConsumerBase

Throws:

java.lang.Exception - if there was a problem getting a TopicSession.

close

public void close()

Release JMS resources.

Specified by:

close in class JMSConsumerBase

main

public static void main(java.lang.String[] args)

main() -- for testing

Parameters:

args - commandline arguments