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.

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.