IBM Integration Bus, Version 9.0.0.8 Operating Systems: AIX, HP-Itanium, Linux, Solaris, Windows, z/OS

See information about the latest product version

Configuring for coordinated JMS transactions

Configure your message flow to receive or output messages under coordinated transactions.

When you include a node using JMS transport in a message flow, such as the JMSInput or SOAPInput node when using JMS transport, the value that you set for Transaction mode defines whether messages are received under sync point.

If you set this property to Yes with the Coordinated transaction flow property selected, the message is received under external sync point coordination; that is, within a WebSphere® MQ unit of work. Any messages that are sent later, by an output node in the same instance of the message flow, are put under sync point, unless the output node overrides this setting explicitly.
If you set this property to Yes with the Coordinated transaction flow property not selected, the message is received under the local sync point control of the node. Any messages that are sent later, by an output node in the flow, are not put under local sync point, unless an individual output node specifies that the message must be put under local sync point.
If you set this property to No, the message is not received under sync point. Any messages that are sent later, by an output node in the flow, are not put under sync point, unless an individual output node specifies that the message must be put under sync point.

To receive messages under external sync point, you must take additional configuration steps, which need be applied only the first time that a specific node using JMS transport is deployed to the broker for a particular JMS provider.

On distributed systems, the external sync point coordinator for the broker is WebSphere MQ. Before you deploy a message flow in which the Transaction mode property is set to Global or Yes, and is intended to use XA coordinated transactions, modify the queue manager .ini file to include extra definitions for each JMS provider resource manager that participates in globally coordinated transactions.
- On Windows:
  1. Start WebSphere MQ Explorer.
  2. Right-click the queue manager name in the left pane and click Properties.
  3. Click XA resource managers in the left pane.
  4. Click Add... .
  5. Set the options as follows:
    - Set Name to any value.
    - On Windows on x86 systems, set the SwitchFile property to install_dir\bin\DynJMSSwitch.dll. On Windows on x86-64 systems, set the SwitchFile property to DynJMSSwitch.dll.
    - Set the XAOpenString property to a string value as follows: Initial Context,location JNDI,Optional_parms.
    - Set the ThreadOfControl property to Thread.
  6. On Windows on x86-64 systems only, copy the switch file DynJMSSwitch32.dll to the \exits subdirectory in the WebSphere MQ installation directory, and rename it to DynJMSSwitch.dll. Copy the switch file DynJMSSwitch.dll to the \exits64 subdirectory in the WebSphere MQ installation directory.
  For more information, see the System Administration Guide section of the WebSphere MQ Version 7 product documentation online.
- On Linux and UNIX systems, add a stanza to the queue manager .ini file for each JMS provider.
  For example:
```
XAResourceManager:
Name=Jms_Provider_Name 
SwitchFile=/install_dir/bin/DynJMSSwitch.so
XAOpenString=Initial Context,location JNDI,Optional_parms
ThreadOfControl=THREAD
```
  Where:
  Name
  
  is an installation defined name that identifies a JMS provider resource manager.
  
  SwitchFile
  
  is the file system path to the DynJMSSwitch library that is supplied in the bin directory of the broker.
XAOpenString can have the following values:
- Initial Context is the value that is set in the JMSInput node property Initial context factory.
- location JNDI is the value that is set in the JMSInput node property Location JNDI bindings. This value must include a supported URL prefix that has a URL handler that is available on the class path.
The following parameters are optional:
- LDAP Principal matches the value that is set for the broker by using the mqsicreatebroker or mqsichangebroker commands. LDAP Principal is not currently supported, it is reserved for future use.
- LDAP Credentials matches the value that is set for the broker by using the mqsicreatebroker or mqsichangebroker commands. LDAP Credentials is not currently supported, it is reserved for future use.
- Recovery Connection Factory Name is the JNDI administered connection factory that is defined in the bindings file. If a value is not specified, you must add a default value for recoverXAQCF to the bindings file. In either case, the Recovery Connection Factory must be defined as an XA Queue Connection Factory for the JMS provider that is associated with the Initial context factory.
The optional parameters are comma-separated and are positional. Therefore, any parameters that are missing must be represented by a comma. For example:
```
com.sun.jndi.fscontext.RefFSContextFactory,file:/C:/webservices/SOAP/JMS/JNDIXA,,,QCF
```
1. Update the Java™ CLASSPATH environment variable for the queue manager of the broker to include a reference to xarecovery.jar; for example:
```
install_dir/classes/xarecovery.jar
```
2. Update the Java PATH environment variable for the queue manager of the broker to point to the bin directory in which the SwitchFile is located; for example:
```
install_dir/bin
```
Finally, ensure that you have taken the following configuration steps:
- In the message flow, ensure that the coordinated property is enabled by using the IBM® Integration Bus Archive editor.
- Ensure that each node that must be part of the XA transaction is set to the global transaction mode.
- Ensure that the service ID that is used for the broker and the queue manager is the same user ID.
- Ensure that the JNDI connection factory objects that the JMS nodes use for a global transaction are configured to be of the type MQXAConnectionFactory, MQXAQueueConnectionFactory, or MQXATopicConnectionFactory.
  - If you create the bindings using IBM Integration Explorer, ensure the Support XA Transactions option is checked when you define your connection factory.
  - If you create the bindings using JMSAdmin, use the command DEF XAQCF or DEF XATCF, instead of DEF QCF or DEF TCF, when you define your connection factory.
For more information, see the System Administration Guide section of the WebSphere MQ Version 7 product documentation online.
On z/OS®, the external sync point manager is Resource Recovery Services (RRS). The only JMS provider that is supported on z/OS is WebSphere MQ JMS. The only transport option that is supported for WebSphere MQ JMS on z/OS is the bind option.
Sync point control for the JMS provider is managed with RRS sync point coordination of the queue manager of the broker. You do not have to modify the .ini file.

Restrictions using globally coordinated JMS transactions

Single XA Queue Manager

Only a single queue manager can be enabled for JMS or JDBC XA on a given machine or virtual image. Any number of additional queue managers that are not enabled for JMS or JDBC XA can be used simultaneously on the same machine as a queue manager enabled for JMS or JDBC XA.

Resource Managers must support transaction time-outs

In the event that the integration node or transaction manager, fails in such a way that for a particular transaction branch an XA_END call completes successfully but an XA_PREPARE call for the same transaction is issued by the Transaction Manager but not received by the Resource Manager: The transaction manager assumes that the Resource Manager will not persist this transaction because the Transaction Manager has not received a response from PREPARE.

Work falling in to this state is not recovered during XA recovery because the Resource Manager does not include it in the returned list of prepared transactions. Each individual resource manager has a responsibility to time-out this work. Until the transaction is timed out, this work might appear as uncommitted or pending on the Resource Manager.

This situation could arise when either the Transaction Manager or the IBM Integration Bus integration server performing XA work fails catastrophically (for example by crashing or abending).

In order to avoid uncommitted messages it is therefore required that every Resource Manager supports a transaction time-out. Where this support is provided via the standard JMS API it might be enabled via the environment variable MQSI_JMSXA_TRANSACTION_TIMEOUT which takes a value in seconds. Setting this environment variable causes IBM Integration Bus to attempt to set the transaction timeout using the XAResource.setTransactionTimeout() API. The same value is set on all JMS Resource Managers when this variable is set. It is the responsibility of the Resource Manager to honor this setting or otherwise provide server wide configuration for transaction timeouts.

Where the transaction time-out is configurable only using the Resource Manager administrative facilities, and not using the standard XAResource API then this means it is the customers responsibility to ensure that Resource Managers are correctly configured.

When the Syslog or MQ error logs indicates that either the Broker Queue Manager or any integration server processing XA workload has crashed, you should monitor the JMS queues at the JMS provider level to check for uncommitted transaction and to check that the transaction timeout is being honored.

Classloader Isolation is not supported

It is possible to deploy the jar files for a JMS client in a bar file, or to isolate JMSProviders in separate classloaders by setting a provider specific path in the jarsURL property of the JMS configurable service.

The XA Recovery process does not have access to the configurable service name, so all JMS Clients used in coordinated transactions must be located in the $MQSI_WORKPATH/shared-classes directory.

User name and password for connection to the JNDI is not supported

Setting a user name and password for connection to the JNDI provider or for the JMS connection, is not currently supported when a flow is enabled for dynamic XA registration. Support for this behavior in the future can be requested by raising a "Request for Enhancement" or RFE at the following URI https://www.ibm.com/developerworks/rfe/?PROD_ID=532

bc19030_.htm |

Last updated Friday, 21 July 2017