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
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.
| 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—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—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 isnativeorraw, otherwisefalse. 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. JMSDestinationtype- Defaults to
queue. JMSReplyTotype- 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 |
