IBM Support

WebSphere MQ V6.0.2 and V7.0 resource adapter statement of support

Product documentation


Abstract

This document contains the statement of support for the WebSphere MQ resource adapter provided with WebSphere MQ V6.0.2 and V7.0

Content

WebSphere MQ V6.0.2 and V7.0 includes a J2EE Connector Architecture (JCA) V1.5 resource adapter. The resource adapter implements the JCA V1.5 interfaces and can be used in application servers that are certified as having passed the J2EE 1.4 (or later) Compatibility Test Suite to access the resources of a WebSphere MQ queue manager.

IBM has tested the resource adapters on the application servers shown below:

  • WebSphere Application Server Community Edition V1.0.0 and V1.1.0
  • JBoss Application Server V4.0.4 and V4.0.5

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


Using the resource adapter with WebSphere Application Server Version 6
The resource adapter should not be used with WebSphere Application Server Version 6. To access the resources of a WebSphere MQ queue manager from within WebSphere Application Server, the WebSphere MQ messaging provider should be used. Refer to the WebSphere Application Server Statement of Environment for information about supported environments:

In environments supported by WebSphere MQ V6 and WebSphere MQ V7, WebSphere Application Server Version 6 can be configured to use the WebSphere MQ classes for JMS to connect to a WebSphere MQ queue manager, provided that the WebSphere MQ client is installed on the same machine and operating system image. Please refer to the WebSphere Application Server V6 Information Center for details:


Using the resource adapter with WebSphere Application Server Version 7
The WebSphere MQ messaging provider in WebSphere Application Server Version 7 includes a version of the WebSphere MQ Version 7 Resource Adapter. To determine the level of Resource Adapter being used by the application server , the following Jython and JACL commands can be used:

    Jython
    wmqInfoMBeansUnsplit = AdminControl.queryNames("WebSphere:type=WMQInfo,*")
    wmqInfoMBeansSplit = AdminUtilities.convertToList(wmqInfoMBeansUnsplit)
    for wmqInfoMBean in wmqInfoMBeansSplit: print wmqInfoMBean; print AdminControl.invoke(wmqInfoMBean, 'getInfo', '')

    Note: You need to press Return twice after entering this command in order to run it.

    JACL
    set wmqInfoMBeans [$AdminControl queryNames WebSphere:type=WMQInfo,*]
    foreach wmqInfoMBean $wmqInfoMBeans {
    puts $wmqInfoMBean;
    puts [$AdminControl invoke $wmqInfoMBean getInfo [] []]
    }

Updates to the WebSphere MQ Resource Adapter that is installed with the application server are included in WebSphere Application Server Fix Packs.


Using the resource adapter with JBoss Application Server
For a detailed guide to how to set up the WebSphere MQ resource adapter with JBoss Application Server, please see the developerWorks article entitled " Installing and configuring WebSphere MQ resource adapter on JBoss Application Server".

JBoss Application Server V4 provides a function called session interleaving, where the same JMS session can be used in multiple transactions, although it is only enlisted in one at a time. This is not supported by the WebSphere MQ resource adapter, and can lead to the issues shown below:
  • An attempt to put a message to a WebSphere 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 WebSphere MQ queue manager being accessed from the application server.

To prevent these issues, and other transaction related problems, the following statements should be added to the wmq.jmsra-ds.xml file for every connection factory being used:

<track-connection-by-tx/>
<application-managed-security/>


When running the IVT, the default name for the JMS Connection Factory should be replaced with IVTCF, and the default name for the JMS Destination should be replaced with IVTQueue (this assumes that a tx-connection-factory with <jndi-name>IVTCF</jndi-name> and an admin object with <attribute-name="JNDIName">IVTQueue</attribute> was defined in the JBoss -ds.xml file. If different names were used, then the names used by the IVT should be changed as appropriate).


Using the resource adapter with WebSphere Application Server Community Edition
If the WebSphere MQ resource adapter is deployed on a WebSphere Application Server Community Edition (WAS CE) Version 1.0.1.1 server running with a Sun Java 1.5 environment, the resource adapter will fail on startup with an exception similar to the one shown below:

java.lang.ClassCastException: java.lang.String
at com.ibm.mq.connector.ResourceAdapterImpl$$FastClassByCGLIB$$5bac0b9d

This is due to a known incompatibility with the Apache Geronimo project used to build this version of WAS CE. See the following for more information:

http://publib.boulder.ibm.com/wasce/V1.1.0/en/Tasks/QuickStart.html

In order to use the WebSphere MQ resource adapter, the WAS CE instance must be running within an IBM Java Runtime Environment.


The WebSphere MQ "Using Java" manual states that the default value of the ActivationSpec property useJNDI is false. However, when the ActivationSpec is deployed into WAS CE, this is not the case - if the property is not explicitly set, useJNDI will default to the value true.


Using the resource adapter with Oracle WebLogic 11G R1
When using the resource adapter with Oracle WebLogic 11G R1, WebSphere MQ APAR IV14464 must be applied to the resource adapter, and the Java System Property:

com.ibm.mq.connector.performJavaEEContainerChecks=false

must be defined on the application server.

WebLogic 11G R1 provides session pooling functionality, which allows multiple JMS sessions to be created from a single JMS connection. Using this functionality with the WebSphere MQ resource adapter can lead to errors similar to the one shown below:

com.ibm.msg.client.jms.DetailedJMSException: MQJCA1018: Only one session per connection is allowed. The application attempted to create more than one JMS session on the same JMS connection. This exception occurs only if the application is running in a managed environment. Modify the application so that it creates only one JMS session on a JMS connection.

To resolve this issue, modify the deployment descriptor for the enterprise application that was running when the error occurred so that the res-type attribute in the resource reference is set to java.lang.Object. Here is an example, taken from the deployment descriptor for the WebSphere MQ Bridge for HTTP application:

<!-- Define the connection factory -->
<resource-ref>
<res-ref-name>jms/WMQHTTPJCAConnectionFactory</res-ref-name>
<!-- Set the res-type to be java.lang.Object, to disable session pooling -->
<res-type>java.lang.Object</res-type>
<res-auth>Container</res-auth>
</resource-ref>


General issues and workarounds
When performing outbound messaging, the resource adapter is configured to support distributed (XA) transactions by default. If CLIENT (TCP/IP) connections are used, then this requires the WebSphere MQ transactional client jar file (com.ibm.mqetclient.jar) to be present on the classpath. This requirement can be avoided by configuring the resource adapter to use local transactions. To do this, unpack wmq.jmsra.rar and edit META-INF/ra.xml.
The tag

<transaction-support>
XATransaction
</transaction-support>

should be changed to read

<transaction-support>
LocalTransaction
</transaction-support>

and the archive should then be repackaged.

Note that local transactions do not guarantee the same level of reliability that is provided by XA transactions, especially when multiple resources are used and failures occur before the transaction is committed. If transactional integrity is required in all situations then distributed transactions should be used.

Some servers will provide JCA ManagedConnection objects with a LogWriter object for diagnostic trace. If this is provided then trace is redirected to this object, which may cause trace to be split between two locations (the trace destination defined on the resource adapter, and the server log writer). To keep trace in the location defined on the resource adapter, the resource adapter property logWriterEnabled should be set to false, which causes the resource adapter to ignore the LogWriter object provided by the server.

Product Alias/Synonym

WebSphere MQ WMQ MQSeries

Document information

More support for: WebSphere MQ
Documentation

Software version: 6.0, 7.0

Operating system(s): AIX, HP-UX, IBM i, Linux, Solaris, Windows

Reference #: 7009524

Modified date: 02 October 2014


Translate this page: