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 "Switch" library that is supplied in the
bin directory of the integration node. There are 2 options:
- The library called JMSSwitch which manages XAResources that statically enlist with the
transaction coordinator.
- The library called DynJMSSwitch which manages dynamically enlisted XAresources.
- 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 Principal 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.