Using JMS with WebSphere MQ Everyplace

This section describes how to set up your system to run the example programs, including the Installation Verification Test (IVT) example which verifies your WebSphere MQ Everyplace JMS installation. To use JMS with WebSphere MQ Everyplace you must have the following jar files, in addition to MQeBase.jar, on your class path:

jms.jar
This is Sun's interface definition for the JMS classes
MQeJMS.jar
This is the WebSphere MQ Everyplace implementation of JMS

Obtaining jar files

WebSphere MQ Everyplace does not ship with Sun's JMS interface definition, which is contained in jms.jar, and this must be downloaded before JMS can be used. At the time of writing, this can be freely downloaded from
http://java.sun.com/products/jms/docs.html
The JMS Version 1.0.2b jar file is required.

In addition, if JMS administered objects are to be stored and retrieved using the Java Naming and Directory Interface (JNDI), the javax.naming.* classes must be on the classpath. If Java 1 is being used, for example, a 1.1.8 JRE, jndi.jar must be obtained and added to the classpath. If Java 2 is being used, a 1.2 or later JRE, the JRE might contain these classes. You can use WebSphere MQ Everyplace without JNDI, but at the cost of a small degree of provider dependence.WebSphere MQ Everyplace-specific classes must be used for the ConnectionFactory and Destination objects. You can download JNDI jar files from
http://java.sun.com/products/jndi

Testing the JMS class path

You can use the example program examples.jms.MQeJMSIVT to test your JMS installation. Before you run this program, you need a WebSphere MQ Everyplace queue manager that has a SYSTEM.DEFAULT.LOCAL.QUEUE. In addition to the JMS jar files mentioned above, you also need the following or equivalent jar files on your class path to run examples.jms.MQeJMSIVT:

You can run the example from the command line by typing:

	java examples.jms.MQeJMSIVT -i 
			<ini file name>

where <ini file name> is the name of the initialisation (ini) file for the WebSphere MQ Everyplace queue manager. You can optionally add a "-t" flag to turn tracing on:

java examples.jms.MQeJMSIVT -t -i 
			<ini file name>

The example program checks that the required jar files are on the class path by checking for classes that they contain. It creates a QueueConnectionFactory and configures it using the ini file name that you passed in on the command line. It starts a connection, which:

  1. Starts the WebSphere MQ Everyplace queue manager
  2. Creates a JMS Queue representing the queue SYSTEM.DEFAULT.LOCAL.QUEUE on the queue manager
  3. Sends a message to the JMS Queue
  4. Reads the message back and compares it to the message it sent

The SYSTEM.DEFAULT.LOCAL.QUEUE should not contain any messages before running the program, otherwise the message read back will not be the one that the program sent. The output from the program should look like this:

using ini file '<.ini file name>' 
		to configure the connection
checking classpath
found JMS interface classes
found MQe JMS classes
found MQe base classes
Creating and configuring QueueConnectionFactory
Creating connection
From the connection data, JMS 
	provider is IBM WebSphere MQ Everyplace Version 2.0.0.0
Creating session
Creating queue
Creating sender
Creating receiver
Creating message
Sending message
Receiving message


HEADER FIELDS
----------------------------------------
 JMSType:          jms_text
 JMSDeliveryMode:  2
 JMSExpiration:    0
 JMSPriority:      4
 JMSMessageID:     ID:00000009524cf094000000f052fc06ca
 JMSTimestamp:     1032184399562
 JMSCorrelationID: null
 JMSDestination:   null:SYSTEM.DEFAULT.LOCAL.QUEUE
 JMSReplyTo:       null
 JMSRedelivered:   false

 PROPERTY FIELDS (read only)
-----------------------------------------
 JMSXRcvTimestamp : 1032184400133

 MESSAGE BODY (read only)
-----------------------------------------
A simple text message from the MQeJMSIVT program

Retrieved message is a TextMessage; now checking 
for equality with the sent message
Messages are equal. Great!
Closing connection
connection closed
IVT finished

Running other WebSphere MQ Everyplace JMS example programs

WebSphere MQ Everyplace provides two other example programs for the JMS classes. The program examples.jms.PTPSample01 is similar to the IVT examples described above, but there is a command line argument to tell it not to use the Java Naming and Directory Interface (JNDI) and it does not have the same checks on the class path. The program requires the same JMS and WebSphere MQ Everyplace jar files on the class path as examples.jms.MQeJMSIVT, that is jms.jar, MQeJMS.jar, MQeBase.jar, and MQeExamples.jar. It also requires the jndi.jar file, even if it does not use JNDI, because the program imports javax.naming. The section on Using JNDI provides more information on the jndi.jar file. You can run the example from the command line by typing:

 java examples.jms.PTPSample01 -nojndi -i <ini file name>

where <ini file name > is the name of the initialisation (ini) file for the WebSphere MQ Everyplace queue manager. By default, the program will use the SYSTEM.DEFAULT.LOCAL.QUEUE on this queue manager. You can specify a different queue by using the -q flag:

java examples.jms.PTPSample01 -i <ini file name> -q <queue name> 

You can also turn tracing on by adding the -t flag:

java examples.jms.PTPSample01 -t -i <ini file name> -q <queue name> 

The examples.jms.PTPSample02 program uses message listeners and filters. This program creates a QueueReceiver with a "blue" filter and creates a message listener for it. It creates a second QueueReceiver with a "red" filter and message listener. It then sends four messages to a queue, two with the filter property colour set to blue and two with the filter property colour set to red, and checks that the message listeners receive the correct messages. The program has the same command line parameters as examples.jms.PTPSample01.