About this task
The JMS provider can be specified by a JMS or SOAP node that
is included in a message flow that is running on the integration
node.
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.
To
configure the queue manager for Linux and UNIX:
- Add a stanza to the queue manager .ini file
for each JMS provider, in the following format:
XAResourceManager:
Name=<Name>
SwitchFile=/install_dir/server/lib/JMSSwitch.so
XAOpenString=<Initial Context Factory>,
<location of JNDI bindings>'
<LDAP Principal>,
<LDAP Credentials>,
<Recovery Connection Factory Name>,
<JMS Principal>,
<JMS Credentials>
ThreadOfControl=THREAD
The parameters
for the stanza are as follows:
- <Name>
- Required. The name of the defined JMS provider resource manager.
- <SwitchFile>
- Required. The file system path to the JMSSwitch library that is
supplied in the bin directory of the
integration node.
- install_dir
- The location of the IBM® Integration Bus installation.
This value is required where the LDAP parameters are omitted,
but a user-defined Queue Connection Factory is specified
for recovery.
- <Initial Context Factory>
- Required. The Initial Context Factory identifier for the JMS provider.
This value is set in the JMSInput node
property Initial context
factory.
- <Location of JNDI bindings>
- Required. Use either the filepath 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.
If you supply a file path to the bindings file, do not include the
file name. For more information about creating the JNDI administered
objections, see JMSInput node or JMSOutput node.
The values for the Initial
Context factory and Location of JNDI bindings in
the stanza must match the values that you specified in the JMS or
SOAP nodes in the message flows.
- <LDAP Principal>
- Optional. Specify the principal (user ID) that might be required
when an LDAP database is used to hold the JNDI administered
objects. LDAP Credentials must
match the value that is set for the integration node by using
the mqsicreatebroker or
mqsichangebroker commands.
- <LDAP Credentials>
- Optional. Specify the Credentials (password) that might be required
if a password protected LDAP database is used to hold the
JNDI administered objects. LDAP
Credentials must match the value that is set for
the integration node by using the mqsicreatebroker or mqsichangebroker commands.
- <Recovery Connection Factory Name>
- Optional. Specify the name of a Queue Connection Factory object
in the JNDI administered objects for recovery purposes. 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.
- <JMS Principal>
- Optional. Provide the user ID required to connect to a JMS provider,
by using a secure JMS Connection Factory.
- <JMS Credentials>
- Optional. Provide the password that is required to connect to
the same JMS provider in conjunction with the JMS principal.
The JMS Principal and JMS Credentials must be configured
together.
The optional parameters are comma-separated
and are positional. Therefore, any parameters that are missing
must be represented by a comma, as seen in the following example
stanza.
The example stanza describes WebSphere® MQ Java™ as the JMS provider for global transactions:XAResourceManager:
Name=XAJMS_PROVIDER1
SwitchFile=/install_dir/server/lib/JMSSwitch.so
XAOpenString= com.sun.jndi.fscontext.RefFSContextFactory,
/Bindings/JMSProvider1_Bindings_Directory,
,
,
,
myJMSuser1,
passwd
ThreadOfControl=THREAD
where: - XAJMS_PROVIDER1 is the user-defined name for
the resource manager
- /install_dir/server/lib/JMSSwitch.so is
the installation path
- com.sun.jndi.fscontext.RefFSContextFactory is
the <Initial Context Factory>
- /Bindings/JMSProvider1_Bindings_Directory is
the location of the bindings file
- myJMSuser1 is the <JMS Principal>
- passwd is the password used in <JMS
Credentials>
In this example, the optional fields <LDAP Principal>, <LDAP
Credentials>, and <Recovery Connection
Factory Name> are not required, therefore the positional
comma delimiters only are configured in the XAOpenString stanza.
- Update the Java CLASSPATH
environment variable for the queue manager of the integration
node to include a reference to xarecovery.jar. For example:
install_dir/server/classes/xarecovery.jar
- Update the Java PATH
environment variable for the queue manager of the integration
node to point to the bin directory in which
the switch file is located. For example:
install_dir/server/bin
Switch files are installed in the
install_dir/server/lib directory. To simplify the contents of
the
qm.ini file, create a symbolic link to the switch file for the queue
manager to retrieve from the
/var/mqm/exits64 directory. For example:
ln -s install_dir/server/lib/libJMSSwitch.so /var/mqm/exits64/JMSSwitch
What to do next
Check your configuration:
- In the message flow, ensure that the coordinated property
is enabled by using the IBM Integration Bus Archive
editor.
- Ensure that each message flow node that is part of the XA transaction
is set to the global transaction mode.
- Ensure that the service ID that is used for the integration node
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 by 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
Transactional support in the
WebSphere MQ Version 7.5 product documentation
online.