Chapter 8. Advanced Message Queuing Protocol (AMQP)

Abstract

Oasis AMQP is an open standard application protocol for messaging. In contrast to JMS, AMQP standardizes the wire protocol, not the programming API, thus facilitating interoperability at the transport level.

URI syntax

The URI syntax given here is valid only for specifying the endpoint in a transport connector element (broker endpoint).

A basic AMQP endpoint has the following URI syntax:

amqp://Host:[Port]?transportOptions

An AMQP endpoint with NIO support has the following syntax:

amqp+nio://Host:[Port]?transportOptions

A secure AMQP endpoint has the following URI syntax:

amqp+ssl://Host:[Port]?transportOptions

IdleTimeout

Connections are subject to a configurable idle timeout threshold. The idle timeout is measured in milliseconds.

To configure the timeout threshold, use the following URI option:

transport.wireFormat.idleTimeout=10000

It can be used in the following way:

<transportConnector name="amqp" uri="amqp://0.0.0.0:5672?transport.wireFormat.idleTimeout=10000&...."/>

Replace 10000 in the example with the number of milliseconds after which the connection will timeout due to inactivity.

Security

The AMQP adapter is fully integrated with Apache ActiveMQ security. This means that the broker accepts SASL (Simple Authentication and Security Layer) authentication and any authorization settings configured on the broker will be applied.

SSL security can also be enabled for AMQP. To enable SSL, configure the broker's sslContext element in the XML configuration and use the secure AMQP scheme, amqp+ssl, to define the AMQP URI in the broker's transportConnector element. For more details about SSL security, see the "Security Guide".

SSL transport options

In addition to the options supported by the non-secure AMQP transports, the SSL transport also supports the options for configuring the SSLServerSocket created for the connection. These options are listed in Table 2.1, “SSL Transport Options”.

Warning

If you are planning to enable SSL/TLS security, you must ensure that you explicitly disable the SSLv3 protocol, in order to safeguard against the Poodle vulnerability (CVE-2014-3566). For more details, see Disabling SSLv3 in JBoss Fuse 6.x and JBoss A-MQ 6.x.

Configuring broker SSL options

On the broker side, you must specify an SSL transport option using the syntax transport.OptionName. For example, to enable an AMQP SSL port on a broker, you would add the following transport element:

<transportConnector name="amqpssl" uri="amqp+ssl://localhost:61617?transport.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2" />

Tip

Remember, if you are specifying more than one option in the context of XML, you need to escape the ampersand, &, between options as &.

Configuring client SSL options

On the client side, you must specify an SSL transport option using the syntax socket.OptionName. For example, to connect to an AMQP SSL port, you would use a URL like the following:

amqp+ssl://localhost:61617?socket.enabledProtocols=TLSv1,TLSv1.1,TLSv1.2

Mapping from AMQP to JMS

Because AMQP is not a JMS compliant protocol, the AMQP messages and their headers are defined in a different format from JMS. It is therefore necessary to map AMQP messages to JMS format. The mapping is implemented by a transformer and the transformer type can be selected by specifying the transport.transformer option on the AMQP endpoint.

For example, the following transport connector selects the jms transformer type:

<transportConnector name="amqp" uri="amqp://localhost:5672?transport.transformer=jms"/>

AMQP-to-JMS transformers

Table 8.1, “AMQP-to-JMS Transformer Types” lists the available transformer types and describes the basic characteristics of each mapping.

Table 8.1. AMQP-to-JMS Transformer Types
Transformer	Description
`native`	(Default) Wraps the bytes of the AMQP message into a JMS `BytesMessage`, and maps the AMQP message headers to JMS message headers.
`raw`	Wraps the bytes of the AMQP message into a JMS `BytesMessage`.
`jms`	Maps the body of the AMQP message to JMS body, and maps the AMQP message headers to JMS message headers.

Header mapping for all transformers

The JMS headers shown in the following table are always created, no matter which transformer type is selected.

AMQP Header	JMS Header
	`JMS_AMQP_NATIVE`
`message-format`	`JMS_AMQP_MESSAGE_FORMAT`

The JMS_AMQP_NATIVE header is a boolean type, which indicates whether or not the JMS message body is a direct copy of the raw AMQP message body. It is set to true for the native and jms transformer types and false for the jms transformer type.

Header mapping for native or jms transformers

The JMS headers shown in the following table are mapped from AMQP headers, if the native or jms transformer type is selected.

AMQP Header	JMS Header
`header.durable`	`JMSDeliveryMode`
`header.priority`	`JMSPriority`
`header.ttl`	`JMSExpiration`
`header.first-acquirer`	`JMS_AMQP_FirstAcquirer`
`header.deliveryCount`	`JMSXDeliveryCount`
`delivery-annotations.name`	`JMS_AMQP_DA_name`
`message-annotations.x-opt-jms-type`	`JMSType`
`message-annotations.x-opt-to-type`	Type of the `JMSDestination`
`message-annotations.x-opt-reply-type`	Type of the `JMSReplyTo`
`message-annotations.name`	`JMS_AMQP_MA_name`
`application-properties.JMSXGroupID`	`JMSXGroupID`
`application-properties.JMSXGroupSequence`	`JMSXGroupSequence`
`application-properties.JMSXUserID`	`JMSXUserID`
`application-properties.name`	`name`
`properties.message-id`	`JMSMessageID`
`properties.user-id`	`JMSXUserID`
`properties.to`	`JMSDestination`
`properties.subject`	`JMS_AMQP_Subject`
`properties.reply-to`	`JMSReplyTo`
`properties.correlation-id`	`JMSCorrelationID`
`properties.content-type`	`JMS_AMQP_ContentType`
`properties.content-encoding`	`JMS_AMQP_ContentEncoding`
`properties.creation-time`	`JMSTimestamp`
`properties.group-sequence`	`JMSXGroupSequence`
`properties.reply-to-group-id`	`JMS_AMQP_ReplyToGroupID`
`footer.name`	`JMS_AMQP_FT_name`

Note

The properties.user-id property is decoded as a UTF-8 String.

Default header values

When mapping AMQP message properties to JMS header values, the following default JMS header values are used:

JMS_AMQP_NATIVE: Defaults to true, if the transformer is native or raw, otherwise false.
JMSDeliveryMode: Defaults to javax.jms.Message.DEFAULT_DELIVERY_MODE.
JMSPriority: Defaults to javax.jms.Message.DEFAULT_PRIORITY.
JMSExpiration: Defaults to javax.jms.Message.DEFAULT_TIME_TO_LIVE.
JMSDestination type: Defaults to queue.
JMSReplyTo type: Defaults to queue.
JMSMessageID: Auto-generated, if not set.

Property type mapping

AMQP property types are converted to Java types as shown in the following table:

AMQP Type	Java Type	Notes
`bool`	`Boolean`
`byte`	`Byte`
`short`	`Short`
`int`	`Integer`
`long`	`Long`
`ubyte`	`Byte` or `Short`	`Short` is used, if `value > Byte.MAX_VALUE`
`ushort`	`Short` or `Integer`	`Integer` is used if `value > Short.MAX_VALUE`
`uint`	`Integer` or `Long`	`Long` is used, if `value > Integer.MAX_VALUE`
`ulong`	`Long`
`double`	`Double`
`float`	`Float`
`symbol`	`String`
`binary`	`String`	Hex encoding of the binary value

Message body mapping

When the jms transformer type is selected, the AMQP message body is mapped to a JMS message type, as shown in the following table:

AMQP Body Type	JMS Message Type
`null`	`Message`
`Data`	`BytesMessage`
`AmqpSequence`	`StreamMessage`
`AmqpValue` holding a `null`	`Message`
`AmqpValue` holding a `String`	`TextMessage`
`AmqpValue` holding a `binary`	`BytesMessage`
`AmqpValue` holding a `list`	`StreamMessage`
`AmqpValue`	`ObjectMessage`