Part 1 — Getting started on AMQP using IBM MQ

A couple of days ago, a customer requested for a Proof of Concept to show how to configure IBM MQ to provide messaging service via AMQP. This feature is not new, but I never gotten around to play with it. I spent a couple of hours fiddling and found that it wasn’t rocket science. I wrote this article so that others can benefit from my journey.

As it is middle of a lock down due to COVID-19, I do have some spare time; therefore I decided this to be a 4-part series.

• Part 1 — Getting started on AMQP using IBM MQ
• Part 2 — Enable TLS communications via AMQP
• Part 3 — Create a custom Docker image with AMQP configurations
• Part 4 — Deploy Docker image on Red Hat OpenShift

Before I begin

First of all, let me start by laying out the environment.

• IBM MQ v9.1.0.4
• RedHat v7.7
• OpenJDK v11 to compile and run the sample Java code

Step 1: Prepare the AMQP configuration

1. Ensure that you have included the AMQP bundle when installing IBM MQ. To check if you have installed this bundle, run the following command.

$ rpm -qa --qf "%{NAME}-%{VERSION}-%{RELEASE}\t%{INSTPREFIXES}\n" | grep MQSeriesAMQP
MQSeriesAMQP-9.1.0-4 /opt/mqm

2. Run sample script to create a sample configuration for AMQP. Note that you must run this command using a user that is in the mqmgroup.

$ cd /opt/mqm/amqp/samples
$ ./SampleMQM.sh

This script does the following:

• Creates a queue manager AMQP_SAMPLE_QM.
• Sets authorizations to allow everybody to connect to the queue manager and to publish and subscribe to the base topic SYSTEM.BASE.TOPIC.
• Start the queue manager and the AMQP service SYSTEM.AMQP.SERVICE.
• Defines a AMQP channel with port ranging 1–5672
• Finally starts the channel

# This script creates an AMQP-enabled Queue manager to allow quick testing.
# Get the name of the Queue Manager
QMGR=AMQP_SAMPLE_QM
# Get the Port number
PORT=${1-5672}
# Check the queue manager doesn't exist already
dspmq -m $QMGR >/dev/null 2>&1
rc=$?
if [ $rc -eq 0 ]; then
  echo "Queue manager $QMGR already exists."
  exit 1
fi
crtmqm $QMGR
strmqm $QMGR
# Allow user nobody to publish and subscribe on any topic.
# Note: Allowing the user nobody to do something in MQ, allows all users to do it!
setmqaut -m $QMGR -t qmgr -p nobody -all +connect
setmqaut -m $QMGR -t topic -n SYSTEM.BASE.TOPIC -p nobody -all +pub +sub
# Start the service
echo "START SERVICE(SYSTEM.AMQP.SERVICE)" | runmqsc $QMGR
# Create and start a channel
echo "DEFINE CHANNEL(SAMPLE.AMQP.CHANNEL) CHLTYPE(AMQP) PORT($PORT) MCAUSER('nobody')" | runmqsc $QMGR
sleep 2
echo "START CHANNEL(SAMPLE.AMQP.CHANNEL)" | runmqsc $QMGR

Step 2: Compile and run a sample Java code

1. Clone the java-mqlight repository from Github

$ git clone https://github.com/mqlight/java-mqlight.git

2. Before you try to compile and generate the JAR file, let’s make a couple of modifications in the pom.xml to save you many heartaches.

• Remove the version here — so that we can use the later version. There is some problems with version 3.0.0.

<groupId>org.codehaus.mojo</groupId>
<artifactId>findbugs-maven-plugin</artifactId>
<!-- version>3.0.0</version -->

• Remove the plugin maven-javadoc-plugin. This is some issues generating Java documentation

<!--
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-javadoc-plugin</artifactId>
          <version>2.10.1</version>
          <configuration>
            <excludePackageNames>com.ibm.mqlight.api.impl</excludePackageNames>
          </configuration>
          <executions>
            <execution>
              <id>attach-javadocs</id>
              <goals>
                <goal>jar</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
-->

3. Now, you can start compile and generate the target JAR files; but remember to skip the test because there are some issues. All we need is the JAR executable is generated.

$ cd java-mqlight
$ mvn install -Dmaven.test.skip=true

5. On build success, you will see this.

[INFO] Reactor Summary for com.ibm.mqlight:mqlight-project 1.0-SNAPSHOT:
[INFO]
[INFO] com.ibm.mqlight:mqlight-project .................... SUCCESS [  0.347 s]
[INFO] com.ibm.mqlight:mqlight-api ........................ SUCCESS [  8.752 s]
[INFO] com.ibm.mqlight:mqlight-api-samples ................ SUCCESS [  2.572 s]
[INFO] com.ibm.mqlight:mqlight-distribution ............... SUCCESS [  0.487 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  12.726 s
[INFO] Finished at: 2020-04-18T17:47:51+10:00
[INFO] ------------------------------------------------------------------------

6. You will find the following executable JARs generated that you are interested in.

• ./mqlight/target/mqlight-api-1.0-SNAPSHOT.jar
• ./mqlight-samples/target/mqlight-api-samples-1.0-SNAPSHOT.jar

7. There is a error in the packaging; a missing dependencies JAR file — proton-j-0.12.1.jar. Google and download to the lib folder.

8. Now, try to run the Receive application.

java -classpath ./lib/proton-j-0.12.1.jar:./lib/gson-2.2.4.jar:./lib/logback-classic-1.1.2.jar:./lib/logback-core-1.1.2.jar:./lib/netty-all-4.0.21.Final.jar:./lib/slf4j-api-1.7.5.jar:./lib/stateless4j-2.5.0.jar:./mqlight/target/mqlight-api-1.0-SNAPSHOT.jar:./mqlight-samples/target/mqlight-api-samples-1.0-SNAPSHOT.jar com.ibm.mqlight.api.samples.Receive -s amqp://ibmmqserver:5672

It shows it is connected and it is subscribed to the public topic.

Connected to amqp://ibmmqserver:5672 using client-id AUTO_7e2839f
Subscribed to pattern: public

9. Open another terminal window, and run the Send application to send 10 messages.

java -classpath ./lib/proton-j-0.12.1.jar:./lib/gson-2.2.4.jar:./lib/logback-classic-1.1.2.jar:./lib/logback-core-1.1.2.jar:./lib/netty-all-4.0.21.Final.jar:./lib/slf4j-api-1.7.5.jar:./lib/stateless4j-2.5.0.jar:./mqlight/target/mqlight-api-1.0-SNAPSHOT.jar:./mqlight-samples/target/mqlight-api-samples-1.0-SNAPSHOT.jar com.ibm.mqlight.api.samples.Send -s amqp://[ibmmqserver]:5672 -r 10

It shows it is connected and sending 10 messages before exiting

Connected to amqp://ibmmqserver:5672 using client-id AUTO_714422f
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Exiting

10. Now switch back to the terminal window that is running the Receive application. You will see the messages received.

Subscribed to pattern: public
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!
Hello World!

Finally

OK, there you have it, it was not difficult. The most challenging aspect was trying to get the Java sample code to compile. There were Java incompatibility issues and bundle incompatibility issues. And then, there was a packaging issue (maybe should feedback to the author). Nevertheless, I did some workaround and managed to make it work. It was not perfect, but it works!! Maybe, I should try the Python sample code next round?

Disclaimer:

All opinions expressed here are very much my own and not of IBM. All codes/scripts/artifacts are provided as-is with no support unless otherwise stated.