You can use Atomikos and IBM MQ for JMS/XA messaging. To do so, please follow the configuration instructions outlined below.

NOTE: these instructions have been tested with IBM MQ version 6.0.2.1 for all components (queue manager, extended client, and JMS jars).

Install the IBM "Extended Transactional Client"

If MQ is to participate in JTA/XA transactions then you need the "Extended Transactional Client" module from IBM. This is an additional set of JMS libraries licensed separately from MQ. Contact your IBM representative if you don't have this module.

Add the IBM jars to your classpath

You need to add the following jars to your classpath:

1. com.ibm.mqetclient.jar
2. com.ibm.mq.jar
3. com.ibm.mqjms.jar
4. com.ibm.mq.pcf.jar

The first jar file is included in the extended client installation, not in the default MQ installation. Don't forget any, or it will not work!

Create the server-side JMS objects

You need at least the following on the server:

• A queue manager
• An XA queue connection factory, bound in JNDI
• A queue (or topic), bound in JNDI

Ask your server administrator to create these for you.

Atomikos/Spring configuration

To configure Atomikos with Spring and MQ, you need to do the following:

• Look up the XA connection factory in JNDI (Spring can do this)
• Look up the queue (topic) in JNDI (Spring can do this)
• Create the AtomikosConnectionFactoryBean (in Spring)
• IMPORTANT: make sure that the AtomikosConnectionFactoryBean's uniqueResourceName property includes "MQSeries_XA_RMI"!

Example Spring config

The following shows an example Spring configuration fragment. Keep in mind that the jndi.properties should be set correctly for this to work (see your IBM documentation or ask your administrator).

<bean id="mqXaFactory" class="org.springframework.jndi.JndiObjectFactoryBean">
  <!-- set the JNDI name of the xa connection factory as configured on the server -->
  <property name="jndiName" value="..."/>
</bean>

<bean id="queue" class="org.springframework.jndi.JndiObjectFactoryBean">
  <!-- set the JNDI name of the queue as configured on the server -->
  <property name="jndiName" value="..."/>
</bean>

<bean id="atomikosConnectionFactory" class="com.atomikos.jms.AtomikosConnectionFactoryBean"
      init-method="init" destroy-method="close">
  <property name="xaConnectionFactory"><ref bean="mqXaFactory"/></property>
  <!-- IMPORTANT: the resourceName MUST contain MQSeries_XA_RMI -->
  <property name="uniqueResourceName" value="My_MQSeries_XA_RMI"/>
</bean>

Programmatic configuration of the XA connection factory

You can also choose to configure the XA connection factory programmatically. In that case, you need to create and configure an instance of

com.ibm.mq.jms.MQXAQueueConnectionFactory (for queues) or com.ibm.mq.jms.MQXATopicConnectionFactory (for topics).

What about the xa_open string?

The IBM Extended Client documentation refers to the xa_open string that needs to be defined. In Java and with JMS, this is all done by the connectors so you don't need to worry about this.

What about the xa_switch?

The IBM documentation also refers to the xa switch structure. Once again, this is taken care of by the JMS connectors so you don't need to worry. The only thing you need to do is ensure that the resourceName of the connection factory includes the string "MQSeries_XA_RMI" as outlined above.

WebSphere MQ Bug

IMPORTANT: Due to a WebSphere MQ Java Client error (version 7.0.1.0), the JMS Listener may not close connections to MQ Series and/or may have a memory leak when trying to retrieve a connection. This may even cause your queue manager to crash. Make sure you get the WebSphere MQ 7.0.1.4 Jar Files!