Please note that some or all of this wiki is OUT of DATE and only applies to older versions of Websphere mq where they did not have an adapter.
If you are using Websphere 6.0 or above, please use the adapter configurations specified in:
IBM Webspher MQ Adapter Installation
JBoss Websphere MQ Adapter Installation
-
Using WebSphere MQ Series with JBoss Application Server - Part I
This wiki explains how to configure WebSphere MQ Series (a.k.a. WSMQ) as a JMS provider in JBossAS.
This how-to is divided in 2 documents, {FOOTNOTE DEF Part I} and {FOOTNOTE DEF Part II}.
In Part I we explain how to setup WSMQ and JBossAS in order to run the examples and we'll walk thru the most common scenario, a message received from a JBossMQ queue is forwarded to a WSMQ queue with and without XA support.
In Part II, we'll explain how to replace completely JBossMQ with WSMQ.
Note: If you just need to send some JMS messages to WSMQ from a bean deployed in JBoss, and you do not need any kind of XA transaction support, then you do not need to go through this readme. Use the WSMQ JMS interface in your bean code as any other Java API and you are done. (However, it's still not a bad idea to access your connections using a JCA deployer, i.e. through a -ds.xml.)
*Note: * Required changes to setup the package on JBossAS 3.2.x instances are explained at the bottom of the page
Initial Setup
Installing JBoss
Create a directory for the demo; for instance /wsmqdemo. We'll refer to this directory as HOME
Grab a copy of the latest JBossAS release and exploded it under HOME.
We'll refer to this directory as JBOSS_HOME.
Make a copy of the default server configuration and rename it "wsmq". SERVER_HOME refers to this directory
Installing the demo archive
Download the archive wsmqdemo.zip attached to this wiki and exploded in HOME. We'll refer to it as DEMO_HOME
Installing Websphere MQ
In this demo we have used WebSphere MQ 5.3 with CSD10 and the WebSphere MQ Extended Transactional Client
From the Java/lib directory, copy the following jar files in SERVER_HOME/lib:
com.ibm.mq.jar
com.ibm.mqjms.jar
com.ibm.mqbind.jar
IBM Websphere version 6
com.ibm.mqbind.jar is no longer supplied and is not needed
See swg21213220
IBM Websphere version 6 requires the following jars
com.ibm.mq.jar
com.ibm.mqjms.jar
dhbcore.jar
Note: we'll install the jar for the Extended TX client later
Creating and binding the WSMQ administered objects
The next step is to bind the WSMQ JMS administered objects (destinations - queue/topic - and connection factories) in the JBoss JNDI namespace.
Multiple options are possible, such as using the JMSAdmin tool provided by WSMQ to create those objects by hand in the JBoss JNDI space
or in another JNDI space and bind it into JBoss. Search through the JBoss JMS forum at http://www.jboss.org for more details on those options.
For this sample, we will create some custom MBeans that, once deployed in JBoss, will create the WSMQ JMS objects and add them
to JBoss JNDI space automatically. With this option, it is very easy to add new objects (just adding a couple of lines to an xml file and redeploy),
and each time JBoss is started those objects are created and available.
The custom MBean code is under the jmx.service.wsmq package in DEMO_HOME/src/jmx. It will be packaged in a SAR file and deployed in JBossAS.
The jboss-service.xml file containing the WSMQ JMS object definitions is in DEMO_HOME/resources.
To build and deploy the custom MBeans, perform the following steps:
Edit the DEMO_HOME/resources/jboss-service.xml and update the different WSMQ specific settings according to your environement.
For the connection factories, QueueManagerName, HostName and Channel must match your WSMQ installation and configuration.
TransportType is the attribute you can tweak to use the different WSMQ transport (client, binding or direct).
For the destinations, QueueManagerName and DestinationName must match your WSMQ configuration. This sample is using
two different WSMQ queues (RequestQueue and ResponseQueue) that must be created in your WSMQ queue manager (you can also use some existing ones, you just need to update the DestinationName attribute accordingly).
Edit build.xml and update the jboss.dist property to point to your JBOSS_HOME.
Open a shell and run the following commands from the directory where build.xml is located:
$ant mb-build $ant mb-deploy
The first command builds and packages the custom MBeans. The second one will deploy them in JBoss.
Make sure that there is no compilation errors and no deployment errors (no exceptions in the JBoss console/log).
In the JMX console, use the JNDIView service to see the WSMQ objects you just deployed.
Global JNDI Namespace
+- wsmq (class: org.jnp.interfaces.NamingContext) | +- ResponseQueue (class: com.ibm.mq.jms.MQQueue) | +- RequestQueue (class: com.ibm.mq.jms.MQQueue) ..... +- WSMQXAQueueConnectionFactory (class: com.ibm.mq.jms.MQXAQueueConnectionFactory) .... +- WSMQQueueConnectionFactory (class: com.ibm.mq.jms.MQQueueConnectionFactory) ....
Adding additional destinations
For some of the demos you'll use two additional destinations, ResponseQueue and RequestQueue.
To deploy, just drop DEMO_HOME/resources/demo-destinations-service.xml into SERVER_HOME/deploy/jms
Configuring loaders and connection factories
The JBoss JMS resource adapter provides transaction enlistment, connection/session pooling and security. We'll use it to configured two connection factories; one with XA support and another without.Refer to http://wiki.jboss.org/wiki/Wiki.jsp?page=JBossJMSRA for detailed information.
To deploy, just drop DEMO_HOME/resources/wsmq-ds.xml into SERVER_HOME/deploy/jms
Validation
This target will run some standard JMS clients sending and receiving messages to WSMQ.
JBossAS is used only as a JNDI server for the WSMQ JMS objects but it will make sure that those objects, as well as WSMQ, are properly configured.
$ant wsmq-tests
If those tests ran successfully, congratulations, the custom MBeans are correctly deployed and configured.
Otherwise, don't go any further.
Scenario 1a: Message-Driven Bean listening to a JBoss Queue, sending to a WSMQ Queue
Edit the resources/ejb-jar.xml:
- Change the env-entry-value for the mdb/responseFactory to WSMQQueueConnectionFactory (defined in the resources/jboss-service.xml)
- Change the env-entry-value for the mdb/responseDestination to wsmq/ResponseQueue (defined in the resources/jboss-service.xml
- Change the env-entry-value for the mdb/responseTransacted to false.
Edit the resources/jboss.xml:
- Change the configuration-name to Standard Message Driven Bean in order to have the MDB container using the JBoss JMS provider
- Change the destination-jndi-name to queue/RequestQueue (matching the queue deployed in demo-destinations-service.xml)
Rebuild and redeploy the MDB:
$ant mdb-build $ant mdb-deploy
Run the demo
$ant jboss2wsmq
Check the JBoss console/log
[echo] Send messages to JBoss MDB, receive replies from WSMQ response queue... [java] ========== Send Message to queue/RequestQueue [java] Message sent: Hello World [java] ========== Receive Message from wsmq/ResponseQueue [java] Message received: Response to Hello World [java] Timeout exceeded: no more message found in response queue
Scenario 1b: Message-Driven Bean listening to a JBoss Queue, sending to a WSMQ Queue with XA support
One might ask "So what happens if an exception is thrown while processing the message?". Good question, let's try it.
To simulate this error, we'll use a simple trick. A boolean is passed to the client which it will use to mark the message as "doomed". The flag is evaluated by the mdb to invoke MessageDrivenContext.SetRollbackOnly()
$ant jboss2wsmq -DdoFail=true
Let's see the output
[echo] Send messages to JBoss MDB, receive replies from WSMQ response queue... [java] ========== Send Message to queue/RequestQueue [java] Message sent: Hello World [java] ========== Receive Message from wsmq/ResponseQueue [java] Message received: Response to Hello World [java] Message received: Response to Hello World [java] Timeout exceeded: no more message found in response queue
The response message is found twice in the response queue. The root cause is the absence of a distributed transaction to span the "receiving" of the request message in the mdb and the "sending" of the response message to the WSMQ queue.
To enable XA support and insure full transaction integrity between the JBoss and the WSMQ queue, we need to:
- Install the WebSphere MQ Extended Transactional Client (sold in a seperate package)
This package contains a jar file com.ibm.mqetclient.jar that goes in SERVER_HOME/lib
- Update resource/ejb-jar.xml
Change the env-entry-value for the mdb/responseFactory to java:/WSMQJmsXA (defined in the resources/wsmq-ds.xml)
First we redeploy
$ant mdb-build $ant mdb-deploy
and we try again
$ant jboss2wsmq -DdoFail=true
Here is the ouput
[echo] Send messages to JBoss MDB, receive replies from WSMQ response queue... [java] ========== Send Message to queue/RequestQueue [java] Message sent: Hello World [java] ========== Receive Message from wsmq/ResponseQueue [java] Message received: Response to Hello World [java] Timeout exceeded: no more message found in response queue
We now get only one response message in the response queue managed by WSMQ. The receiving and the sending are both done in the same global transaction hence they get rolled back together.
How to make it work with JBossAS 3.2.x?
JBossAS 3.2.x supports JCA 1.0 whereas 4.x supports JCA 1.5 See this page for details.
In other words, the connection factory descriptors in wsmq-ds.xml need to be updated accordingly
JBossAS 3.2.4+
<tx-connection-factory> <jndi-name>WSMQJmsXA</jndi-name> <xa-transaction></xa-transaction> <adapter-display-name>JMS Adapter</adapter-display-name> ....
JBossAS 4.x
<tx-connection-factory> <jndi-name>WSMQJmsXA</jndi-name> <xa-transaction></xa-transaction> <rar-name>jms-ra.rar</rar-name> ....
Next step:
In PartII we'll explain how to replace JBossMQ with WSMQ as the default JMS provider.
Acknowledgements
Many thanks to Thomas Cherel who put together originally this how-to for JBoss 3.2.x. This new version is a 40% revamp mainly to take avantage of the JBoss JMS resource adapter plus a few fixes. Also several manual changes have been moved to their own configuration files to avoid manipulation of the default ones.
References
Comments