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.
Preconfigured?	No
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: Remote JMS server context factory file name URL (IP address and port) Connection factory file name and location User name and password Public key for the CA or trusted certificates (if used) from the trading partner for access to their JMS server or system certificate (if used)
Platform availability	All supported platforms
Related services	Related services: JMS 1.1 Acquire Connection and Session service JMS 1.1 Release Connection and Session service JMS 1.1 Send Message service JMS 1.1 Request Reply service JMS 1.1 Receive Message service
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
Restrictions	Default
Persistence level	None
Testing considerations	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: 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.
Connection Type	Defines whether to use JNDI or not. Required. Valid values are: Using JNDI (Default) - Use JNDI when the JMS administered objects (such as, Connection Factory and Destination) needs to be looked up from the JNDI of the JMS provider. This can be useful if the provider wants to control the creation of these administered objects rather than JMS clients and wants to share the same across all the clients. Some vendors (WebLogic and JBoss) only support JNDI mode. Using Non -JNDI - If the client wants to create the administered objects in the client code. Several JMS vendors do not support Non-JNDI. If you need additional information to determine which connection type is supported by your vendor, consult the vendor documentation.
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: QUEUE (default) TOPIC
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 are: Yes No (default)
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 are: Default (default) - Async mode. On receiving a message a Business Process is kicked off in a separate thread. This ensures that the adapter is free to receive another message without waiting for the business process to finish. Using transactions here ensures that if system fails to persist the message then it is returned back to the provider. If the business process fails, then the message is NOT returned back. FIFO - First In First Out (FIFO) mode ensures that the bootstrapped business process runs in FIFO mode. It can be considered as an async mode that guarantees the ordering of bootstrapped business processes. FIFO mode can be used where order of the bootstrapped business process should be same as received message. FIFO provides the ability to kick off a business process in a separate thread, but ensures that the kicked off business processes follows the correct order. As a result, you should be careful when selecting your transaction strategy with FIFO. Non-Queued - Sync mode. On receiving a message a Business Process is kicked off in the same thread. This ensures that the adapter is blocked, new messages are not received until the business process has completed. Using transactions here ensures that if the business process fails, then the message is returned back.
Document Storage Type	Document storage type for received messages. Valid values are: System Default (default) Database File System
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 (V5.2.6.1 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: less than or equal to this value, the adapter receives the message. greater than this value, the adapter does not process the message.
Use Durable Subscriber	Ensures durable subscription to a topic. Optional. Only valid when Destination Type is TOPIC. Valid values are: Yes No (default)
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 are: SSL_NONE (default) SSL_MUST
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. When set to false (no), the third-party jars already installed are used. Default is False. When set to true (yes), the user does need not install the third-party jars; instead they can provide the path to the jar directory. The advantage of using custom class loading includes: Eliminates the need to restart the system every time a new vendor jar is added. Handles multiple versions of the same vendor jar. You should consider using the custom class loading in following scenarios: The JMS provider being used has jars that conflict with the jars already present in the system and are of a different version. You do not want to add JMS vendor jars in the Sterling B2B Integrator classpath as they might cause some conflicts. You can not afford to restart the system after adding JMS provider jars. You want to run several versions of JMS providers in the system. In that case adding the same vendor jar with multiple versions can cause conflict. You are not sure which jars to keep for the vendor and can not afford to restart the system for every jar combination they add. The only limitation is that in certain scenarios with custom class loading customers might have to change the JMS_EXCLUDES list. There is a standard list that has been provided in the documentation for well know vendors. You should review the JMS_EXCLUDES property for proper configuration. Permissions to the jar and directory need to be read for the user that the system is running as.
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: `D:\SI\install\jdk\bin\keytool -importcert -keystore D:\SI\install\jdk\jre\lib\security\cacerts -file D:\certs\AMQ_ROOT.cer -storepass changeit -noprompt` `D:\SI\install\jdk\bin\keytool -importcert -keystore D:\SI\install\jdk\jre\lib\security\cacerts -file D:\certs\AMQ_INTERMEDIATE.cer -storepass changeit -noprompt -alias AMQ_INTERMEDIATE` `D:\SI\install\jdk\bin\keytool -importcert -keystore D:\SI\install\jdk\jre\lib\security\cacerts -file D:\certs\AMQ_LEAF.cer -storepass changeit -noprompt -alias AMQ_LEAF` 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

Copy the bindings file from the WebSphereMQ server to any accessible location on the docker container where Sterling B2B Integrator is running.

docker cp <bindings file path>
<container_id:/ibm/resources>

Note: In a clustered environment, you must run 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 file:///<bindings_file_location>.

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.

If this is the situation, the system is unable to send the message to a destination specified in the replyTo header. To correct this, you will need to do one of the following:

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?

Yes. If you plan to change any of the pool parameters, you need to:

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.

There are two scenarios where transactions in async mode can be useful:

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

The parameters that need to be set in the JMS 1.1 Release Connection and Session service are:

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.