JMS Topic Adapter
The JMS Topic adapter exchanges messages with remote JMS topics.
The following table provides an overview of the JMS Topic adapter:
|System name||JMS Topic Adapter|
|Graphical Process Modeler (GPM) category||All Services and Messaging > Queuing|
|Description||Exchanges messages with remote JMS topics. Use this adapter when you want to send messages to or receive messages from a remote JMS Topic server as part of a business process within your application. The adapter can also be configured to process messages sequentially, avoiding potential problems when business process execution depends on data captured during processing of the previous message.|
|Requires third-party files?||A 3rd party jar file may be necessary if the value specified for either the InitJndiFactory parameter or the Factory parameter refers to a class that is not already included in the installation of your application. For example, if your application server is JBoss but you need to communicate with an external Weblogic JMS server, you need to install the jar file that includes the weblogic.jndi.WLInitialContextFactory class. You can obtain the necessary jar file from the corresponding vendor or your trading partner.|
|Platform availability||All supported platforms for your application|
|Related services||JMS Queue adapter|
|Initiates business processes?||Initiates a business process when configured for async receive.|
|Invocation||This adapter can only be used in a business process when configured for sending or sync receive.|
How the JMS Topic Adapter Works
The JMS Topic adapter is a stateful adapter; therefore, once the adapter is started, it establishes and maintains the connection to the configured Topic. The adapter can be configured to work in one of three modes: send, sync receive, or async receive.
When configured for Send mode, the adapter waits to be invoked by a business process. The adapter can either send a single workflow document in one invocation or it can send multiple workflow documents in one invocation (batch mode). Each workflow document is sent as a separate message. See Invoking Batch Sending.
If connection to the JMS Server is lost, JMS Topic adapter attempts to reestablish connection with the JMS Server with a retry delay of 60 seconds (60000 milliseconds) between two attempts. JMS Topic adapter attempts a maximum of twenty times to reestablish connection with the JMS Server.
When configured for Sync Receive mode, the adapter waits to be invoked by a business process. Unlike when in Async Receive mode, messages remain on the server until this adapter is invoked to receive the data. One advantage of using Sync Receive mode is that multiple messages can be received in one invocation of the adapter (batch mode). The number of messages received in one invocation can be limited, if necessary. Each message received is placed into the current workflow as a separate document. See Invoking Batch Receiving.
When configured for Async Receive mode, the adapter cannot be invoked by a business process.
- Messages are received when they become available and a new workflow is started (bootstrapped) to process each message. See Invoking Batch Receiving.
- Messages are processed in a single thread. See the Single Thread Execution parameter under Configuring the JMS Topic Adapter.
Implementing the JMS Topic Adapter
- Activate your license for the JMS Topic adapter.
- Set up a topic in your JMS server.
- Create a JMS Topic adapter configuration. See Creating a Service Configuration.
- Configure the JMS Topic adapter. See Configuring the JMS Topic Adapter.
- Create a business process that includes the JMS Topic adapter and enable it.
- Test the business process and the adapter.
- Run the business process.
Configuring the JMS Topic Adapter
To configure the JMS Topic adapter, you must specify field settings in your application.
The following table describes the fields used to configure the JMS Topic adapter:
|Name||Unique, meaningful name for the adapter configuration. Required.|
|Description||Meaningful description for the adapter configuration, for reference purposes. Required.|
|Select a Group||Select one of the options:
Note: See Using Service Groups.
|Connection Type||Whether or not the adapter uses JNDI lookup to
connect to the remote JMS Topic server. Valid values are:
|Initial Context Factory (InitJndiFactory)||Initial context factory for connecting to the remote JMS Topic server. Used for JNDI lookup. Example: weblogic.jndi.WLInitialContextFactory. Required.|
|URL (JndiUrl)||(JNDI only) Uniform Resource Locator of the application server that listens for connection requests. Required.|
|Broker URL (BrokerURL)||(non-JNDI only) Universal Resource Locator of the application server that listens for connection requests.|
|Remote Topic name (RemoteQueueTopicName)||Name of the remote JMS Topic that you want to exchange messages with. Required.|
|Remote Topic Connection Factory (Factory)||Encapsulates connection configuration information and enables JMS applications to create a connection with predefined attributes. Defines and configures one or more connection factories, and the JMS server adds them to the JNDI space during start up. The default is javax.jms.TopicConnectionFactory. Required.|
|Remote User Name (Username)||User name for accessing the JMS Server. Required if the JMS Server requires security credentials.|
|Remote Password (Password)||Password for accessing the JMS Server. Required if the JMS Server requires security credentials.|
|Connection User Name||Authentication user ID when security is enabled.|
|Connection Password||Password for the authentication user ID when security is enabled.|
|Turn on debug messages (Debug)||Whether to log debug messages for this adapter
instance. Required. Valid values:
|Topic Type (Action)||Type of topic to access. Valid values are:
|Message Type (Payload)||Type of message to send. Used only if topic type
is Topic Send. Valid values are:
|Bootstrap Workflow (InitialWorkFlowId)||Business process to initiate when data is received. Used only if topic type is Topic Receive Async. Required.|
|Document Storage Type (docStorageType)||Defines how the document will be stored in the
system. Used only if topic type is Topic Receive Async. Required.
Note: See Selecting a Document Storage Method for Bootstrap Adapters.
|Single Thread Execution||Processes a message completely before beginning
the processing of the subsequent message. Preferred mode for processes
that require sequential processing. However, processing will be slower.
Valid values: Yes, No
Note: Single thread execution sets the value for Max Bootstrap Threads to one, even if the user has configured another value.
|Maximum Bootstrap Threads (MaxThreads)||Maximum number of threads used when receiving files
and starting business processes. Used only if topic type is Topic
Receive Async. Each message received uses one thread. Default is 10.
Note: Single thread execution sets the value for Max Bootstrap threads to one, even if the user has configured another value.
|Buffer Size (BufferSize)||Size of the buffer when receiving data. Used only if topic type is Topic Receive Async. Enables you to fine-tune the performance of the adapter according to data expectations. Default is 30000. Optional.|
|Document Filename (OutputFileName)||If you choose Topic Receive Async as the topic type for the JMS Topic adapter, then you can specify a file name for the data that the JMS Topic receives. A unique file name generator placeholder, %^, can be used to generate a sequence in the form nodename_yyyymmddhhmmsslll.|
|Connection retry attempts (RetryCount)||Maximum number of connection retry attempts. Used only if topic type is Topic Receive Async. Specify -1 for an infinite number of retry attempts. Default is 20. Optional.|
|Delay between retries (RetrySleep)||Number of milliseconds to wait between retry attempts. Default is 300000 ms (5 minutes). Used only if topic type is Topic Receive Async. Optional.|
|Notification Workflow (NotifyWorkFlow)||Business process initiated by the JMS Topic adapter if the maximum number of connection retries specified in Connection retry attempts is exceeded. Used only if topic type is Topic Receive Async. Required. If the adapter does not initiate a business process, select Not Applicable.|
|User||User ID to use for running the adapter. Select
a user ID from the list. Valid values: Any valid application user
Note: This parameter allows someone who doesn't have rights to a specific business process to run it. If you select Admin as the user ID, you will inherit Administrative rights (for this run of the business process only), and enable the scheduled run.
|Jar Locations||Optional. Specify the preferred libraries of the jar files to be loaded with the JMS Topic adapter. You must specify the full path of the location of the jar files. Use semicolon (;) to separate multiple paths.|
Parameters Passed From Business Process to Adapter
The following table contains the parameters passed from the business process to the JMS Topic adapter:
|batchSndFilter||Optional. Only used when sending. If specified in the business process, triggers batch mode sending based on the documents that match the filter. You can use an asterisk '*' in the filter as a wildcard.|
|batchRcvLimit||Optional. Only used when receiving synchronously. If specified in the business process, the number of messages received is limited to the number specified. If not specified, all messages available are received.|
|batchRcvTimeout||Optional. Only used when receiving synchronously. If specified in the business process, it overrides the default receive timeout. If not specified, the default timeout is 2000 milliseconds (2 seconds).|
Setting JMS Header Object Properties
When sending, you can set JMS object properties within the JMS header that are not part of the payload data. You can specify name/value pairs during run time within the BPML. Because the user-defined name/value pairs are unknown ahead of time, they cannot be set in the application or GPM configuration so they must be manually added directly in the BPML. The JMS Topic adapter will look in ProcessData for the XML node name JMSetProperty and use any child nodes it finds to set the name/value pairs. There is a list of reserved property names that will set specific JMS message properties. An example of the ProcessData XML tree would look like this:
<ProcessData> <JMSetProperty> <somename1>somevalue1</somename1> <somename2>somevalue2</somename2> Reserved names that set specific JMS message properties <correlationID>someStringValue</correlationID > <deliveryMode>someIntegerValue</deliveryMode> <destination>someTopicName</destination> <expiration>someLongValue</expiration> <messageID>someStringValue</messageID> <priority>someIntegerValue</priority> <redelivered>someBooleanValue(true/false)</redelivered> <replyTo>someTopicName</replyTo> <timestamp>someLongValue</timestamp> <type>someStringValue</type> </JMSetProperty> </ProcessData>
An example of BPML that could be used to set these ProcessData name/value pairs follows:
<assign to="JMSetProperty/somename1" from="'somevalue1'" append="true"/> <assign to="JMSetProperty/somename2" from="'somevalue2'" append="true"/>
When receiving, the JMS Topic adapter will set ProcessData items for all the JMS header fields and any object properties. Any object properties set in the JMS header will be put into ProcessData with the node name of JMS. For example, if there is a property called somename with a value of somevalue, ProcessData will contain JMS/somename with the corresponding value:
<JMS> <somename>somevalue</somename> </JMS>
The JMSetProperty can be used as a global property (under the ProcessData node) or a local property (under individual documents). Local JMSetProperty parameters override any global parameters and are useful when sending in batch mode. In the below example, the global JMSetProperty has a parameter called “test” with a value of zero. Since the PrimaryDocument does not have a local JMSetProperty, it uses the global one. However, since doc1, doc2, and doc3 have local JMSetProperty parameters, they use the local parameters.
<ProcessData> <JMSetProperty> <test>0</test> </JMSetProperty> <PrimaryDocument SCIObjectID="1833955:1063b363ed5:-774a"/> <doc1 SCIObjectID="1833955:1063b363ed5:-774b"> <JMSetProperty> <test>1</test> </JMSetProperty> </doc1> <doc2 SCIObjectID="1833955:1063b363ed5:-774c"> <JMSetProperty> <test>2</test> </JMSetProperty> </doc2> <doc3 SCIObjectID="1833955:1063b363ed5:-774d"> <JMSetProperty> <test>3</test> </JMSetProperty> </doc3> </ProcessData>
Invoking Batch Sending
If a business process contains multiple documents in ProcessData, the JMS adapter can be invoked once with the workflow parameter batchSndFilter, which enables the adapter to send multiple messages for each of the documents that match the batchSndFilter criteria.
- You do not need to make changes to the main adapter configuration; just add the appropriate assignment to the business process in the JMS adapter invocation step.
An example ProcessData for the example BPMLs below would look like this:
<ProcessData> <PrimaryDocument SCIObjectID="fe64b9:1060cac437b:-6a2a"/> <doc1 SCIObjectID="fe64b9:1060cac437b:-6a2b"/> <XYZ> <doc1 SCIObjectID="fe64b9:1060cac437b:-6a2c"/> <doc2 SCIObjectID="fe64b9:1060cac437b:-6a2d"/> <doc3 SCIObjectID="fe64b9:1060cac437b:-6a2e"/> </XYZ> </ProcessData>
Sends all documents in ProcessData (including the PrimaryDocument). In this example, all five documents in ProcessData above are sent.
<operation name="JMS batch send"> <participant name="JMSadapter"/> <output message="toService"> <assign to="." from="*"/> <assign to="batchSndFilter" from="'*'"/> </output> <input message="fromService"> <assign to="." from="*"/> </input> </operation>
Sends all documents that begin with “doc” under the XYZ node. In this example, only three documents in the ProcessData above are sent.
<operation name="JMS batch send"> <participant name="JMSadapter"/> <output message="toService"> <assign to="." from="*"/> <assign to="batchSndFilter" from="'XYZ/doc*'"/> </output> <input message="fromService"> <assign to="." from="*"/> </input> </operation>
Invoking Batch Receiving
The type of receive adapter you choose to use is based on your business needs. If you are processing a large volume of messages, you may find that batching them is more efficient than bootstrapping one workflow for every message.
- Topic Receive Async – Registers a listener to the topic so that when messages are available they are received immediately, or pushed down to the adapter, and a new workflow is bootstrapped to handle that single message. The business process that the adapter is going to bootstrap should be in sync mode.
- Topic Receive Sync – Must be called by a business process for the adapter to poll for any available messages. But, instead of bootstrapping one workflow per message (such as the Async Receive adapter does), the Sync Receive adapter will create a separate workflow document for each message and place them all into the current workflow (no bootstrapping occurs).
- batchRcvLimit – (Optional) If used, this parameter limits the number of messaged batched into the bootstrapped workflow. Default = no limit.
- batchRcvTimeout – (Optional) If used, this parameter specifies how long the adapter waits without receiving a message before ending. Default = 2000 (milliseconds)
- JMS/DocumentCount – This parameter is always created to show how many documents were created from messages received, even if zero messages were received.
- JMS/Documentxxx – For every message received, a document is created under the JMS node and then sequentially numbered starting with one (that is, Document1, Document2, and so forth).
Another difference between Async Receive mode and Sync Receive mode is where the message metadata is stored in ProcessData. In Async Receive mode, it only creates one document (the PrimaryDocument), so all the metadata is stored as JMS/metadataName. However, in Sync Receive mode, the metadata is stored under each document as JMS/documentName/metadataName as shown in the example below.
Example of ProcessData after a batch receive was performed:
<ProcessData> <JMS> <DocumentCount>3</DocumentCount> <Document1 SCIObjectID="1833955:1060de6d03d:-697b"> <redelivered>false</redelivered> <deliveryMode>2</deliveryMode> <destination>testtopic</destination> <expiration>0</expiration> <messageID>ID:234-11255156360801</messageID> <priority>4</priority> <timestamp>1125515636080</timestamp> </Document1> <Document2 SCIObjectID="1833955:1060de6d03d:-6978"> <redelivered>false</redelivered> <deliveryMode>2</deliveryMode> <destination>testtopic</destination> <expiration>0</expiration> <messageID>ID:234-11255156361102</messageID> <priority>4</priority> <timestamp>1125515636110</timestamp> </Document2> <Document3 SCIObjectID="1833955:1060de6d03d:-6975"> <redelivered>false</redelivered> <deliveryMode>2</deliveryMode> <destination>testtopic</destination> <expiration>0</expiration> <messageID>ID:234-11255156361243</messageID> <priority>4</priority> <timestamp>1125515636124</timestamp> </Document3> </JMS> </ProcessData>