JMS 1.1 Async Receive Adapter
The JMS 1.1 Async Receive adapter enables a client to receive messages in async mode.
A client can register a message consumer against a destination and whenever a message comes to the destination it is passed to the client. Unlike the JMS 1.1 Receive Message service, a client will not need to make a request to the destination for getting the message. The JMS 1.1 Async Receive adapter internally used MessageListener and implements the onMessage() method to receive messages as compared to the receive() call of JMS Receive Message Service.
This adapter internally uses pooling of connections, sessions, consumers, and producers. If you disable this adapter, the connection to the JMS provider is not closed. To close this pool, you will need to run the Business Process suggested in the JMS 1.1 Release Connection Session service. The name of the pool to shutdown is <Name of adapter instance>_<random number>. You should be able to see this in the drop-down list for the pools.
Also changing the number of consumers, connection factory, or URL creates another pool with the name <Name of adapter instance>_<different random number> and leaves the original one around until it is either specifically closed for the node is reset. If you want to edit the adapter parameters, you should disable the adapter first, shutdown the pool, and then enable the adapter. If the older pool is not shut down and the parameters are changed, a new pool will get created and the older pool remains enabled though it will not be used. The older pool is still available, until you close it or reset the node. To free the connections the older pool is using, it is recommended that the older pool is shut down after disabling the adapter and before editing the parameters and starting the adapter instance.
The following table provides an overview of the JMS 1.1 Async Receive adapter:
|System Name||JMS 1.1 Async Receive adapter|
|Graphical Process Modeler (GPM) categories)||None|
|Description||The JMS 1.1 Async Receive adapter enables a client to receive messages in async mode. A client can register a message consumer against a destination and whenever a message comes to the destination it is passed to the client. Unlike JMS 1.1 Receive Message service, a client will not need to make a request to the destination to receive the message.|
|Business usage||You can receive messages from a trading partner using a JMS 1.1 messaging queue or topic in async mode.|
|Usage example||Based on low inventory of a certain item, your company sends a JMS message to a queue stating that more inventory that needs to be sent. You configure an instance of JMS 1.1 Async Receive adapter which listens to this queue. As soon as a message is received on the queue, the JMS 1.1 Async Receive adapter triggers a business process responsible for providing the necessary inventory to your company.|
|Requires third-party files?||The JMS provider jar must be installed on the server
using install3rdParty script. Before installing the jar file, you
need to know:
|Platform availability||All supported platforms|
|Application requirements||It depends on how you plan to use JMS. Creation of a JMS connection factory and destinations will be required if you want to use the JNDI approach for JMS.|
|Initiates business processes?||Yes. When a message is received from the specified JMS provider, the adapter bootstraps the business process you specified during adapter configuration. This adapter cannot be used in a business process. It should always be used as a listening adapter and never in a business process.|
|Invocation||Event driven. Triggers a business process for every JMS message received.|
|Business process context considerations||None|
|Returned status values||None|
Configuring the JMS 1.1 Async Receive Adapter in the Admin UI Console
Use the field definitions in the following table to create a new configuration of the JMS 1.1 Async Receive adapter.
|UI Field Name||Description|
|Name||Unique name for the service configuration. Required.|
|Description||Description for the service configuration, for reference purposes. Required.|
|Select a Group||Select one of the options:
|Connection Type||Defines whether to use JNDI or not. Required. Valid
|Context Factory||Context Factory name as provided by the JMS Provider. Required. Only displayed if using JNDI.|
|URL||URL needed to connect with the JMS provider. Required.|
|Connection Factory||Connection Factory name as provided by the JMS Provider. Required.|
|Receive Destination||Destination name from where to receive the messages. Required.|
|Connection Factory User Name||User name for JNDI look up, if the JNDI lookup is secured. This field is only displayed for JNDI.|
|Connection Factory Password||Password for JNDI lookup, if the JNDI lookup is secured. This field is only displayed for JNDI.|
|Connection User Name||Identifies the Connection User Name.|
|Connection Password||Identifies the Connection Password.|
|Message Selector||Message selector in case the customer wants messages matching only the given selector to be picked.|
|Destination Type||Destination type. Required. Valid values are:
|Time to Live (per connection in ms)||Amount of time the connection should be kept alive in milliseconds. Required. Valid value is any valid integer. Default is 300000 (milliseconds).If a connection remains idle (not used by either producer or consumer) for this amount of time, whenever a new call comes to create a new connection or use an existing connection from pool, the idle connection is closed and a fresh connection is created and added to the pool. The idle connection will not be closed automatically but only when a new call comes to create/fetch a new connection.|
|Concurrent Consumers||Concurrent number of consumers on this given destination at any given time This parameter should be adjusted for performance. Required. Valid value is an integer. By default for FIFO mode or when using TOPICS this value is always set to 1.|
|Is Session Transacted||Whether the session that receives this message
should be transacted or not. If transacted, it ensures that the message
is not lost even if the application crashes. Required. Valid values
|Success Business Process||The business process that should be bootstrapped when a message is received. Required. Select from the list of business processes. If you need more information, see the Process Execution Mode and Is Session Transacted parameter descriptions.|
|Process Execution Mode||Defines how the business process is queued at run
time. Select the process execution mode from the list. Valid values
|Document Storage Type||Document storage type for received messages. Valid
|Document Filename||Filename for the data that is received. You can use a generator placeholder, %^, which generates a sequence in the form of <nodename>_yyyymmddhhmmsslll.It is important that the document file name is a unique name. If the same document file name is used, it can cause potential data loss scenario as the file could potentially be overwritten.|
|Business Process Queue Depth Threshold (V188.8.131.52 or later)||Maximum number of queued business processes allowed for this adapter.
If this value is not defined, or the value is 0, the adapter processes a message if there is one.
If the business process queue depth in the queue assigned to the Success Business Process is:
|Use Durable Subscriber||Ensures durable subscription to a topic. Optional.
Only valid when Destination Type is TOPIC. Valid values are:
|Client ID||Client ID is set in the connection when using durable subscription. Optional. Only valid when Destination Type is TOPIC.|
|Durable Subscriber Name||Name used when using durable subscription. Only valid when the Destination Type is TOPIC. Required, when Durable Subscription value is Yes.|
|User||User name used when bootstrapping the business process. Required. Select the user name from the list.|
|Connection retry attempts||Number of retry attempts to connect to a JMS server if connection is lost. Optional.|
|Delay between retries||Delay between each retry attempt. Optional. Default value is 0, retries will not happen.|
|Notification Business Process||Notification business process to bootstrap if unable to connect to server after the number of retries. Optional.|
|Use SSL||Whether to use SSL or not. Required. Valid values
|SSL SETTING ca cert ids||Select from list of available CA certificates checked in on the server. Required. Only displayed if SSL_MUST was selected.|
|SSL SETTING key certID||Select from list of available system certificates checked in on the server. Optional.|
|JMS Provider||If you are using SSL, select ActiveMQ or WebSphereMQ as the JMS Provider from the list of providers.|
|JMS Provider Specific Properties||In Property Name field, type provider-specific parameters as key/value pairs. Supports up to 5 key/value pairs. For example, if the setting of Provider is sampleProp = testValue, then "Property Name" should be completed as sampleProp and "Property Value" should be testValue. This allows you to configure up to 5 properties. This setup is only available if connection type is JNDI.|
|jar Location||Path and directory to the jars required for custom class loading. Required. This field is only displayed if True was selected for Use Custom Class Loading.In you want to change the jar location or use new jars, you need to release the old custom class loader using the JMS 1.1 Release Connection Session service and then the new class loader needs to be created.If need you more information, see the JMS 1.1 Release Connection Session service or the JMX documentation.|
|Use Custom Class Loading||Required.
|System Certificate||System Certificate Name. Required when SSL_MUST is selected for Use SSL.|
|CA Certificate||CA Certificate Name. Required when SSL_MUST is selected for Use SSL. If failover
URL is used to connect to ActiveMQ, then add ActiveMQ certificates to the B2B JDK's cacerts store.
Below are the example commands:
and restart B2B node.
Configuring external WebSphereMQ for JMS Adapter
To configure the JMS 1.1 Async Receive Adapter on Sterling B2B Integrator:
Install the required WebSphereMQ jar files corresponding to the WebSphereMQ server version using
CustomJar from the
Customization user interface.
To configure the JMS 1.1 Async Receive Adapter on Docker container
docker cp <bindings file path> <container_id:/ibm/resources>
docker cp <bindings file path> <container_id:/ibm/resources>on all the nodes. You can also copy the files to the mapped resource folder on all nodes.
To configure the JMS 1.1 Async Receive Adapter on Certified Container
Copy the bindings file from the WebSphereMQ server to the resources volume mapped folder, which is the same location where the database driver jar file, JCE files, and other resources are placed for the Certified Container deployment.
While configuring the JMS Adapter using the JNDI option, the URL configuration field value is
Frequently Asked Questions
Why is my message failing?
If you are using Custom Class Loading, there is a chance that when receiving messages via the JMS 1.1 Sync Receive Service or the JMS 1.1 Async Receive Adapter, that the replyTo header object in the JMS Message header might be a class that is not present in the Sterling B2B Integrator dynamic class path.
- Add the jar to the Sterling B2B Integrator dynamic class path rather than using custom class loading.
- Provide a queue/topic name explicitly in the service.
What happens when the JMS provider goes down?
For more information about JMS 1.1 Pools, see the JMS 1.1 Pool documentation topic.
Do I need to shut down the pool every time I shut down my adapter?
- Shut down the adapter.
- Shut down the pool.
- Edit the parameters.
- Re-enable the adapter.
Failure to do so may result in having multiple pools with same name.
How is the pool affected when I edit my adapter rather than shutting it down?
If you edit your adapter instance before shutting it down and end up changing one of the pool parameters, you might end up with multiple pools with the same name.
How do I use transactions in JMS 1.1 Async Receive adapter?
Transactions can be enabled in JMS 1.1 Async Receive Adapter by setting the IS SESSION TRANSACTED parameter to YES.
- When the bootstrap mode is Default or Async: If the business process is kicked off in the async mode as soon as a message is received. But before kicking off the business process the payload is stored in database. The transaction is committed as soon as the persistence to database is successful. If the database is down, then the session is rolled back and the message is returned. Failure of bootstrapped business process does not ensure that the message is returned to the destination.
- When the bootstrap mode is Sync: Once a message is received the business process is kicked off in sync mode (until the time the business process has completed executing the new message is not picked up). The session is committed only if the bootstrapped business process has successfully finished. Failure in the business process results in returning the messaged back to the destination.
Why do I keep receiving the same message when using transactions in JMS 1.1 Async Receive adapter?
When using transactions, if a transaction is not committed (because of any failures) then the same message is returned. Depending on the redelivery policy of the destination and the message, the same message might be returned to this destination. You might receive the same message again. You should configure the redelivery mechanism at both destination and message level.
Customers can check to see if the received message is delivered for the first time or whether it is being redelivered, because the delivery failed first time by checking the JMSRedelivered message header of the received message. This value can either be true or false depending on whether the message is being redelivered or not. Depending on this flag, the bootstrapped business process may decide to choose or carry or ignore certain steps.
How do I set up a durable subscription in JMS 1.1 Async Receive adapter?
Setting up a durable subscription for the JMS 1.1 Async Receive adapter is similar to the setting up the JMS 1.1 Receive Message service. The first time the adapter is started the durable subscription is registered. You will need to restart the adapter to start getting messages using durable subscription.
How can I unsubscribe from a durable subscription in case of JMS 1.1 Async Receive Adapter?
Shutting down the adapter does not unsubscribe the durable subscription. To unsubscribe from durable subscription, run the following work flow:
Start >JMS 1.1 Release Connection and Session service > Stop
- RELEASE ACTION should be set as UNSUBSCRIBE DURABLE.
- RELEASE DURABLE SUBSRIBER should be provided with the durable subscriber name that was provided in the JMS 1.1 Receive Message Service.
- POOL NAME that was provided in the JMS 1.1 Acquire Connection and Session service when the JMS 1.1 Receive Message service was used.