JMS 1.1 Request Reply Service

The JMS 1.1 Request Reply service is used in scenarios where response from user matters to the sender and depending on this response an action needs to be taken by the sender.

The following table provides an overview of the JMS 1.1 Request Reply service:

System Name JMS 1.1 Request Reply service
Graphical Process Modeler (GPM) categories) Services
Description This service is used in scenarios where response from user matters to the sender and depending on this response an action needs to be taken by the sender.
Business usage This service is used in scenarios where response from user matters to the sender and depending on this response an action needs to be taken by the sender.
Usage example For example, consider credit card verification. In this example, the payment should be blocked until the credit card authentication happens. The user sends a request to verify credit card credentials to the bank. The bank verifies the credentials and sends a reply and then the flow proceeds. No other steps are carried out until bank has replied.
Preconfigured? Yes
Requires third-party files? The JMS provider jar must be provided to the system, by using one of the following methods:
  • Install by using the install3rdParty script
  • Load by using the custom classloader
For JBoss and WebLogic, you must use the custom classloader as these vendor jars contain classes that already exist in system classloader.
Platform availability All supported platforms
Related services This service is used with JMS 1.1 Acquire Connection and Session service and JMS 1.1 Release Connection and Session service. The JMS connection and session required for the Request Reply service is created by the JMS 1.1 Acquire Connection and Session service. The JMS 1.1 Acquire Connection and Session is also used to release to the pool.
Application requirements This depends on how you want to use the JMS. You must create the JMS connection factory and destinations if you want to use JNDI.
Initiates business processes? No
Invocation This service can only be used in a business process.
Business process context considerations None
Returned status values None
Restrictions The JMS 1.1 specification states, a temporary destination is used to receive a message. Typically the JMS 1.1 Request Reply is used to make sure that the reply comes within a specified period. With multiple business processes running, the system might exhaust all the threads allocated for running the business process. You can use the JMS 1.1 Request Reply to specify:
  • Time-out for the reply
  • Number for replies expected per request
  • Permanent destination rather than a temporary destination
Persistence level Since this service operates between the JMS 1.1 Acquire Connection and Session Service and JMS 1.1 Release Connection and Session service, the service has minimum persistence.
Testing considerations None

Configuring the JMS 1.1 Request Reply Service

You must specify field settings, by using the Admin Console and the GPM.

Use the field definitions in the following table to create a new configuration of the JMS 1.1 Request Reply service, or to set up the configuration provided with the system. Some fields are available in both the Admin Console and in the GPM.

UI Field GPM Field Description
Name   Unique and meaningful name for the service configuration. Required.
Description   Meaningful description for the service configuration, for reference purposes. Required.
Select a Group   Select one of the options:
  • None – Do not include the configuration in a service group at this time.
  • Create New Group – Enter a unique name for a new group, which will be created with this configuration. (You can then add other services to the group as well.)
  • Select Group – If service groups already exist for this service type, they are displayed in the list. Select a group from the list.
  Config Select the service configuration from the list.
  BOUNDED_HASHMAP_SIZE Number of requests that can be sent from the JMS 1.1 Request Reply service instance without receiving any replies for the requests. After the requests have been sent, the business process that uses this request reply service will not be able to send a message until a reply is received for the pending requests. This maintains an equilibrium between requests and replies. This parameter is only valid if using the request reply with a permanent destination. Default value is 10.
  JMSCorrelationID Unique correlation ID identifies a message. Not required for permanent destination mode, as it will be set automatically.
  JMSDeliveryMode Specifies the JMS Delivery Mode. Valid value is any string value. Optional.
  JMSDestination Specifies the JMS Message Property Destination. Valid value is a destination name. Optional.
  JMSExpiration Specifies the JMS Message Property Expiration. Valid value is a long string value. Optional.
  JMSMessageID Specifies the JMS Message Property Message ID. Valid value any string value. Optional.
  JMSPriority Specifies the JMS Message Property Priority. Optional. Valid value is an integer. Optional.
  JMSRedelivered Specifies the JMS Message Property delivery flag. Optional. Valid value is true or false.
  JMSTimestamp Specifies the JMS Message Property Timestamp. Optional. Valid value is a long string value.
  JMSType Specifies the JMS type. Optional. Valid value is any string value. Some JMS providers use a message repository that contains the definitions of messages sent by applications. The JMSType header field may reference a message's definition in the provider's repository. WebLogic JMS currently does not have a message definition repository. If the message will not be forwarded to a foreign vendor, the JMSType can be used to store an arbitrary value, similar to the usage for JMSCorrelationID.
  MSG_TYPE Type of JMS Message to be sent. Required. Valid values are:
  • Bytes Message
  • Object Message
  • Text Message
  • Stream Message
No default value.
  MESSAGE_SELECTOR

Specifies the selector filter on the consumer.

Example values are:

JMSCorrelationID='ABC'

JMSPriority=6

JMSPriority=6 AND JMSCorrelationID='abc'

JMSPriority=6 OR JMSCorrelationID='abc'

  OUTPUT_FILE_NAME User specified file name for the data that gets received from the destination. If you are receiving documents in batch mode or from the Async Adapter, you can use %^ as the output file name. When using the %^, the output file name is assigned in the format <nodename>_yyyymmddhhmmsslll.
  REQUEST_REPLY_EXPECTED_REPLIES Number of expected replies for a given request. This is valid only when using permanent destination. For temporary destination the value is always 1. If the number of requested replies specified is not received within the time-out period a request timeout exception is thrown. Default value is 1.
  REQUEST_REPLY_RECEIVE Name of the reply destination. Any valid destination. Required only when using permanent destination mode.
  REQUEST_REPLY_SEND Name of the request destination. Destination is retrieved depending on whether the JMS 1.1 Acquire Connection Session service uses JNDI or Non-JNDI. If the request destination is not specified at the JMS 1.1 Acquire Connection Session Service level, then this destination is mandatory. If specified in both places, this parameter takes precedence.
  REQUEST_REPLY SEND_TYPE Destination type of request destination. Required for both permanent and temporary destination mode.
  REQUESTER_TYPE Whether to use a single permanent destination to receive all the replies or a temporary destination per request. Value values are:
  • Permanent Destination
  • Temporary Destination (This value is not supported if you are using SonicMQ 7.5 or JBOSS 4.2.2.)
  RR_CONC_CONSUMERS Concurrent number of consumers that can be present on this reply destination at any given time. This is a performance enhancement parameter. Required only when using permanent destination mode. Valid only when using permanent destination. Default value is 1. For permanent destination, the number of concurrent consumers + bounded hash map size should be less than the number of sessions specified in the acquire connection session service. Ideally, the number of sessions is 2*(bounded hash map size + concurrent consumers). With a setting greater than 1, multiple consumers will process replies and the order in which messages where requested may not be the order in which they are responded to. The same applies to the number of responders, if it is greater than 1, the order is not maintained.
  TIMEOUT Time in milliseconds for which the request should wait when expecting a reply. If a reply is not received within this time, a request timeout exception is thrown. Any valid integer. Default is 120000 milliseconds. Required for permanent destination mode.

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 1.1 Request Reply Service 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>someQueueName</destination>
    <expiration>someLongValue</expiration>
    <messageID>someStringValue</messageID>
    <priority>someIntegerValue</priority>
    <redelivered>someBooleanValue(true/false)</redelivered>
    <replyTo>someQueueName</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 1.1 Request Reply Service 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>
In addition to the user-defined properties, the JMS 1.1 Request Reply Service will also set the following JMS header fields in ProcessData (if they are not null):
  • JMS/correlationID
  • JMS/deliveryMode
  • JMS/destination
  • JMS/expiration
  • JMS/messageID
  • JMS/priority
  • JMS/redelivered
  • JMS/replyTo
  • JMS/timestamp
  • JMS/type

Business Process Example

Example 1

This business process illustrates sending a request and waiting for the time specified in the TIMEOUT (milliseconds) parameter. If no response is received within the timeout parameter, the business process will fail with a request time-out exception. This business process uses a permanent destination rather than a temporary destination to receive a response.

This business process uses the following parameters to specify:
  • Timeout for reply
  • Number of expected replies
  • Permanent destination
  • Bounded hash map size to maintain equilibrium between request replies
<process name="default">
    <sequence>
         <operation name="JMS11AcquireConnSessionService">
               <participant name="testRegressionsAcquireConnSessionService" />
               <output message="JMS11AcquireConnSessionServiceInputMessage">
                    <assign to="." from="*"></assign>
               </output>
               <input message="inmsg">
                    <assign to="." from="*"></assign>
               </input>
            </operation>
         <operation name="JMSReqRepService">
              <participant name="JMSRequestReplyPermanentDestinationService" />
              <output message="JMSReqRepServiceInputMessage">
                    <assign to="." from="*"></assign>
                    <assign to="BOUNDED_HASHMAP_SIZE">10</assign>
                    <assign to="MSG_TYPE">TextMessage</assign>
                    <assign to="REQUEST_REPLY_EXPECTED_REPLIES">1</assign>
                    <assign to="REQUEST_REPLY_RECIEVE">ReplyDestination</assign>
                    <assign to="REQUEST_REPLY_SEND">RequestDestination</assign>
                    <assign to="REQUEST_REPLY_SEND_TYPE">QUEUE</assign>
                    <assign to="REQUESTER_TYPE">Permanent Destination</assign>
                    <assign to="RR_CONC_CONSUMERS">1</assign>
                    <assign to="TIMEOUT">30000</assign>
									<assign to="MESSAGE_SELECTOR">JMSCorrelationID ='ABC'</assign>
                 		<input message="inmsg">
                    <assign to="." from="*"></assign>
                  </input>
            </operation>
         <operation name="JMS11ReleaseConnSessionService">
               <participant name="testRegressionsReleaseConnSessionService" />
               <output message="JMS11ReleaseConnSessionServiceInputMessage">
                    <assign to="." from="*"></assign>
                    <assign to="RELEASE_ACTION">NONE</assign>
                </output>
                <input message="inmsg">
                     <assign to="." from="*"></assign>
                  </input>
            </operation>
      </sequence> 
</process>

Example 2

This business process uses a temporary destination rather than a permanent destination to receive a response.

<process name="default">
  <sequence>
    <operation name="JMS11AcquireConnSessionService">
      <participant name="testRegressionsAcquireConnSessionService"/>
      <output message="JMS11AcquireConnSessionServiceInputMessage">
        <assign to="." from="*"></assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
    <operation name="JMSReqRepService">
      <participant name="JMSRequestReplyTemporaryDestination"/>
      <output message="JMSReqRepServiceInputMessage">
        <assign to="." from="*"></assign>
        <assign to="MSG_TYPE">TextMessage</assign>
        <assign to="REQUEST_REPLY_SEND">RequestDestination</assign>
        <assign to="REQUEST_REPLY_SEND_TYPE">QUEUE</assign>
        <assign to="REQUESTER_TYPE">Temporary Destination</assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
    <operation name="JMS11ReleaseConnSessionService">
      <participant name="testRegressionsReleaseConnSessionService"/>
      <output message="JMS11ReleaseConnSessionServiceInputMessage">
        <assign to="." from="*"></assign>
        <assign to="RELEASE_ACTION">NONE</assign>
      </output>
      <input message="inmsg">
        <assign to="." from="*"></assign>
      </input>
    </operation>
  </sequence> 
</process>

Frequently Asked Questions

What is the difference between PERMANENT and TEMPORARY DESTINATION mode?

TEMPORARY DESTINATION

If the JMS API specifies that the Topic or Queue Requestor is used for a request reply, the message is sent to the request/send destination specified in the service. A temporary destination is created for each message sent and is set in the JMS Reply To header of the sent message. A third-party consumer can receive this message and reply back at the temporary destination specified in the reply to header. As soon as the reply is received on this temporary destination, the JMS 1.1 Request Reply flow is marked as complete.

Temporary destination limitations include:
  • For every request sent, only one reply can be received.
  • The JMS 1.1 Request Reply service remains in the waiting state unless a reply is not received. The business process remains in active state until a reply is not received. You need to determine if having the business process staying in the active state impacts your system.
  • No throttling can be attained between sends and receives. This means, if you have a fast producer (sending messages) and slow consumer (replying to these messages) then you might end up overloading the provider with too many sends.
  • This has the overhead of creating a new temp destination for each request which can be resource-intensive.

PERMANENT DESTINATION

For the permanent destination mode, the customer provides a receive/reply destination along with the send/request destination. A message is sent to the request destination but instead of setting a temporary destination in the reply to header, the reply/receive destination is specified in the header. A unique correlation id is set in the message header to ensure that we are able to match a request to a response. Additionally, an async receiver is started at the reply/receive destination that collects the replies.

Advantages of using PERMANENT DESTINATION mode include:
  • More than one reply can be received for a single request.
  • Time-out can be specified for a request. If no reply is received within the time-out, then the business process is marked as failed.
  • A parameter called the BOUNDED HASHMAP LIMIT can be used to maintain throttling between send and receive messages. The BOUNDED HASHMAP LIMIT defines the maximum number of messages that can send to the provider at any given point in time.

How do I stop the async receiver started in PERMANENT DESTINATION mode by JMS 1.1 Request Reply service?

An async receiver starts listening on the reply destination assigned in the JMS 1.1 Request Reply service as soon as the first request/message is sent. It continues to remain active until manually shutdown. The async receiver can also be stopped by using the JMX or using the JMS 1.1 Release Connection and Session service. The pools span the Async Receiver instances, so shutting down a given Async Receiver only releases the resources back to the pool. The pool to a large degree has its own life cycle that is independent of a given adapter. Thus, to shut down the pool you have to do it explicitly.

The following is an example of the JMS 1.1 Release Connection And Session workflow:

Start > JMS 1.1 Release Connection And Session Service > Stop

In the JMS 1.1 Release Connection and Session service:
  • RELEASE MULTIPLEXER is ACTION
  • Select the async receiver from the drop-down
  • Run the business process to shut down async receiver

The async receiver in the drop down has a format of replyDestination_URL_numberOfConccurentConsumers_BoundedHashMapSize_uniqueID. There is a chance that customer might have created different receivers to the same destination but with different number of concurrent Consumers and different bounded hash map size.

When should I stop the async receiver started in PERMANENT DESTINATION mode by JMS 1.1 Request Reply service?

You should manually shut down the async receiver:
  • When all the business processes using the JMS 1.1 Request Reply service have finished successfully and the none of these business processes need to be run again.
  • If you edited any of the pool parameters of the JMS 1.1 Acquire Connection and Session service that was a part of the business processes that use the JMS 1.1 Request Reply service. Since the async receiver is also setup using the same pool, any changes in this pool lead to the creation of a new async receiver along with the old one. The old async receiver should be shut down before making any changes to the pool parameters.
  • If you edited the BOUNDED HASH MAP LIMIT, REPLY DESTINATION, or the CONCURRENT CONSUMERS parameters in the JMS 1.1 Request Reply service, you need to shut down the async receiver before running a new workflow with the modified parameters. If the async receiver is not shut down before editing any of these parameters, you might end up with more than one async receivers against the same destination and the JMS 1.1 Request Reply service will not work properly. You can confirm this by listing the multiplexers using the JMX.

Why am I seeing more than one async receiver in the PERMANENT DESTINATION mode?

If you fail to shut down the async receiver before changing the BOUNDED HASH MAP LIMIT, REPLY DESTINATION, or the CONCURRENT CONSUMERS parameters, you will see multiple instances of the async receiver. The request reply might fail as more than one receiver is listening to the reply destination. You must shut down the multiplexer before editing any of the parameters.

You can use the JMX to list the number of multiplexers and check if more than one multiplexer is listed against the same destination. Additionally, the multiplexers can be listed using the JMS 1.1 Release Connection and Session service by using the drop down of RR_LIST parameter.

Do I need to specify the correlation id when using JMS 1.1 Request Reply service?

The Correlation Id is not used in the TEMPORARY DESTINATION mode. If you are using the PERMANENT DESTINATION mode, the correlation id is used to uniquely match a request to a reply. You need to have a unique correlation id for every message sent using Request Reply. Unless customers have a unique mechanism to ensure that they will be able to set a unique correlation id for every request this field should be left blank as a unique correlation id is automatically generated in code and set. If the customer provides own correlation id the default one is overridden.

How is a response to a request sent using JMS 1.1 Request Reply service?

For TEMPORARY DESTINATION, the reply should be sent to the destination specified in the reply to header of the received message.

For PERMANENT DESTINATION, the reply should be sent to the destination specified in the reply to header of the received message. The correlation id to the reply should be set to the same as the correlation id of the received/request message.

What happens if I get a message after the received time-out in the PERMANENT DESTINATION mode?

If you are using the PERMANENT DESTINATION mode, the async receiver remains active, unless it is shut down manually. If you receive more replies than was specified in the number of replies, or if a reply is received after the time out of a request, the replies are not lost. To ensure that none of these messages are lost, you can set a property called ERROR_QUEUE as a message header in the reply. Specify the destination where you want these replies to be redirected in case this reply is received after a time-out or if it is more than the number of replies that were expected.

What happens when the JMS provider goes down?

If you are using the PERMANENT DESTINATION mode, there is always an async receiver listening against the reply/receive queue waiting for messages. If the JMS provider goes down, this async receiver executes the retry logic to reconnect itself and the JMS provider will come back. The number of retries and the amount of time between each retry is defined in the jms11.properties file.

What is the difference between disabling the Async Receive Service and stopping the Async Receive/shutting down the pool using the JMX or the Release Connection and Session component?

Shutting down a given async receiver only releases resources back to the pool. The pool to a large degree has its own life cycle that is independent of a given adapter. Thus to shut down the pool you have to do it explicitly.