Repository: qpid-site Updated Branches: refs/heads/asf-site 2b7a4a813 -> c3ab60f6d
http://git-wip-us.apache.org/repos/asf/qpid-site/blob/c3ab60f6/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-amqp0-10-mapping.html.in ---------------------------------------------------------------------- diff --git a/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-amqp0-10-mapping.html.in b/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-amqp0-10-mapping.html.in new file mode 100644 index 0000000..e6514fe --- /dev/null +++ b/input/releases/qpid-cpp-1.39.0/messaging-api/book/section-amqp0-10-mapping.html.in @@ -0,0 +1,164 @@ +<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">1.16. The AMQP 0-10 mapping</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="ch01s15.html">Prev</a> </td><th align="center" width="60%">Chapter 1. Using the Qpid Messaging API</th><td align="right" width="20%"> <a accesskey="n" href="Message-Groups-Guide.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="section-amqp0-10-mapping"></a>1.16. The AMQP 0-10 mapping</h2></div></div></div><p> + This section describes the AMQP 0-10 mapping for the Qpid + Messaging API. + </p><p> + 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. + </p><p> + 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. + </p><p> + 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. + </p><p> + 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. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + 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). + </p></li><li class="listitem"><p> + 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. + </p></li><li class="listitem"><p> + 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. + </p></li><li class="listitem"><p> + 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. + </p></li><li class="listitem"><p> + For the XML exchange,<a class="footnote" href="#ftn.idm140612067709360" id="idm140612067709360"><sup class="footnote">[12]</sup></a> 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. + </p></li></ul></div><p> + 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. + </p><p>The following table shows how Qpid Messaging API message + properties are mapped to AMQP 0-10 message properties and + delivery properties. In this table <code class="varname">msg</code> + refers to the Message class defined in the Qpid Messaging API, + <code class="varname">mp</code> refers to an AMQP 0-10 + <code class="varname">message-properties</code> struct, and + <code class="varname">dp</code> refers to an AMQP 0-10 + <code class="varname">delivery-properties</code> struct.</p><div class="table"><a id="table-amqp0-10-message-properties"></a><p class="title"><strong>Table 1.9. Mapping to AMQP 0-10 Message Properties</strong></p><div class="table-contents"><table border="1" class="table" summary="Mapping to AMQP 0-10 Message Properties" width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>Python API</th><th>C++ API + <a class="footnote" href="#ftn.idm140612067697312" id="idm140612067697312"><sup class="footnote">[a]</sup></a> + </th><th>AMQP 0-10 Property<a class="footnote" href="#ftn.idm140612067695520" id="idm140612067695520"><sup class="footnote">[b]</sup></a></th></tr></thead><tbody><tr><td>msg.id</td><td>msg.{get,set}MessageId()</td><td>mp.message_id</td></tr><tr><td>msg.subject</td><td>msg.{get,set}Subject()</td><td>mp.application_headers["qpid.subject"]</td></tr><tr><td>msg.user_id</td><td>msg.{get,set}UserId()</td><td>mp.user_id</td></tr><tr><td>msg.reply_to</td><td>msg.{get,set}ReplyTo()</td><td>mp.reply_to<a class="footnote" href="#ftn.idm140612067688384" id="idm140612067688384"><sup class="footnote">[c]</sup></a></td></tr><tr><td>msg.correlation_id</td><td>msg.{get,set}CorrelationId()</td><td>mp.correlation_id</td></tr><tr><td>msg.durable</td><td>msg.{get,set}Durable()</td><td>dp.delivery_mode == delivery_mode.persistent<a class="footnote" href="#ftn.idm140612067685344" id="idm140612067685344"><sup class="footnote">[d]</sup></a></td></tr><tr><td>msg.priority</td><td>msg.{get,set}Priority( )</td><td>dp.priority</td></tr><tr><td>msg.ttl</td><td>msg.{get,set}Ttl()</td><td>dp.ttl</td></tr><tr><td>msg.redelivered</td><td>msg.{get,set}Redelivered()</td><td>dp.redelivered</td></tr><tr><td>msg.properties</td><td>msg.getProperties()/msg.setProperty()</td><td>mp.application_headers</td></tr><tr><td>msg.content_type</td><td>msg.{get,set}ContentType()</td><td>mp.content_type</td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div class="footnote" id="ftn.idm140612067697312"><p><a class="para" href="#idm140612067697312"><sup class="para">[a] </sup></a> + The .NET Binding for C++ Messaging provides all the + message and delivery properties described in the C++ API. + See <a class="xref" href="ch02s03.html#table-Dotnet-Binding-Message" title="Table 2.13. .NET Binding for the C++ Messaging API Class: Message">Table 2.13, “.NET Binding for the C++ Messaging API Class: Message”</a> . + </p></div><div class="footnote" id="ftn.idm140612067695520"><p><a class="para" href="#idm140612067695520"><sup class="para">[b] </sup></a>In these entries, <code class="literal">mp</code> refers to an AMQP message property, and <code class="literal">dp</code> refers to an AMQP delivery property.</p></div><div class="footnote" id="ftn.idm140612067688384"><p><a class="para" href="#idm140612067688384"><sup class="para">[c] </sup></a>The reply_to is converted from the protocol representation into an address.</p></div><div class="footnote" id="ftn.idm140612067685344"><p><a class="para" href="#idm140612067685344"><sup class="para">[d] </sup></a>Note that msg.durable is a boolean, not an enum.</p></div></td></tr></tbody></table></div></div><br class="table-break" /><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="section-amqp0-10-message-props"></a>1.16.1. 0-10 Message Property Keys</h3></div></div></div><p> + The QPID Messaging API also recognises special message property keys and + automatically provides a mapping to their corresponding AMQP 0-10 definitions. + </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p> + When sending a message, if the properties contain an entry for + <code class="literal">x-amqp-0-10.app-id</code>, its value will be used to set the + <code class="literal">message-properties.app-id</code> property in the outgoing + message. Likewise, if an incoming message has + <code class="literal">message-properties.app-id</code> set, its value can be accessed + via the <code class="literal">x-amqp-0-10.app-id</code> message property key. + </p></li><li class="listitem"><p> + When sending a message, if the properties contain an entry for + <code class="literal">x-amqp-0-10.content-encoding</code>, its value will be used to + set the <code class="literal">message-properties.content-encoding</code> property in + the outgoing message. Likewise, if an incoming message has + <code class="literal">message-properties.content-encoding</code> set, its value can be + accessed via the <code class="literal">x-amqp-0-10.content-encoding</code> message + property key. + </p></li><li class="listitem"><p> + The routing key (<code class="literal">delivery-properties.routing-key</code>) in an + incoming messages can be accessed via the + <code class="literal">x-amqp-0-10.routing-key</code> message property. + </p></li><li class="listitem"><p> + If the timestamp delivery property is set in an incoming message + (<code class="literal">delivery-properties.timestamp</code>), the timestamp value will + be made available via the <code class="literal">x-amqp-0-10.timestamp</code> message + property. + <a class="footnote" href="#ftn.idm140612067665056" id="idm140612067665056"><sup class="footnote">[13]</sup></a> + </p></li></ul></div><div class="example"><a id="idm140612067663776"></a><p class="title"><strong>Example 1.20. Accessing the AMQP 0-10 Message Timestamp in Python</strong></p><div class="example-contents"><p> + The following code fragment checks for and extracts the message timestamp from + a received message. + </p><pre class="programlisting" lang="python" xml:lang="python"> + 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 + </pre></div></div><br class="example-break" /><div class="example"><a id="idm140612067661392"></a><p class="title"><strong>Example 1.21. Accessing the AMQP 0-10 Message Timestamp in C++</strong></p><div class="example-contents"><p> + The same example, except in C++. + </p><pre class="programlisting" lang="c++" xml:lang="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; + } + } + </pre></div></div><br class="example-break" /></div><div class="footnotes"><br /><hr align="left" width="100" /><div class="footnote" id="ftn.idm140612067709360"><p><a class="para" href="#idm140612067709360"><sup class="para">[12] </sup></a>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.</p></div><div class="footnote" id="ftn.idm140612067665056"><p><a class="para" href="#idm140612067665056"><sup class="para">[13] </sup></a> + This special property is currently not supported by the Qpid JMS client. + </p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="ch01s15.html">Prev</a> </td><td align="center" width="20%"><a accesskey="u" href="using-the-qpid-messaging-api.html">Up</a></td><td align="right" width="40%"> <a accesskey="n" href="Message-Groups-Guide.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">1.15. Logging </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td align="right" valign="top" width="40%"> 1.17. Using Message Groups</td></tr></table></div></div> \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
