JMS with Ballerina lang: Part 6

Connecting to IBM MQ via JMS

6 min readJun 5, 2024

(This article is written using Ballerina Swan Lake 2201.9.0)

In this article we will discuss how we can connect to an IBM MQ server using Ballerina JMS connector.

IBM MQ

IBM MQ is a powerful messaging middleware platform that facilitates the exchange of data between applications and systems in a reliable, secure, and scalable manner. It supports various messaging models, including point-to-point and publish/subscribe, making it suitable for diverse messaging needs across industries.

As we discussed in our first article, the Java Message Service (JMS) serves as a standardized API for accessing enterprise messaging systems, offering a unified interface for applications to engage with messaging providers. IBM MQ offers support for JMS, allowing applications to seamlessly integrate with IBM MQ messaging infrastructure.

Setting up IBM MQ server

We have the option to either physically setup IBM MQ or use an IBM MQ container image.

To set up IBM MQ physically, please refer to this guide.
To use and understand about the IBM MQ docker image, please refer to this tutorial.

To simplify the setup we will use the latest IBM MQ docker image in this article. Following is a sample docker-compose file you could use to set up the IBM MQ infrastructure.

services:
  mq:
    image: icr.io/ibm-messaging/mq:latest
    container_name: ibmmq-server
    ports:
      - "1414:1414"
    environment:
      - LICENSE=accept
      - MQ_QMGR_NAME=BALLERINA_QM1
      - MQ_ADMIN_PASSWORD=password
    healthcheck:
      test: ["CMD-SHELL", "chkmqstarted"]
      interval: 10s
      timeout: 5s
      retries: 3

Start the docker-compose using the following command:

docker compose -f <path/to>/docker-compose.yml up

Once, you started the docker-compose execute the following command to check the container status.

docker ps

If the STATUS column indicates healthy then your IBM MQ container is up and running smoothly.

Setting up IBM MQ Explorer

IBM MQ Explorer is a graphical tool provided by IBM for managing and administering IBM MQ resources. It offers a user-friendly interface for configuring, monitoring, and interacting with various components of an IBM MQ infrastructure.

IBM MQ Explorer is commonly used by administrators and developers to perform tasks such as creating and managing queues, topics, channels, and queue managers.

In addition, IBM MQ Explorer can be used to generate Java Naming and Directory Interface (JNDI) bindings for JMS applications that connect to IBM MQ. These JNDI bindings enable JMS clients to look up and connect to IBM MQ resources such as connection factories and destinations.

Please use following guides to setup IBM MQ Explorer in your machine;

For MS Windows based system, use this guide
For Linux based system, use this guide

Once the setup is done start the IBM MQ Explorer by following these instructions.

Connecting to the QueueManager

Run the IBM MQ explorer and right-click on the Queue Managers section. Select Add Remote Queue Manager from the drop-down menu.

Update the Queue manager name . In this case it is Ballerina_QM1(This configuration has be provided in the docker-compose configuration using MQ_QMGR_NAME environment variable).

Go to the next page and update the connection details. For the channel name use DEV.ADMIN.SVRCONN .

Click next until you land on Specify user identification details page. Here, as the Userid provide admin and select Prompt for password option in the Password section.

Then click next until you land on Specify SSL option details page. Keep the default configurations and click Finish .

Now, in the main window you can see the Queue Manager you created.

Generating the JNDI bindings

Right-click on the JMS Administered Objects section in the main window and select Add Initial Context from the drop down menu.

In the Connection details page select File system as the JNDI namespace location and provide a directory in your machine to save the configurations.

Click next and once you go to the next page click Finish . Once, this is done, you will be able to see the initial-context you created on the side-pane.

Right-click on the Connection Factories section and select New >> Connection Factory.

In the Create a Connection Factory window provide a name for the connection factory and click Next.

In the next page select the Connection factory type as Connection Factory and click Next.

In the next page select MQ Client as the transport and click Next.

Click next until you land on Change properties page and there select Connection from the left pane and select the Queue manager we created earlier as both Base queue manager and Broker queue manager.

Select Channels from the left pane and select DEV.ADMIN.SVRCONN as the channel and click Finish.

Writing the code

Let’s create a new Ballerina project and call it as ibmmq_with_jms.

bal new ibmmq_with_jms

Let’s create the jms:Connection and the jms:Session .

Here, we are using a different initialContextFactorybecause we are following the JNDI-based connection creation process.

When connecting to IBM MQ, authentication details must be provided. In this example, we use the admin user and set the password to password. To change the password, update the MQ_ADMIN_PASSWORD environment variable in your IBM MQ docker-compose file.

Let’s write the producer code.

Let’s write the consumer code.

For this application to work, we need a driver that provides a JMS implementation for connecting to IBM MQ. We can use the com.ibm.mq.allclient for this purpose. Let’s add this dependency in the Ballerina.toml file.

[[platform.java17.dependency]]
groupId="com.ibm.mq"
artifactId="com.ibm.mq.allclient"
version="9.3.3.0"

Additionally, we need two other dependent JAR files required for JNDI-based JMS administered object access.

fscontext.jar
providerutil.jar

These JAR files come with the IBM MQ installation. Refer to this article to locate them on your local setup. In a Docker-based setup, you can find the JAR files in the /opt/mqm/java/lib directory.

Use the following commands to copy the files from the container.

# copy `fscontext.jar`
docker cp ibmmq-server:/opt/mqm/java/lib/fscontext.jar <destination-path>

# copy `providerUtil.jar`
docker cp ibmmq-server:/opt/mqm/java/lib/providerutil.jar <destination-path>

Add them as dependencies in the Ballerina.toml file.

[[platform.java17.dependency]]
path="/path/to/fscontext.jar"

[[platform.java17.dependency]]
path="/path/to/providerutil.jar"

Once all are set up, run the application using following command.

bal run

In this article we discussed how we can connect to an IBM MQ server using Ballerina JMS connector. Hope you guys enjoyed the process. Happy coding…!

References

IBM MQ documentation: https://www.ibm.com/docs/en/ibm-mq/9.3
IBM MQ Explorer documentation: https://www.ibm.com/docs/en/ibm-mq/9.3?topic=mq-explorer

Previous: JMS with Ballerina lang: Part 5