JMS Bindings

This document defines how to describe JMS-specific information on AsyncAPI.

Versions

The version of this bindings specification is 0.0.1. This is also the bindingVersion for all binding objects defined by this specification. In any given binding object, latest MAY alternatively be used to refer to the currently latest published version of this bindings specification.

Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this bindings specification are to be interpreted as described in IETF RFC2119.

Protocol

These bindings use the jms protocol in AsyncAPI documents to denote connections to and interactions with JMS message brokers.

JMS is not technically a protocol, rather it is an API. A JMS Provider implements the JMS API and may define a protocol for implementing JMS API operations. Regardless, for the purposes of AsyncAPI we can treat it like a "protocol" to enable AsyncAPI definitions that are somewhat portable between various JMS Providers. If necessary, the user is free to combine this binding with other bindings that implement a JMS Provider (e.g. Apache Pulsar, Amazon SQS, IBM MQ, etc.) to detail JMS Provider specific configuration.

NOTE that from protocol version 3.0, this binding is compatible with Jakarta Messaging.

Server Object

The fields of the standard Server Object are constrained and interpreted as follows:

Server Binding Object

The JMS Server Binding Object is defined by a JSON Schema, which defines these fields:

Examples

The following example shows a servers object with a server binding object for jms with JMS specific properties:

1servers:
2  production:
3    url: jms://my-activemq-broker:61616
4    protocol: jms
5    protocolVersion: '1.1'
6    description: The production ActiveMQ broker accessed via JMS.
7    bindings:
8      jms:
9        # JMS protocol specific server details
10        jmsConnectionFactory: org.apache.activemq.ActiveMQConnectionFactory
11        properties:
12          - name: disableTimeStampsByDefault
13            value: false
14        clientID: my-application-1

Channel Binding Object

The JMS Channel Binding Object is defined by a JSON Schema, which defines these fields:

Examples

The following example shows a channels object with two channels, the second having a channel binding object for jms:

1channels:
2  user.signup:
3    description: This application receives command messages from this channel about users to sign up.
4    bindings:
5      jms:
6        destination:     user-sign-up
7        destinationType: fifo-queue
8        bindingVersion:  '0.0.1'
9    publish:
10      #...

Operation Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

Message Binding Object

The JMS Message Binding Object is defined by a JSON Schema, which defines these fields:

Note that application headers must be specified in the headers field of the standard Message Object and are set as Message Properties of the JMS Message; how they are transmitted is defined by the JMS Provider and need not be considered here. In contrast, protocol headers such as JMSMessageID must be specified in the headers field of the message binding object and are transmitted in the headers section of the JMS message.

Examples

The following example shows a message object with both application specific headers, and a message binding object for jms with JMS specific headers:

1message:
2  messageId: my-message-1
3  bindings:
4    jms:
5      headers:
6        # JMS protocol specific message headers
7        required:
8          - JMSMessageID
9      properties:
10        JMSMessageID:
11          name: JMSMessageID
12          description: A unique message identifier. This may be set by your JMS Provider on your behalf.
13          type: string
14        JMSReplyTo:
15          name: JMSReplyTo
16          description: The queue or topic that the message sender expects replies to.
17          type: string
18  headers:
19    # Application specific message headers
20    required:
21      - MyToken
22      - MyOperationID
23    properties:
24      MyToken:
25        name: MyToken
26        description: Some sort of identificaton token for the publishing application.
27        type: string
28      MyOperationID:
29        name: MyOperationID
30        description: Some sort of unique identifier for the application operation to perform.
31        type: string