IBM MQ resource adapter statement of support

The resource adapter that comes with IBM MQ Version 8.0 or later implements the JMS 2.0 specification. It can be deployed only into an application server that is Java Platform, Enterprise Edition 7 (Java EE 7) compliant and therefore supports JMS 2.0.

A list of certified application servers is maintained on Oracle's web site.


Deployment within WebSphere Liberty

WebSphere Application Server Liberty Version 8.5.5, Fix Pack 6 and later, and WebSphere Application Server Liberty Version 9.0 and later are Java EE 7 certified application servers so the IBM MQ Version 9.0 resource adapter can be deployed into them.

WebSphere Liberty has two features available for working with resource adapters:

  • The wmqJmsClient-1.1 feature to allow working with JMS 1.1 resource adapters.
  • The wmqJmsClient-2.0 feature to allow working with JMS 2.0 resource adapters.

Important: The IBM MQ Version 8.0 or later resource adapter must be deployed with the wmqJmsClient-2.0 feature.

Information on this configuration is in the Scenario Connect WebSphere Liberty Liberty to IBM MQ.


Deployment within WebSphere Application Server traditional

WebSphere Application Server traditional Version 9.0 is supplied with an IBM MQ Version 9.0 resource adapter already installed. Therefore, there is no requirement to install a new resource adapter. The installed resource adapter can connect in CLIENT or BINDINGS transport mode to any queue managers that are running on a supported version of IBM MQ or IBM WebSphere MQ. For more information, see Connectivity to IBM MQ Version 8.0 or later queue managers.

Important: The IBM MQ Version 9.0 resource adapter cannot be deployed into versions of WebSphere Application Server traditional before Version 9.0, as these versions are not Java EE 7 certified.

Any supported version of WebSphere Application Server can use the IBM MQ resource adapter that is bundled with it to connect to any supported version of IBM MQ.


Use the resource adapter with other application servers

For all other Java EE 7 compliant application servers, problems that occur following the successful completion of the IBM MQ resource adapter Installation Verification Test (IVT) can be reported to IBM for the investigation of IBM MQ product trace and other IBM MQ diagnostic information. If the IBM MQ resource adapter IVT cannot be run successfully, any problems that are encountered are likely to be caused by incorrect deployment or incorrect resource definitions that are application server specific and the problems must be investigated by using the application server documentation and/or the support organization for that application server.


Java Runtime

The Java Runtime (JRE) that is used to run the application server must be one that is supported with the IBM MQ Version 9.0 or later Client. For more information, see System Requirements for IBM MQ. (Select which version and operating system or component report we want to see then follow the Java link that is listed under the Supported Software tab.)


Connectivity to IBM MQ Version 8.0 or later queue managers

The full range of JMS 2.0 functionality is available when connecting to a Version 8.0 or later queue manager by using the resource adapter that has been deployed into a Java EE 7 certified application server. For more information about the versions of the resource adapter that are shipped with WebSphere Application Server, see the technote Which version of WebSphere MQ Resource Adapter (RA) is shipped with WebSphere Application Server?.

To make use of the JMS 2.0 functionality, the resource adapter needs to connect to the queue manager by using IBM MQ messaging provider normal mode. For more information, see Configure the JMS PROVIDERVERSION property.


Connectivity to IBM WebSphere MQ Version 7.5 or earlier queue managers

It is supported to deploy the IBM MQ Version 9.0 or later resource adapter into a Java EE 7 certified application server that supports JMS 2.0 and connect that resource adapter to a queue manager that is running IBM WebSphere MQ Version 7.5 or earlier. The functionality that is available is limited by the capabilities of the queue manager. For more information, see Configure the JMS PROVIDERVERSION property.


MQ Extensions

The JMS 2.0 specification introduces changes to how certain behaviors work. Because IBM MQ Version 8.0 or later implements this specification, there are changes in behavior between IBM MQ Version 8.0 and later and versions of IBM WebSphere MQ before IBM MQ Version 8.0. In Version 8.0 or later, the IBM MQ classes for JMS include support for the Java system property com.ibm.mq.jms.SupportMQExtensions that, when set to TRUE, causes these versions of IBM MQ to revert these behaviors to those of IBM WebSphere MQ Version 7.5 or earlier. The default value of the property is FALSE.

The IBM MQ Version 9.0 or later resource adapter also includes a resource adapter property called supportMQExtensions that has the same effect and default value as the com.ibm.mq.jms.SupportMQExtensions Java system property. This resource adapter property is set to false in the ra.xml by default.

If both the resource adapter property and Java system property are set, then the system property has precedence.

Note that within the resource adapter that is already deployed within WebSphere Application Server traditional Version 9.0, this property is automatically set to TRUE to aid migration.

For more information, see SupportMQExtensions property.


General issues

    Session interleaving is not supported
    Some application servers provide a capability called session interleaving, where the same JMS session can be used in multiple transactions, although it is only enlisted in one at a time. The IBM MQ resource adapter does not support this capability, which can lead to the following issues: 
    An attempt to put a message to a MQ queue fails with reason code 2072 (MQRC_SYNCPOINT_NOT_AVAILABLE).
    Calls to xa_close() fail with reason code -3 (XAER_PROTO), and an FDC with probe ID AT040010 is generated on the IBM MQ queue manager being accessed from the application server. For information on how to disable this capability, see the application server documentation.

    Java Transaction API (JTA) specification of how XA resources are recovered for XA transaction recovery
    Section 3.4.8 of the JTA specification does not define a specific mechanism by which XA resources are re-created to perform XA transactional recovery. As such, it is up to each individual transaction manager (and, therefore, the application server) how XA resources involved in an XA transaction are recovered. It is possible that, for some application servers, the IBM MQ Version 9.0 resource adapter does not implement the application server specific mechanisms that are used to perform XA transactional recovery.

    Matching connections in a ManagedConnectionFactory
    An application server can invoke the matchManagedConnections method on a ManagedConnectionFactory instance provided by the IBM MQ resource adapter. A ManagedConnection is returned only if the method finds one that matches both the javax.security.auth.Subject and javax.resource.spi.ConnectionRequestInfo arguments that were passed to the method by the application server.

Parent topic: Use the IBM MQ resource adapter