This project contains two samples. One sample is a Java EE web application demonstrating how to use a message-driven bean (MDB). The second sample is a JMS ConnectionFactory sample that connects to a remote IBM MQ queue manager using an MQ client mode connection. This sample can also be used to write a JMS message for the MDB sample to process. For further details on how to develop these samples refer to the accompanying IBM developer tutorial Develop a JMS application for CICS Liberty
com.ibm.cicsdev.mqjms.mdb
- EJB project containing the MySimpleMDB that
recives a message put to the MDB queue.com.ibm.cicsdev.mqjms.mdb.ear
- EAR project referring to the MDB EJB
project.com.ibm.cicsdev.mqjms.mdb.cicsbundle
- CICS bundle project that references
the EAR project for the MDB sample.com.ibm.cicsdev.mqjms.cf.web
- Web project containing the MQJMSDemo servlet
that uses a JMS ConnectionFactory.com.ibm.cicsdev.mqjms.cf.ear
- EAR project referring to the the web project
com.ibm.cicsdev.mqjms.cf.web
.com.ibm.cicsdev.mqjms.cf.cicsbundle
- CICS bundle project that references
the web project for the
ConnectionFactory sample.DEMO.MDBQUEUE
and writes these messages to the
CICS TSQ RJMSTSQ
.DEMO.SIMPLEQ
using an MQ client mode connection to
a remote queue manager.Setup the following resources in the IBM MQ queue manager:
WAS.JMS.SVRCONN
DEMO.MDBQUEUE
. This must be defined as shareableDEMO.SIMPLEQ
. This should be defined as shareableNote: DEMO.MDBQUEUE
must be defined as shareable to allow usage in the
multi-threaded environment in Liberty. In addition it is advisable to set the
BackoutThreshold
attribute on the MDBQUEUE to a finite value, to prevent the MDB being
constantly redriven if the MDB fails during the processing of the message.
DEMO.SIMPLEQ
should be defined as shareable as Liberty servlets can be
accessed concurrently.
wmq.jmsra.rar
. To deploy the MDB sample you must have previously imported the projects into CICS Explorer.
Export the CICS bundle from Eclipse by selecting the project
com.ibm.cicsdev.mqjms.mdb.cicsbundle
> Export Bundle Project to z/OS UNIX File System
Define and install a Liberty JVMSERVER named DFHWLP
in the CICS region
(see Starting a CICS Liberty JVM server in 4 easy steps).
Specify the location of the IBM MQ Resource Adapter by adding the following entry to the server.xml file:
<variable name="wmqJmsClient.rar.location" value="/path/to/wmq/rar/wmq.jmsra.rar"/>
where the value
attribute specifies the absolute path to the IBM MQ
Resource Adapter file, wmq.jmsra.rar
.
Add the features mdb-3.2
and wmqJmsClient-2.0
to the featureManager
element in the Liberty JVM server's server.xml configuration file.
Add a definition to the server.xml for the queue required by the sample:
<jmsQueue id="jms/mdbq" jndiName="jms/mdbq">
<properties.wmqJms baseQueueName="DEMO.MDBQUEUE" />
</jmsQueue>
Add a JMS activation spec to the server.xml for the MDB test. This defines
that the MDB MySimpleMDB
is invoked when the MDBQUEUE is written to.
<jmsActivationSpec id="com.ibm.cicsdev.mqjms.mdb.ear/com.ibm.cicsdev.mqjms.mdb/MySimpleMDB">
<properties.wmqJms destinationRef="jms/mdbq" destinationType="javax.jms.Queue"
channel="WAS.JMS.SVRCONN"
hostName="localhost"
port="1414"
queueManager="QM1"
transportType="CLIENT" />
</jmsActivationSpec>
where the port
attribute specifies the port the IBM MQ queue manager is
running on and the queueManager
attribute specifies the name of the IBM MQ
queue manager. These values will be specific to your MQ installation.
Define and install a CICS BUNDLE resource definition referring to the deployed bundle directory on zFS in step 1, and ensure all resources are enabled.
Optinally, you can define and install a CICS TSMODEL resource named RJMSTSQ
with the attribute RECOVERY(YES)
if you want to make the MDB test
transactional.
Note: The jmsActivationSpec id
attribute must match the JNDI name of the
MDB in the java:global
namespace. In Liberty, EJBs are registered to the
java:global
namespace using the following scheme: application/module/bean
.
This name is displayed in the Liberty servers messages.log file when the MDB is registered into the EJB container:
[8/16/17 15:42:47:611 BST] 0000004b com.ibm.ws.ejbcontainer.runtime.AbstractEJBRuntime I CNTR0180I: The MySimpleMDB message-driven bean in the com.ibm.cicsdev.mqjms.mdb.jar module of the com.ibm.cicsdev.mqjms.mdb.ear application is bound to the com.ibm.cicsdev.mqjms.mdb.ear/com.ibm.cicsdev.mqjms.mdb/MySimpleMDB activation specification.
DEMO.MDBQUEUE
.RJMSTSQ
, the record written in
DEMO.MDBQUEUE
will have been read by the MDB and written to this CICS TSQ.Records can be written using the IBM MQ client sample program amqsputc
, or by
running the JMS servlet provided with the JMS Connection Factory part of this sample. The
IBM MQ client samples are provided with a distributed (workstation) installation of MQ.
To use the amqsputc
sample from the workstation command line, set the MQSERVER variable to the name of the channel:
set MQSERVER=WAS.JMS.SVRCONN/TCP/localhost(1414)
where localhost
is the hostname of the system the IBM MQ queue manager is
running on and 1414
is the TCP port the IBM MQ queue manager is listening on.
Then connect to the MDB queue and write some test data as follows using amqsputc from the workstation command line:
amqsputc DEMO.MDBQUEUE
Sample AMQSPUT0 start
target queue is DEMO.MDBQUEUE
hello from CICS
The next section describes how to use the JMS Connection Factory Servlet to send a message to the MDB.
Export the CICS bundle from Eclipse by selecting the project
com.ibm.cicsdev.mqjms.cf.cicsbundle
> Export Bundle Project to z/OS UNIX File System
Define and install a Liberty JVMSERVER named DFHWLP
in the CICS region.
Add the features mdb-3.2
, wmqJmsClient-2.0
and jndi-1.0
to the
featureManager
element in the Liberty JVM server's server.xml
configuration file.
Add a JMS connection factory definition to the server.xml:
<jmsQueueConnectionFactory connectionManagerRef="ConMgrJms" jndiname="jms/qcf1">
<properties.wmqJms channel="WAS.JMS.SVRCONN"
hostName="localhost"
port="1414"
queueManager="QM1"
transportType="CLIENT"/>
</jmsQueueConnectionFactory>
<connectionManager id="ConMgr" maxPoolSize="10"/>
where the port
attribute specifies the port the IBM MQ queue manager is
running on and the queueManager
attribute specifies the name of the IBM MQ
queue manager.
Add a definition to the server.xml for the queue required by the ConnectionFactory sample.
<jmsQueue id="jms/simpleq" jndiName="jms/simpleq">
<properties.wmqJms baseQueueName="DEMO.SIMPLEQ" />
</jmsQueue>
Using a web browser, access the web application using the following URL:
http://mvs.example.ibm.com:9080/jmsweb?test=putq
where mvs.example.ibm.com
is the hostname of the LPAR and 9080
is the
HTTP port Liberty is configured to run on.
This will write a record to the IBM MQ queue DEMO.SIMPLEQ
and return the
following HTTP response:
22/06/2017 16:11:20 Message has been written to queue:///DEMO.SIMPLEQ
Using a web browser, access the web application using the following URL:
http://mvs.example.com:9080/jmsweb?test=readq
This will read a record from the IBM MQ queue DEMO.SIMPLEQ
and return it
in the HTTP response.
Both the MDB sample and the ConnectionFactory sample can be run together. The ConnectionFactory servlet can be used to write messages onto the queue the MDB is bound to.
The same servlet can then be used to read records from the TSQ the MDB stores the messages to.
Using a web browser, access the web application using the following URL:
http://mvs.example.ibm.com:9080/jmsweb?test=putmdbq
where mvs.example.ibm.com
is the hostname of the LPAR and 9080
is the
HTTP port Liberty is configured to run on.
Using a web browser, access the web application using the following URL:
http://mvs.example.ibm.com:9080/jmsweb?test=readtsq
This should return the TSQ record writen by the MDB from the IBM MQ queue.
For further details on using the JMS APIs in CICS Liberty refer to this tutorial
For further information on JMS and IBM MQ refer to the following:
2042 MQRC_OBJECT_IN_USE when an MDB tries to get a message
This project is licensed under Apache License Version 2.0.