Skip to content

Commit

Permalink
feat: first draft of JMS Binding Objects
Browse files Browse the repository at this point in the history
  • Loading branch information
adamretter committed Apr 3, 2023
1 parent d979555 commit 11e3bf9
Show file tree
Hide file tree
Showing 4 changed files with 256 additions and 6 deletions.
80 changes: 74 additions & 6 deletions jms/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,25 +3,85 @@
This document defines how to describe JMS-specific information on AsyncAPI.

<a name="version"></a>
## Versions

## Version
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.

Current version is `0.1.0`.
## 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](https://www.ietf.org/rfc/rfc2119.txt).

## Protocol

These bindings use the `jms` [protocol](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#definitionsProtocol) 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 defined a protocol for implementing JMS API operations. Regardless, for the purposes of AsyncAPI we can treat it as a "protocol" to enable AsyncAPI definitions that are somewhat portable between various JMS Providers.



## Server Object

The fields of the standard [Server Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#serverObject) are constrained and interpreted as follows:

Server Object Field Name | Values for JMS Protocol | Description
---|:---|:---
<a name="serverObjectProtocolFieldValueJMS"></a>`protocol` | `jms` | **REQUIRED**. MUST be `jms` for the scope of this specification.
<a name="serverObjectUrlFieldValueJMS"></a>`url` | e.g., `jms://host:port` | **REQUIRED**. MUST be a URL containing the hostname and port of a JMS Broker.
<a name="serverObjectProtocolVersionFieldValueJMS"></a>`protocolVersion` | e.g., `2.0` | **OPTIONAL**, defaults to `2.0`. If present MUST be the version indicator of the JMS API. Valid values are `1.0`, `1.0.1`, `1.0.1a`, `1.0.2`, `1.0.2a`, `1.0.2b`, `1.1`, `2.0`, `2.0a`, `2.1`, or `3.0`.


<a name="server"></a>

## Server Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.
The JMS [Server Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#server-bindings-object) is defined by a [JSON Schema](json_schemas/server.json), which defines these fields:

Field Name | Type | Description
---|:---:|---
<a name="serverBindingObjectJMSConnectionFactory"></a>`jmsConnectionFactory` | string | **REQUIRED**. The classname of the [ConnectionFactory](https://docs.oracle.com/javaee/7/api/javax/jms/ConnectionFactory.html) implementation for the JMS Provider.
<a name="serverBindingObjectJMSProperties"></a>`properties` | [Schema Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject) | **OPTIONAL**. Additional properties to set on the JMS ConnectionFactory implementation for the JMS Provider.
<a name="serverBindingObjectJMSClientID"></a>`clientID` | string | **OPTIONAL**. A client identifier for applications that use this JMS connection factory. If the Client ID Policy is set to 'Restricted' (the default), then configuring a Client ID on the [ConnectionFactory](https://docs.oracle.com/javaee/7/api/javax/jms/ConnectionFactory.html) prevents more than one JMS client from using a connection from this factory.
<a name="serverBindingObjectBindingVersion"></a>`bindingVersion` | string | **OPTIONAL**, defaults to `latest`. The version of this binding.


<a name="channel"></a>

<a name="channel"></a>
## Channel Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.
The JMS [Channel Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#channel-bindings-object) is defined by a [JSON Schema](json_schemas/channel.json), which defines these fields:

Field Name | Type | Description
---|:---:|---
<a name="channelBindingObjectDestinationType"></a>`destinationType` | string | **OPTIONAL**, defaults to `queue`. The type of destination, which MUST be either `queue`, or `fifo-queue`. SHOULD be specified to document the messaging model (point-to-point, or strict message ordering) supported by this channel.
<a name="channelBindingObjectDestination"></a>`destination` | string | **OPTIONAL**, defaults to the channel name. The destination (queue) name for this channel. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name according to the JMS Provider.
<a name="channelBindingObjectBindingVersion"></a>`bindingVersion` | string | **OPTIONAL**, defaults to `latest`. The version of this binding.

### Examples

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

```yaml
channels:
user.signup:
description: |
This application receives command messages from this channel about users to sign up.
Minimal configuration, omitting a channel binding object.
publish:
#...
user.signedup:
description: |
This application sends events to this channel about users that have signed up.
Explicitly provides a channel binding object.
bindings:
jms:
destination: user-signed-up
destinationType: fifo-queue
bindingVersion: '0.0.1'
subscribe:
#...
```



Expand All @@ -37,4 +97,12 @@ This object MUST NOT contain any properties. Its name is reserved for future use

## Message Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.
The JMS [Message Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](json_schemas/message.json), which defines these fields:

Field Name | Type | Description
---|:---:|---
<a name="messageBindingObjectHeaders"></a>`headers` | [Schema Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#schemaObject) | **OPTIONAL**. A Schema object containing the definitions for JMS specific headers (so-called protocol headers). This schema MUST be of type `object` and have a `properties` key. Examples of JMS protocol headers are `JMSMessageID`, `JMSTimestamp`, and `JMSCorrelationID`.
<a name="messageBindingObjectBindingVersion"></a>`bindingVersion` | string | **OPTIONAL**, defaults to `latest`. The version of this binding.

Note that application headers must be specified in the [`headers` field of the standard Message Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#messageObjectHeaders) and are set as [Message Properties](https://docs.oracle.com/javaee/7/api/javax/jms/Message.html#Message%20Properties) 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](#messageBindingObjectHeaders) and are transmitted in the [`headers` section of the JMS message](https://docs.oracle.com/javaee/7/api/javax/jms/Message.html#Message%20Headers).
40 changes: 40 additions & 0 deletions jms/json_schemas/channel.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/jms/channel.json",
"title": "Channel Schema",
"description": "This object contains configuration for describing a JMS queue, or FIFO queue as an AsyncAPI channel. This objects only contains configuration that can not be provided in the AsyncAPI standard channel object.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\-\\_]+$": {
"$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension"
}
},
"properties": {
"destination": {
"type": "string",
"description": "The destination (queue) name for this channel. SHOULD only be specified if the channel name differs from the actual destination name, such as when the channel name is not a valid destination name according to the JMS Provider. Defaults to the channel name."
},
"destinationType": {
"type": "string",
"enum": ["queue", "fifo-queue"],
"default": "queue",
"description": "The type of destination. SHOULD be specified to document the messaging model (point-to-point, or strict message ordering) supported by this channel."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.0.1"
],
"description": "The version of this binding. If omitted, 'latest' MUST be assumed."
}

},
"examples": [
{
"destination": "user-signed-up",
"destinationType": "fifo-queue",
"bindingVersion": "0.0.1"
}
]
}
73 changes: 73 additions & 0 deletions jms/json_schemas/message.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/jms/message.json",
"title": "Message Schema",
"description": "This object contains configuration for describing a JMS message as an AsyncAPI message. This objects only contains configuration that can not be provided in the AsyncAPI standard message object.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\-\\_]+$": {
"$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension"
}
},
"properties": {
"headers": {
"$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema",
"description": "A Schema object containing the definitions for JMS headers (protocol headers). This schema MUST be of type 'object' and have a 'properties' key. Examples of JMS protocol headers are 'JMSMessageID', 'JMSTimestamp', and 'JMSCorrelationID'."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.0.1"
],
"description": "The version of this binding. If omitted, 'latest' MUST be assumed."
}

},
"examples": [
{
"headers": {
"type": "object",
"required": ["JMSMessageID"],
"properties": {
"JMSMessageID": {
"type": ["string", "null"],
"description": "A unique message identifier. This may be set by your JMS Provider on your behalf."
},
"JMSTimestamp": {
"type": "integer",
"description": "The time the message was sent. This may be set by your JMS Provider on your behalf. The time the message was sent. The value of the timestamp is the amount of time, measured in milliseconds, that has elapsed since midnight, January 1, 1970, UTC."
},
"JMSDeliveryMode": {
"type": "string",
"enum": ["PERSISTENT", "NON_PERSISTENT"],
"default": "PERSISTENT",
"description": "Denotes the delivery mode for the message. This may be set by your JMS Provider on your behalf."
},
"JMSPriority": {
"type": "integer",
"default": 4,
"description": "The priority of the message. This may be set by your JMS Provider on your behalf."
},
"JMSExpires": {
"type": "integer",
"description": "The time at which the message expires. This may be set by your JMS Provider on your behalf. A value of zero means that the message does not expire. Any non-zero value is the amount of time, measured in milliseconds, that has elapsed since midnight, January 1, 1970, UTC, at which the message will expire."
},
"JMSType": {
"type": ["string", "null"],
"description": "The type of message. Some JMS providers use a message repository that contains the definitions of messages sent by applications. The 'JMSType' header field may reference a message's definition in the provider's repository. The JMS API does not define a standard message definition repository, nor does it define a naming policy for the definitions it contains. Some messaging systems require that a message type definition for each application message be created and that each message specify its type. In order to work with such JMS providers, JMS clients should assign a value to 'JMSType', whether the application makes use of it or not. This ensures that the field is properly set for those providers that require it."
},
"JMSCorrelationID": {
"type": ["string", "null"],
"description": "The correlation identifier of the message. A client can use the 'JMSCorrelationID' header field to link one message with another. A typical use is to link a response message with its request message. Since each message sent by a JMS provider is assigned a message ID value, it is convenient to link messages via message ID, such message ID values must start with the 'ID:' prefix. Conversely, application-specified values must not start with the 'ID:' prefix; this is reserved for provider-generated message ID values."
},
"JMSReplyTo": {
"type": "string",
"description": "The queue or topic that the message sender expects replies to."
}
}
},
"bindingVersion": "0.0.1"
}
]
}
69 changes: 69 additions & 0 deletions jms/json_schemas/server.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "http://asyncapi.com/bindings/jms/server.json",
"title": "Server Schema",
"description": "This object contains configuration for describing a JMS broker as an AsyncAPI server. This objects only contains configuration that can not be provided in the AsyncAPI standard server object.",
"type": "object",
"additionalProperties": false,
"patternProperties": {
"^x-[\\w\\d\\.\\-\\_]+$": {
"$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension"
}
},
"required": ["jmsConnectionFactory"],
"properties": {
"jmsConnectionFactory": {
"type": "string",
"description": "The classname of the ConnectionFactory implementation for the JMS Provider."
},
"properties": {
"type": "array",
"items": {
"$ref": "#/schemas/property"
},
"description": "Additional properties to set on the JMS ConnectionFactory implementation for the JMS Provider."
},
"clientID": {
"type": "string",
"description": "A client identifier for applications that use this JMS connection factory. If the Client ID Policy is set to 'Restricted' (the default), then configuring a Client ID on the ConnectionFactory prevents more than one JMS client from using a connection from this factory."
},
"bindingVersion": {
"type": "string",
"enum": [
"0.0.1"
],
"description": "The version of this binding. If omitted, 'latest' MUST be assumed."
}

},
"schemas": {
"property": {
"type": "object",
"required": ["name", "value"],
"properties": {
"name": {
"type": "string",
"description": "The name of a property"
},
"value": {
"type": ["string", "boolean", "number", "null"],
"description": "The name of a property"
}
}
}
},
"examples": [
{
"jmsConnectionFactory": "org.apache.activemq.ActiveMQConnectionFactory",
"properties": [
{
"name": "disableTimeStampsByDefault",
"value": false
}
],
"clientID": "my-application-1",
"bindingVersion": "0.0.1"
}
]
}

0 comments on commit 11e3bf9

Please sign in to comment.