Howto: Using WebSphere MQ JMS guide

This document explains how WebSphere MQ (formerly MQSeries) can 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 is located at http://www-3.ibm.com/software/integration/mqfamily/library/manualsa/.

This document was written after 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, cannot run collocated with JOnAS. WebSphere MQ is an external software which must be independently administered and configured.

Administering WebSphere MQ consists of the following:

The link between JOnAS and WebSphere MQ is established via the registry. WebSphere MQ JMS objects are 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 these objects from JOnAS. Therefore, during the starting phase, a JOnAS server expects that WebSphere MQ JMS objects have already been bound to the registry. Thus it is necessary to start an independent registry to which WebSphere MQ can bind its JMS objects, and which can also be used by the starting JOnAS server. The start-up sequence looks like the following:

  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 running two JOnAS server instances. For this, the following steps are proposed:

  1. Create two base directories: e.g., JONAS_REGISTRY and JONAS_EJB.
  2. Set the JONAS_BASE environment variable so that it points to 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 to the JONAS_EJB directory.
  5. In the $JONAS_ROOT directory, type: ant create_jonasbase.

The JOnAS servers can now be configured independently.

Configuring the "Registry" server

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

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

jonas.services    registry,jmx

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

carol.protocols=jeremie

Its port can also be configured:

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

Configuring the "EJB" server

The "EJB" server is the JOnAS server that 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

... and the JMS service as WebSphere MQ:

jonas.service.jms.mom    org.objectweb.jonas_jms.JmsAdminForWSMQ

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

The JOnAS's client.jar library must also be added to the classpath for WebSphere MQ.

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:

If one of these objects cannot be found, JOnAS will print a message that looks like the following:

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

This does not prevent JOnAS from working. However, if there is no connection factory 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 cannot 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 destinations to be created. Since it is not possible to create WebSphere MQ JMS objects from JOnAS, this will work only if the destinations are previously created and bound to the registry.

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

To launch WebSphere MQ administration tool, type: JMSAdmin

The following prompt appears: InitCtx>

To create a QueueConnectionFactory and binding it with name "JQCF", type:

    InitCtx> DEF QCF(JQCF)

More parameters can be entered (for example for specifying the queue manager).

To create a Queue that represents a WebSphere MQ queue named "myWSMQqueue", and to bind it with name "sampleQueue", type:

    InitCtx> DEF Q(sampleQueue) QUEUE(myWSMQqueue)

Objects bound in the registry can be viewed by typing:

    InitCtx> DIS CTX

Starting the application

To start the registry server:

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

To administer WebSphere MQ:

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

To start the EJB server:

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

To start 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 has some limitations, as compared with using JORAM or SwiftMQ.

First of all, WebSphere MQ is compliant with the old 1.0.2b JMS specifications. Code that is written following the JMS 1.1 latest spec (such as the jms samples provided with JOnAS) will not 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 will not work. For this reason, 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 resolve this issue.