In this tutorial, you create applications that use the open Advanced Message Queuing Protocol (AMQP) which IBM MQ supports with Qpid AMQP JMS APIs. You run these applications as standard Java applications, as Quarkus applications, and finally as GraalVM applications.

Before you get started, this tutorial explains the technologies you use:

AMQP
Quarkus & GraalVM
IBM MQ Qpid samples

If you're ready to dive in, check that you have all the prerequisites and get started!

Using AMQP, an open standard messaging protocol

AMQP is a non-proprietary messaging protocol that provides an open standard wire protocol for messaging. Apache Qpid is an open source project that provides messaging tools for AMQP as core libraries. They don’t claim it, but think of it as a development kit for AMQP-based apps. For Java Jakarta Messaging 3.0, Apache Qpid provides a .jar library. Speaking of Java Jakarta Messaging 3.0, it’s a Java API for messaging.

You may already have Jakarta Messaging or JMS applications that use the IBM MQ JMS libraries, com.ibm.mq.allclient. While this library supports JMS 2.0 and Java Jakarta Messaging 3.0 and offers support for the full spectrum of messaging features available in IBM MQ, it is proprietary. Some projects prefer to adopt open standards, including over the wire protocols like AMQP.

IBM MQ provides support for AMQP APIs through an AMQP channel that accepts connections from AMQP client applications. Using IBM MQ, Apache Qpid JMS applications can do publish/subscribe messaging and point-to-point messaging. Messaging is not just confined to AMQP client applications, as intercommunication with client applications based on other IBM MQ API stacks is possible.

Using Quarkus and GraalVM for your Java apps

Now that the messaging jargon is clear, this section explains the Java jargon that you need to understand for this tutorial. In this tutorial, you use both Quarkus and GraalVM.

Quarkus is a native Java framework that creates a Java platform for Kubernetes, microservices, and serverless environments. Quarkus’ native execution delivers runtime efficiencies such as fast start up, low memory utilization, and smaller application and container footprints for Java applications.
GraalVM is an advanced JDK with ahead-of-time Native Image compilation. GraalVM allows programs, including Java code, to be compiled into a native executable. The JVM is compiled into the native executable and provides features such as memory management and thread scheduling for the application. So, with GraalVM, your Java apps become leaner, faster, and no longer need a run anywhere JVM. They become better adapted to becoming containerized and for running in the cloud. JVMs provide a run anywhere capability that is an unneeded overhead in a controlled container. This allows the entire Java stack to be optimized when the Java application is compiled by Quarkus for execution as a GraalVM application.

However, not all Java apps will compile and run on GraalVM because not all applications or libraries are compatible with this level of optimization. Particularly, code that uses the intricacies of Java for their own optimization can not use GraalVM. This becomes a significant barrier to Java applications that want to migrate to the cloud. Using a library stack for JMS that runs on GraalVM opens up a path for messaging applications.

Hang on. You might be wondering where Open Liberty fits in to all this. Essentially, if you are looking to deploy new functions and microservices, then Quarkus is a good choice. GraalVM’s native executable capabilities give the ideal runtime characteristics for microservices and serverless functions. Read more about choosing the right Java runtime for the job in this article.

Using IBM MQ Qpid samples for AMQP messaging

In this tutorial, you use samples from the mq-dev-patterns repository, which provides a home for getting started with messaging in a range of programming languages. The samples are ready to run most of the JMS API classes that you want to try in your applications, whether the API feature is supported by IBM MQ over AMQP or not.

The Qpid JMS samples, which are available starting in IBM MQ 9.2.1, support AMQP 1.0 beyond publish/subscribe messaging. There was already a Qpid JMS Client stack for Quarkus, so that stack was configured to use IBM MQ, and a sample was built that explores the Jakarta Messaging 3.0 API, blind as to whether each feature that was exercised was actually supported in IBM MQ.

To verify API functionality using the Qpid Jakarta Messaging 3.0 stack on Quarkus and with GraalVM, the samples exercise the same set of API features outside of Quarkus, in a regular Java stack. The samples exercise the JMS API. Although it looks like there are multiple samples, there is really one sample with two different veneers. The samples exercise features that are supported as well as features that are not supported by IBM MQ over the AMQP Channel. The samples can run as regular stand-alone applications, as well as on the Quarkus stack as compiled native applications.

Building native executables with GraalVM

There are two ways to create a GraalVM native build.

Install GraalVM as the Java JDK.
Install Docker or Podman so a GraalVM container can be run to create the native binary.

Prerequisites

To complete this tutorial, you need to install or set up:

Git, Maven, and a Java JDK. You can use SDKMAN to install and manage versions of Java and Maven.
A mechanism to build native images either with:
- GraalVM as the SDKMAN installed Java JDK or
- Docker or Podman. Docker commands shown in these tutorial steps can be replaced with Podman commands.
Optionally Quarkus CLI If you want to run the sample code as a non-native Quarkus application.
An AMQP channel enabled instance of IBM MQ. Follow the steps in this tutorial
Optionally for TLS The client-trust.jks that you created in the setting up AMQP with MQ tutorial.

Steps

Step 1. Run the Qpid AMQP JMS client apps as standard Java apps

You should have a running instance of IBM MQ with the AMQP service running. Use the Qpid sample from the mq-dev-patterns repository and run it as a regular JMS application.

The repository makes use of symbolic links to share implementation code across veneer codes. If cloning on Windows, it's recommended to use WSL 2. See this blog Building a customised IBM MQ Container on WSL 2 on how to clone a repository in a WSL 2 subsystem.

Clone the mq-dev-patterns repository:
```
 git clone https://github.com/ibm-messaging/mq-dev-patterns
```
CD to the cloned repository, and then to the amqp-qpid/qpid-standard directory where the Qpid samples reside.
```
 cd mq-dev-patterns/amqp-qpid/qpid-standard
```
Configure the sample for IBM MQ.

The src/main/resources/jndi.properties file is already configured for a customized MQ container. This file contains placeholders for the InitialContextFactory, connection url, queues, topics names, and MQ user username and password that the application uses. If you followed the instructions to create a customized MQ container, then you can leave most of these settings as they are. Otherwise, edit them to suitable settings for your MQ Server.

The setting for queue.myReplyQueueLookup is commented out. This way the application will use temporary queues when requested to run in request / response mode. If you want to use a permanent queue for replies then uncomment the line queue.myReplyQueueLookup = DEV.QUEUE.2.

For TLS over AMQP If you have configured the queue manager to use TLS over AMQP then change the connectionfactory.myFactoryLookup setting from amqp to amqps. ie.
```
 connectionfactory.myFactoryLookup = amqps://localhost:5672?jms.username=app&jms.password=passw0rd
```
Build the AMQP JMS client application. The provided maven pom.xml file builds a .jar file that contains everything that is needed to run the application. Build the application by running the maven command.
```
 mvn clean package
```

Run the application using the default mode settings:

 java -jar target/mq-dev-patterns-qpid-0.1.0.jar

This command puts 5 messages onto the queue. You can retrieve the messages by running the command:

 java -jar target/mq-dev-patterns-qpid-0.1.0.jar get

For TLS over AMQP

You need client-trust.jks, which if you followed the setting up AMQP with MQ tutorial has the associated password SecureKeySt0re.

Copy the client-trust.jks file into the current directory.

The run commands then become:

 java  -Djavax.net.ssl.keyStorePassword=SecureKeySt0re -Djavax.net.ssl.trustStore=./client-trust.jks -Djavax.net.ssl.trustStorePassword=SecureKeySt0re -jar target/mq-dev-patterns-qpid-0.1.0.jar

and

 java  -Djavax.net.ssl.keyStorePassword=SecureKeySt0re -Djavax.net.ssl.trustStore=./client-trust.jks -Djavax.net.ssl.trustStorePassword=SecureKeySt0re -jar target/mq-dev-patterns-qpid-0.1.0.jar get

Note the additional settings.

 -Djavax.net.ssl.keyStorePassword=SecureKeySt0re -Djavax.net.ssl.trustStore=./client-trust.jks -Djavax.net.ssl.trustStorePassword=SecureKeySt0re

If the keystore is in the current directory, these are the only additions you need to run all subsequent AMQP examples over TLS.

These are Qpid AMQP client apps that use the Qpid JMS API stack, and nothing is IBM proprietary. The configuration jndi.properties file is the only link to IBM MQ.

Step 2. Run the apps as compiled executables on GraalVM

Now that you have built and run the Qpid sample client app as a regular Java application, you can run the same application (with a different veneer): as compiled native code on Quarkus.

Regular Java apps can have their own main method, but in Quarkus, apps are run inside a Jakarta EE container, with application endpoints indicated by the @ApplicationScoped annotation. The single configurable app allows you to investigate features of the API without having to rebuild the applications.

This is why there are only two samples, or rather two sample veneers. One for regular Java with its own main method, and one for Quarkus annotated with @ApplicationScoped which allows the Quarkus framework to find and start it. Beyond that, the code is shared and hence the same. The application determines, based on options passed in on the command line, which JMS API features to exercise.

CD to your cloned mq-dev-patterns repository and then to the Qpid samples for Quarkus, amqp-qpid/qpid-quarkus.
Configure the sample for IBM MQ.

Quarkus doesn’t support JNDI, but does provide an alternative mechanism for application configuration. The repository contains an application.properties that is already configured for a customized MQ container. If you want to make changes then edit the src/main/resources/jndi.properties file. This file contains placeholders for the connection URL, queues, topics names and MQ user username and password, that the application uses. It also contains a default set of command line arguments under the setting amqp-mqtest.appargs. If you followed the instructions to create a customized MQ container, then you can leave most of these settings as they are. Otherwise, edit them to suitable settings for your MQ Server.

For TLS over AMQP If you have configured the queue manager to use TLS over AMQP then change the quarkus.qpid-jms.url setting from amqp to amqps. ie.
```
 quarkus.qpid-jms.url=amqps://localhost:5672
```
If you have installed Quarkus, you can run the app inside a Quarkus framework, without building a native binary.
```
 quarkus dev
```
This command starts Quarkus in development mode, and puts 5 messages onto the IBM MQ Queue Manager queue. Press Ctrl-C to stop Quarkus.

For TLS over AMQP: Copy the client-trust.jks file you used previously into the current directory and run this command:
```
 quarkus dev -Djavax.net.ssl.keyStorePassword=SecureKeySt0re -Djavax.net.ssl.trustStore=./client-trust.jks -Djavax.net.ssl.trustStorePassword=SecureKeySt0re
```
Build the AMQP client app. The provided pom.xml files build a GraalVM compiled executable. Build the application by running the command:
```
 mvn package -Pnative
```
Run the app. The application can be started using default mode settings by running the command:
```
 ./target/mq-dev-patterns-quarkus-0.1.0-runner
```
For TLS over AMQP the command becomes:
```
 ./target/mq-dev-patterns-quarkus-0.1.0-runner -Djavax.net.ssl.keyStorePassword=SecureKeySt0re -Djavax.net.ssl.trustStore=./client-trust.jks -Djavax.net.ssl.trustStorePassword=SecureKeySt0re
```
This command puts 5 messages onto the queue. You can retrieve the messages by running the command:
```
 ./target/mq-dev-patterns-quarkus-0.1.0-runner -Damqp-mqtest.appargs=get
```
The -Damqp-mqtest.appargs command line setting overrides the value in the application.properties file.

Although the source code is Java, the executable is a binary, and Java is not being used to execute it. Although it takes longer to build than the regular Java veneer, it executes quicker.

Step 3. Explore the JMS API through the sample clients

You should now have built and running versions of both the regular Java Qpid Client and the Quarkus binary version.

You can now exercise the JMS API through these samples. Unless you make your own code changes, you do not need to rebuild the applications as their JMS modes are command line configurable. The applications determine, based on options passed in on the command line, which JMS API features to exercise.

The options are mostly cumulative which can lead to interesting combinations. Mostly cumulative as there are some exclusive option sets where the last option specified takes precedence.

Commands to run the client apps

To put message on queues using peer-to-peer messaging of high priority messages, use this command to run the GraalVM binary:

./target/mq-dev-patterns-quarkus-0.1.0-runner -Damqp-mqtest.appargs=put,queue,high

Use this command to run the equivalent for the regular Java veneer:

java -jar /target/mq-dev-patterns-qpid-0.1.0.jar put,queue,high

Subsequent examples will show only the options in the form put,queue,high.

You can use both veneers to interact with each other as you explore the JMS API.

Put / Get / Browse

At the most basic level, the exclusive set of options includes PUT, GET, and browse. They all default to using peer-to-peer messaging over queues. If you want to use publish/subscribe over topics, add topic as an option. The mode options topic and queue are another exclusive set.

For peer-to-peer For PUT, use the options: put,queue

For GET, use the options: get,queue
For publish/subscribe For publish, use the options: put,topic

For subscribe, use the options: get,topic

The JMS API allows you to send 5 types of messages: Text, Stream, Map, Object, and Bytes. The samples are configured to send and receive all of these types. By default, the put and publish modes send 3 TextMessages, a StreamMessage, and a MapMessage.

The sending of ObjectMessage and BytesMessage is optional. The examples originally sent these by default, but they are now optional as they show interesting behavior.

To add a BytesMessage, and ObjectMessage as part of the message cycle use these options: put,queue,bytes,object or put,topic,bytes,object.

Request/response

If you want to try request/response then add reply to the list of options in put mode.

For a regular request/response, use: put,queue,reply.

This adds a reply to queue (either temporary or permanent) to the message, which a GET sees and replies to. The put application waits some time for the response.
You can add a reply to queue to a published message by specifying this: put,topic,reply.

This demonstrates a polling pattern as all subscribers see the reply to queue and send a reply.

Message priority

The applications can be set to send higher or lower priority messages. Higher priority messages are taken off queues and topics before lower priority messages.

To send low priority messages, use: put,queue,low.
To send high priority messages, use: put,queue,high.

More options and combinations

The command line options for the samples allow you to control the priority of messages, run the gets asynchronously or synchronously, try session modes like client acknowledge durable subscriptions, request/response, message persistence and custom properties.

As well as features that may not be supported such as use of a selector, transactions, message expiry, and message delay.

For example:

get,selector
put,transaction

For a full list of mode settings see the sample documentation.

Summary and next steps

In this tutorial, you set up and ran working sample client applications based on the Qpid AMQP JMS stack that are able to use messaging with IBM MQ over the AMQP channel. These applications run as regular Java apps and as compiled native Quarkus apps that are ready to deploy into containers and into the cloud. These applications are command line configurable which means that you can explore JMS capability and GraalVM compatibility without having to rebuild them.

For more IBM MQ samples across several languages, explore the samples and patterns repository.

Also, check out more IBM MQ tutorials to keep learning more about building messaging apps.

Developing JMS apps with Quarkus and GraalVM

Developing JMS apps with Quarkus and GraalVM