IBM Developer

Tutorial

Write and run your first IBM MQ JMS application

Develop a point-to-point JMS app

By

Richard J. Coppen,

Tanmay Kudchadkar

On this page

JMS stands for Java Message Service. JMS is a standard that defines how you can access enterprise messaging systems from Java programs. The JMS API is implemented by messaging service providers like IBM MQ to allow JMS client applications to access the provider's messaging service.

Since version 9.3.0, IBM MQ included support for Jakarta Messaging 3.0. Jakarta Messaging 3.0 is functionally equivalent to JMS 2.0, but there are some differences in naming. The official name for version 3.0 is Jakarta Messaging rather than Java Message Service (JMS), and the package and constant names are prefixed with jakarta rather than javax. You can read more about these changes in the IBM MQ Documentation pages. The IBM MQ JMS samples in the mq-dev-patterns repo have been updated to include package import references for both JMS 2.0 and Jakarta Messaging 3.0, with the latter import statements commented out for developer reference. For convenience, the remainder of this article will use JMS as a general term to reflect the user’s choice.

In this tutorial, you'll put a message that holds your data to a queue and the consuming application will get it from the queue. You’ll be using the JMS API to connect to your messaging provider, which in this case is IBM MQ.

Prerequisites

Developing a point-to-point app with JMS and IBM MQ

Your application will be able to do these things:

  • Connect to the queue manager
  • Open a queue
  • Put a message
  • Get a message
  • Close the queue
  • Disconnect from the queue manager

We assume that these MQ objects are set up on the MQ server that you are connecting to:

  • Queue manager QM1
  • Queue DEV.QUEUE.1
  • Channel DEV.APP.SVRCONN (For IBM Cloud users: Channel CLOUD.APP.SVRCONN)
  • Port 1414 (For IBM Cloud users: refer to the connection_info file downloaded)

If you are using your own objects, you'll need to adjust these names accordingly. Or, you can go to a tutorial in the Ready, Set, Connect series to get started.

If you’ve already worked through a Ready, Set, Connect tutorial, your queue manager should already be configured correctly. If not, you'll need to set up authorization on the queue manager to accept connection from the application through a named channel and the application has to be authorized to put and get messages to and from the queue.

Watch this video to learn how messaging fits into your apps and how to build the IBM MQ JMS application explained in this tutorial.

If you already have a JMS application, but you want some help with performance or debugging, review this article.

Set up your environment

In this first step, we walk you through installing and setting up the prerequisites. The following instructions assume Windows users are working with a PowerShell command prompt unless otherwise stated.

  1. Create a directory to save the files needed for the sample, for example in your home directory.

     mkdir MQClient
 cd MQClient

  2. From the MQClient folder, download the com.ibm.mq.allclient.jar file by using curl.

     curl -o com.ibm.mq.allclient-9.4.1.0.jar https://repo1.maven.org/maven2/com/ibm/mq/com.ibm.mq.allclient/9.4.1.0/com.ibm.mq.allclient-9.4.1.0.jar

  3. From the MQClient folder, download the JMS API file by using curl.

     curl -o javax.jms-api-2.0.1.jar https://repo1.maven.org/maven2/javax/jms/javax.jms-api/2.0.1/javax.jms-api-2.0.1.jar

  4. From the MQClient folder, download the JSON .jar file by using curl.

     curl -o json-20220320.jar https://repo1.maven.org/maven2/org/json/json/20220320/json-20220320.jar

Downloading the point-to-point JMS sample application

Let's get the sample from GitHub, save it on your local machine, and look through some of the key JMS constructs and where you can add the host, port, channel, and queue details so that your sample can connect to the queue manager.

  1. In your MQClient directory, create the following directory structure: com/ibm/mq/samples/jms.

    On Windows:

     mkdir -p com\ibm\mq\samples\jms
 cd com\ibm\mq\samples\jms

    On Linux or Mac:

     mkdir -p com/ibm/mq/samples/jms
 cd com/ibm/mq/samples/jms

  2. From the MQClient/com/ibm/mq/samples/jms directory, download the JmsPutGet.java sample from GitHub by using curl:

     curl -o JmsPutGet.java https://raw.githubusercontent.com/ibm-messaging/mq-dev-samples/master/gettingStarted/jms/com/ibm/mq/samples/jms/JmsPutGet.java

  3. Edit the Java file you downloaded. Replace the host, port, and app password variables to match your queue manager configuration. The CHANNEL will be DEV.APP.SVRCONN.

    For IBM Cloud users, you can find your hostname and port in the Connection Information file, called "connection_info". It will contain your host name and port number (under Listener port). Your APP_PASSWORD is the API key that you generated when you created your application username. The CHANNEL will be CLOUD.APP.SVRCONN.

     // Create variables for the connection to MQ
 private static final String HOST = "_YOUR_HOSTNAME_"; // Host name or IP address
 private static final int PORT = _YOUR_PORT_; // Listener port for your queue manager
 private static final String CHANNEL = "_DEV_OR_CLOUD_.APP.SVRCONN"; // Channel name
 private static final String QMGR = "QM1"; // Queue manager name
 private static final String APP_USER = "app"; // User name that application uses to connect to MQ
 private static final String APP_PASSWORD = "_APP_PASSWORD_"; // Password that the application uses to connect to MQ
 private static final String QUEUE_NAME = "DEV.QUEUE.1"; // Queue that the application uses to put and get messages to and from

Additional Steps for IBM Cloud

If you are running your IBM MQ queue manager in IBM Cloud, you need to also complete these steps to enable a TLS connection with the queue manager hosted on the public cloud:

  1. Edit the JmsPut.java file. Uncomment the following line, and then save the file.

     //cf.setStringProperty(WMQConstants.WMQ_SSL_CIPHER_SUITE, "*TLS12");

  2. Move the qmgrcert.pem file into the main MQClient directory.

     cd ~/MQClient
 mv ~/Downloads/qmgrcert.pem .

  3. Since TLS is automatically enabled with IBM Cloud, our application will need a keystore. We will use keytool (a Java security tool) to create the keystore. This is included in with Java JREs and JDKs. To set up the keystore, run the following command:

keytool -keystore clientTruststore.p12 -storetype pkcs12 -importcert -file qmgrcert.pem -alias server-certificate

You are required to create a password for the keystore. This can be anything you want but, in these examples, we use “passw0rd”. Then, re-enter the same password again. After this, you will be asked to trust the certificate. Once you agree, the certificate called “clientTruststore.p12” will be created.

To test if the keystore is good, run the following command:

keytool -list -keystore clientTruststore.p12

This should give you details of your keystore and tell you the number of entries in your keystore.

You should now be able to compile your application and run it.

Change your working directory back to the MQClient.

Compile and run your JMS application

This is where you’ll finally connect your application to the queue manager and put and get messages to and from the queue.

To compile the sample, go to your MQClient directory.

Use javac to compile your application.

  1. From the MQClient directory, use javac to compile your application.

    On Windows:

     javac -cp .\com.ibm.mq.allclient-9.4.1.0.jar;.\javax.jms-api-2.0.1.jar;.\json-20220320.jar com\ibm\mq\samples\jms\JmsPutGet.java

    On Windows PowerShell:

     javac -cp ‘.\com.ibm.mq.allclient-9.4.1.0.jar;.\javax.jms-api-2.0.1.jar;.\json-20220320.jar’ .\com\ibm\mq\samples\jms\JmsPutGet.java

    On Linux or Mac:

     javac -cp ./com.ibm.mq.allclient-9.4.1.0.jar:./javax.jms-api-2.0.1.jar:./json-20220320.jar com/ibm/mq/samples/jms/JmsPutGet.java

    To confirm that the sample is compiled, run one of these commands. You should now see a .class file accompanying the .java file.

    On Windows, run the dir command:

     dir com\ibm\mq\samples\jms\

    On Linux or Mac, run the ls command:

     ls -l com/ibm/mq/samples/jms/

    You should now see a .class file accompanying the .java file: Output of the ls command

  2. Run your application.

    On Windows:

     java -cp .\com.ibm.mq.allclient-9.4.1.0.jar;.\javax.jms-api-2.0.1.jar;.\json-20220320.jar;. com.ibm.mq.samples.jms.JmsPutGet

    On Windows PowerShell:

    java -cp ‘.\com.ibm.mq.allclient-9.4.1.0.jar;.\javax.jms-api-2.0.1.jar;.\json-20220320.jar;.’ com.ibm.mq.samples.jms.JmsPutGet

    On Linux or Mac:

     java -cp ./com.ibm.mq.allclient-9.4.1.0.jar:./javax.jms-api-2.0.1.jar:./json-20220320.jar:. com.ibm.mq.samples.jms.JmsPutGet

    For IBM Cloud Users:

    On Windows:

     java -Djavax.net.ssl.trustStore=clientTruststore.p12 -Djavax.net.ssl.trustStorePassword=passw0rd -cp .\com.ibm.mq.allclient-9.4.1.0.jar;.\javax.jms-api-2.0.1.jar;.\json-20220320.jar;. com.ibm.mq.samples.jms.JmsPutGet

    On Windows PowerShell:

     java -D'javax.net.ssl.trustStore=clientTruststore.p12' -D'javax.net.ssl.trustStorePassword=passw0rd' -cp '.\com.ibm.mq.allclient-9.4.1.0.jar;.\javax.jms-api-2.0.1.jar;.\json-20220320.jar;.' com.ibm.mq.samples.jms.JmsPutGet

    On Linux or Mac:

     java -Djavax.net.ssl.trustStore=clientTruststore.p12 -Djavax.net.ssl.trustStorePassword=passw0rd -cp ./com.ibm.mq.allclient-9.4.1.0.jar:./javax.jms-api-2.0.1.jar:./json-20220320.jar:. com.ibm.mq.samples.jms.JmsPutGet

    You should see output like this:

    Output of running your JMS app

Additional step for MQ on Cloud users

Log into your MQ Web Console. The link is provided in the Connection Information file, called "connection_info".

MQ Web Console screenshot

If you click on the message, it will provide you with more information related to it.

Message Details image

Summary

Congratulations! You edited and compiled your first JMS application, sent a message to an IBM MQ queue, and got that message from the queue. You also set up your environment with everything you need to develop with JMS and IBM MQ.

You have a basic understanding of what you’re aiming to hit on the MQ server side with the objects in your JMS application and how JMS helps you achieve that.

If you want to make sure your JMS application is going to perform reliably and well, have a look at this article.


05 February 2025

Legend