Application developers who are working in Java, using the JMS interface, often choose to work with the Spring Framework. Spring can simplify the coding of new applications by providing templates for common patterns, and has been successfully used for many years with the MQ JMS classes. The JmsTemplate class in Spring is the key interface here, but it still relies on having dependencies and configurations defined or coded.

The Spring Framework includes several modules for different capabilities. One of these components is Spring Boot. Spring Boot starters conveniently pull in all the dependencies and auto-configuration libraries required to use a particular technology. This makes it very easy to get going with a new application and technology, faster than working directly with classes like JmsTemplate. So how can we enable this easy access for MQ applications?

In this post I described how MQ’s Java classes are available for direct download from Maven Central Repository. And we have now exploited that to create a Spring Boot Starter for MQ. You can download full source code for the module from GitHub.

Getting Started with MQ Spring Boot

First of all, you need a running queue manager. Then you will create an application that accesses that queue manager.

Running a Queue Manager in a container

To get started quickly, you can use the IBM MQ for Developers container which runs the server processes. When that container runs, it creates several objects by default and those definitions are known by the auto-configuration module here. Default values match those needed by the container’s queue manager.

This means that you can run a queue manager using that Docker environment and connect to it without further configuration. You can run the container on a Linux system with this command:

  docker run --env LICENSE=accept --env MQ_QMGR_NAME=QM1 \
             --publish 1414:1414 \
             --publish 9443:9443 \
             --detach \

An example application

The approach taken here is to follow the model for JMS applications shown in the Spring Getting Started Guide for JMS. I followed the path to import that project into an Eclipse workspace and used a gradle build process, but the maven-based process works just as well. As an exercise, I used the maven configuration from the command line instead of from the Eclipse IDE.

The same application code from that example works with MQ with very little modification:

  • Change the original messaging provider given in the dependency list to point at the IBM MQ package.
  • Change the queue name in (“mailbox” is used in the example) to “DEV.QUEUE.1”, a queue predefined with the Developer configuration in the Docker container. If you are not using the Developer configuration defaults, then you will have to either set the queue name to an existing queue or define a new queue to match.

The modified build.gradle file that controls the compilation now has:

  dependencies {

If you prefer to use Maven, then the corresponding section in pom.xml looks like this:


The only real difference is that the Maven configuration has an explicit version number for the MQ Spring Boot module.

Default Configuration

Configuration attributes for the MQ Boot Starter are named with the prefix of “”. The default attributes are set to

This matches the Docker container defaults.

Further Configuration Options

If you already have a running MQ queue manager that you want to use, then you can easily modify the default configuration to match by providing override values. The queue manager may be local or even as a hosted service in the IBM Cloud. An file attached to the Java project is one way to externalise these attributes. The configuration takes effect without requiring any code alterations.

Specify the queue manager name with the attribute


For client connections to a queue manager, you must also set


If you do not set both the channel and connName, then a local queue manager is assumed. The configuration component also supports some TLS-related attributes. These are described more fully in the README file but the default values are null. You will probably also need to set


to override the default values. These attributes can be left empty to use the local OS userid with no authentication, if permitted by the queue manager.

For example in an file:

Spring Boot will then create a ConnectionFactory that can then be used to interact with your queue manager.

Testing the example program

Running the example program can be done with the gradle bootRun command. Or with maven, run mvn package followed by java -jar ./target/gs-messaging-jms.jar to execute the program. You should see output like this:
Spring Boot JMS program output
It shows how the application has put a message (“sending an email message”) and then retrieved it.


Using this Spring Boot Starter with MQ makes it very easy to get going quickly. Then after your first application is running, you can then extend it to take advantage of the many features of MQ. If you try it out, you can give feedback here or on the GitHub issues page.

Update – June 2018

Earlier this year, there was a major update to the Spring Boot Framework, known as Boot 2. The MQ boot starter has been updated to work with this new level of the framework. Of course, all publicly released levels of this code are available from the Maven Central Repository. For Spring Boot 1 compatibility, you should continue to use the 0.0.4 version of this artifact; the 2.0.0 version is Boot 2 compatible and will be used as the base for any future updates.

9 comments on"MQ JMS application development with Spring Boot"

  1. Nice work Mark.
    It is possible to handle more than one queue?
    I see the prefix is hardcoded on the @ConfigurationProperties(prefix = “”)

    • Mark E Taylor May 17, 2019

      I don’t really understand the question. The “prefix” points at the configuration attributes that mostly show how to connect to a queue manager. It’s got nothing to do with the queues that the application uses once connected. If you really meant to ask about connecting to more than one queue manager, then see for techniques that some people have used.

  2. Hi there,

    I’m trying to connect using the CCDT tab file, but failed.
    I’ve copeid the /mnt/mqm/data/qmgrs/QM1/@ipcc/AMQCLCHL.TAB file from the docker container to my computer running docker and running the Java app trying to connect to the MQ inside docker, but got the following exception: JMSWMQ2020: Failed to connect to queue manager ‘QM1’ with connection mode ‘Client’ and supplied CCDT URL ‘file://\work\CIB\IG3\AMQCLCHL.TAB’, see linked exception for more information.

    Caused by: JMSCMQ0001: IBM MQ call failed with compcode ‘2’ (‘MQCC_FAILED’) reason ‘2278’ (‘MQRC_CLIENT_CONN_ERROR’).
    … 31 common frames omitted
    Caused by: CC=2;RC=2278
    … 30 common frames omitted

    Any ideas how to get it work?

  3. Worked very well. Also tried to run transaction management while receiving and sending messages. All went fine.
    But the issue is, producer is non-jms and my application is going in error for those messages.
    So question is there any way to use non -jms client with spring with transaction management? or any ideas how to do it.

  4. Mark, I ran into the following exception. Any idea?


    Xin Wu

    Parameter 0 of method myFactory in hello.Application required a bean of type ‘javax.jms.ConnectionFactory’ that could not be found.- Bean method ‘connectionFactory’ not loaded because AnyNestedCondition 0 matched 2 did not; NestedCondition on JndiConnectionFactoryAutoConfiguration.JndiOrPropertyCondition.Property @ConditionalOnProperty (spring.jms.jndi-name) did not find property ‘jndi-name’; NestedCondition on JndiConnectionFactoryAutoConfiguration.JndiOrPropertyCondition.Jndi @ConditionalOnJndi JNDI environment is not available

  5. there’s no “hello.Application”, are the files are on the github ?

    • Mark E Taylor June 12, 2018

      I used the Spring Getting Started page linked above to extract and import the sample application – see – and then made the minor changes. For various reasons, I deliberately did not want to have a separate copy of that application code in here.

  6. Mark E Taylor May 08, 2018

    Connection is not the same as accessing a queue. You connect to a queue manager, and that can be handled through this Spring Boot mechanism. Individual queues can then be named explicitly. There are other Spring interfaces for JMS that you may prefer to use, as they give access to JNDI-based lookups for both connections (queue managers) and destinations (queues/topics). For example, see

  7. Hello Mark, Thanks for the article. I did see your github source. MY question is that you are connecting to MQ directly with host, port, id , password, but in a secure environment these are not exposed. I am new to spring integration and I see MQ queue is configured into a WebSphere JMS Queue, and we need to lookup those queues. only Admin owns the configuration details. In such case how to connect?

Join The Discussion

Your email address will not be published.