[AIX, Linux, Windows]

Developing AMQP client applications

The IBM® MQ support for AMQP APIs, allows an IBM MQ administrator to create an AMQP channel. When it is started, this channel defines a port number that accepts connections from AMQP client applications.

You can install an AMQP channel on AIX®, Linux®, or Windows; it is not available on IBM i or z/OS®.

An AMQP 1.0 client application can connect to queue manager with an AMQP channel.

[MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]

Developing applications using the Apache Qpid JMS library

Introduction

The Apache Qpid JMS library uses the AMQP 1.0 protocol to provide an implementation of the JMS 2 specification.

Apache Qpid JMS uses some aspects of the AMQP 1.0 protocol in a different way from the MQ Light messaging APIs. IBM MQ 9.2 adds support to IBM MQ AMQP channels, so that Apache Qpid JMS applications are able to connect to IBM MQ and do publish/subscribe messaging, including the use of shared subscriptions.

[MQ 9.2.1 Dec 2020]IBM MQ 9.2.1 adds further support to IBM MQ AMQP channels, so that Apache Qpid JMS applications are able to connect to IBM MQ and perform point to point messaging. See Point-to-point support on AMQP channels for more information.

[MQ 9.2.2 Mar 2021]IBM MQ 9.2.2 adds further queue browse support for IBM MQ AMQP channels, so that Apache Qpid JMS applications can connect to IBM MQ and perform browsing of messages from a queue. See Point-to-point support on AMQP channels for more information.

[MQ 9.2.3 Jul 2021]IBM MQ 9.2.3 adds two additional channel attributes for AMQP channels, TMPMODEL and TMPQPRFX. These attributes are for the model queue, and temporary queue prefix to be used while creating a temporary queue.

Intercommunication with other IBM MQ applications

It is possible to send messages between Apache Qpid JMS applications and other IBM MQ applications. For example, an Apache Qpid application can publish messages on a topic, and MQ Light applications can receive them by creating a subscription.

An Apache Qpid JMS application can also publish messages that are consumed by traditional IBM MQ applications, for example using the MQSUB API call to subscribe to the same topic.

Similarly, Apache Qpid JMS applications can subscribe to IBM MQ topics that traditional IBM MQ applications publish messages on.

It is also possible for an Apache Qpid JMS application to share a subscription with an MQ Light application, as long as both clients specify the same share name and topic pattern.

Note that, in order to do this, the Apache Qpid JMS application must not connect with a client ID. This ensures that the IBM MQ subscription name used by both of the applications is the same.

Attention: It is not possible for an Apache Qpid JMS application to share a subscription with an IBM MQ JMS application.

Apache Qpid JMS restrictions
The following JMS capabilities are supported:
  • Client acknowledge , auto-acknowledge, and dups ok acknowledge mode (DUPS_OK_ACKNOWLEDGE)
    • Connecting with or without credentials
    • Creating a consumer on a topic destination
    • Creating a durable consumer on a topic destination
    • Creating a shared consumer on a topic destination
    • Creating a shared durable consumer on a topic destination
    • Client acknowledge and auto-acknowledge modes
    • Message acknowledgment and session acknowledgment
    • Unsubscribing from a durable subscription
    • [MQ 9.2.1 Dec 2020]Creating a temporary queue
    • [MQ 9.2.1 Dec 2020]Creating a consumer on a queue or temporary queue destination
    • [MQ 9.2.1 Dec 2020]JMS MessageListeners
    • [MQ 9.2.1 Dec 2020]JMS Consumer to receive body; the JMS 2.0 method called Consumer.receiveBody()
    • [MQ 9.2.1 Dec 2020]The following JMS message types are supported:
      • BytesMessage
      • MapMessage
      • ObjectMessage
      • StreamMessage
      • TextMessage
    • [MQ 9.2.2 Mar 2021]Browsing messages from a queue
The following JMS capabilities are not supported by AMQP clients:
  • The use of transacted sessions and transacted JMSContexts
    • The use of message selectors
    • The use of the nolocal attribute
    • The use of transacted sessions
    • The use of delivery delay
    • At IBM MQ 9.2.1, browsing messages from a queue.
    • Creating multiple durable subscriptions or consumers with the same client ID and topic
    • [MQ 9.2.1 Dec 2020]JMS Temporary Topics
    • AMQP filters are not supported.
[MQ 9.2.1 Dec 2020]Attention: Client acknowledge: if any unsettled AMQP transfers of messages are to be used, that is, when a client acknowledgment of messages is required, then either the clients must settle within a timely manner by sending message acknowledgments within a timely manner when using client acknowledge mode, or consider setting the queue manager property MARKINT (MsgMarkBrowseInterval) to a higher value.

The default value for MsgMarkBrowseInterval is five seconds. If an application does not settle within this default value, duplicate messages might be seen. To avoid duplication of messages, you must increase the value of MsgMarkBrowseInterval accordingly, ideally setting it to NOLIMIT, to represent an unlimited time interval. If an application crashes or disconnects before a message is settled, messages are made available to another application.

See MsgMarkBrowseInterval for more information. As this is a queue manager property, the value you set will apply to all applications connected to that queue manager.

On AMQP, MsgMarkBrowseInterval is valid for queues only, not subscriptions.

Downloading sample AMQP clients

IBM MQ does not ship AMQP clients, but you can download MQ Light clients or download open-source AMQP clients based on Apache Qpid libraries. For more information, see IBM MQ Light and Apache Qpid.

You can also download other open-source AMQP clients based on Apache Qpid libraries. For more information, see https://qpid.apache.org/index.html.
Attention: IBM Support is unable to provide configuration or defect support for these client packages, and any usage questions or code defect reports should be directed to the respective projects.

Deploying AMQP clients to IBM MQ

When an application is ready to deploy, it requires all of the monitoring, reliability, and security capabilities of other enterprise applications. It can also exchange data with other enterprise applications.

When you have deployed an AMQP client, you can exchange messages with IBM MQ applications. For example, if you use the AMQP client to send a JavaScript string message, the IBM MQ application receives an MQ message, where the format field of the MQMD is set to MQSTR.

Managing the AMQP channel

The AMQP channel can be managed in the same way as other MQ channels. You can use MQSC commands, PCF command messages, or IBM MQ Explorer to define, start, stop, and manage the channels. In Creating and using AMQP channels, example commands are provided to define and start connecting clients to a queue manager.

When an AMQP channel is started, you can test it by connecting an AMQP 1.0 client. For example, MQ Light, Apache Qpid Proton, or Apache Qpid JMS.