IBM MQ has a Spring Boot Starter, allowing Spring developers an easy way to configure the IBM MQ JMS package.

MQ enables applications to communicate and share data between themselves in a reliable and scalable way that decouples one application from another. In this way, it assists the integration of applications running in different frameworks, languages, platforms, clouds, and locations.

Learning objectives

This tutorial shows you how to use the MQ Spring JMS Starter to access an IBM MQ server from a Spring Boot application. This example uses a local MQ instance running in a Docker container. You could also use an MQ server in IBM Cloud. The application includes an example pair of REST endpoints through which messages can be sent and retrieved from MQ.

You perform the following steps:

• Create a Spring Boot application using the Spring Initializr
• Launch a local MQ Server using Docker
• Add the MQ server config (credentials and URL) to your application
• Add the MQ Spring Starter to your application
• Add a REST endpoint that sends a message
• Add a REST endpoint that retrieves messages
• Build the app and invoke the REST endpoint and display the results from MQ.

Prerequisites

• Maven and Java installed on your computer. It is assumed that you can build and run a Maven based Spring Initializr project.
• Docker installed on your computer. It is assumed that you are able to start/stop containers and are generally familiar with Docker.

Estimated time

This tutorial should take about one hour.

Steps

Step 1. Create a Spring Boot application using the Spring Initializr

On the Spring Initializr page generate a Maven Project with language Java, and the Web dependency. For this example, we use group com.example and artifact mq-spring. Download the project and unzip it.

Step 2. Launch a local MQ Server using Docker

The IBM MQ for Developers container provides a quick and simple way to launch a local MQ Server via Docker. You can launch one using the following command:

docker run ‑‑env LICENSE=accept ‑‑env MQ_QMGR_NAME=QM1 
           ‑‑publish 1414:1414 
           ‑‑publish 9443:9443 
           ‑‑detach 
           ibmcom/mq

Check that the server is running using docker ps:

$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS                                            NAMES
3a225c721428        ibmcom/mq           "runmqdevserver"    4 hours ago        Up 4 hours         0.0.0.0:1414‑>1414/tcp, 0.0.0.0:9443‑>9443/tcp   reverent_bartik

Step 3. Add the MQ server config (credentials and URL) to your application

The default configuration for the local MQ Server includes a user of admin with a password of passw0rd. This can be passed to the application via the normal Spring application.properties file.

Edit the unzipped Spring Initializr project and add the server information to the src/main/resources/application.properties file with the following property names and values:

ini
ibm.mq.queueManager=QM1
ibm.mq.channel=DEV.ADMIN.SVRCONN
ibm.mq.connName=localhost(1414)
ibm.mq.user=admin
ibm.mq.password=passw0rd

Note: It is not recommended to store credentials in your application. We do so here only for the sake of simplicity in this tutorial. The MQ Spring Boot Starter can utilize other property sources such as environment variables, etc.

Step 4. Add the MQ Spring Starter to your application

For this example, we’ll create a simple REST application with an endpoint that sends a message via the MQ Server and a second endpoint that retrieves and returns sent messages.

Edit the unzipped Spring Boot project to make the following changes:

1. Add the following dependencies to the pom.xml dependencies section:

   
      xml
       <dependency>
           <groupId>com.fasterxml.jackson.core</groupId>
           <artifactId>jackson‑databind</artifactId>
       </dependency>
       <dependency>
           <groupId>com.ibm.mq</groupId>
           <artifactId>mq‑jms‑spring‑boot‑starter</artifactId>
           <version>2.0.0</version>
       </dependency>
   

   Show more

2. Add annotations to the Spring Boot application class that was created by the Spring Initializr – com/example/mqpring/MqspringApplication.java. (Note that the Java package and class names are derived from the Group and Artifact values entered on the Initializr.)

   • @RestController to enable REST endpoints.
   • @EnableJms to allow discovery of methods annotated @JmsListener

3. Add an @Autowired annotation for the JmsTemplate object. The IBM MQ Spring Boot Starter creates the JmsTemplate with the properties configured via the application.properties:

   
       java
       @SpringBootApplication
       @RestController
       @EnableJms
       public class MqspringApplication {
   
           @Autowired
           private JmsTemplate jmsTemplate;
   
           public static void main(String[] args) {
               SpringApplication.run(MqspringApplication.class, args);
           }
   
       }
      

   Show more

Step 5. Add a REST endpoint that sends a message via MQ

Add a REST endpoint to the with the @GetMapping annotation with a path of send. Use the JmsTemplate convertAndSend method to send a message Hello World! to the queue DEV.QUEUE.1. Add Exception handling as required.

java
@GetMapping("send")
String send(){
    try{
        jmsTemplate.convertAndSend("DEV.QUEUE.1", "Hello World!");
        return "OK";
    }catch(JmsException ex){
        ex.printStackTrace();
        return "FAIL";
    }
}

Note: The queue DEV.QUEUE.1 is precreated by the IBM MQ for Developers container. The method is kept brief for this tutorial, a real application would likely have better exception handling and can use typed objects as message payloads. See the Spring guide for Messaging with JMS for more information.

Step 6. Add a REST endpoint that retrieves messages via MQ

Add a REST endpoint with the @GetMapping annotation with a path of recv. Use the JmsTemplate receiveAndConvert method to receive a message from the queue DEV.QUEUE.1. Add Exception handling as required.

java
@GetMapping("recv")
String recv(){
    try{
        return jmsTemplate.receiveAndConvert("DEV.QUEUE.1").toString();
    }catch(JmsException ex){
        ex.printStackTrace();
        return "FAIL";
    }
}

Note: *The JmsTemplate receive methods are blocking! (You can try this by invoking the recv endpoint before invoking send and it will not return until send is invoked, unblocking the receive call.) For a non-blocking alternative, consider using a @JmsListener

Step 7. Build the app and invoke the REST endpoints and display the results

Build and run your app with the following command:

mvn package spring‑boot:run

Now you can invoke the REST endpoint for send, http://localhost:8080/send. You should see the OK reply from your endpoint confirming that the message has been sent.

Having sent a message, you can invoke the REST endpoint for receive, http://localhost:8080/recv. You should see the reply from the endpoint with the content of the message “Hello World!“

Summary

The IBM MQ Spring Starter makes it easy to send and receive messages from an MQ Service using Spring’s JmsTemplate API, with Spring auto configuration.