Installing and configuring WebSphere MQ resource adapter on JBoss Application Server

Learn how to install and configure WebSphere MQ resource adapter on JBoss Application Server V4, verify the install with the Install Verification Test, and enable diagnostic trace to analyze problems.

Ben Ritchie (ben.ritchie@uk.ibm.com), Staff Software Engineer, WebSphere MQ Client Development, EMC

Ben Ritchie is a software engineer at the IBM Hursley Software Lab in the UK, and he works as a Java developer on the WebSphere MQ Client Development team. Ben joined IBM in 2001 after completing a DPhil in astrophysics at the University of Sussex, and has worked with JMS ever since, first with WebSphere MQ Everyplace and more recently with WebSphere MQ. You can contact Ben at ben.ritchie@uk.ibm.com.


developerWorks Contributing author
        level

24 October 2007

Introduction

This article shows you how to install, configure, and troubleshoot the IBM® WebSphere® MQ resource adapter Install Verification Test (IVT) on JBoss Application Server.

WebSphere MQ resource adapter provides an implementation of the J2EE Connector Architecture (JCA) V1.5 interfaces, and is shipped with the WebSphere MQ V6.0.2.1 Fix Pack. WebSphere MQ resource adapter has been tested on JBoss 4.0.3SP1 and JBoss 4.0.4GA on Linux, and on JBoss 4.0.4CR2 and JBoss 4.0.5 on Windows. It is fully supported on any level of JBoss Application Server certified for J2EE 1.4. For more information about the resource adapter, the location of resource adapter files, and properties that can be defined on the resource adapter, see the WebSphere MQ resource adapter chapter in the WebSphere MQ V6.0.2.1 Using Java manual.

Installation

This section shows you how to install the WebSphere MQ resource adapter on JBoss. In addition it describes how to install the WebSphere MQ Extended Transactional Client to support XA distributed transactions in CLIENT transport mode, and how to configure the system to support BINDINGS mode connections to a WebSphere MQ Queue Manager.

Installing WebSphere MQ resource adapter

To install WebSphere MQ resource adapter, stop the JBoss server and copy the file wmq.jmsra.rar to the server deploy directory, for example <install path>/server/default/deploy The resource adapter will be automatically picked up when the server restarts. In order to use the resource adapter you must define JCA resources as described below.

Installing the WebSphere MQ Extended Transactional Client

The WebSphere MQ Extended transactional client lets you use XA distributed transactions with CLIENT mode connections to a WebSphere MQ queue manager. To install it on JBoss, stop the server and copy the file com.ibm.mqetclient.jar to the server lib directory, for example <install path>/server/default/lib. Then restart the server and verify the installation by running the transactional element of the Install Verification Test (IVT) (see below, Running the Install Verification Test), or by enabling diagnostic trace (see below, Enabling diagnostic trace). When trace is enabled and the transactional client was successfully installed, startup trace will contain the message:

Extended transactional client found

.

If installation was not successful or the transactional client was not installed, then startup trace will contain the message:

Extended transactional client not found
MQJCA4005:client-mode XA transactions are unavailable

If the transactional client has not been installed and CLIENT transport has been selected, then attempts to use XA transactions will fail by exception at run time with a JMSException:

javax.jms.JMSException: MQJCA1004:
XA transactions are unavailable

Using the WebSphere MQ Resource Adapter with BINDINGS transport

Bindings-mode connections to WebSphere MQ use the Java Native Interface (JNI) to connect to a WebSphere MQ queue manager. Bindings connections support XA transactions by default, but they require the WebSphere MQ queue manager to be installed on the same system as the application server. In addition, the queue manager installation must include the WebSphere MQ Java client install at the same level as the WebSphere MQ resource adapter. Therefore, you can use bindings-mode connections only when connecting to a WebSphere MQ V6 queue manager. Attempts to connect to a V5.3 queue manager in bindings mode will fail by exception.

The WebSphere MQ resource adapter uses CLIENT transport by default. In order to use BINDINGS transport, the transportType property on the JCA activationSpec or ConnectionFactory must be defined and set to BINDINGS. It may also be necessary to set the username property to a valid username on the system. Depending on how the system is configured, attempts to connect with a default blank username may fail with the message:

javax.jms.JMSSecurityException: MQJMS2013: 
invalid security authentication supplied for MQQueueManager

This exception may be linked to the top-level exception:

javax.jms.JMSException: MQJCA0001:
An exception occurred in the JMS layer. See the linked exception for details.

Configuring JCA resources

For details on the configuration properties available on WebSphere MQ JCA resources, see Appendix F of the WebSphere MQ Using Java manual.

The following sections describe how to define these resources on JBoss Application Server V4.

Configuring the resource adapter

The WebSphere MQ resource adapter lets you define a number of global properties. Four of these are related to diagnostic trace, while others let you define the behaviour of the connection pool for inbound message delivery and Message-Driven Bean reconnection parameters. Default values are defined in the ra.xml file included in the WebSphere MQ .rar file. Normally you can override then, but a limitation in JBoss means that resource adapter properties cannot be overridden with a -ds.xml file. Trace properties can be overridden using JVM system properties (see below, Enabling diagnostic trace), but you cannot override the connection pool values in this way. The default connection pool values are acceptable for normal operation, but if they need to be changed, then you must extract ra.xml from the WebSphere MQ .rar file, alter the default values in the XML, and repackage the .rar file before redeploying it on JBoss.

Configuring outbound message delivery

Resource definitions for outbound JCA flows are defined in a JBoss -ds.xml file named wmq.jmsra-ds.xml. The outline form of this file:

<?xml version="1.0" encoding="UTF-8"?>

<connection-factories>

  <!-- mbeans defining JCA administered objects -->
  <mbean ... >

  </mbean>

  <!-- JCA Connection factory definitions -->
  <tx-connection-factory>

  </tx-connection-factory>
</connection-factories>

The contents of the mbean and tx-connection-factory elements are described in more detail below.

Configuring JCA connection factories

JCA connection factories are defined in the

<connection-factories>
  <tx-connection-factory>
     ...
  </tx-connection-factory>
</connection-factories>

element of the wmq.jmsra-ds.xml file. Here is a typical definition:

  <tx-connection-factory>

    <!-- Bind this ConnectionFactory with the JNDI name IVTCF -->
    <jndi-name>IVTCF</jndi-name>

    <!-- Indicate that the connection factory supports XA transactions -->
    <xa-transaction />

    <!-- rar-name is the actual RAR file name, in this case wmq.jmsra.rar -->
    <rar-name>wmq.jmsra.rar</rar-name>

    <!-- connection-definition is the ConnectionFactory interface 
      defined in the ra.xml -->
    <connection-definition>
      javax.jms.ConnectionFactory
    </connection-definition>

    <!--
        Configuration for the ConnectionFactory. This defines the channel, hostname, port,
        queueManager, and transportType properties for a client (TCP/IP) connection to WMQ
    -->
    <config-property name="channel" type="java.lang.String">
      SYSTEM.DEF.SVRCONN
    </config-property>
    <config-property name="hostName" type="java.lang.String">
      192.168.0.42
    </config-property>
    <config-property name="port" type="java.lang.String">
      1414
    </config-property>
    <config-property name="queueManager" type="java.lang.String">
      ExampleQM
    </config-property>
    <config-property name="transportType" type="java.lang.String">
      CLIENT
    </config-property>

    <!-- define security domain ->
    <security-domain-and-application>JmsXARealm</security-domain-and-application>
  </tx-connection-factory>

You can include multiple ConnectionFactory definitions in the -ds.xml file, and any of the properties described in the WebSphere MQ JCA documentation may be defined.

Configuring JCA administered objects

JMS queues and topics are defined as JCA administered object mbeans in the wmq.jmsra-ds.xml file. Definitions are in

<connection-factories>
  <mbean code="org.jboss.resource.deployment.AdminObject" ... >
    ...
  </mbean>
</connection-factories>

elements, for example:

  <mbean code="org.jboss.resource.deployment.AdminObject"
      name="jca.wmq:name=ivtqueue">

    <!-- Bind this AdminObject  with the JNDI name IVTQueue -->
    <attribute name="JNDIName">
      IVTQueue
    </attribute>

    <!-- this MBean depends on the WebSphere MQ resource adapter -->
    <depends optional-attribute-name="RARName">
      jboss.jca:service=RARDeployment,name='wmq.jmsra.rar'
    </depends>

    <!-- this admin object is a javax.jms.Queue -->
    <attribute name="Type"<javax.jms.Queue</attribute>

    <!--
       Configuration for Queue TEST.QUEUE on queue manager ExampleQM. All messages sent 
       to this queue will have their expiry time overridden so that messages never expire
    -->
    <attribute name="Properties">
      baseQueueManagerName=ExampleQM
      baseQueueName=TEST.QUEUE
      expiry=EXP_UNLIMITED
    </attribute>
  </mbean>

As with ConnectionFactories, multiple AdminObjects can be defined in the -ds.xml file.

Configuring inbound message delivery

Message delivery to a Message-Driven Enterprise JavaBean (MDB) is configured using a standard ejb-jar.xml and a JBoss-specific file named jboss.xml, both located in the MDB .ear file. ejb-jar.xml is the standard Enterprise JavaBean deployment descriptor file, and declares a range of parameters about the beans contained in the archive. The contents of this file will vary, but will be of the form:

<?xml version="1.0"?>

<!DOCTYPE ejb-jar PUBLIC
   '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 1.1//EN'
   'http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd'>

<ejb-jar>
  <message-driven>
    <display-name>TestMDB</display-name>
    <ejb-name>TestMDB</ejb-name>
    <ejb-class>mdb.TestMessageDrivenBean</ejb-class>
    <messaging-type>javax.jms.MessageListener</messaging-type>
    <transaction-type>Container</transaction-type>
  </message-driven>
  <assembly-descriptor>

    <!-- include assembly descriptor here -->

  </assembly-descriptor>
</ejb-jar>

This deployment descriptor will be used in conjunction with a JBoss-specific deployment descriptor in jboss.xml, with the form:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE jboss PUBLIC  "-//JBoss//DTD JBOSS 4.0//EN"
   "http://www.jboss.org/j2ee/dtd/jboss_4_0.dtd">

<jboss>
   <enterprise-beans>
      <message-driven>

         <!-- name of the MDB -->
         <ejb-name>TestMDB</ejb-name>

         <!-- use the a JMS invoker bindings for message inflow driven beans -->
         <invoker-bindings>
           <invoker>
             <invoker-proxy-binding-name>message-inflow-driven-bean</
                 invoker-proxy-binding-name>
           </invoker>
         </invoker-bindings>

         <!-- instruct the MDB to use the WebSphere MQ resource adapter -->
         <resource-adapter-name>wmq.jmsra.rar</resource-adapter-name>

         <!-- WebSphere MQ resource adapter configuration properties for the MDB -->
         <activation-config>

         <!-- activation spec properties go here, for example

           <activation-config-property>
             <activation-config-property-name>destinationType</
                 activation-config-property-name>
             <activation-config-property-value>javax.jms.Queue</
                 activation-config-property-value>
           </activation-config-property>

         -->

         </activation-config>
      </message-driven>
   </enterprise-beans>
</jboss>

The activation-config section contains properties to set on the MDB activationSpec. A typical set for the WebSphere MQ resource adapter:

destinationType      javax.jms.Queue
destinationName   SYSTEM.DEFAULT.LOCAL.QUEUE
channel                    SYSTEM.DEF.SVRCONN
hostname               192.168.0.42
port                           1414
queueManager      ExampleQM
transportType        CLIENT

The destinationType and destinationName properties must be specified. Other properties are optional, and if omitted, take on their default values. These properties are defined in jboss.xml as follows:

   <activation-config>
     <activation-config-property>
        <activation-config-property-name>destinationType</activation-config-property-name>
        <activation-config-property-value>javax.jms.Queue</
            activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
        <activation-config-property-name>destination</activation-config-property-name>
        <activation-config-property-value>SYSTEM.DEFAULT.LOCAL.QUEUE</
            activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
        <activation-config-property-name>channel</activation-config-property-name>
        <activation-config-property-value>SYSTEM.DEF.SVRCONN</
            activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
        <activation-config-property-name>hostname</activation-config-property-name>
        <activation-config-property-value>192.168.0.42</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
        <activation-config-property-name>port</activation-config-property-name>
        <activation-config-property-value>1414</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
        <activation-config-property-name>queueManager</activation-config-property-name>
        <activation-config-property-value>ExampleQM</activation-config-property-value>
     </activation-config-property>
     <activation-config-property>
        <activation-config-property-name>transportType</activation-config-property-name>
        <activation-config-property-value>CLIENT</activation-config-property-value>
     </activation-config-property>
   </activation-config>

After ejb-jar.xml and jboss.xml have been defined, they should be included in the MDB .ear file and it should be copied to the server deploy directory. You should stop and restart the server for MDB deployment.


Running the Install Verification Test (IVT)

Defining resources

The IVT requires a Connection Factory and a JMS Queue or Topic to be defined before it can be run. The simplest definitions would be a Connection Factory named IVTCF with the properties:

channel          SYSTEM.DEF.SVRCONN
hostname         192.168.0.42
port             1414
queueManager     ExampleQM
transportType    CLIENT

and a JMS Queue named IVTQueue with the properties:

baseQueueName            SYSTEM.DEFAULT.LOCAL.QUEUE
baseQueueManagerName     ExampleQM

The channel and port names are default values and can be omitted, although it is good practice to specify queue manager properties as fully as possible. These objects are defined with the following wmq.jmsra-ds.xml file:

<?xml version="1.0" encoding="UTF-8"?>

<connection-factories>
  <!-- connection factory definition -->
  <tx-connection-factory>

    <jndi-name>IVTCF</jndi-name>
    <xa-transaction />
    <rar-name>wmq.jmsra.rar</rar-name>

    <connection-definition>
      javax.jms.ConnectionFactory
    </connection-definition>

    <config-property name="channel" type="java.lang.String">
      SYSTEM.DEF.SVRCONN
    </config-property>
    <config-property name="hostName" type="java.lang.String">
      192.168.0.42
    </config-property>
    <config-property name="port" type="java.lang.String">
      1414
    </config-property>
    <config-property name="queueManager" type="java.lang.String">
      ExampleQM
    </config-property>
    <config-property name="transportType" type="java.lang.String">
      CLIENT
    </config-property>

    <security-domain-and-application>JmsXARealm</security-domain-and-application>
  </tx-connection-factory>

  <!-- admin object definition -->
  <mbean code="org.jboss.resource.deployment.AdminObject"
      name="jca.wmq:name=ivtqueue">

    <attribute name="JNDIName">
      IVTQueue
    </attribute>
    <depends optional-attribute-name="RARName">
      jboss.jca:service=RARDeployment,name='wmq.jmsra.rar'
    </depends>
    <attribute name="Type">javax.jms.Queue</attribute>

    <attribute name="Properties">
      baseQueueManagerName=ExampleQM
      baseQueueName=SYSTEM.DEFAULT.LOCAL.QUEUE
    </attribute>
  </mbean>
</connection-factories>

This assumes that a running queue manager named ExampleQM exists at IP address 192.168.0.42. Substitute correct values as required.

Deploying the IVT servlet

To deploy the IVT servlet, copy wmq.jmsra.ivt.ear and the wmq.jmsra-ds.xml file above (or any other suitable -ds.xml file) to the JBoss server deploy directory, for example /opt/JBoss/server/default/deploy. JBoss will automatically deploy the servlet, which can be seen in the server output:

INFO  [AdminObject] Bound admin object 'com.ibm.mq.connector.outbound.MQQueueProxy' 
    at 'IVTQueue'
INFO  [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=
    ConnectionFactoryBinding,name=IVTCF' to JNDI name 'java:IVTCF'
INFO  [EARDeployer] Init J2EE application: file:/opt/jboss/server/default/deploy/
    wmq.jmsra.ivt.ear
INFO  [EjbModule] Deploying WMQ_TransactedIVT
INFO  [ProxyFactory] Bound EJB Home 'WMQ_TransactedIVT' to jndi 'WMQ_TransactedIVT'
INFO  [EJBDeployer] Deployed: file:/opt/jboss/server/default/tmp/deploy/
    tmp37991wmq.jmsra.ivt.ear-contents/WMQ_TransactedIVT.jar

You should restart the server after deployment.

Running the IVT servlet

Once the servlet is deployed, you can access it at http://<hostname>:8080/WMQ_IVT/, where <hostname> should be replaced with the IP address or hostname of the system being used. You should see a page like this:

Figure 1
Figure 1

You can use default values, but if distributed transactions are to be used, the IVT transacted test should also be enabled by checking Transactional test. This option triggers an additional test using a transacted EJB to ensure that the additional resources required to support XA transactions have been configured on the system. When the servlet is run, the following page should be seen if the IVT completed successfully:

Figure 2
Figure 2

Because of JBoss naming conventions, add a java: prefix to the Connection Factory name and remove the /ejb/ejbs/ prefix from the EJB name. The IVT does this automatically. If an error occurs, the IVT will halt at the step that caused the failure, for example:

Figure 3
Figure 3

Click View stack trace to show the full exception stack trace for the failure:

Figure 4
Figure 4

In this case, the root cause of the failure was an MQException with reason code 2059 MQRC_Q_MGR_NOT_AVAILABLE, and the IVT failed because the servlet could not connect to the WebSphere MQ Queue Manager because it had not been started.


Enabling diagnostic trace

The WebSphere MQ resource adapter lets you configure diagnostic trace as a property on the resource adapter or by setting JVM system properties. JBoss limitations prevent you from enabling trace as a resource adapter property without extracting and editing ra.xml, and the recommended method is to use JVM system properties. On systems that use run.sh, you can set these by editing the JBoss run.conf file in the /bin directory to include the following JVM properties:

# Settings to enable WebSphere MQ resource adapter trace
JAVA_OPTS="-DtraceEnabled=true -DtraceDestination=wmq_jca.trc 
    -DtraceLevel=10 -DlogWriterEnabled=false"

while on Windows systems these options are set in run.bat:

set JAVA_OPTS=%JAVA_OPTS% -DtraceEnabled=true 
    -DtraceDestination=wmq_jca.trc -DtraceLevel=10 -DlogWriterEnabled=false

These options enable trace and direct all output to the file wmq_jca.trc in the working directory. By default JBoss will pass JCA ManagedConnectionFactories a reference to an org.jboss.logging.util.LoggerPluginWriter that redirects diagnostic output to the JBoss log4j INFO stream. This procedure splits the WebSphere MQ resource adapter trace between two locations: startup trace goes to the destination defined by the traceDestination parameter, while subsequent trace goes to the JBoss INFO stream. To prevent this split, either configure JBoss to not pass a PrintWriter to the JCA ManagedConnectionFactory, or else specify logWriterEnabled=false to instruct the resource adapter to ignore the PrintWriter supplied by the server. Either step will cause all resource adapter trace to be directed to a single location.

In the event that the WebSphere MQ resource adapter trace is not sufficient to diagnose a problem, you can enable WebSphere MQ JMS client trace using the -DMQJMS_TRACE_LEVEL=base system property, which may be combined with the properties used for configuring resource adapter trace:

# Settings to enable WebSphere MQ resource adapter trace
JAVA_OPTS="-DtraceEnabled=true -DtraceDestination=wmq_jca.trc 
    -DtraceLevel=10 -DlogWriterEnabled=false -DMQJMS_TRACE_LEVEL=base"

or

set JAVA_OPTS=%JAVA_OPTS% -DtraceEnabled=true -DtraceDestination=wmq_jca.trc 
    -DtraceLevel=10 -DlogWriterEnabled=false -DMQJMS_TRACE_LEVEL=base

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=264500
ArticleTitle=Installing and configuring WebSphere MQ resource adapter on JBoss Application Server
publish-date=10242007