org.openeai.jms.consumer
Class PointToPointConsumer

java.lang.Object
  org.openeai.OpenEaiObject
      org.openeai.jms.consumer.MessageConsumer
          org.openeai.jms.consumer.PointToPointConsumer

public class PointToPointConsumer
extends MessageConsumer

This consumer consumes messages from a JMS Queue. Then based on the content of the message it executes commands associated to the consumer and the message consumed as specified in it's configuration document (deployment descriptor).

If the JMSReplyTo property of the consumed message contains data (i.e. - the Queue to which replies should be sent), it will execute a 'RequestCommand' and return it's response to the calling application. Otherwise, it will execute a 'SyncCommand'.

The actual business logic related to the message consumed is performed by the Request/Sync command implementations.

Version:

3.0 - 4 February 2003

Author:

Tod Jackson (tod@openeai.org), Steve Wheat (steve@openeai.org)

Nested Class Summary

protected class	PointToPointConsumer.ConsumerShutdownHook This Thread will be started when the consumer receives a shutdown signal from the os.
protected class	PointToPointConsumer.MonitorConsumer This Thread will sleep for a specified period of time and then wake up and check the status of the consumer by attempting to create/delete a TemporaryQueue.
protected class	PointToPointConsumer.MyQueueListener This is the JMS MessageListener implementation for OpenEAI PointToPointConsumers.
protected class	PointToPointConsumer.RequestTransaction This is the class that is used to execute the RequestCommand associated to a message consumed by the Consumer.

Nested classes/interfaces inherited from class org.openeai.jms.consumer.MessageConsumer

MessageConsumer.MessageTransaction

Field Summary

Fields inherited from class org.openeai.jms.consumer.MessageConsumer

_maxThreadPoolShutdownWaitTime, CONNECTED, DISCONNECTED, INITIALIZED, m_commandConfigs, m_inProcessMessages, m_messages, m_numThreads, m_password, m_startOnInitialization, m_threadPool, m_userName, NOT_INITIALIZED, STARTED, STOPPED

Fields inherited from class org.openeai.OpenEaiObject

logger

Constructor Summary

PointToPointConsumer()

PointToPointConsumer(ConsumerConfig cConfig)
As AppConfig reads through a gateway's deployment document, it will build a ConsumerConfig Java object and pass that object to this constructor.

PointToPointConsumer(java.lang.String cFactory, java.lang.String qName)

Method Summary

void	addRequestCommand(java.lang.String requestName, java.lang.String className) Adds an initialized RequestCommand object to the list of RequestCommands that might be executed by this Consumer.
javax.jms.Queue	getQueue() Returns the Consumer's Queue object.
javax.jms.QueueConnection	getQueueConnection() Returns the Consumer's QueueConnection object.
javax.jms.QueueConnectionFactory	getQueueConnectionFactory() Returns the Consumer's QueueConnectionFactory object.
javax.jms.QueueReceiver	getQueueReceiver() Returns the Consumer's QueueReceiver object.
javax.jms.QueueSession	getQueueSession() Returns the Consumer's QueueSession object.
protected RequestCommand	getRequestCommand(java.lang.String commandName) Returns a RequestCommand from the HashMap of RequestCommands supported by this Consumer.
protected javax.jms.Message	handleRequest(int messageNumber, javax.jms.Message aMessage) RequestCommand execution routine.
protected void	init(java.util.Properties props) Invokes MessageConsumer.init(Properties) and adds the ConsumerShutDownHook for this consumer.
void	initializeConsumer() Calls the MessageConsumer initializeConsumer method to initialize any SyncCommands that this consumer may need to execute, then it initializes all RequestCommands associated to this consumer.
protected void	initRequestCommands() Iterates through all RequestCommands that were listed in the CommandConfig objects associated to this Consumer in its deployment document and instantiates those RequestCommands by calling the addRequestCommand method.
void	setQueue(javax.jms.Queue queue) Sets the Consumer's Queue object.
void	setQueueConnection(javax.jms.QueueConnection queueConnection) Sets the Consumer's QueueConnection object.
void	setQueueConnectionFactory(javax.jms.QueueConnectionFactory qcf) Sets the Consumer's QueueConnectionFactory object.
void	setQueueReceiver(javax.jms.QueueReceiver queueReceiver) Sets the Consumer's QueueReceiver object.
void	setQueueSession(javax.jms.QueueSession session) Sets the Consumer's QueueSession object.
void	shutdownCommands() Shuts down all commands executed by this consumer.
void	startConsumer() Starts the consumer making it ready to consume messages from the Queue that it connects to.
void	startMonitor() This method starts the Consumer's "Monitor Thread".
void	stop() This method should process any pending jobs that are currently in progress and then disconnect this Consumer from the broker.
void	stopConsumer() Attempts to cleanly shutdown the Consumer.
void	stopMonitor() This method stops the Consumer's "Monitor Thread" so it won't attempt to restart the consumer.

Methods inherited from class org.openeai.jms.consumer.MessageConsumer

addCommandConfig, addSyncCommand, consumptionStopped, getAbsoluteCommandName, getCommandConfig, getConfig, getConnectionFactoryName, getConsumerName, getConsumerStatus, getDefaultCommandName, getDestinationName, getGenericErrorDoc, getInitialContext, getInitialContextFactory, getInitializationStatus, getInstanceName, getMaximumThreadPoolShutdownWaitTime, getPassword, getProviderUrl, getSecurityCredentials, getSecurityPrincipal, getStartOnInitialization, getSyncCommand, getThreadPool, getTransacted, getUserName, handleSync, initSyncCommands, isStarted, setAbsoluteCommandName, setCommandConfigs, setConfig, setConnectionFactoryName, setConsumerName, setConsumerStatus, setDefaultCommandName, setDestinationName, setGenericErrorDoc, setInitialContextFactory, setInitializationStatus, setInstanceName, setMaximumThreadPoolShutdownWaitTime, setPassword, setProviderUrl, setSecurityCredentials, setSecurityPrincipal, setStartOnInitialization, setThreadPool, setTransacted, setUserName, stopConsumption

Methods inherited from class org.openeai.OpenEaiObject

getAppName, getDebug, getFromAddr, getMailHost, getMailService, getProperties, getToAddr, initializeLog4j, initializeLog4j, initializeLog4j, setAppName, setDebug, setFromAddr, setMailHost, setMailService, setProperties, setToAddr

Methods inherited from class java.lang.Object

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

Constructor Detail

PointToPointConsumer

public PointToPointConsumer()

PointToPointConsumer

public PointToPointConsumer(java.lang.String cFactory,
                            java.lang.String qName)

PointToPointConsumer

public PointToPointConsumer(ConsumerConfig cConfig)
                     throws javax.jms.JMSException,
                            javax.naming.NamingException,
                            java.io.IOException

As AppConfig reads through a gateway's deployment document, it will build a ConsumerConfig Java object and pass that object to this constructor. Then this consumer will have all the information it needs to initialize itself which includes:

• Initializing the consumer itself
• Initializing all Commands that the consumer may execute

  Parameters:

  cConfig - org.openeai.config.ConsumerConfig

  Throws:

  javax.jms.JMSException

  javax.naming.NamingException

  java.io.IOException

  See Also:

  ConsumerConfig

Method Detail

stopMonitor

public void stopMonitor()

This method stops the Consumer's "Monitor Thread" so it won't attempt to restart the consumer.

When the consumer is started it starts a Thread that monitors the Consumer's connection to the broker. If that connection is broken for some reason, that "Monitor Thread" will attempt to restart the consumer. This continues indefinitely until the consumer is able to re-connect to the broker.

This method allows an application to in effect stop that monitor thread so they can shut the consumer down without it restarting itself.

startMonitor

public void startMonitor()

This method starts the Consumer's "Monitor Thread". This is a thread that runs for the life of the consumer and checks the status of the consumer's connection to the broker every thirty seconds. If that connection is broken for some reason, the Monitor Thread will attempt to restart the consumer, re-connecting it to the broker. It will continue to do this until either the consumer is able to re-connect or the consumer is shutdown.

getQueueConnectionFactory

public javax.jms.QueueConnectionFactory getQueueConnectionFactory()

Returns the Consumer's QueueConnectionFactory object.

See the JMS Specification to learn more about JMS objects.

Returns:

javax.jms.QueueConnectionFactory

setQueueConnectionFactory

public void setQueueConnectionFactory(javax.jms.QueueConnectionFactory qcf)

Sets the Consumer's QueueConnectionFactory object.

See the JMS Specification to learn more about JMS objects.

Parameters:

qcf - javax.jms.QueueConnectionFactory

getQueue

public javax.jms.Queue getQueue()

Returns the Consumer's Queue object.

See the JMS Specification to learn more about JMS objects.

Returns:

javax.jms.Queue

setQueue

public void setQueue(javax.jms.Queue queue)

Sets the Consumer's Queue object.

See the JMS Specification to learn more about JMS objects.

Parameters:

queue - javax.jms.Queue

getQueueConnection

public javax.jms.QueueConnection getQueueConnection()

Returns the Consumer's QueueConnection object.

See the JMS Specification to learn more about JMS objects.

Returns:

javax.jms.QueueConnection

setQueueConnection

public void setQueueConnection(javax.jms.QueueConnection queueConnection)

Sets the Consumer's QueueConnection object.

See the JMS Specification to learn more about JMS objects.

Parameters:

queueConnection - javax.jms.QueueConnection

getQueueSession

public javax.jms.QueueSession getQueueSession()

Returns the Consumer's QueueSession object.

See the JMS Specification to learn more about JMS objects.

Returns:

javax.jms.QueueSession

setQueueSession

public void setQueueSession(javax.jms.QueueSession session)

Sets the Consumer's QueueSession object.

See the JMS Specification to learn more about JMS objects.

Parameters:

session - javax.jms.QueueSession

getQueueReceiver

public javax.jms.QueueReceiver getQueueReceiver()

Returns the Consumer's QueueReceiver object.

See the JMS Specification to learn more about JMS objects.

Returns:

javax.jms.QueueReceiver

setQueueReceiver

public void setQueueReceiver(javax.jms.QueueReceiver queueReceiver)

Sets the Consumer's QueueReceiver object.

See the JMS Specification to learn more about JMS objects.

Parameters:

queueReceiver - javax.jms.QueueReceiver

initializeConsumer

public void initializeConsumer()
                        throws javax.jms.JMSException

Calls the MessageConsumer initializeConsumer method to initialize any SyncCommands that this consumer may need to execute, then it initializes all RequestCommands associated to this consumer. Since this is a PointToPointConsumer, messages may be sent to this consumer that expect a response.

Overrides:

initializeConsumer in class MessageConsumer

Throws:

javax.jms.JMSException - if any errors occur initializing any of the Sync or Request commands.

See Also:

MessageConsumer.initSyncCommands(), initializeConsumer()

addRequestCommand

public void addRequestCommand(java.lang.String requestName,
                              java.lang.String className)
                       throws javax.jms.JMSException

Adds an initialized RequestCommand object to the list of RequestCommands that might be executed by this Consumer. Uses the className and CommandConfig object associated to the commandName paramater passed in to instantiate the command. Then, it adds that initialized command to this Consumer's HashMap of RequestCommands that might be executed by this PointToPointConsumer. Therefore, the command itself is only intantiated and initialized once, then, its exeucte method is called whenever this consumer determines that a message it consumed is to be processed by that command.

It is here that the determination is made wether or not the command is the "default" or "absolute" command based on information found in the CommandConfig object associated to the Command.

Parameters:

requestName - String name of the command

className - String class name of the command that should be instantiated and initialized as specified in the CommandConfig Element/Java object

Throws:

javax.jms.JMSException

See Also:

CommandConfig, ConsumerConfig, ConsumerCommand, RequestCommand, RequestCommandImpl, SyncCommand, SyncCommandImpl

initRequestCommands

protected void initRequestCommands()
                            throws javax.jms.JMSException

Iterates through all RequestCommands that were listed in the CommandConfig objects associated to this Consumer in its deployment document and instantiates those RequestCommands by calling the addRequestCommand method.

Throws:

javax.jms.JMSException - if errors occur initializing the SyncCommands

See Also:

addRequestCommand(String, String)

getRequestCommand

protected RequestCommand getRequestCommand(java.lang.String commandName)
                                    throws java.io.IOException

Returns a RequestCommand from the HashMap of RequestCommands supported by this Consumer. This method looks for the RequestCommand with a name matching the name passed in and returns it. This will be an initialized command that is ready to be executed. The consumer will call this method when it consumes a message and determines that there is an expected reply.

It will use the "COMMAND_NAME" JMS Property from the message to retrieve that RequestCommand from its list.

Parameters:

commandName - String the name of the RequestCommand to find (COMMAND_NAME property on the JMS Message)

Returns:

RequestCommand the RequestCommand that matches the name passed in and should be executed.

Throws:

java.io.IOException - if a RequestCommand with the specified name cannot be found.

handleRequest

protected javax.jms.Message handleRequest(int messageNumber,
                                          javax.jms.Message aMessage)
                                   throws javax.jms.JMSException

RequestCommand execution routine. This method is called by the RequestTransaction's run method and is used to actually execute the RequestCommand associated to the message consumed.

The method will look for a JMS String property called "COMMAND_NAME" on the Message passed in. If the property is found, it will execute the RequestCommand associated to that name and return the output from that execution.

This property is automatically set by the OpenEAI Message Object API (MOA) foundation when a message is sent using an organization's MOA implementation (a business object).

If an "Absolute" command has been associated to the consumer, it will execute that command implementation NO MATTER what.

If no COMMAND_NAME is found on the Message passed in and there has been a "Default" command associated to the consumer, it will execute that command implementation.

If no COMMAND_NAME property exists and there has been no "Default" or "Absolute" command associated to this consumer, an error will occur.

If a COMMAND_NAME property DOES exist but it doesn't map to a known command implementation and no "Absolute" command has been specified, an error will occur.

Parameters:

messageNumber - int a message number managed by the consumer (the number of messages consumed by the consumer).

aMessage - Message the JMS Message consumed by the consumer.

Returns:

Message the output from the call to #org.openeai.jms.consumer.commands.RequestCommand.execute(int, Message)

Throws:

javax.jms.JMSException - if errors occur executing the Command. Note, this should be a very rare occurrence because Commands are generally responsible for handling their own errors. The most common place where an exception might be thrown by a command is if it had problems retrieving the data from the Message passed to it. Otherwise, the Command should either publish a Sync-Error or return an Error to the requesting application depending on the type of command being executed (RequestCommand vs. SyncCommand)

init

protected void init(java.util.Properties props)
             throws java.io.IOException

Invokes MessageConsumer.init(Properties) and adds the ConsumerShutDownHook for this consumer.

Overrides:

init in class MessageConsumer

Parameters:

props - Properties

Throws:

java.io.IOException

See Also:

MessageConsumer.init(Properties)

startConsumer

public void startConsumer()
                   throws javax.jms.JMSException,
                          javax.naming.NamingException

Starts the consumer making it ready to consume messages from the Queue that it connects to. This follows the typical JMS pattern of starting a message consumer. This includes:

• Retrieving the JMS Administered objects (QueueConnectionFactory and Queue) from a directory server or other JNDI source
• Creating a QueueConnection with the QueueConnectionFactory
• Creating a QueueSession with the QueueConnection
• Creating a QueueReceiver with the QueueSession and Queue
• Establishing the MessageListener that will be used when messages are delivered to the Queue.

Additionally, this method starts the Consumer's Monitor that will monitor and attempt to resolve any broker connection issues encountered for the life of the Consumer.

Throws:

javax.jms.JMSException

javax.naming.NamingException

See Also:

PubSubConsumer.startConsumer(), PointToPointConsumer.MonitorConsumer

stop

public void stop()

Description copied from class: MessageConsumer

This method should process any pending jobs that are currently in progress and then disconnect this Consumer from the broker. It is implemented by PointToPoint and PubSub consumers.

Specified by:

stop in class MessageConsumer

stopConsumer

public void stopConsumer()

Attempts to cleanly shutdown the Consumer. This includes closing all JMS resources (QueueReceiver, QueueSession and QueueConnection). If errors occur, it will log those errors as warnings. However, regardless of the outcome of the "clean" shutdown attempt, the consumer will be stopped. This method is called anytime the consumer detects connection problems to the broker or when the consumer receives a shutdown hook from the operating system.

See Also:

PointToPointConsumer.MonitorConsumer, PointToPointConsumer.ConsumerShutdownHook

shutdownCommands

public void shutdownCommands()

Shuts down all commands executed by this consumer.