JMS Transactionality

JMS destinations that supply messages to a JMSInput node, or receive messages from a JMSOutput node, can be syncpoint coordinated as part of a message flow global transaction.

Transactions involving the Syncpoint coordinator

A diagram that depicts the message flow through a JMSInput node and a JMSOutput node, including a Synchpoint coordinator.

In this diagram, messages are consumed from a topic by a JMSInput node, and are produced to a JMS queue JMSOutput node. The nodes are connected with and are in session with a JMS provider. Any message flow input node can inform the external Syncpoint Coordinator when a message flow transaction starts and ends, and whether any resources that have been touched by the flow should be committed or rolled back.

The Syncpoint Coordinator sends XA/Open compliant requests to all participating Resource Managers to inform them to prepare. Any changes are then either committed or rolled back. Resource Managers such as WebSphere MQ, DB2 and any XA compliant JMS provider can participate in a global transaction. The external Syncpoint Coordinator is WebSphere MQ on distributed platforms, and RRS (Resource Recovery Services) on z/OS.

The JMSInput node and JMSOutput node can participate in a global transaction only if the JMS provider to which they connect supports the XA/Open interface through the JMS XAResource Class. An example JMS provider is the WebSphere MQ Java Client.

In-doubt transactions

In-doubt transactions can occur when a Resource Manager does not reply to a call from the Syncpoint manager, where the call is to commit or to rollback resources. During start up of the broker's WebSphere MQ queue manager, an initial recovery step is taken to ensure that any in-doubt transactions are resolved before the broker message flows start to process new input. A JMS provider that participates in broker global transactions is included in this recovery step.

Configuration to enable global transaction support

Additional configuration is required to enable global transaction support for the JMSInput and JMSOutput node. You must complete the following steps:
  1. Set the Message Flow property Coordinated Transaction to yes.
  2. For each JMSInput or JMSOutput node that is required to participate in the global transaction, set the Advanced property Transaction Mode to global.
  3. Create a queue connection factory and supply either a default name, recoverXAQCF or supply a user defined name. Refer to the JMSInput or JMSOutput node for further details on creating JNDI administered objects.
  4. On distributed platforms, an WebSphere MQ administration task is required prior to deployment. This task is needed to register a broker component with the queue manager. The component, which is referred to a Switch file, is a shared library (a DLL on Windows).

    When the broker's WebSphere MQ queue manager starts up, it loads the Switch file. The Switch file forwards XA/Open transaction calls from the Syncpoint Coordinator to the JMS Provider. This ensures that the JMS resources that participate in the transaction can be coordinated in synchronization with other Resource managers that are involved in the same transaction.

    The task varies by platform.
    • Linux and UNIX
      For the broker's queue manager for each JMS provider that can be used by a JMSInput node, place a stanza entry in an initialization file, for example qm.ini. The following is an example of a stanza entry that can be added when you are using WebSphere MQ Java as the JMS provider:
      XAResourceManager:
      	Name=WBIWMQJMS 
          SwitchFile=/<Installation Path>/lib/JMSSwitch.so
          XAOpenString=<Initial Context Factory>,
                    <location of JNDI bindings>'
                    <LDAP Principal>,
                    <LDAP Credentials>,
                    <Recovery Connection Factory Name>  
          ThreadOfControl=THREAD 
      Where:

      <Installation Path> is the location of the WebSphere Message Broker installation. This value is mandatory.

      The parameters that are supplied on the XAOpenString are comma delimited and positional. Any missing optional parameter must be represented by a comma if other parameters are provided later in the string.
      • <Initial Context Factory> This is the Initial Context Factory identifier for the JMS provider. This value is mandatory.
      • <Location of JNDI bindings> This is either the file path to the bindings file, or the LDAP directory location of the JNDI administered objects that can be used to create an initial context factory for the JMS connection. When supplying the file path to the bindings file, do not include the file name. Refer to the JMSInput or JMSOutput node for further details on creating the JNDI administered objects. This value is mandatory.
      • <LDAP Principal> This is an optional parameter that is used to specify the principal (user ID) that might be required when an LDAP database is used to hold the JNDI administered objects.
      • <LDAP Credentials> This is an optional parameter that is used to specify the Credentials (password) that might be required if a password protected LDAP database is used to hold the JNDI administered objects.
      • <Recovery Connection Factory Name> This is an optional parameter that is used to specify the name of a Queue Connection Factory object in the JNDI administered objects for recovery purposes, when the non default name is required.

      You must specify a stanza in the broker's queue manager .ini file for each JMS provider that you want to use, that is, there should be one stanza for each new JMS provider, where the JMS provider can be specified by any JMSInput or JMSOutput node included in a message flow that is running on a broker.

      The values for the Initial Context factory and Location of JNDI bindings in the stanza must match those specified in the JMSInput or JMSOutput nodes in the message flows.

      Any LDAP parameters must match those which have been specified by using the mqsicreatebroker or mqsichangebroker command.

      The Recovery Factory Name must match a Queue Connection Factory name that is created in the JNDI administered objects. If this is omitted, a default factory called recoverXAQCF is used. In either case this value must refer to a JNDI administered object that has already been created.

      The following is an example stanza:

      XAOpenString=com.sun.jndi.fscontext.RefFSContextFactory,
           /u/myJndiFileLocation,
           ,
           ,
           myRecoveryQCFName    
      Where the LDAP parameters are omitted, but a user defined Queue Connection Factory is specified for recovery.
    • On Windows platforms

      As with Linux and Unix, the same information is required on Windows but it is configured using the WebSphere MQ Explorer or WebSphere MQ Services snap-in depending on which version of WebSphere MQ you are using. On Windows, the Switch file is called JMSSwitch.dll. Refer to the WebSphere MQ System Administration Guide for details on how to update the qm.ini file. The extra entry, called the XACloseString, should match the values provided for the XAOpenString.

    • On z/OS

      In WebSphere Message Broker the only JMS provider currently supported is the IBM WebSphere MQ Java Client. The only transport mode currently supported for the client is BIND mode. No further configuration steps are required

    For further information, see the section on Configuring for coordinated transactions section within the JMSInput node and JMSOutput node topics.
  5. The JMS provider can supply additional jar files that are required for transactional support. Refer to the JMS provider documentation for more information. For instance, on distributed platforms (not z/OS), the WebSphere MQ JMS provider supplies an extra jar file com.ibm,mqetclient.jar. This jar must also be added to the broker shared_classes directory. On Windows, this directory is C:\Documents and Settings\All Users\Application Data\IBM\MQSI\shared-classes. For more information, refer to the section on making the JMS provider client available to the JMS Nodes in the following topics: JMSInput node.

Choice of JMS Provider

Any JMS provider that conforms to the Java Message Service Specification, version 1.1 and that supports the JMS XAResource API through the JMS session can be used if transaction coordination is required.

If the message designer has specified a non XA compliant provider, the non transactional mode only is supported. In this case, you must set the Transaction mode property to no for all JMSInput and JMSOutput nodes.

Related reference
JMS message types
JMS message structure
JNDI administered objects
JMSInput node
JMSOutput node