Chapter 19. The AMQP 0-10 mapping
19.1. The AMQP 0-10 mapping
The interaction with the broker triggered by creating a sender or receiver depends on what the specified address resolves to. Where the node type is not specified in the address, the client queries the broker to determine whether it refers to a queue or an exchange.
When sending to a queue, the queue's name is set as the routing key and the message is transferred to the default (or nameless) exchange. When sending to an exchange, the message is transferred to that exchange and the routing key is set to the message subject if one is specified. A default subject may be specified in the target address. The subject may also be set on each message individually to override the default if required. In each case any specified subject is also added as a
qpid.subject entry in the application-headers field of the message-properties.
When receiving from a queue, any subject in the source address is currently ignored. The client sends a
message-subscribe request for the queue in question. The accept-mode is determined by the reliability option in the link properties; for unreliable links the accept-mode is none, for reliable links it is explicit. The default for a queue is reliable. The acquire-mode is determined by the value of the mode option. If the mode is set to browse the acquire mode is not-acquired, otherwise it is set to pre-acquired. The exclusive and arguments fields in the message-subscribe command can be controlled using the x-subscribe map.
When receiving from an exchange, the client creates a subscription queue and binds that to the exchange. The subscription queue's arguments can be specified using the
x-declare map within the link properties. The reliability option determines most of the other parameters. If the reliability is set to unreliable then an auto-deleted, exclusive queue is used meaning that if the client or connection fails messages may be lost. For exactly-once the queue is not set to be auto-deleted. The durability of the subscription queue is determined by the durable option in the link properties. The binding process depends on the type of the exchange the source address resolves to.
- For a topic exchange, if no subject is specified and no
x-bindingsare defined for the link, the subscription queue is bound using a wildcard matching any routing key (thus satisfying the expectation that any message sent to that address will be received from it). If a subject is specified in the source address however, it is used for the binding key (this means that the subject in the source address may be a binding pattern including wildcards). - For a fanout exchange the binding key is irrelevant to matching. A receiver created from a source address that resolves to a fanout exchange receives all messages sent to that exchange regardless of any subject the source address may contain. An
x-bindingselement in the link properties should be used if there is any need to set the arguments to the bind. - For a direct exchange, the subject is used as the binding key. If no subject is specified an empty string is used as the binding key.
- For a headers exchange, if no subject is specified the binding arguments simply contain an
x-matchentry and no other entries, causing all messages to match. If a subject is specified then the binding arguments contain anx-matchentry set to all and an entry forqpid.subjectwhose value is the subject in the source address (this means the subject in the source address must match the message subject exactly). For more control thex-bindingselement in the link properties must be used. - For the XML exchange, if a subject is specified it is used as the binding key and an XQuery is defined that matches any message with that value for
qpid.subject. Again this means that only messages whose subject exactly match that specified in the source address are received. If no subject is specified then the empty string is used as the binding key with an xquery that will match any message (this means that only messages with an empty string as the routing key will be received). For more control the x-bindings element in the link properties must be used. A source address that resolves to the XML exchange must contain either a subject or an x-bindings element in the link properties as there is no way at present to receive any message regardless of routing key.
If an x-bindings list is present in the link options a binding is created for each element within that list. Each element is a nested map that may contain values named
queue, exchange, key, or arguments. If the queue value is absent the queue name the address resolves to is implied. If the exchange value is absent the exchange name the address resolves to is implied.
The following table shows how Qpid Messaging API message properties are mapped to AMQP 0-10 message properties and delivery properties. In this table
msg refers to the Message class defined in the Qpid Messaging API, mp refers to an AMQP 0-10 message-properties struct, and dp refers to an AMQP 0-10 delivery-properties struct.
| Python API | C++ API [a] | AMQP 0-10 Property [b] |
|---|---|---|
msg.id | msg.{get,set}MessageId() | mp.message_id |
msg.subject | msg.{get,set}Subject() | mp.application_headers ["qpid.subject"] |
msg.user_id | msg.{get,set}UserId() | mp.user_id |
msg.reply_to | msg.{get,set}ReplyTo() | mp.reply_to [c] |
msg.correlation_id | msg.{get,set}CorrelationId() | mp.correlation_id |
msg.durable | msg.{get,set}Durable() | dp.delivery_mode == delivery_mode.persistent [d] |
msg.priority | msg.{get,set}Priority() | dp.priority |
msg.ttl | msg.{get,set}Ttl() | dp.ttl |
msg.redelivered | msg.{get,set}Redelivered() | dp.redelivered |
msg.properties | msg.{get,set}Properties() | mp.application_headers |
msg.content_type | msg.{get,set}ContentType() | mp.content_type |
[a]
The .NET Binding for C++ Messaging provides all the message and delivery properties described in the C++ API.
[b]
In these entries, mp refers to an AMQP message property, and dp refers to an AMQP delivery property.
[c]
The reply_to is converted from the protocol representation into an address.
[d]
Note that msg.durable is a boolean, not an enum.
| ||
