Using WebSphere MQ JMS guide

This document explains how WebSphere MQ (formerly MQSeries) may be used as JMS provider within a JOnAS application server.

WebSphere MQ is the messaging platform developed by IBM. It provides Java and JMS interfaces. Documentation may be found at http://www-3.ibm.com/software/integration/mqfamily/library/manualsa/.

The document has been written after an integration work done with JOnAS 3.3 and 3.3.1 and WebSphere MQ 5.3.

The content of this guide is the following:

Architectural rules

WebSphere MQ, contrary to JORAM or SwiftMQ, can not run collocated with JOnAS. WebSphere MQ is an external software which needs to be independently administered and configured.

Administering WebSphere MQ consists in:

The link between JOnAS and WebSphere MQ will be established thanks to the registry. WebSphere MQ JMS objects will be bound to the JOnAS registry. JMS lookups will then return the WebSphere MQ JMS objects, and messaging will take place through these objects.

Given the complex configuration of WebSphere MQ JMS objects, it is not possible to create them from JOnAS. Thus, during the starting phase, a JOnAS server expects WebSphere MQ JMS objects to have already been bound to the registry. Obviously there is a need to start an independent registry, to which WebSphere MQ may bind its JMS objects, and which may also be used by the starting JOnAS server. The start-up sequence looks as follows:

  1. Starting a registry.
  2. Creating and binding WebSphere MQ JMS objects.
  3. Launching the JOnAS server.

The following architecture is proposed:

Setting the JOnAS environment

The proposed architecture requires to run two JOnAS server instances. In order to do that, the following steps are proposed:

  1. Create two base directories. For example JONAS_REGISTRY and JONAS_EJB.
  2. Set the JONAS_BASE environment variable so that it points towards the JONAS_REGISTRY directory.
  3. In the $JONAS_ROOT directory, type: ant create_jonasbase
  4. Set the JONAS_BASE environment variable so that it points towards the JONAS_EJB directory.
  5. In the $JONAS_ROOT directory, type: ant create_jonasbase

The JOnAS servers may now be configured independently.

Configuring the "Registry" server

The "Registry" server is the JOnAS server which will host the registry service. Its configuration files are in JONAS_REGISTRY/conf.

In the jonas.properties files, only declare the registry and jmx services:

jonas.services    registry,jmx

In the carol.properties file, declare the jeremie protocol:

carol.protocols=jeremie

You may also configure its port:

carol.jeremie.url=jrmi://localhost:2000

Configuring the "EJB" server

The "EJB" server is the JOnAS server which will be used as the application server. Its configuration files are in JONAS_EJB/conf. Libraries must be added in JONAS_EJB/lib/ext.

In the jonas.properties files, set the registry service as remote:

jonas.service.registry.mode    remote

In the carol.properties file, declare the jeremie protocol and set the correct port:

carol.protocols=jeremie
carol.jeremie.url=jrmi://localhost:2000

In lib/ext, the following libraries must be added:

Configuring WebSphere MQ

WebSphere MQ JMS administration is documented in chapter 5 of the "WebSphere MQ Using Java" document.

The configuration file of the JMS administration tool must be edited so that the JOnAS registry is used for binding the JMS objects. This file is the JMSAdmin.config file located in WebSphereMQ's Java/bin directory. Set the factory and provider URL as follows:

INITIAL_CONTEXT_FACTORY=org.objectweb.jeremie.libs.services.registry.jndi.JRMIInitialContextFactory
PROVIDER_URL=jrmi://localhost:2000

You also need to add JOnAS's client.jar library to WebSphere MQ's classpath.

When starting, JOnAS expects JMS objects to have been created and bound to the registry. Those objects are connection factories, needed for connecting to WebSphere MQ destinations, and destinations.

JOnAS automatically tries to access the following factories:

It one of these objects can't be found, JOnAS will simply print a message which looks as follows:

    JmsAdminForWSMQ.start : WebSphere MQ XAConnectionFactory could not be retrieved from JNDI

This does not prevent JOnAS from working. However if no connection factory at all is available, no JMS operations will be possible from JOnAS.

If destinations have been declared in the jonas.properties file, JOnAS will also expect to find them. For example, if the following destinations are declared:

jonas.service.jms.topics    sampleTopic
jonas.service.jms.queues    sampleQueue

The server expects to find the following JMS objects in the registry:

If one of the declared destination can't be retrieved, the following message appears, and the server stops:

    JOnAS error: org.objectweb.jonas.service.ServiceException : Cannot init/start service jms': org.objectweb.jonas.service.ServiceException : JMS Service Cannot create administered object: java.lang.Exception: WebSphere MQ Queue creation impossible from JOnAS

Contrary to connection factories, the JOnAS administration tool allows to create destinations. Since it is not possible to create WebSphere MQ JMS objects from JOnAS, this will work only if the destinations are preliminary created and bound to the registry.

For example, if you try to create through the JonasAdmin tool a queue named "myQueue", this will only work if:

Launching WebSphere MQ administration tool is simply done by typing: JMSAdmin

The following prompt appears: InitCtx>

Creating a QueueConnectionFactory, and binding it with name "JQCF" is done by typing:

    InitCtx> DEF QCF(JQCF)

More parameters may be put (for example for specifying the queue manager).

Creating a Queue, representing a WebSphere MQ queue named "myWSMQqueue", and binding it with name "sampleQueue" is done by typing:

    InitCtx> DEF Q(sampleQueue) QUEUE(myWSMQqueue)

Objects bound in the registry may be seen by typing:

    InitCtx> DIS CTX

Starting the application

Starting the registry server:

  1. Clean the local CLASSPATH: set/export CLASSPATH=""
  2. Set the JONAS_BASE variable so that it points towards JONAS_REGISTRY.
  3. Start the JOnAS server: jonas start -n Registry

Administering WebSphere MQ:

  1. In WebSphere MQ's Java/bin directory, launch the JMSAdmin tool: JMSAdmin
  2. Create the needed JMS objects.

Starting the EJB server:

  1. Clean the local CLASSPATH: set/export CLASSPATH=""
  2. Set the JONAS_BASE variable so that it points towards JONAS_EJB.
  3. Start the JOnAS server: jonas start -n EJB

Starting an EJB client:

  1. Add in the jclient classpath the ibm.com.mq.jar and ibm.com.mqjms.jar libraries.
  2. Launch the client: jclient ...

Limitations

Using WebSphere MQ as JMS transport within JOnAS raises some limitations compared to using JORAM or SwiftMQ.

First of all, WebSphere MQ is compliant with the old 1.0.2b JMS specifications. Code written following the JMS 1.1 latest spec (such as the jms samples provided with JOnAS) won't work with WebSphere MQ.

Depending on the WebSphere MQ distribution, JMS Publish/Subscribe may not be available. In this case, the message-driven bean samples provided with JOnAS won't work. That's why a specific sample is provided.

Finally, for an unknown reason, asynchronous consumption of messages (through message driven beans) does not work in transactional mode. Further inquiry is needed to solve this issue.