Menu Search

2.16. The AMQP 0-10 mapping

This section describes the AMQP 0-10 mapping for the Qpid Messaging API.

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 transfered to the default (or nameless) exchange. When sending to an exchange, the message is transfered 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-bindings are 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-bindings element 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-match entry and no other entries, causing all messages to match. If a subject is specified then the binding arguments contain an x-match entry set to all and an entry for qpid.subject whose 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 the x-bindings element in the link properties must be used.

  • For the XML exchange,[12] 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.

Table 2.9. Mapping to AMQP 0-10 Message Properties

Python APIC++ API [a] AMQP 0-10 Property[b]
msg.idmsg.{get,set}MessageId()mp.message_id
msg.subjectmsg.{get,set}Subject()mp.application_headers["qpid.subject"]
msg.user_idmsg.{get,set}UserId()mp.user_id
msg.reply_tomsg.{get,set}ReplyTo()mp.reply_to[c]
msg.correlation_idmsg.{get,set}CorrelationId()mp.correlation_id
msg.durablemsg.{get,set}Durable()dp.delivery_mode == delivery_mode.persistent[d]
msg.prioritymsg.{get,set}Priority()dp.priority
msg.ttlmsg.{get,set}Ttl()dp.ttl
msg.redeliveredmsg.{get,set}Redelivered()dp.redelivered
msg.propertiesmsg.getProperties()/msg.setProperty()mp.application_headers
msg.content_typemsg.{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. See Table 5.13, “.NET Binding for the C++ Messaging API Class: Message” .

[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.


2.16.1. 0-10 Message Property Keys

The QPID Messaging API also recognises special message property keys and automatically provides a mapping to their corresponding AMQP 0-10 definitions.

  • When sending a message, if the properties contain an entry for x-amqp-0-10.app-id, its value will be used to set the message-properties.app-id property in the outgoing message. Likewise, if an incoming message has message-properties.app-id set, its value can be accessed via the x-amqp-0-10.app-id message property key.

  • When sending a message, if the properties contain an entry for x-amqp-0-10.content-encoding, its value will be used to set the message-properties.content-encoding property in the outgoing message. Likewise, if an incoming message has message-properties.content-encoding set, its value can be accessed via the x-amqp-0-10.content-encoding message property key.

  • The routing key (delivery-properties.routing-key) in an incoming messages can be accessed via the x-amqp-0-10.routing-key message property.

  • If the timestamp delivery property is set in an incoming message (delivery-properties.timestamp), the timestamp value will be made available via the x-amqp-0-10.timestamp message property. [13]

Example 2.20. Accessing the AMQP 0-10 Message Timestamp in Python

The following code fragment checks for and extracts the message timestamp from a received message.

	    try:
	    msg = receiver.fetch(timeout=1)
	    if "x-amqp-0-10.timestamp" in msg.properties:
	    print("Timestamp=%s" % str(msg.properties["x-amqp-0-10.timestamp"]))
	    except Empty:
	    pass
          

Example 2.21. Accessing the AMQP 0-10 Message Timestamp in C++

The same example, except in C++.

	    messaging::Message msg;
	    if (receiver.fetch(msg, messaging::Duration::SECOND*1)) {
	    if (msg.getProperties().find("x-amqp-0-10.timestamp") != msg.getProperties().end()) {
	    std::cout << "Timestamp=" << msg.getProperties()["x-amqp-0-10.timestamp"].asString() << std::endl;
	    }
	    }
          



[12] Note that the XML exchange is not a standard AMQP exchange type. It is a Qpid extension and is currently only supported by the C++ broker.

[13] This special property is currently not supported by the Qpid JMS client.