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:
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:
The following architecture is proposed:
The proposed architecture requires to run two JOnAS server instances. In order to do that, the following steps are proposed:
The JOnAS servers may now be configured independently.
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
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:
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 registry server:
Administering WebSphere MQ:
Starting the EJB server:
Starting an EJB client:
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.