JMS/AMQP Properties

Edit online

The JMS/AMQP Properties policy can be configured to set AMQP or JMS Properties, a few standard AMQP or JMS Headers, and HTTP Transport Headers in the outgoing JMS message that is being sent from the proxy API to the native API.

AMQP or JMS headers are part of the JMS message that are used by both clients and providers. They are used to identify a message and to route the message to the applicable JMS Providers or consumers.

You can add HTTP Headers such as API Key, Authorization header, and so on. This is useful when the native API is configured with the Enable AMQP/JMS policy and the proxy API wants to pass the security headers over to that native API.

Every JMS message includes JMS/AMQP properties that are always passed from provider to client. The purpose of the properties is to convey extra information to the client outside the normal content of the message body. Additionally, JMS/AMQP property values are set exclusively by the consumer application. When a client receives a message, the properties are in read-only mode. If a client tries to modify any of the properties, a MessageNotWriteableException occurs.

The properties are standard Java name or value pairs. The property names must conform to the message selector syntax specifications defined in the message interface. Property fields are most often used for message selection and filtering. By using a property field, a message consumer can interrogate the property field and perform message filtering and selection. When this action is configured for a proxy API, API Gateway uses the JMS or AMQP properties to authenticate client requests before submitting to the native APIs. JMS or AMQP headers can also be set using properties, however, JMS or AMQP properties take precedence over headers.

The JMS/AMQP properties section has separate policies that you can configure for REST and SOAP APIs. They are as follows:

  • JMS/AMQP REST Properties
  • JMS/AMQP SOAP Properties
The table lists the properties that you can specify for this policy:
Property Description
JMS Property Key Specify the JMS property key.
JMS Property Value Specify the JMS property value for the specified key.

As both these properties support variable framework, you can use the available variables to specify the JMS property key and value.

For example, if you provide a property key as ${request.header.token1} and the corresponding property value as ${request.header.token2}, then the value in token1 and token2 passes security headers to the native API.

For details about the variables available in API Gateway, see Variables Available in API Gateway.

Predefined JMS Properties

Property categories Property Description
Run-time settings
  • jms.deliveryMode
  • jms.priority
  • jms.timeToLive
  • jms.messageType
If the jms.messageType is set to TextMessage, the SOAP envelope in the request is sent as a text message to the JMS queue instead of byte stream.
Standard JMS headers
  • JMSType
  • JMSCorrelationID
  • JMSXGroupID
  • JMSXGroupSeq
The following headers are not applicable. If they are added an error response would be sent at runtime:
  • JMSMessageID
  • JMSExpiration
  • JMSRedelivered
  • JMSTimestamp
  • JMSDeliveryMode
  • JMSPriority
  • JMSReplyTo
  • JMSDestination
Application specific properties
  • SOAPJMS_requestURI
  • SOAPJMS_bindingVersion
  • SOAPJMS_soapAction
  • SOAPJMS_targetService
  • SOAPJMS_contentType

Mapping AMQP messages to JMS

Header

Field name Description
durable When receiving a message, the durable field of header MUST be mapped to the JMSDeliveryMode header of the Message. If the durable field of header is set to false or is not set then the JMSDeliveryMode MUST be taken to be NONPERSISTENT. When the durable field of header is set to true the JMSDeliveryMode of the Message MUST be taken to be PERSISTENT.
priority This field is mapped to the JMSPriorityheader of the Message. JMS Priority is specified as being of type int despite the valid values only being 0-9. AMQP allows for the priority field of header to be any valid ubyte value. When receiving a message with the priority field of header greater than 9, the JMSPriority MUST be set to 9. If the priority field of header is unset then the JMSPriority MUST be taken to be DEFAULT_PRIORITY that is, the value 4).
ttl This field defines the number of milliseconds for which a given message is considered live. There is no direct equivalent for the ttl field of header in the JMS specification.

If and only if the absolute-expiry-time field of properties is not set,JMSExpiration SHOULD be based on the ttl field of header if set, by summing it with the current time in milliseconds since the Unix Epoch

first acquirer This field does not have a direct equivalent within the JMS specification, although JMSRedelivered is related, and so vendor property JMS_AMQP_FIRST_ACQUIRER SHOULD be used.
delivery-count This field is mapped to the JMS-defined JMSXDeliveryCount property and JMSRedelivered header of the Message as follows.

AMQP uses the delivery-count field of header to track previously failed delivery attempts for a message, with the first delivery attempt having a value of zero, and soon.

JMSXDeliveryCount is defined as a Java int count of delivery attempts, set by the provider on receive, where the first delivery attempt has value 1, the second has value 2 and so on.

The value of JMSXDeliveryCount property is thus equal to delivery-count + 1.

The JMSRedelivered header MUST be considered to be true if and only if the delivery-count field of header has a value greater than 0.

Properties

Field name Description
message-id This field is equivalent to the JMSMessageID header of the Message.

The JMSMessageID value is a Java String where as the message-id field of properties is defined as being of type providing message-id, that is message-id-ulong, message-id-uuid, message-id-binary or message-id-string.

The JMS client library MUST prefix ID: to the value of the message-id field of properties before returning it as the JMSMessageID value.

user-id This field is mapped to the JMS-defined JMSXUserID property of the Message.

JMSXUserID is specified as being of type String, while the user-id field of properties field is specified as type binary. To maintain end-to-end fidelity for this property implementations SHOULD convert between AMQP binary and Java String by using the UTF-8 Unicode[UNICODE63] character encoding.

to This field is mapped to the JMSDestination header of the Message.

JMSDestination is defined as being of the JMS Destination type, while the to field of properties requires an address-string.

If the to field of properties was not set on a received message, the JMSDestination header value SHOULD be derived from the Destination to which the receiving consumer was established.

subject This field is mapped to the JMSType header of the Message.
reply-to This field is mapped to the JMSReplyTo header of the Message.

JMSReplyTo is defined as being of the JMSDestination type, while the reply-to field of properties requires an address-string.

correlation-id This field is mapped to the JMSCorrelationID header of the Message.

The JMSCorrelationID value is a Java String where as the correlation-id field of properties is defined as being of type providing message-id, that is message-id-ulong, message-id-uuid, message-id-binary or message-id-string.

Where the correlation-id field of properties for the received message is of type message-id-string and the boolean message annotation with symbol key of x-opt-app-correlation-id is either not set or is false, then the correlation-id field of properties MUST be formatted as a JMSMessageID, that is the client library MUST prefix ID: to the value before returning it as the JMSCorrelationID value.

content-type This field does not have an equivalent within the JMS specification, and so the vendor property JMSAMQPCONTENTTYPESHOULD be used.
content-encoding This field does not have an equivalent within the JMS specification, and so the vendor property JMSAMQPCONTENTENCODINGSHOULD be used.
absolute-expiry-time This field is mapped to the JMSExpiration head of the Message.

If the absolute-expiry-time field of properties is set, then JMSExpiration MUST have the equivalent Java long value, representing the time at which the message expires, in milliseconds since the Unix Epoch. If the absolute-expiry-time field of properties is not set then JMSExpiration SHOULD be based on the ttl field of header instead if set.

creation-time This field is mapped to the JMSTimestamp header of the Message.

If the creation-time field of properties is not set, then JMSTimestamp MUST have the value zero. If the creation-time field of properties field is set, then JMSTimestamp MUST have the equivalent Java long value, representing the time at which the message was sent or created, in milliseconds since the Unix Epoch.

group-id This field is mapped to the JMS-defined JMSXGroupID property of the Message.
group-sequence This field is mapped to the JMS-defined JMSXGroupSeq property of the Message.

As the group-sequence field of properties is an uint and JMSXGroupSeq is an int, group-sequence values in the range 231 to 232-1 inclusive MUST be mapped to JMSXGroupSeq values in the range −231 to -1 inclusive.

reply-to-group-id This field does not have an equivalent within the JMS specification, and so the vendor property JMS_AMQP_REPLY_TO_GROUP_ID MUST be used.

For more information on AMQP properties and JMS to AMQP mapping properties, see https://www.oasis-open.org/committees/download.php/56418/amqp-bindmap-jms-v1.0-wd06.pdf.