JMS Topic Adapter

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.

Send Mode

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.

Sync Receive

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.

Async Receive

When configured for Async Receive mode, the adapter cannot be invoked by a business process.

Implementing the JMS Topic Adapter

Configuring the JMS Topic Adapter

To configure the JMS Topic adapter, you must specify field settings in your application.

Configuration

The following table describes the fields used to configure the JMS Topic adapter:

Parameters Passed From Business Process to Adapter

The following table contains the parameters passed from the business process to the JMS Topic adapter:

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.

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>

Example 1

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>

Example 2

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.

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>