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:
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:
The following architecture is proposed:
The proposed architecture requires running two JOnAS server instances. For this, the following steps are proposed:
The JOnAS servers can now be configured independently.
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
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:
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
To start the registry server:
To administer WebSphere MQ:
To start the EJB server:
To start an EJB client:
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.