Liberty and the IBM MQ resource adapter

The IBM® MQ resource adapter can be installed into WebSphere® Liberty 8.5.5 Fix Pack 2 or later, by using either the wmqJmsClient-1.1 or wmqJmsClient-2.0 feature, depending on which version of the resource adapter you are installing. Alternatively you can, subject to some restrictions, install the resource adapter by using generic Java Platform, Enterprise Edition Connector Architecture (Java EE JCA) support.

General restrictions when installing the resource adapter into Liberty

The following restrictions apply to the resource adapter when using either the wmqJmsClient-1.1 or wmqJmsClient-2.0 feature and also when using generic JCA support:

The IBM MQ classes for Java are not supported in Liberty. They must not be used with either the IBM MQ Liberty messaging feature or with the generic JCA support. For more information, see Using WebSphere MQ Java Interfaces in J2EE/JEE Environments.
The IBM MQ resource adapter has a transport type of BINDINGS_THEN_CLIENT. This transport type is not supported within the IBM MQ Liberty messaging feature.
Before IBM MQ 9.0, the Advanced Message Security (AMS) feature was not included in the IBM MQ Liberty messaging feature. However, AMS is supported with an IBM MQ 9.0 or later resource adapter.

Note: On IBM MQ versions greater than IBM MQ 9.0.0.6 and IBM MQ 9.1.0.1 you should use the transportSecurity-1.0 feature instead of the ssl-1.0 feature.

For more information, see:

Restrictions when using the Liberty features

With WebSphere Liberty 8.5.5 Fix Pack 2 to WebSphere Liberty 8.5.5 Fix Pack 5 inclusive, only the wmqJmsClient-1.1 feature was available and only JMS 1.1 could be used. WebSphere Liberty 8.5.5 Fix Pack 6 added the wmqJmsClient-2.0 feature so JMS 2.0 could be used.

However, the feature that you must use depends on which version of the resource adapter you are using:

The IBM WebSphere MQ 7.5.0 Fix Pack 6 and later resource adapter can be used with the wmqJmsClient-1.1 feature only.
The IBM MQ 8.0.0 Fix Pack 3 and later IBM MQ 8.0 resource adapter can be used with wmqJmsClient-2.0 feature only.
The IBM MQ 9.0 resource adapter can be used with wmqJmsClient-2.0 feature only.

Restrictions when using generic JCA support

If you are using generic JCA support, the following restrictions apply:

You must specify the level of JMS when using the generic JCA support:
- JMS 1.1 and JCA 1.6 must be used only with the IBM WebSphere MQ 7.5.0 Fix Pack 6 and later IBM WebSphere MQ 7.5 resource adapters.
- JMS 2.0 and JCA 1.7 must be used only with the IBM MQ 8.0.0 Fix Pack 3 and later IBM MQ 8.0 resource adapters.
It is not possible to run the IBM MQ resource adapter on z/OS® using generic JCA support. In order to run the IBM MQ resource adapter on z/OS, it must be run with the wmqJmsClient-1.1 or wmqJmsClient-2.0 feature.

The location of the resource adapter is specified by using the following xml element:

<resourceAdapter id="mqJms" location="${server.config.dir}/wmq.jmsra.rar">
  <classloader apiTypeVisibility="spec, ibm-api, api, third-party"/>        
</resourceAdapter>

Important: The value of the ID tag can be anything EXCEPT for wmqJms. If you do use wmqJms as the ID, then Liberty is not able to properly load the resource adapter. This is because wmqJms is the ID that is used internally to refer to the specific feature for IBM MQ. It actually creates a NullPointerException.

The following examples show some snippets from a server.xml file:

<!-- Enable features -->    
  <featureManager>       
    <feature>servlet-3.1</feature>     
    <feature>jndi-1.0</feature>    
    <feature>jca-1.7</feature>      
    <feature>jms-2.0</feature>   
  </featureManager>

Tip: Note the use of the jca-1.7 and jms-2.0 features and the lack of the wmqJmsClient-2.0 feature.

<resourceAdapter id="mqJms" location="${server.config.dir}/wmq.jmsra.rar">
  <classloader apiTypeVisibility="spec, ibm-api, api, third-party"/>        
</resourceAdapter>

Tip: Note the use of mqJms for the ID, which is preferred. Do not use wmqJms.

<application id="WMQHTTP" location="${server.config.dir}/apps/WMQHTTP.war" 
name="WMQHTTP" type="war">    
    <classloader apiTypeVisibility="spec, ibm-api, api, third-party" 
classProviderRef="mqJms"/>    
</application>

Tip: Note the classloaderProviderRef back to the resource adapter through the id mqJms; this is to permit IBM MQ specific classes to be loaded.

Restrictions when tracing using generic JCA support

Tracing, and logging are not integrated within the Liberty trace system. Instead, the IBM MQ resource adapter trace must be enabled using either Java system properties, or an IBM MQ classes for JMS configuration file, as described in Tracing IBM MQ classes for JMS applications. For details about how to set Java system properties in Liberty, see the WebSphere Liberty documentation.

For example, in order to enable trace of IBM MQ resource adapter in Liberty 19.0.0.9, add an entry to the Liberty file jvm.options:

Create a text file named jvm.options.

Insert the following JVM options to enable tracing, one per line, into this file:

-Dcom.ibm.msg.client.commonservices.trace.status=ON
-Dcom.ibm.msg.client.commonservices.trace.outputName=C:\Trace\MQRA-WLP_%PID%.trc

To apply these settings to a single server, save jvm.options at:
```
${server.config.dir}/jvm.options
```
To apply these changes to all Liberty, save jvm.options at:
```
${wlp.install.dir}/etc/jvm.options
```
This will take effect for all JVMs that do not have a locally defined jvm.options file.
Restart the server to enable changes.

This results in trace being written to a trace file called MQRA-WLP_<process identifier>.trc in the directory <path_to_trace_to>.

Full Liberty XA support with client channel definition tables

When using WebSphere Liberty 18.0.0.2 onwards, with IBM MQ 9.2.0, you can make use of queue manager groups within the client channel definition table (CCDT) in conjunction with XA transactions. This means that it is now possible to make use of workload distribution and availability, provided by queue manager groups, whilst maintaining transaction integrity.

In the event of connectivity errors to a queue manager, the queue manager needs to become available again so that the transaction can be resolved. The transaction recovery is managed by Liberty, and you might need to configure the transaction manager, so that an appropriate period of time is allowed for the queue managers to become available again. For more information, see Transaction manager (transaction) in the WebSphere Liberty product documentation.

This is a client-side feature, that is, you need an IBM MQ 9.2.0 resource adapter, not an IBM MQ 9.2.0 queue manager.