org.openeai.jms.consumer
Class MessageConsumer

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

Direct Known Subclasses:

PointToPointConsumer, PubSubConsumer

public abstract class MessageConsumer
extends OpenEaiObject

The ancestor class for PubSub and PointToPoint consumers. These are the counterparts to OpenEAI MessageProducers. These classes (PubSub and PointToPoint Consumers) consume and potentially respond to messages sent by OpenEAI MessageProducers (PointToPoint and PubSub Producers)

Version:

3.0 - 28 January 2003

Author:

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

See Also:

ConsumerConfig, MessageProducer

Nested Class Summary

protected class

MessageConsumer.MessageTransaction This is the class that is used to execute the SyncCommand associated to a message consumed by the Consumer.

Field Summary

protected int	_maxThreadPoolShutdownWaitTime
protected static java.lang.String	CONNECTED
protected static java.lang.String	DISCONNECTED
protected static java.lang.String	INITIALIZED
protected java.util.HashMap	m_commandConfigs
protected java.util.Vector	m_inProcessMessages
protected java.util.HashMap	m_messages
protected int	m_numThreads
protected java.lang.String	m_password
protected boolean	m_startOnInitialization
protected ThreadPool	m_threadPool
protected java.lang.String	m_userName
protected static java.lang.String	NOT_INITIALIZED
protected static java.lang.String	STARTED
protected static java.lang.String	STOPPED

Fields inherited from class org.openeai.OpenEaiObject

logger

Constructor Summary

MessageConsumer()

Method Summary

void	addCommandConfig(java.lang.String name, CommandConfig cConfig) Adds a CommandConfig Java object to the list of Commands associated to this consumer.
void	addSyncCommand(java.lang.String commandName, java.lang.String className) Adds an initialized SyncCommand object to the list of SyncCommands that might be executed by this Consumer.
boolean	consumptionStopped() This is the method each consumer calls whenever they consume a message to see if they can continue to consume messages.
java.lang.String	getAbsoluteCommandName() Returns the name of the Absolute command that should be executed by this consumer NO MATTER what the COMMAND_NAME JMS Property might be.
CommandConfig	getCommandConfig(java.lang.String name) Returns a CommandConfig Java object from the list of ConsumerCommands associated to this consumer by name.
ConsumerConfig	getConfig() Returns the ConsumerConfig object associated to this Consumer.
java.lang.String	getConnectionFactoryName() Returns the connection factory name (QueueConnectionFactory or TopicConnectionFactory) that this Consumer should retrieve and use to initialize its connection to the broker with.
java.lang.String	getConsumerName() Returns the name of this consumer as specified in the Consumer's configuration information.
java.lang.String	getConsumerStatus() Returns the current status of the Consumer.
java.lang.String	getDefaultCommandName() Returns the name of the Default command that should be executed if a Message consumed does not have a COMMAND_NAME JMS Property associated to it.
java.lang.String	getDestinationName() Returns the destination name (Queue or Topic) that this Consumer should connect to and consume from.
org.jdom.Document	getGenericErrorDoc() Returns the generic response document that this consumer should use to reply to incomming requests if it has problems executing the command associated to the request consumed.
protected javax.naming.directory.DirContext	getInitialContext() Establishes an InitialContext to be used by the calling application to retrieve ConnectionFactories and Destination objects via JNDI.
java.lang.String	getInitialContextFactory() Returns the class name of the JNDI context factory that will be used to retrieve the JMS administered objects from a Directory Server or wherever the administered objects are stored.
java.lang.String	getInitializationStatus() Returns the initialization status of the consumer.
java.lang.String	getInstanceName() Returns the instance name of this consumer.
int	getMaximumThreadPoolShutdownWaitTime() Returns the maximum amount of time the consumer will wait for the thread pool to empty itself.
java.lang.String	getPassword() Returns the broker user password that should be used when establishing a connection with the broker.
java.lang.String	getProviderUrl() Returns the location where the administered objects can be retrieved from.
java.lang.String	getSecurityCredentials() Returns the LDAP security credentials (password) this consumer should use when connecting to the directory server to retrieve JMS administered objects (ConnectionFactories and Destinations).
java.lang.String	getSecurityPrincipal() Returns the LDAP security principal this consumer should use when connecting to the directory server to retrieve JMS administered objects (ConnectionFactories and Destinations).
boolean	getStartOnInitialization() Returns a boolean indicating whether or not this consumer should be started (connected to the broker and ready to consume messages) when it is initialized.
protected SyncCommand	getSyncCommand(java.lang.String commandName) Returns a SyncCommand from the HashMap of SyncCommands supported by this Consumer.
ThreadPool	getThreadPool() Returns the ThreadPool object that will be used by this Consumer to execute ConsumerCommands in.
boolean	getTransacted() Returns the JMS property indicating whether or not this consumer operates in transacted mode or not.
java.lang.String	getUserName() Returns the broker user name that should be used when establishing a connection with the broker.
protected void	handleSync(int messageNumber, javax.jms.Message aMessage) Default SyncCommand execution routine.
protected void	init(java.util.Properties props) Takes the Properties object contained within the ConsumerConfig object passed to the constructor of this consumer and sets all the appropriate instance variables on this consumer during initialization.
void	initializeConsumer() Calls the initSyncCommands() method that will retrieve all SyncCommands from the ConsumerConfig object passed to the constructor and initialize those commands making them available for use.
protected void	initSyncCommands() Iterates through all SyncCommands that were listed in the CommandConfig objects associated to this Consumer in its deployment document and instantiates those SyncCommands by calling the addSyncCommand method.
boolean	isStarted() Returns a boolean that indicates whether or not the consumer is started.
void	setAbsoluteCommandName(java.lang.String name) Sets the name of the Absolute command that should be executed by this consumer NO MATTER what the COMMAND_NAME JMS Property might be.
void	setCommandConfigs(java.util.HashMap cConfigs) Sets the HashMap of CommandConfigs to the value passed in.
void	setConfig(ConsumerConfig config) Sets the ConsumerConfig object associated to this Consumer.
void	setConnectionFactoryName(java.lang.String name) Sets the connection factory name (QueueConnectionFactory or TopicConnectionFactory) that this Consumer should retrieve and use to initialize its connection to the broker with.
void	setConsumerName(java.lang.String name) Sets the name of this consumer as specified in the Consumer's configuration information.
void	setConsumerStatus(java.lang.String status) Sets the current status of the Consumer.
void	setDefaultCommandName(java.lang.String name) Sets the name of the Default command that should be executed if a Message consumed does not have a COMMAND_NAME JMS Property associated to it.
void	setDestinationName(java.lang.String name) Sets the destination name (Queue or Topic) that this Consumer should connect to and consume from.
void	setGenericErrorDoc(org.jdom.Document doc) Sets the generic response document that this consumer should use to reply to incomming requests if it has problems executing the command associated to the request consumed.
void	setInitialContextFactory(java.lang.String in) Sets the class name of the JNDI context factory that will be used to retrieve the JMS administered objects from a Directory Server or wherever the administered objects are stored.
void	setInitializationStatus(java.lang.String status) Sets the initialization status of the consumer.
void	setInstanceName(java.lang.String instanceName) Sets the instance name of this consumer.
void	setMaximumThreadPoolShutdownWaitTime(int maxWaitTime) Sets the maximum amount of time (in milliseconds) that the consumer will wait for the ThreadPool to empty when the consumer's shutdown hook is triggered.
void	setPassword(java.lang.String in) Sets the broker user password that should be used when establishing a connection with the broker.
void	setProviderUrl(java.lang.String in) Sets the location where the administered objects can be retrieved from.
void	setSecurityCredentials(java.lang.String credentials) Sets the LDAP security credentials (password) this consumer should use when connecting to the directory server to retrieve JMS administered objects (ConnectionFactories and Destinations).
void	setSecurityPrincipal(java.lang.String principal) Sets the LDAP security principal this consumer should use when connecting to the directory server to retrieve JMS administered objects (ConnectionFactories and Destinations).
void	setStartOnInitialization(boolean start) Sets a boolean indicating whether or not this consumer should be started (connected to the broker and ready to consume messages) when it is initialized.
void	setThreadPool(ThreadPool tPool) Sets the ThreadPool object that will be used by this Consumer to execute ConsumerCommands in.
void	setTransacted(boolean trans) Sets the JMS property indicating whether or not this consumer operates in transacted mode or not.
void	setUserName(java.lang.String in) Sets the broker user name that should be used when establishing a connection with the broker.
abstract void	stop() This method should process any pending jobs that are currently in progress and then disconnect this Consumer from the broker.
void	stopConsumption() Puts the consumer in a state that will prohibit it from consuming any more messages.

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

Field Detail

m_messages

protected java.util.HashMap m_messages

m_userName

protected java.lang.String m_userName

m_password

protected java.lang.String m_password

m_commandConfigs

protected java.util.HashMap m_commandConfigs

STOPPED

protected static java.lang.String STOPPED

STARTED

protected static java.lang.String STARTED

DISCONNECTED

protected static java.lang.String DISCONNECTED

CONNECTED

protected static java.lang.String CONNECTED

NOT_INITIALIZED

protected static java.lang.String NOT_INITIALIZED

INITIALIZED

protected static java.lang.String INITIALIZED

m_threadPool

protected ThreadPool m_threadPool

m_numThreads

protected int m_numThreads

_maxThreadPoolShutdownWaitTime

protected int _maxThreadPoolShutdownWaitTime

m_startOnInitialization

protected boolean m_startOnInitialization

m_inProcessMessages

protected java.util.Vector m_inProcessMessages

Constructor Detail

MessageConsumer

public MessageConsumer()

Method Detail

setMaximumThreadPoolShutdownWaitTime

public final void setMaximumThreadPoolShutdownWaitTime(int maxWaitTime)

Sets the maximum amount of time (in milliseconds) that the consumer will wait for the ThreadPool to empty when the consumer's shutdown hook is triggered. This is to avoid situations where a command or commands get themselves stuck in a state where they will never return. Without a hard timeout like this, the application would never be allowed to completely shutdown because it would wait on the commands to complete indefinitely.

The default value for this is 15000 (15 seconds).

Parameters:

maxWaitTime -

getMaximumThreadPoolShutdownWaitTime

public final int getMaximumThreadPoolShutdownWaitTime()

Returns the maximum amount of time the consumer will wait for the thread pool to empty itself.

Returns:

the maximum time the consumer will wait for the thread pool to empty.

setDefaultCommandName

public final void setDefaultCommandName(java.lang.String name)

Sets the name of the Default command that should be executed if a Message consumed does not have a COMMAND_NAME JMS Property associated to it. This is determined as the consumer initializes the commands associated to it during consumer intiailization. Note: this is not applicable if a command is designated as the "absolute" command.

Parameters:

name - String name of the default command as specified in the Command's configuration object in the gateway's deployment document.

See Also:

CommandConfig.isDefault()

getDefaultCommandName

public final java.lang.String getDefaultCommandName()

Returns the name of the Default command that should be executed if a Message consumed does not have a COMMAND_NAME JMS Property associated to it. This is determined as the consumer initializes the commands associated to it during consumer intiailization. Note: this is not applicable if a command is designated as the "absolute" command.

Returns:

String name of the default command as specified in the Command's configuration object in the gateway's deployment document.

See Also:

CommandConfig.isDefault()

setAbsoluteCommandName

public final void setAbsoluteCommandName(java.lang.String name)

Sets the name of the Absolute command that should be executed by this consumer NO MATTER what the COMMAND_NAME JMS Property might be. This means no matter what message the consumer consumes, it will execute the command that has this name. This is determined as the consumer initializes the commands associated to it during consumer intiailization.

Parameters:

name - String name of the absolute command as specified in the Command's configuration object in the gateway's deployment document.

See Also:

CommandConfig.isAbsolute()

getAbsoluteCommandName

public final java.lang.String getAbsoluteCommandName()

Returns the name of the Absolute command that should be executed by this consumer NO MATTER what the COMMAND_NAME JMS Property might be. This means no matter what message the consumer consumes, it will execute the command that has this name. This is determined as the consumer initializes the commands associated to it during consumer intiailization.

Returns:

String name of the absolute command as specified in the Command's configuration object in the gateway's deployment document.

See Also:

CommandConfig.isAbsolute()

setConsumerName

public final void setConsumerName(java.lang.String name)

Sets the name of this consumer as specified in the Consumer's configuration information.

Parameters:

name - String name of the consumer.

getConsumerName

public final java.lang.String getConsumerName()

Returns the name of this consumer as specified in the Consumer's configuration information.

Returns:

String name of the consumer.

getInstanceName

public final java.lang.String getInstanceName()

Returns the instance name of this consumer. This is used when establishing durable subscriptions.

Returns:

String the consumer's instance name.

setInstanceName

public final void setInstanceName(java.lang.String instanceName)

Sets the instance name of this consumer. This is used when establishing durable subscriptions. This is specified in the gateway's property file (NOT the gateway deployment XML document) and is automatically set by AppConfig as it starts the consumer.

Parameters:

instanceName - String the consumer's instance name.

setSecurityPrincipal

public final void setSecurityPrincipal(java.lang.String principal)

Sets the LDAP security principal this consumer should use when connecting to the directory server to retrieve JMS administered objects (ConnectionFactories and Destinations). This is specified in the Consumer's configuration element (ConsumerConfig).

Parameters:

principal - String the LDAP principal

See Also:

ConsumerConfig

getSecurityPrincipal

public final java.lang.String getSecurityPrincipal()

Returns the LDAP security principal this consumer should use when connecting to the directory server to retrieve JMS administered objects (ConnectionFactories and Destinations). This is specified in the Consumer's configuration element (ConsumerConfig).

Returns:

String the LDAP principal

See Also:

ConsumerConfig

setSecurityCredentials

public final void setSecurityCredentials(java.lang.String credentials)

Sets the LDAP security credentials (password) this consumer should use when connecting to the directory server to retrieve JMS administered objects (ConnectionFactories and Destinations). This is specified in the Consumer's configuration element (ConsumerConfig).

Parameters:

credentials - String the LDAP credentials

See Also:

ConsumerConfig

getSecurityCredentials

public final java.lang.String getSecurityCredentials()

Returns the LDAP security credentials (password) this consumer should use when connecting to the directory server to retrieve JMS administered objects (ConnectionFactories and Destinations). This is specified in the Consumer's configuration element (ConsumerConfig).

Returns:

String the LDAP credentials

See Also:

ConsumerConfig

setGenericErrorDoc

public final void setGenericErrorDoc(org.jdom.Document doc)

Sets the generic response document that this consumer should use to reply to incomming requests if it has problems executing the command associated to the request consumed.

Parameters:

doc - org.jdom.Document

See Also:

ConsumerConfig

getGenericErrorDoc

public final org.jdom.Document getGenericErrorDoc()

Returns the generic response document that this consumer should use to reply to incomming requests if it has problems executing the command associated to the request consumed.

Returns:

org.jdom.Document

See Also:

ConsumerConfig

getConsumerStatus

public final java.lang.String getConsumerStatus()

Returns the current status of the Consumer. Consumers can be in several different status as they are used. Most common, the statuses are either STOPPED or STARTED.

Returns:

String the status of the consumer.

setConsumerStatus

public final void setConsumerStatus(java.lang.String status)

Sets the current status of the Consumer. Consumers can be in several different status as they are used. Most common, the statuses are either STOPPED or STARTED. The status is set by the consumer as it initializes itself and when it is shutdown.

Parameters:

status - String the status of the consumer.

isStarted

public final boolean isStarted()

Returns a boolean that indicates whether or not the consumer is started. This is determined based on the status of the consumer (STARTED or STOPPED).

Returns:

boolean true=consumer is started, false=consumer is not started.

stopConsumption

public final void stopConsumption()

Puts the consumer in a state that will prohibit it from consuming any more messages. Both PubSub and PointToPoint consumers check to see if consumption has been stopped each time they consume a message. If consumption has been stopped, they do not exit out of their 'onMessage' method. This in affect stops message consumption for the consumer. Then the shutdown hook facility looks for any pending messages that need to be executed that might have been saved if this situation occurred and it processes the pending messages. This does not disconnect the consumer from the broker.

consumptionStopped

public final boolean consumptionStopped()

This is the method each consumer calls whenever they consume a message to see if they can continue to consume messages. If this returns false, they do not exit their 'onMessage' method affectively stopping message consumption for the consumer.

Both PubSub and PointToPoint consumers check to see if consumption has been stopped each time they consume a message.

setTransacted

public final void setTransacted(boolean trans)

Sets the JMS property indicating whether or not this consumer operates in transacted mode or not. This is specified in the ConsumerConfig Element in the deployment document for the gateway being started.

See JMS Specification for details regarding JMS and transactions.

Parameters:

trans - boolean true means the consumer is transacted false means it is not.

getTransacted

public final boolean getTransacted()

Returns the JMS property indicating whether or not this consumer operates in transacted mode or not. This is specified in the ConsumerConfig Element in the deployment document for the gateway being started.

See JMS Specification for details regarding JMS and transactions.

Returns:

boolean true means the consumer is transacted false means it is not.

addCommandConfig

public final void addCommandConfig(java.lang.String name,
                                   CommandConfig cConfig)

Adds a CommandConfig Java object to the list of Commands associated to this consumer. This CommandConfig object will be used to initialize the Command associated to it. Then these Commands will be stored with the consumer and executed based on Messages consumed by the Consumer.

Parameters:

name - String name of the ConsumerCommand that will be initialized with the CommandConfig object

cConfig - CommandConfig the CommandConfig object that holds initialization information for the Command that will be instantiated and executed by the Consumer.

See Also:

CommandConfig, ConsumerCommand, RequestCommand, RequestCommandImpl, SyncCommand, SyncCommandImpl

getCommandConfig

public final CommandConfig getCommandConfig(java.lang.String name)

Returns a CommandConfig Java object from the list of ConsumerCommands associated to this consumer by name. This CommandConfig object will be used to initialize the ConsumerCommand associated to it. Then these ConsumerCommands will be stored with the consumer and executed based on Messages consumed by the Consumer.

Parameters:

name - String name of the Command that will be initialized with the CommandConfig object

Returns:

CommandConfig the CommandConfig object stored in the HashMap of CommandConfigs that matches the name passed in. Returns null if a CommandConfig cannot be found matching the name passed in.

See Also:

CommandConfig, ConsumerCommand, RequestCommand, RequestCommandImpl, SyncCommand, SyncCommandImpl

setCommandConfigs

public final void setCommandConfigs(java.util.HashMap cConfigs)

Sets the HashMap of CommandConfigs to the value passed in. This is a HashMap of configured CommandConfig objects that will be used to initialize ConsumerCommand objects.

Parameters:

cConfigs - HashMap

getStartOnInitialization

public final boolean getStartOnInitialization()

Returns a boolean indicating whether or not this consumer should be started (connected to the broker and ready to consume messages) when it is initialized. This is specified in the ConsumerConfig Element (startOnInitialization Attribute) of the deployment document for the gateway being started.

Returns:

boolean

See Also:

ConsumerConfig

setStartOnInitialization

public final void setStartOnInitialization(boolean start)

Sets a boolean indicating whether or not this consumer should be started (connected to the broker and ready to consume messages) when it is initialized. This is specified in the ConsumerConfig Element (startOnInitialization Attribute) of the deployment document for the gateway being started.

See Also:

ConsumerConfig

setConfig

public final void setConfig(ConsumerConfig config)

Sets the ConsumerConfig object associated to this Consumer. This object holds all the configuration information as specified in the Deployment document that this consumer needs to initialize itself.

Parameters:

config - ConsumerConfig the ConsumerConfig Java object that has been built from contents of the deployment document for the gateway being started.

getConfig

public final ConsumerConfig getConfig()

Returns the ConsumerConfig object associated to this Consumer. This object holds all the configuration information as specified in the Deployment document that this consumer needs to initialize itself.

Returns:

ConsumerConfig the ConsumerConfig Java object that has been built from contents of the deployment document for the gateway being started.

setDestinationName

public final void setDestinationName(java.lang.String name)

Sets the destination name (Queue or Topic) that this Consumer should connect to and consume from.

See JMS Specification for a description of Destinations.

Parameters:

name - String the destination (Queue or Topic) name.

See Also:

ConsumerConfig

getDestinationName

public final java.lang.String getDestinationName()

Returns the destination name (Queue or Topic) that this Consumer should connect to and consume from.

See JMS Specification for a description of Destinations.

Returns:

String the destination (Queue or Topic) name.

See Also:

ConsumerConfig

setConnectionFactoryName

public final void setConnectionFactoryName(java.lang.String name)

Sets the connection factory name (QueueConnectionFactory or TopicConnectionFactory) that this Consumer should retrieve and use to initialize its connection to the broker with.

See JMS Specification for a description of Connection Factories.

Parameters:

name - String name of the Connection Factory.

See Also:

ConsumerConfig

getConnectionFactoryName

public final java.lang.String getConnectionFactoryName()

Returns the connection factory name (QueueConnectionFactory or TopicConnectionFactory) that this Consumer should retrieve and use to initialize its connection to the broker with.

See JMS Specification for a description of Connection Factories.

Returns:

String name of the Connection Factory.

See Also:

ConsumerConfig

getInitializationStatus

public final java.lang.String getInitializationStatus()

Returns the initialization status of the consumer. Since a Consumer can be initialized but not started, there is a distinction between a consumer's "status" and its "initialization status". Initialization statuses can be either INITIALIZED or NOT_INITIALIZED. This status is set during the initialization of the consumer and is used primarily by the consumer to determine what state it's in.

Returns:

String the consumer's initialization status.

setInitializationStatus

public final void setInitializationStatus(java.lang.String status)

Sets the initialization status of the consumer. Since a Consumer can be initialized but not started, there is a distinction between a consumer's "status" and its "initialization status". Initialization statuses can be either INITIALIZED or NOT_INITIALIZED. This status is set during the initialization of the consumer and is used primarily by the consumer to determine what state it's in.

setThreadPool

public final void setThreadPool(ThreadPool tPool)

Sets the ThreadPool object that will be used by this Consumer to execute ConsumerCommands in. When a Consumer receives a message from a destination it determines what ConsumerCommand should be executed via the OpenEAI JMS "COMMAND_NAME" then it adds a job to this ThreadPool which is a call to that Command's execute method.

This ThreadPool is configured in the ConsumerConfig Element of the gateway's deployment document and is passed to the Consumer as part of the ConsumerConfig Java object.

Parameters:

tPool - org.openeai.threadpool.ThreadPool

See Also:

ThreadPool, ConsumerConfig, ThreadPoolConfig

getThreadPool

public final ThreadPool getThreadPool()

Returns the ThreadPool object that will be used by this Consumer to execute ConsumerCommands in. When a Consumer receives a message from a destination it determines what ConsumerCommand should be executed via the OpenEAI JMS "COMMAND_NAME" then it adds a job to this ThreadPool which is a call to that Command's execute method.

This ThreadPool is configured in the ConsumerConfig Element of the gateway's deployment document and is passed to the Consumer as part of the ConsumerConfig Java object.

Returns:

org.openeai.threadpool.ThreadPool

See Also:

ThreadPool, ConsumerConfig, ThreadPoolConfig

setUserName

public final void setUserName(java.lang.String in)

Sets the broker user name that should be used when establishing a connection with the broker. Typically, this is specified in the ConnectionFactory used by this Consumer and it is not needed here. However, if you don't want to use the ConnectionFactory for this you can do it here by specifying it in the ConsumerConfig Element in the deployment document.

Parameters:

in - String broker user name

See Also:

ConsumerConfig

getUserName

public final java.lang.String getUserName()

Returns the broker user name that should be used when establishing a connection with the broker. Typically, this is specified in the ConnectionFactory used by this Consumer and it is not needed here. However, if you don't want to use the ConnectionFactory for this you can do it here by specifying it in the ConsumerConfig Element in the deployment document.

Returns:

String broker user name

See Also:

ConsumerConfig

setPassword

public final void setPassword(java.lang.String in)

Sets the broker user password that should be used when establishing a connection with the broker. Typically, this is specified in the ConnectionFactory used by this Consumer and it is not needed here. However, if you don't want to use the ConnectionFactory for this you can do it here by specifying it in the ConsumerConfig Element in the deployment document.

Parameters:

in - String broker user name

See Also:

ConsumerConfig

getPassword

public final java.lang.String getPassword()

Returns the broker user password that should be used when establishing a connection with the broker. Typically, this is specified in the ConnectionFactory used by this Consumer and it is not needed here. However, if you don't want to use the ConnectionFactory for this you can do it here by specifying it in the ConsumerConfig Element in the deployment document.

Returns:

String broker user name

See Also:

ConsumerConfig

setProviderUrl

public final void setProviderUrl(java.lang.String in)

Sets the location where the administered objects can be retrieved from. To maintain broker independance, this should reference a location in a Directory server.

Parameters:

in - String the URL that resolves to the location of the JMS Administered Objects (ConnectionFactories and Destinations).

See Also:

ConsumerConfig

getProviderUrl

public final java.lang.String getProviderUrl()

Returns the location where the administered objects can be retrieved from. To maintain broker independance, this should reference a location in a Directory server.

Returns:

String the URL that resolves to the location of the JMS Administered Objects (ConnectionFactories and Destinations).

See Also:

ConsumerConfig

setInitialContextFactory

public final void setInitialContextFactory(java.lang.String in)

Sets the class name of the JNDI context factory that will be used to retrieve the JMS administered objects from a Directory Server or wherever the administered objects are stored.

Typically, this is com.sun.jndi.ldap.LdapCtxFactory.

Parameters:

in - String initial context factory class name.

See Also:

ConsumerConfig

getInitialContextFactory

public final java.lang.String getInitialContextFactory()

Returns the class name of the JNDI context factory that will be used to retrieve the JMS administered objects from a Directory Server or wherever the administered objects are stored.

Typically, this is com.sun.jndi.ldap.LdapCtxFactory.

Returns:

String initial context factory class name.

See Also:

ConsumerConfig

getInitialContext

protected javax.naming.directory.DirContext getInitialContext()
                                                       throws javax.naming.NamingException

Establishes an InitialContext to be used by the calling application to retrieve ConnectionFactories and Destination objects via JNDI.

Returns:

DirContext the InitialContext object established

Throws:

javax.naming.NamingException

getSyncCommand

protected SyncCommand getSyncCommand(java.lang.String commandName)
                              throws java.io.IOException

Returns a SyncCommand from the HashMap of SyncCommands supported by this Consumer. Since both PubSub and PointToPoint Consumers may handle sync commands, this is specified in this ancestor class. This method looks for the SyncCommand 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 no expected reply.

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

Parameters:

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

Returns:

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

Throws:

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

initializeConsumer

public void initializeConsumer()
                        throws javax.jms.JMSException

Calls the initSyncCommands() method that will retrieve all SyncCommands from the ConsumerConfig object passed to the constructor and initialize those commands making them available for use.

This method is extended by the PointToPoint Consumer because it also needs to initialize RequestCommands.

Throws:

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

See Also:

initSyncCommands(), PointToPointConsumer.initializeConsumer()

addSyncCommand

public final void addSyncCommand(java.lang.String commandName,
                                 java.lang.String className)
                          throws javax.jms.JMSException

Adds an initialized SyncCommand object to the list of SyncCommands 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 SyncCommands that might be executed by either a PointToPoint or PubSub Consumer. Therefore, the command itself is only intantiated and initialized once, then, it's 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:

commandName - 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

stop

public abstract void stop()

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.

initSyncCommands

protected void initSyncCommands()
                         throws javax.jms.JMSException

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

Throws:

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

See Also:

addSyncCommand(String, String)

handleSync

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

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

The method will look for a JMS String property called "COMMAND_NAME". If the property is found, it will execute the SyncCommand associated to that name. 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.

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

Takes the Properties object contained within the ConsumerConfig object passed to the constructor of this consumer and sets all the appropriate instance variables on this consumer during initialization.

Parameters:

props - Properties the Java properties object retrieved from the ConsumerConfig object built from the ConsumerConfig Element in the gateway's deployment document.

Throws:

java.io.IOException - if errors occur populating the instance variables from the Properties object.