JMS messaging with WebSphere MQ example

JMS messaging with WebSphere MQ example

+
Search Tips | Advanced Search

JMS Messaging

Here is a summary of a process you can use to set up your message queues:

Create MQ queue manager, queues, and listener
Test MQ Queues
Create queue connection factories
Create queue destinations and bind to MQ queues
Create listener ports

Queue Names

Q1
Q2
...

Note that JNDI uses camel-case; MQ uses all caps.

Create Websphere MQ queue manager, queues, and listener

Use runmqsc to:

Create a queue manager.
Start a queue listener.
Create required queues.

Here are examples of two scripts you can use to perform these tasks:

createmq.sh Shell script for creating queue manager, MQ listener, and MQ command server.
createmq.mqs MQS script for creating queues

In createmq.sh, replace every instance of queue_manager with your queue manager name. Replace portnumber with your port number.
The createmq.mqs jacl script is called by createmq.sh. To run both scripts, from the UNIX commandline, execute:
./createmq.sh

In qm.ini, increate values of KeepAlive and MaxChannels.
TCP:
  KeepAlive=yes
CHANNELS:
  MaxChannels=400
  MaxActiveChannels=400
MQ queue names are case-sensitive. When you define your MQ queue destinations, define the base queue name with the same case as the queue you define in this step. As a convention, you can define all your queue names as upper-case letters.
Test MQ Queues

You can test the functionality of your new MQ queues by running amqsput, amqsputc, amqsget, and amqsgetc. amqsput and amqsget can only be run locally, i.e., on the same box on which the MQ server is running. amqsputc and amqsgetc can be run from anywhere within the network, and uses channels to communication with an MQ listener on another box in the network.
If a queue manager is not specified, amqsput connects to the default queue manager and amqsputc connects to the queue manager identified by an environment variable or the client channel definition file.
Sample usage for amqsput:
 amqsput queue_name queue_mgr_name 
Sample usage for amqsputc
 export PATH=/opt/mqm/samp/bin:/opt/mqm/bin:$PATH  export MQSERVER=channelname/TCP/'MQHost(MQPort)'  amqsputc queuename queue_mgr_name 
For example:
# export MQSERVER=SYSTEM.DEF.SVRCONN/TCP/'jupiter(1414)'
# amqsputc MATCHQUEUE QMGR.JUPITER.WSTEST2
Sample AMQSPUT0 start target queue is MATCHQUEUE this is a test
Use amqsget and amqsgetc to retrieve the messages from the queue.
If you have active message-driven beans using the WebSphere message listener service, meaning that listener ports are tied to your queues and are turned on, then the amqsput and amqsputc programs will work, but the MDBs will pick up your messages right away, and amqsqet and amqsgetc will not find any messages on the queue. Turn off the listener ports first before testing.
Create queue connection factories

Create the following queue connection factories:

Reference Name Maps To XA
yourco/buyer/jms/XaQueueConnectionFactory The JNDI name of the XaQueueConnectionFactory object used for obtaining a connection to a queue. Yes

XA interface.
When assigning a JNDI name, use something similar to the reference name.
For example, for the reference name:

yourco/buyer/jms/XaQueueConnectionFactory

Create this JNDI name:

jms/XaQueueConnectionFactory

Use these settings to create a Queue Connection Factory in WebSphere:

Menu: WebSphere MQ JMS Provider | WebSphere MQ Queue Connection Factories
Configuration Level: CELL
Configuration File: resources.xml
JNDI name bound from: application resource references; Listener Ports

Setting Description
Scope In a cluster, this should refer to a cell-level scope, such as cells:myNetwork.
Name Required. For display only.
JNDI Name Required. This name will be used from the Listener Ports and Map resource references to resources pages.
Description No required value.
Category No required value.
Component-managed Authentication Alias Required. You must enter the same value as Container-managed Authentication Alias.
Container-managed Authentication Alias Required. You must enter the same value as Component-managed Authentication Alias.
Mapping-Configuration Alias Must be set to Default Principal Mapping.
Queue Manager Required. Name of the MQ Queue Manager
Host Required. The name of the host on which the MQ Manager runs.
Port Required. The port number where the MQ Manager is listening.
Channel Required. Enter SYSTEM.DEF.SVRCONN.
Transport Type Must be set to CLIENT.
Model Queue Definition No required value.
Client ID No required value.
CCSID No required value.
Message Retention Tested with YES.
XA Enabled Must be YES.
Connection Pool: Scope Must be the same value as you specified in the Scope field.
Connection Pool: Connection Timeout Tested with 180.
Connection Pool: Max Connections Tested with 50.
Connection Pool: Min Connections Tested with 1.
Connection Pool: Reap Time Tested with 180.
Connection Pool: Unused Timeout Tested with 1800.
Connection Pool: Aged Timeout Tested with 0.
Connection Pool: Purge Policy Tested with Failing Connection Only.
Session Pool: Scope Same as Scope, above.
Session Pool: Connection Timeout Tested with 180.
Session Pool: Max Connections Tested with 10.
Session Pool: Min Connections Tested with 1.
Session Pool: Reap Time Tested with 180.
Session Pool: Unused Timeout Tested with 1800.
Session Pool: Aged Timeout Tested with 0.
Session Pool: Purge Policy Tested with Failing Connection Only.

You can use the set_MQ_QCF.jacl script to create queue connection factories.
wsadmin.sh -username was -password notiv@ -f set_MQ_QCF.jacl cellname nodename servername

Before running, edit script and plug in your values for MQ host/port, queue manager, and authentication alias.
Create queue destinations and bind to MQ queues

Create one queue destination for each queue created above.
Use these settings to bind the MQ queues from the WAS:

Menu: WebSphere MQ JMS Provider | WebSphere MQ Queue Destinations
Configuration Level: CELL
Configuration File: resources.xml
JNDI names bound from: application resource environment references; Listener Ports

Setting Description
Scope In a cluster, this should refer to a cell-level scope, such as cells:myNetwork.
Name Required. For display only.
JNDI Name Required. This name will be used from the Listener Ports and Map resource env entry references to resources pages.
Description No required value.
Category No required value.
Persistence

Priority Tested with APPLICATION DEFINED.
Specified Priority Tested with 0.
Expiry Tested with APPLICATION DEFINED.
Specified Expiry Tested with 0.
Base Queue Name Corresponds to an MQ queue
MQ queue names are case-sensitive. The case must match for these names:

All QM queues
The base queue name

Here is an example of a correct configuration:

You define the base queue name as JOBEXECQUEUE.
You define a queue named JOBEXECQUEUE.

Here is an example of an incorrect configuration:

You define a queue named JOBEXECQUEUE.
You define the base queue name as JobExecQueue.

When you try to use a queue where the case does not match, you receive this message:
MQJMS2008: failed to open MQ queue

Base Queue Manager Name Corresponds to your MQ queue manager
CCSID No required value.
Native Encoding Tested with NO.
Integer Encoding Tested with NORMAL.
Decimal Encoding Tested with NORMAL.
Floating Point Encoding Tested with IEEENORMAL.
Target Client Tested with JMS.
Queue Manager Host Required. The name of the host on which the MQ Manager runs.
Queue Manager Port Required. The port number where the MQ Manager is listening.
Server Connection Channel Name Required. Enter SYSTEM.DEF.SVRCONN.
User ID username used to connect to the Queue Manager Host.
Password password used to connect to the Queue Manager Host.

You can use the set_MQ_Queues.jacl script to create queue destinations.
wsadmin.sh -username was -password notiv@ -f set_MQ_Queues.jacl cellname nodename servername

Before running, edit script and plug in your values for MQ host/port, queue manager, and MQ login/password.
Create listener ports

Create one listener port for each queue binding
When assigning a listener port name, use something similar to the queues JNDI name, but replace the suffix -Queue with -MessageEJBPort.
For example, for the JNDI name:

jms/JobExecQueue

Create a Listener Port named:

JobExecMessageEJBPort

Use these settings to define your listener ports:

Menu: Application Servers | server-name | Message Listener Service | Listener Ports
Configuration Level: SERVER
Configuration File: server.xml
Port names bound from: application message beans

Setting Description
Name Required. This name will be used from the Provide Listener Ports for Messaging Beans page.
Initial State Always Started.
Description No required value.
Connection factory JNDI name Must bind to the JNDI name of a queue connection factory listed on the WebSphere MQ Queue Connection Factories page.
Destination JNDI name Must bind to the JNDI name of a queue listed on the WebSphere MQ Queue Destinations page.
Maximum sessions For each listener port, you use the Maximum Sessions parameter to assign the maximum number of Message Driven Beans (MDBs) that can be spawned concurrently within the JVM:

You can add more workers (MDBs) to handle more volume or to complete a batch job more quickly.

MDBs cannot be added endlessly without performance consequences. Imagine each MDB as a user. Just as the application needs more system resources to handle more users, it also needs resources to run more MDBs.

Personal testing showed that 5 to 10 MDBs per WebSphere Application Server obtained the best processing rate:

Fewer, and system resources were not fully employed.
More, and workers began stealing cycles from each other.

In Personal testing, WebSphere 5.1 seemed to be able to efficiently run more beans than WebSphere5.0.
Here are suggested maximum session settings:

WebSphere 5.0: 5
WebSphere 5.1: 10

Maximum retries Tested with 0.
Maximum messages Tested with 1.

To enable listener ports to stay started during batch match processing, you might want to enable a backout queue for MATCHQUEUE.
You can use the set_listener_ports.jacl script to create listener ports:
wsadmin.sh -username was -password password -f set_listener_ports.jacl cellname nodename servername

createmq.sh	Shell script for creating queue manager, MQ listener, and MQ command server.
createmq.mqs	MQS script for creating queues

Menu:	WebSphere MQ JMS Provider \| WebSphere MQ Queue Connection Factories
Configuration Level:	CELL
Configuration File:	resources.xml
JNDI name bound from:	application resource references; Listener Ports

Setting	Description
Scope	In a cluster, this should refer to a cell-level scope, such as cells:myNetwork.
Name	Required. For display only.
JNDI Name	Required. This name will be used from the Listener Ports and Map resource references to resources pages.
Description	No required value.
Category	No required value.
Component-managed Authentication Alias	Required. You must enter the same value as Container-managed Authentication Alias.
Container-managed Authentication Alias	Required. You must enter the same value as Component-managed Authentication Alias.
Mapping-Configuration Alias	Must be set to Default Principal Mapping.
Queue Manager	Required. Name of the MQ Queue Manager
Host	Required. The name of the host on which the MQ Manager runs.
Port	Required. The port number where the MQ Manager is listening.
Channel	Required. Enter SYSTEM.DEF.SVRCONN.
Transport Type	Must be set to CLIENT.
Model Queue Definition	No required value.
Client ID	No required value.
CCSID	No required value.
Message Retention	Tested with YES.
XA Enabled	Must be YES.
Connection Pool: Scope	Must be the same value as you specified in the Scope field.
Connection Pool: Connection Timeout	Tested with 180.
Connection Pool: Max Connections	Tested with 50.
Connection Pool: Min Connections	Tested with 1.
Connection Pool: Reap Time	Tested with 180.
Connection Pool: Unused Timeout	Tested with 1800.
Connection Pool: Aged Timeout	Tested with 0.
Connection Pool: Purge Policy	Tested with Failing Connection Only.
Session Pool: Scope	Same as Scope, above.
Session Pool: Connection Timeout	Tested with 180.
Session Pool: Max Connections	Tested with 10.
Session Pool: Min Connections	Tested with 1.
Session Pool: Reap Time	Tested with 180.
Session Pool: Unused Timeout	Tested with 1800.
Session Pool: Aged Timeout	Tested with 0.
Session Pool: Purge Policy	Tested with Failing Connection Only.

Setting	Description
Name	Required. This name will be used from the Provide Listener Ports for Messaging Beans page.
Initial State	Always Started.
Description	No required value.
Connection factory JNDI name	Must bind to the JNDI name of a queue connection factory listed on the WebSphere MQ Queue Connection Factories page.
Destination JNDI name	Must bind to the JNDI name of a queue listed on the WebSphere MQ Queue Destinations page.
Maximum sessions	For each listener port, you use the Maximum Sessions parameter to assign the maximum number of Message Driven Beans (MDBs) that can be spawned concurrently within the JVM: You can add more workers (MDBs) to handle more volume or to complete a batch job more quickly. MDBs cannot be added endlessly without performance consequences. Imagine each MDB as a user. Just as the application needs more system resources to handle more users, it also needs resources to run more MDBs. Personal testing showed that 5 to 10 MDBs per WebSphere Application Server obtained the best processing rate: Fewer, and system resources were not fully employed. More, and workers began stealing cycles from each other. In Personal testing, WebSphere 5.1 seemed to be able to efficiently run more beans than WebSphere5.0. Here are suggested maximum session settings: WebSphere 5.0: 5 WebSphere 5.1: 10
Maximum retries	Tested with 0.
Maximum messages	Tested with 1.