Websphere MQ Integration with JBoss FAQ

Solution Verified - Updated -



This FAQ is not JBoss version specific, but specific version instructions may be added into the article or notes about the article.

1.  Where Can I find IBM information on integrating WebsphereMQ with JBoss?


Note: This article only addresses EJB2.x on JBoss using the IBM JCA adapter.  It also does not address some of the idiosyncrasies  of the IBM adapter, which is discussed in other JBoss wikis.  Please note that prior to opening a case with IBM, they will require you to get the Install Verification Tests to run.

2.  Where Can I find JBoss instructions for integrating WebsphereMQ with JBoss?


Note: This article specifically discusses how to install and configure the adapter for EJB2.x

3.  How can I test to see if my adapter is working correctly?

The following url will tell you how to test your adapter[http://www.ibm.com/developerworks/websphere/library/techarticles/0710_ritchie/0710_ritchie.html?ca=drs|http://www.ibm.com/developerworks/websphere/library/techarticles/0710_ritchie/0710_ritchie.html?ca=drs].

Note:  You need to use the following settings.  The settings in the instructions do not work for jboss 4.x and above due to the transaction engine.  You will get a classcast exception if you don't use these Settings.

Settings for IVTTest

Connection Factory:      java:IVTCF

Destination:             IVTQueue

Transactional Test:      Checked

Transactional Bean Name: WMQ_TransactedIVT

Note:  Please review the Install Verification Test and perform them prior to opening a ticket.  Also note that the following settings should be used in the test application.  If you use the IBM settings, you will get a ClassCastException using version 4.x.  So please use the following settings.

4.  How do I use the IBM adapter with JBoss EJB3?

Follow this link for instructions on configuring an EJB3 MDB with the IBM adapter.

5.  What does "WMQ Resource Adapter warning: MQJCA4005:Distributed transactions are not available in client mode" mean?

What it means is that you are trying to use the CLIENT transport(remote access) and XA together with the regular adapter(non-extended).  It means that you have configured your adapter to be XA, but the normal IBM JCA adapter does not support XA through the CLIENT transport mode.  XA transactions are only allowed in Client mode with the Extended Transactional client. Please read below.

6.  What is the Extended Transactional client?



7.  Does the IBM adapter support XA?

Yes and No.  IBM supports XA using the BINDING transport with the regular adapter.  IBM also supports XA in a remote protocol by using the CLIENT transport in the Extended Transaction Client.  Please note that the Extended transaction client is required to do XA when the WebsphereMQ server is not located on the same machine as the JBoss Server.  But also be aware that there are license costs associated with distributing the Extended Transaction Client to each of your JBoss Servers.

8.  What is the BINDING transport and the CLIENT transport for IBM clients.

BINDING transport

The CLIENT transport is an in memory transport that requires that the Queue Manager run on the same machine as the Adapter.   This means that the WebsphereMQ server be located on the same machine as the JBoss server.  The BINDING mode is required for XA using the regular adapter.

CLIENT transport

The CLIENT transport is a remote protocol that uses the network to send data back and forth.  In the normal Adapter, the CLIENT transport can not use XA.  In order to use XA remotely, you MUST use the Extended Transaction Client.

9.  I can't afford the license fees for the Extended Client Adapter(you must use for remote XA), but I need some sort of transaction handling for my MDBs.  What are my options?

  • Use the Binding Transport instead of the Client Transport.  This will require a queue manager on the JBoss Server.
  • Use the Extended Transactional Client.  It is freely distributed with your websphere server, but if used on another server such as jboss, IBM will require you to buy another IBM server License for it.
  • Use a non xa connection factory and throw your exception out of the onmessage

IBM will tell you that you should use the normal client and you should throw a Runtime Exception out of the onMessage.  This should roll the message back, but it doesn't(please read about the IBM defect in the adapter)


I say this because throwing an Exception out of the onMessage will throw away the instance of the MDB.  These instances are pooled for a reason, because they take resources to construct.  If you do this many times, it will cause performance degradation in the JBoss Container.


This was recently brought to the attention of Websphere MQ support.  We had several customers that were trying to get the message to rollback, using the normal adapter and following IBM support's recommendation to throw a RuntimeException out of the onMessage.  This was raised as an issue and it seemed that the adapter was eating the exception and not rolling the message back.

Please see this defect,it's fixed in, which has not come out as of the printing of this wiki.



10. I Get the following Exception "MQJMS2007: failed to send message to MQ queue linkedException: MQJE001: Completion Code 2, Reason 2072".  What does it mean.

Most likely what is happening is that the cohesion between the transaction and the session/connection is getting lost.  The JCA/JMS spec allow transaction interleaving.  This is also known as Transaction Stickyness.  The IBM adapter(s) don't support transaction interleaving, so you must set an attribute in order to pin the same connection to the transaction.

Add <track-connection-by-tx/> to your outbound tx-connection-factory defined in your -ds.xml file in JBoss.


(1) http://wiki.jboss.org/auth/wiki/JBossJCAPooling?action=e&windowstate=normal&mode=view

11.  I am getting "Destroying connection that could not be successfully matched.."

This issue is commonly caused by the security pooling parameters in your tx-connection-factory being removed. The resources are pooled by security credential so that they can be matched quickly. The default pool(onepool) is a singleton MRU list of supposedly equivalent connections. If you have different connections configured from the ConnectionRequestInfo(which you do with IBMMQ), you will run into this problem.

You should define <application-managed-security/>, which will pool users based on userid and password passed into the connection.


(1) http://wiki.jboss.org/auth/wiki/JBossJCAPooling?action=e&windowstate=normal&mode=view

(2) http://wiki.jboss.org/wiki/StrangePoolingConnectionsDestroyed

12.  Where Can I get patches for WebsphereMQ 6.0 patches(requires IBM login)?

IBM WebSphere MQ V6.0 Patches

13.  Do you have a link to a quick setup for Websphere MQ 6.0?

Jump start WebSphere MQ development on Linux

14.  How do I install and run the MQ Explorer.

Here is a pretty good guide to installing and running MQ Explorer remotely.

15.  I'm running MQ Exporer, and the QueueManager says it's running, but i right click and nothing happens.

What is probably happening is that you are not running the MQ Explorer as a different user than the preconfigured mqm user.  You need to run the explorer under the mqm user, because the commands under the gui are local script commands, which requires the mqm user.

16. What causes WebsphereMQ Resource Adapter warning: MQJCA4004:Message delivery to an MDB failed? See the linked exception for details.

This happens with XA JCA and max messages per session (maxMessages) greater than 1, and is explained by:


To resolve the issue, the definition of the ActivationSpec of your WebSphere MQ Resource Adapter must have the following:
maxPoolSize=10 (maxPoolDepth)

17. How to configure WebSphere MQ JMSProvider for XAResourceRecovery in JBoss EAP?

Our JMS recovery module is generic and you can use it for WebSphere MQ. All it needs is a JMSProvider. For instance, create <JBOSS_HOME>/server/<PROFILE>/deploy/wsmq-provider-service.xml:

 <mbean code="org.jboss.jms.jndi.JMSProviderLoader" name="jboss.jms:service=JMSProviderLoader,name=WSMQJMSProvider">
 <attribute name="ProviderName">WSMQJMSProvider</attribute>
 <attribute name="ProviderAdapterClass">org.jboss.jms.jndi.JNDIProviderAdapter</attribute>
 <attribute name="FactoryRef">ConnectionFactory</attribute>
 <attribute name="QueueFactoryRef">QueueConnectionFactory</attribute>
 <attribute name="TopicFactoryRef">TopicConnectionFactory</attribute>
 <attribute name="Properties">

The above JNDI properties must be set appropriately to connect to the remote WebSphere MQ server. (Please ask IBM about the properties.) For instance like the following:


The above FactoryRef properties need to be set accordingly as well. Also, the proper WSMQ jar(s) will need to be on the classpath. Copy the following libraries from WSMQ installation to <JBOSS_HOME>/server/<PROFILE>/lib. This is basically like configuring access from a remote, stand-alone client.

com.ibm.mqetclient.jar  (needed only for XA)

Then you can set the following JMS recovery module in the "jta" section in <JBOSS_HOME>/server/<PROFILE>/conf/jbossjta-properties.xml :

<property name="com.arjuna.ats.jta.recovery.XAResourceRecovery.WSMQ"

18. Where can I find JBoss EAP 5 Integration with WebSphereMQ?

[create another KB article and copy contents from http://community.jboss.org/wiki/JBossEAP5IntegrationwithWebSphereMQ and link it here]

19. How do I enable WebSphereMQ logging in JBoss EAP?


JAVA_OPTS="$JAVA_OPTS -DtraceEnabled=true -DtraceDestination=System.out -DtraceLevel=6 -DlogWriterEnabled=true"

to <JBOSS_HOME>/bin/run.conf

20. I see warnings in the WebSphereMQ log. Is this normal?

Certain warnings are expected. As an example:

CC=2;RC=2495;AMQ8568: The native JNI library 'mqjbnd' was not found. For a client installation this is expected. [3=mqjbnd] [com.ibm.mq.jmqi.JmqiException] at:
   java.security.AccessController.doPrivileged(Native Method)

occurs as the mqjbnd library is optional.

Subscriber exclusive content

A Red Hat subscription provides unlimited access to our knowledgebase of over 48,000 articles and solutions.

Current Customers and Partners

Log in for full access

Log In