Configuring a Resource Adapter for JBoss AS7: OpenMQ

This tutorial shows how to configure a Resource Adapter on JBoss AS 7. The purpose of it, is connecting your MDB on another JMS provider (OpenMQ).

What is a Resource Adapter ? to keep it simple, imagine a resource adapter something analogous to a JDBC driver. Both provide a standard API through which an application can access a resource that is outside the JEE server. For a resource adapter, the outside resource is an EIS (Enterprise Information system) and allows a standard  way for EIS vendor's software to be integrated with JEE applications; on the other hand for a JDBC driver, it is a DBMS(Database Management System).

A resource adapter is stored in a RAR (Resource Adapter Archive) file and may be deployed on any JEE server, much like the EAR file of a JEE application.

 In this tutorial we will show how to configure a resource adapter for connecting with glassfish's OpenMQ messaging system. So the first step is getting the OpenMQ RA. This one can be downloaded from http://mq.java.net/downloads.html  or you can get it bundled into Glassfish distribution (under the folder "GLASSFISH_HOME\mq\lib" ).

So , once you have got the file imqjmsra.rar unzip it with a common unzip tool.
jboss as 7 resource adapter jca
As you can see, in the root folder you can find all the JARs which are used by OpenMQ and the Glassfish's naming context interfaces. In the META-INF folder there's the ra.xml file which contains all the information required to configure the Resource Adapter.

Now we need to configure the resource on JBoss AS 7: how can we do that ? JBoss AS 7 uses IronJacamar as JCA implementation.
The subsystem is contained into the AS 7 configuration file:

  <subsystem xmlns="urn:jboss:domain:jca:1.1">
  . . . . .
  </subsystem>

Now, the simplest way to create your resource adapter configuration is via the rar-info tool contained into the ironjacamar-1.x\doc\as folder. ( The official IronJacamar project page is  http://www.jboss.org/ironjacamar/ where you can download the software) .

The information about the resource adapter is generated using the following command:

./rar-info.sh imqjmsra.rar					

This will generate a report file named imqjmsra-report.txt.  This is the most important part of the report:

<resource-adapters>
  <resource-adapter>
    <archive>imqjmsra.rar</archive>
    <config-property name="UserName">guest</config-property>
    <config-property name="ConnectionURL">mq://localhost:7676/</config-property>
    <config-property name="Password">guest</config-property>
    <transaction-support>XATransaction</transaction-support>
    <connection-definitions>
      <connection-definition class-name="com.sun.messaging.jms.ra.ManagedConnectionFactory" enabled="true" jndi-name="java:jboss/eis/QueueConnection" pool-name="QueueConnection" use-ccm="true" use-java-context="true">
        <config-property name="UserName">guest</config-property>
        <config-property name="AddressList">localhost</config-property>
        <config-property name="Password">guest</config-property>
        <xa-pool>
          <min-pool-size>0</min-pool-size>
          <max-pool-size>10</max-pool-size>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
          <pad-xid>false</pad-xid>
          <wrap-xa-resource>true</wrap-xa-resource>
        </xa-pool>
        <security>
          <application/>
        </security>
      </connection-definition>
      <connection-definition class-name="com.sun.messaging.jms.ra.ManagedConnectionFactory" enabled="true" jndi-name="java:jboss/eis/QueueConnection" pool-name="QueueConnection" use-ccm="true" use-java-context="true">
        <config-property name="UserName">guest</config-property>
        <config-property name="AddressList">localhost</config-property>
        <config-property name="Password">guest</config-property>
        <xa-pool>
          <min-pool-size>0</min-pool-size>
          <max-pool-size>10</max-pool-size>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
          <pad-xid>false</pad-xid>
          <wrap-xa-resource>true</wrap-xa-resource>
        </xa-pool>
        <security>
          <application/>
        </security>
      </connection-definition>
      <connection-definition class-name="com.sun.messaging.jms.ra.ManagedConnectionFactory" enabled="true" jndi-name="java:jboss/eis/TopicConnection" pool-name="TopicConnection" use-ccm="true" use-java-context="true">
        <config-property name="UserName">guest</config-property>
        <config-property name="AddressList">localhost</config-property>
        <config-property name="Password">guest</config-property>
        <xa-pool>
          <min-pool-size>0</min-pool-size>
          <max-pool-size>10</max-pool-size>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
          <pad-xid>false</pad-xid>
          <wrap-xa-resource>true</wrap-xa-resource>
        </xa-pool>
        <security>
          <application/>
        </security>
      </connection-definition>
    </connection-definitions>
    <admin-objects>
      <admin-object class-name="com.sun.messaging.Queue" enabled="true" jndi-name="java:jboss/eis/ao/Queue" pool-name="Queue" use-java-context="true">

      </admin-object>
      <admin-object class-name="com.sun.messaging.Topic" enabled="true" jndi-name="java:jboss/eis/ao/Topic" pool-name="Topic" use-java-context="true">

      </admin-object>
    </admin-objects>
  </resource-adapter>
</resource-adapters>

We need applying just a little change to this XML: get rid of the resource-adapters and resource-adapter and archive root elements and replace them with the <ironjacamar> element as follows:
<?xml version="1.0" encoding="UTF-8"?>

<ironjacamar>

    <config-property name="UserName">guest</config-property>
    <config-property name="ConnectionURL">mq://localhost:7676/</config-property>
    <config-property name="Password">guest</config-property>
    <transaction-support>XATransaction</transaction-support>
    <connection-definitions>
      <connection-definition class-name="com.sun.messaging.jms.ra.ManagedConnectionFactory" enabled="true" jndi-name="java:jboss/eis/QueueConnection" pool-name="QueueConnection" use-ccm="true" use-java-context="true">
        <config-property name="UserName">guest</config-property>
        <config-property name="AddressList">localhost</config-property>
        <config-property name="Password">guest</config-property>
        <xa-pool>
          <min-pool-size>0</min-pool-size>
          <max-pool-size>10</max-pool-size>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
          <pad-xid>false</pad-xid>
          <wrap-xa-resource>true</wrap-xa-resource>
        </xa-pool>
        <security>
          <application/>
        </security>
      </connection-definition>

     <connection-definition class-name="com.sun.messaging.jms.ra.ManagedConnectionFactory" enabled="true" jndi-name="java:jboss/eis/QueueConnection" pool-name="QueueConnection" use-ccm="true" use-java-context="true">
        <config-property name="UserName">guest</config-property>
        <config-property name="AddressList">localhost</config-property>
        <config-property name="Password">guest</config-property>
        <xa-pool>
          <min-pool-size>0</min-pool-size>
          <max-pool-size>10</max-pool-size>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
          <pad-xid>false</pad-xid>
          <wrap-xa-resource>true</wrap-xa-resource>
        </xa-pool>
        <security>
          <application/>
        </security>
      </connection-definition>

      <connection-definition class-name="com.sun.messaging.jms.ra.ManagedConnectionFactory" enabled="true" jndi-name="java:jboss/eis/TopicConnection" pool-name="TopicConnection" use-ccm="true" use-java-context="true">
        <config-property name="UserName">guest</config-property>
        <config-property name="AddressList">localhost</config-property>
        <config-property name="Password">guest</config-property>
        <xa-pool>
          <min-pool-size>0</min-pool-size>
          <max-pool-size>10</max-pool-size>
          <prefill>false</prefill>
          <use-strict-min>false</use-strict-min>
          <flush-strategy>FailingConnectionOnly</flush-strategy>
          <pad-xid>false</pad-xid>
          <wrap-xa-resource>true</wrap-xa-resource>
        </xa-pool>
        <security>
          <application/>
        </security>
      </connection-definition>
    </connection-definitions>
    <admin-objects>
      <admin-object class-name="com.sun.messaging.Queue" enabled="true" jndi-name="java:jboss/eis/ao/Queue" pool-name="Queue" use-java-context="true">

      </admin-object>
      <admin-object class-name="com.sun.messaging.Topic" enabled="true" jndi-name="java:jboss/eis/ao/Topic" pool-name="Topic" use-java-context="true">

      </admin-object>
    </admin-objects>

</ironjacamar>

Deploying the Resource Adapter file (ironjacamar.xml)

The simplest way to deploy the Resource Adapter is using an exploded directory which will contain all the configuration files: create a dir named imqjmsra.rar and save the file created with rar-info under the META-INF folder of it, with the name ironjacamar.xml

 Next step are Resource Adapter libraries : since you might want to deploy remote JMS clients (using OpenMQ JNDI) it's better to install them as module so also other applications can use them.

Create the path modules\com\sun\openmq\main under your installation. There add the JAR files contained into imqjmsra.rar and configure the module in module.xml:

jboss as 7 resource adapter jca

<module xmlns="urn:jboss:module:1.1" name="com.sun.openmq">
    <properties>
        <property name="jboss.api" value="private"/>
    </properties>

    <dependencies>
        <module name="javax.jms.api" />
        <module name="javax.resource.api"/>
        <module name="javax.api"/>

    </dependencies>

    <resources>
       <resource-root path="fscontext.jar"/>
       <resource-root path="imqbroker.jar"/>
       <resource-root path="imqjmsbridge.jar"/>
       <resource-root path="imqjmsra.jar"/>
       <resource-root path="imqjmx.jar"/>
       <resource-root path="imqstomp.jar"/>

    </resources>
</module>

Fine, now let's return to our exploded folder and let's add the module dependency in MANIFEST.MF

Manifest-Version: 1.0
Dependencies: com.sun.openmq export

So this will be our imqjmsra.rar which will just contains three files into the META-INF folder:

imqjmsra.rar
+---META-INF
    ¦   ironjacamar.xml
    ¦   MANIFEST.MF
    ¦   ra.xml

So, when things go OK we should have finished with the resource adapter configuration. All we need is deploying the resource adapter into JBoss AS 7.
Unfortunately installing the RA took a lot more of headaches, since the OpenMQ RA does not seem 100% conform to ActivationSpec. But we fixed and with huge pleasure we managed to get it working!

Follow us on Twitter