qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acon...@apache.org
Subject svn commit: r1368244 [14/14] - in /qpid/site/docs/books/trunk: AMQP-Messaging-Broker-CPP-Book/html/ AMQP-Messaging-Broker-CPP-Book/html/css/ AMQP-Messaging-Broker-CPP-Book/pdf/ AMQP-Messaging-Broker-Java-Book/html/ AMQP-Messaging-Broker-Java-Book/html/...
Date Wed, 01 Aug 2012 20:54:49 GMT
Added: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-addresses.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-addresses.html?rev=1368244&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-addresses.html (added)
+++ qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-addresses.html Wed Aug  1 20:54:46 2012
@@ -0,0 +1,577 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>2.4. Addresses</title><link rel="stylesheet" type="text/css" href="css/style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="Programming in Apache Qpid"><link rel="up" href="ch02.html" title="Chapter 2. Using the Qpid Messaging API"><link rel="prev" href="ch02s03.html" title="2.3. A Simple Messaging Program in .NET C#"><link rel="next" href="replay.html" title="2.5. Sender Capacity and Replay"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/do
 wnload.html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">0.14 Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing List
 s</A></LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</A></LI><LI><A href="http:/
 /www.apache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">Programming in Apache Qpid</a></span> &gt; <span class="breadcrumb-link"><a href="ch02.html">Using the Qpid Messaging API</a></span> &gt; <span class="breadcrumb-node">Addresses</span></DIV><div class="section" title="2.4. Addresses"><div class="titlepage"><div><div><h2 class="title"><a name="section-addresses"></a>2.4. Addresses</h2></div></div></div><p>An <em class="firstterm">address</em> is the name of a message
+      target or message source.
+
+      <sup>[<a name="id593891" href="#ftn.id593891" class="footnote">2</a>]</sup>
+
+      The methods that create senders and receivers require an
+      address. The details of sending to a particular target or
+      receiving from a particular source are then handled by the
+      sender or receiver. A different target or source can be used
+      simply by using a different address.
+      </p><p>An address resolves to a <em class="firstterm">node</em>. The
+      Qpid Messaging API recognises two kinds of nodes,
+      <em class="firstterm">queues</em> and <em class="firstterm">topics</em>
+
+      <sup>[<a name="id593918" href="#ftn.id593918" class="footnote">3</a>]</sup>.
+
+      A queue stores each message until it has been received and
+      acknowledged, and only one receiver can receive a given message
+
+      <sup>[<a name="id593939" href="#ftn.id593939" class="footnote">4</a>]</sup>.
+
+      A topic immediately delivers a message to all eligible
+      receivers; if there are no eligible receivers, it discards the
+      message.  In the AMQP 0-10 implementation of the API,
+
+      <sup>[<a name="id593952" href="#ftn.id593952" class="footnote">5</a>]</sup>
+
+      queues map to AMQP queues, and topics map to AMQP exchanges.
+
+      <sup>[<a name="id593958" href="#ftn.id593958" class="footnote">6</a>]</sup>
+      </p><p>In the rest of this tutorial, we present many examples
+      using two programs that take an address as a command line
+      parameter.  <span class="command"><strong>spout</strong></span> sends messages to the
+      target address, <span class="command"><strong>drain</strong></span> receives messages from
+      the source address.  The source code is available in C++, Python, and
+      .NET C# and can be found in the examples directory for each
+      language. These programs can use any address string as a source
+      or a destination, and have many command line options to
+      configure behavior—use the <span class="command"><strong>-h</strong></span> option
+      for documentation on these options.
+
+      <sup>[<a name="id593988" href="#ftn.id593988" class="footnote">7</a>]</sup>
+
+
+      The examples in this tutorial also use the
+      <span class="command"><strong>qpid-config</strong></span> utility to configure AMQP 0-10
+      queues and exchanges on a Qpid broker.
+      </p><div class="example"><a name="id594016"></a><p class="title"><b>Example 2.4. Queues</b></p><div class="example-contents"><p>Create a queue with <span class="command"><strong>qpid-config</strong></span>, send a message using
+	<span class="command"><strong>spout</strong></span>, and read it using <span class="command"><strong>drain</strong></span>:</p><pre class="screen">
+	  $ qpid-config add queue hello-world
+	  $ ./spout hello-world
+	  $ ./drain hello-world
+
+	  Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='')
+        </pre><p>The queue stored the message sent by <span class="command"><strong>spout</strong></span> and delivered
+        it to <span class="command"><strong>drain</strong></span> when requested.</p><p>Once the message has been delivered and and acknowledged
+	by <span class="command"><strong>drain</strong></span>, it is no longer available on the queue. If we run
+	<span class="command"><strong>drain</strong></span> one more time, no messages will be retrieved.</p><pre class="screen">
+	  $ ./drain hello-world
+	  $
+	</pre></div></div><br class="example-break"><div class="example"><a name="id594090"></a><p class="title"><b>Example 2.5. Topics</b></p><div class="example-contents"><p>This example is similar to the previous example, but it
+	uses a topic instead of a queue.</p><p>First, use <span class="command"><strong>qpid-config</strong></span> to remove the queue
+	and create an exchange with the same name:</p><pre class="screen">
+	  $ qpid-config del queue hello-world
+	  $ qpid-config add exchange topic hello-world
+        </pre><p>Now run <span class="command"><strong>drain</strong></span> and <span class="command"><strong>spout</strong></span> the same way we did in the previous example:</p><pre class="screen">
+	  $ ./spout hello-world
+	  $ ./drain hello-world
+	  $
+        </pre><p>Topics deliver messages immediately to any interested
+        receiver, and do not store messages. Because there were no
+        receivers at the time <span class="command"><strong>spout</strong></span> sent the
+        message, it was simply discarded. When we ran
+        <span class="command"><strong>drain</strong></span>, there were no messages to
+        receive.</p><p>Now let's run <span class="command"><strong>drain</strong></span> first, using the
+	<code class="literal">-t</code> option to specify a timeout in seconds.
+	While <span class="command"><strong>drain</strong></span> is waiting for messages,
+	run <span class="command"><strong>spout</strong></span> in another window.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
+	  $ ./drain -t 30 hello-word
+        </pre><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
+	  $ ./spout hello-word
+        </pre><p>Once <span class="command"><strong>spout</strong></span> has sent a message, return
+	to the first window to see the output from
+	<span class="command"><strong>drain</strong></span>:</p><pre class="screen">
+	  Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='')
+        </pre><p>You can run <span class="command"><strong>drain</strong></span> in several separate
+	windows; each creates a subscription for the exchange, and
+	each receives all messages sent to the exchange.</p></div></div><br class="example-break"><div class="section" title="2.4.1. Address Strings"><div class="titlepage"><div><div><h3 class="title"><a name="id594225"></a>2.4.1. Address Strings</h3></div></div></div><p>So far, our examples have used address strings that
+	contain only the name of a node. An <em class="firstterm">address
+	string</em> can also contain a
+	<em class="firstterm">subject</em> and
+	<em class="firstterm">options</em>.</p><p>The syntax for an address string is:</p><pre class="programlisting">
+	address_string ::=  &lt;address&gt; [ / &lt;subject&gt; ] [ ; &lt;options&gt; ]
+	options ::=  { &lt;key&gt; : &lt;value&gt;, ... }
+	</pre><p>Addresses, subjects, and keys are strings.  Values can
+	be numbers, strings (with optional single or double quotes),
+	maps, or lists. A complete BNF for address strings appears in
+	<a class="xref" href="section-addresses.html#section-address-string-bnf" title="2.4.4. Address String Grammar">Section 2.4.4, “Address String Grammar”</a>.</p><p>So far, the address strings in this tutorial have only
+	used simple names. The following sections show how to use
+	subjects and options.</p></div><div class="section" title="2.4.2. Subjects"><div class="titlepage"><div><div><h3 class="title"><a name="id594268"></a>2.4.2. Subjects</h3></div></div></div><p>Every message has a property called
+	<em class="firstterm">subject</em>, which is analogous to the
+	subject on an email message. If no subject is specified, the
+	message's subject is null. For convenience, address strings
+	also allow a subject. If a sender's address contains a
+	subject, it is used as the default subject for the messages
+	it sends.
+
+	If a receiver's address contains a subject, it is used to
+	select only messages that match the subject—the matching
+	algorithm depends on the message source.
+	</p><p>
+	  In AMQP 0-10, each exchange type has its own matching
+	  algorithm. This is discussed in
+	  <a class="xref" href="section-amqp0-10-mapping.html" title="2.16. The AMQP 0-10 mapping">Section 2.16, “The AMQP 0-10 mapping”</a>.
+	</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+	    Currently, a receiver bound to a queue ignores subjects,
+	    receiving messages from the queue without filtering. Support
+	    for subject filtering on queues will be implemented soon.
+	  </p></div><div class="example"><a name="id594301"></a><p class="title"><b>Example 2.6. Using subjects</b></p><div class="example-contents"><p>In this example we show how subjects affect message
+	  flow.</p><p>First, let's use <span class="command"><strong>qpid-config</strong></span> to create a topic exchange.</p><pre class="screen">
+	    $ qpid-config add exchange topic news-service
+	  </pre><p>Now we use drain to receive messages from <code class="literal">news-service</code> that match the subject <code class="literal">sports</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
+	    $ ./drain -t 30 news-service/sports
+	  </pre><p>In a second window, let's send messages to <code class="literal">news-service</code> using two different subjects:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
+	    $ ./spout news-service/sports
+	    $ ./spout news-service/news
+	  </pre><p>Now look at the first window, the message with the
+	  subject <code class="literal">sports</code> has been received, but not
+	  the message with the subject <code class="literal">news</code>:</p><pre class="screen">
+	    Message(properties={qpid.subject:sports, spout-id:9441674e-a157-4780-a78e-f7ccea998291:0}, content='')
+	  </pre><p>If you run <span class="command"><strong>drain</strong></span> in multiple
+          windows using the same subject, all instances of
+          <span class="command"><strong>drain</strong></span> receive the messages for that
+          subject.</p></div></div><br class="example-break"><p>The AMQP exchange type we are using here,
+        <code class="literal">amq.topic</code>, can also do more sophisticated
+        matching.
+
+	A sender's subject can contain multiple words separated by a
+	<span class="quote">“<span class="quote">.</span>”</span> delimiter. For instance, in a news
+	application, the sender might use subjects like
+	<code class="literal">usa.news</code>, <code class="literal">usa.weather</code>,
+	<code class="literal">europe.news</code>, or
+	<code class="literal">europe.weather</code>.
+
+	The receiver's subject can include wildcard characters—
+	<span class="quote">“<span class="quote">#</span>”</span> matches one or more words in the message's
+	subject, <span class="quote">“<span class="quote">*</span>”</span> matches a single word.
+
+	For instance, if the subject in the source address is
+	<code class="literal">*.news</code>, it matches messages with the
+	subject <code class="literal">europe.news</code> or
+	<code class="literal">usa.news</code>; if it is
+	<code class="literal">europe.#</code>, it matches messages with subjects
+	like <code class="literal">europe.news</code> or
+	<code class="literal">europe.pseudo.news</code>.</p><div class="example"><a name="id594474"></a><p class="title"><b>Example 2.7. Subjects with multi-word keys</b></p><div class="example-contents"><p>This example uses drain and spout to demonstrate the
+	  use of subjects with two-word keys.</p><p>Let's use <span class="command"><strong>drain</strong></span> with the subject
+	  <code class="literal">*.news</code> to listen for messages in which
+	  the second word of the key is
+	  <code class="literal">news</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
+	    $ ./drain -t 30 news-service/*.news
+	  </pre><p>Now let's send messages using several different
+	  two-word keys:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
+	    $ ./spout news-service/usa.news
+	    $ ./spout news-service/usa.sports
+	    $ ./spout news-service/europe.sports
+	    $ ./spout news-service/europe.news
+	  </pre><p>In the first window, the messages with
+	  <code class="literal">news</code> in the second word of the key have
+	  been received:</p><pre class="screen">
+	    Message(properties={qpid.subject:usa.news, spout-id:73fc8058-5af6-407c-9166-b49a9076097a:0}, content='')
+	    Message(properties={qpid.subject:europe.news, spout-id:f72815aa-7be4-4944-99fd-c64c9747a876:0}, content='')
+	  </pre><p>Next, let's use <span class="command"><strong>drain</strong></span> with the
+	  subject <code class="literal">#.news</code> to match any sequence of
+	  words that ends with <code class="literal">news</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
+	    $ ./drain -t 30 news-service/#.news
+	  </pre><p>In the second window, let's send messages using a
+	  variety of different multi-word keys:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
+	    $ ./spout news-service/news
+	    $ ./spout news-service/sports
+	    $ ./spout news-service/usa.news
+	    $ ./spout news-service/usa.sports
+	    $ ./spout news-service/usa.faux.news
+	    $ ./spout news-service/usa.faux.sports
+	  </pre><p>In the first window, messages with
+	  <code class="literal">news</code> in the last word of the key have been
+	  received:</p><pre class="screen">
+	    Message(properties={qpid.subject:news, spout-id:cbd42b0f-c87b-4088-8206-26d7627c9640:0}, content='')
+	    Message(properties={qpid.subject:usa.news, spout-id:234a78d7-daeb-4826-90e1-1c6540781eac:0}, content='')
+	    Message(properties={qpid.subject:usa.faux.news, spout-id:6029430a-cfcb-4700-8e9b-cbe4a81fca5f:0}, content='')
+	  </pre></div></div><br class="example-break"></div><div class="section" title="2.4.3. Address String Options"><div class="titlepage"><div><div><h3 class="title"><a name="id594606"></a>2.4.3. Address String Options</h3></div></div></div><p>
+	  The options in an address string can contain additional
+	  information for the senders or receivers created for it,
+	  including:
+	</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"><p>
+	      Policies for assertions about the node to which an address
+	      refers.
+	    </p><p>
+	      For instance, in the address string <code class="literal">my-queue;
+	      {assert: always, node:{ type: queue }}</code>, the node
+	      named <code class="literal">my-queue</code> must be a queue; if not,
+	      the address does not resolve to a node, and an exception
+	      is raised.
+	    </p></li><li class="listitem"><p>
+	      Policies for automatically creating or deleting the node to which an address refers.
+	    </p><p>
+	      For instance, in the address string <code class="literal">xoxox ; {create: always}</code>,
+	      the queue <code class="literal">xoxox</code> is created, if it does
+	      not exist, before the address is resolved.
+	    </p></li><li class="listitem"><p>
+	      Extension points that can be used for sender/receiver configuration.
+	    </p><p>
+	      For instance, if the address for a receiver is
+	      <code class="literal">my-queue; {mode: browse}</code>, the receiver
+	      works in <code class="literal">browse</code> mode, leaving messages
+	      on the queue so other receivers can receive them.
+	    </p></li><li class="listitem"><p>
+	      Extension points providing more direct control over the underlying protocol.
+	    </p><p>
+	      For instance, the <code class="literal">x-bindings</code> property
+	      allows greater control over the AMQP 0-10 binding process
+	      when an address is resolved.
+	    </p></li></ul></div><p>
+	  Let's use some examples to show how these different kinds of
+	  address string options affect the behavior of senders and
+	  receives.
+	</p><div class="section" title="2.4.3.1. assert"><div class="titlepage"><div><div><h4 class="title"><a name="id594706"></a>2.4.3.1. assert</h4></div></div></div><p>
+	    In this section, we use the <code class="literal">assert</code> option
+	    to ensure that the address resolves to a node of the required
+	    type.
+	  </p><div class="example"><a name="id594721"></a><p class="title"><b>Example 2.8. Assertions on Nodes</b></p><div class="example-contents"><p>Let's use <span class="command"><strong>qpid-config</strong></span> to create a
+	    queue and a topic.</p><pre class="screen">
+	      $ qpid-config add queue my-queue
+	      $ qpid-config add exchange topic my-topic
+	    </pre><p>
+	      We can now use the address specified to drain to assert that it is
+	      of a particular type:
+	    </p><pre class="screen">
+	      $ ./drain 'my-queue; {assert: always, node:{ type: queue }}'
+	      $ ./drain 'my-queue; {assert: always, node:{ type: topic }}'
+	      2010-04-20 17:30:46 warning Exception received from broker: not-found: not-found: Exchange not found: my-queue (../../src/qpid/broker/ExchangeRegistry.cpp:92) [caused by 2 \x07:\x01]
+	      Exchange my-queue does not exist
+	    </pre><p>
+	      The first attempt passed without error as my-queue is indeed a
+	      queue. The second attempt however failed; my-queue is not a
+	      topic.
+	    </p><p>
+	      We can do the same thing for my-topic:
+	    </p><pre class="screen">
+	      $ ./drain 'my-topic; {assert: always, node:{ type: topic }}'
+	      $ ./drain 'my-topic; {assert: always, node:{ type: queue }}'
+	      2010-04-20 17:31:01 warning Exception received from broker: not-found: not-found: Queue not found: my-topic (../../src/qpid/broker/SessionAdapter.cpp:754) [caused by 1 \x08:\x01]
+	      Queue my-topic does not exist
+	    </pre></div></div><br class="example-break"><p>Now let's use the <code class="literal">create</code> option to
+	  create the queue <code class="literal">xoxox</code> if it does not already
+	  exist:</p></div><div class="section" title="2.4.3.2. create"><div class="titlepage"><div><div><h4 class="title"><a name="id594785"></a>2.4.3.2. create</h4></div></div></div><p>In previous examples, we created the queue before
+	  listening for messages on it. Using <code class="literal">create:
+	  always</code>, the queue is automatically created if it
+	  does not exist.</p><div class="example"><a name="id594801"></a><p class="title"><b>Example 2.9. Creating a Queue Automatically</b></p><div class="example-contents"><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">$ ./drain -t 30 "xoxox ; {create: always}"</pre><p>Now we can send messages to this queue:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">$ ./spout "xoxox ; {create: always}"</pre><p>Returning to the first window, we see that <span class="command"><strong>drain</strong></span> has received this message:</p><pre class="screen">Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='')</pre></div></div><br class="example-break"><p>The details of the node thus created can be controlled by further options within the node. See <a class="xref" href="section-addresses.html#table-node-properties" title="Table 2.2. Node Properties">Table 2.2, “Node Properties”
 </a> for details.</p></div><div class="section" title="2.4.3.3. browse"><div class="titlepage"><div><div><h4 class="title"><a name="id594853"></a>2.4.3.3. browse</h4></div></div></div><p>Some options specify message transfer semantics; for
+	  instance, they may state whether messages should be consumed or
+	  read in browsing mode, or specify reliability
+	  characteristics. The following example uses the
+	  <code class="literal">browse</code> option to receive messages without
+	  removing them from a queue.</p><div class="example"><a name="id594869"></a><p class="title"><b>Example 2.10. Browsing a Queue</b></p><div class="example-contents"><p>
+	      Let's use the browse mode to receive messages without
+	      removing them from the queue. First we send three messages to the
+	      queue:
+	    </p><pre class="screen">
+	      $ ./spout my-queue --content one
+	      $ ./spout my-queue --content two
+	      $ ./spout my-queue --content three
+	    </pre><p>Now we use drain to get those messages, using the browse option:</p><pre class="screen">
+	      $ ./drain 'my-queue; {mode: browse}'
+	      Message(properties={spout-id:fbb93f30-0e82-4b6d-8c1d-be60eb132530:0}, content='one')
+	      Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='two')
+	      Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three')
+	    </pre><p>We can confirm the messages are still on the queue by repeating the drain:</p><pre class="screen">
+	      $ ./drain 'my-queue; {mode: browse}'
+	      Message(properties={spout-id:fbb93f30-0e82-4b6d-8c1d-be60eb132530:0}, content='one')
+	      Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='two')
+	      Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three')
+	    </pre></div></div><br class="example-break"></div><div class="section" title="2.4.3.4. x-bindings"><div class="titlepage"><div><div><h4 class="title"><a name="id594912"></a>2.4.3.4. x-bindings</h4></div></div></div><p>Greater control over the AMQP 0-10 binding process can
+	  be achieved by including an <code class="literal">x-bindings</code>
+	  option in an address string.
+
+	  For instance, the XML Exchange is an AMQP 0-10 custom exchange
+	  provided by the Apache Qpid C++ broker. It allows messages to
+	  be filtered using XQuery; queries can address either message
+	  properties or XML content in the body of the message. The
+	  xquery is specified in the arguments field of the AMQP 0-10
+	  command. When using the messaging API an xquery can be
+	  specified in and address that resolves to an XML exchange by
+	  using the x-bindings property.</p><p>An instance of the XML Exchange must be added before it
+	  can be used:</p><pre class="programlisting">
+	    $ qpid-config add exchange xml xml
+	  </pre><p>When using the XML Exchange, a receiver provides an
+	  XQuery as an x-binding argument. If the query contains a
+	  context item (a path starting with <span class="quote">“<span class="quote">.</span>”</span>), then it
+	  is applied to the content of the message, which must be
+	  well-formed XML. For instance, <code class="literal">./weather</code> is
+	  a valid XQuery, which matches any message in which the root
+	  element is named <code class="literal">weather</code>. Here is an
+	  address string that contains this query:</p><pre class="programlisting">
+	  xml; {
+	  link: {
+	  x-bindings: [{exchange:xml, key:weather, arguments:{xquery:"./weather"} }]
+	  }
+	  }
+	  </pre><p>When using longer queries with <span class="command"><strong>drain</strong></span>,
+	  it is often useful to place the query in a file, and use
+	  <span class="command"><strong>cat</strong></span> in the command line. We do this in the
+	  following example.</p><div class="example"><a name="id594982"></a><p class="title"><b>Example 2.11. Using the XML Exchange</b></p><div class="example-contents"><p>This example uses an x-binding that contains queries, which filter based on the content of XML messages. Here is an XQuery that we will use in this example:</p><pre class="programlisting">
+	      
+		       let $w := ./weather
+		       return $w/station = 'Raleigh-Durham International Airport (KRDU)'
+		       and $w/temperature_f &gt; 50
+		       and $w/temperature_f - $w/dewpoint &gt; 5
+		       and $w/wind_speed_mph &gt; 7
+		       and $w/wind_speed_mph &lt; 20 
+	    </pre><p>We can specify this query in an x-binding to listen to messages that meet the criteria specified by the query:</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
+	      $ ./drain -f "xml; {link:{x-bindings:[{key:'weather',
+	      arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}"
+	    </pre><p>In another window, let's create an XML message that meets the criteria in the query, and place it in the file <code class="filename">rdu.xml</code>:</p><pre class="programlisting">
+	      
+		       &lt;weather&gt;
+		       &lt;station&gt;Raleigh-Durham International Airport (KRDU)&lt;/station&gt;
+		       &lt;wind_speed_mph&gt;16&lt;/wind_speed_mph&gt;
+		       &lt;temperature_f&gt;70&lt;/temperature_f&gt;
+		       &lt;dewpoint&gt;35&lt;/dewpoint&gt;
+		       &lt;/weather&gt;
+	      </pre><p>Now let's use <span class="command"><strong>spout</strong></span> to send this message to the XML exchange:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
+		spout --content "$(cat rdu.xml)" xml/weather
+	      </pre><p>Returning to the first window, we see that the message has been received:</p><pre class="screen">$ ./drain -f "xml; {link:{x-bindings:[{exchange:'xml', key:'weather', arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}"
+	      Message(properties={qpid.subject:weather, spout-id:31c431de-593f-4bec-a3dd-29717bd945d3:0},
+	      content='&lt;weather&gt;
+	      &lt;station&gt;Raleigh-Durham International Airport (KRDU)&lt;/station&gt;
+	      &lt;wind_speed_mph&gt;16&lt;/wind_speed_mph&gt;
+	      &lt;temperature_f&gt;40&lt;/temperature_f&gt;
+	      &lt;dewpoint&gt;35&lt;/dewpoint&gt;
+	      &lt;/weather&gt;') 
+	      </pre></div></div><br class="example-break"></div><div class="section" title="2.4.3.5. Address String Options - Reference"><div class="titlepage"><div><div><h4 class="title"><a name="id595082"></a>2.4.3.5. Address String Options - Reference</h4></div></div></div><div class="table"><a name="id595087"></a><p class="title"><b>Table 2.1. Address String Options</b></p><div class="table-contents"><table summary="Address String Options" width="100%" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>option</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td>
+		    assert
+		  </td><td>
+		    one of: always, never, sender or receiver
+		  </td><td>
+		    Asserts that the properties specified in the node option
+		    match whatever the address resolves to. If they do not,
+		    resolution fails and an exception is raised. 
+		  </td></tr><tr><td>
+		    create
+		  </td><td>
+		    one of: always, never, sender or receiver
+		  </td><td>
+		    Creates the node to which an address refers if it does
+		    not exist. No error is raised if the node does
+		    exist. The details of the node may be specified in the
+		    node option.
+		  </td></tr><tr><td>
+		    delete
+		  </td><td>
+		    one of: always, never, sender or receiver
+		  </td><td>
+		    Delete the node when the sender or receiver is closed.
+		  </td></tr><tr><td>
+		    node
+		  </td><td>
+		    A nested map containing the entries shown in <a class="xref" href="section-addresses.html#table-node-properties" title="Table 2.2. Node Properties">Table 2.2, “Node Properties”</a>.
+		  </td><td>
+		    Specifies properties of the node to which the address
+		    refers. These are used in conjunction with the assert or
+		    create options.
+		  </td></tr><tr><td>
+		    link
+		  </td><td>
+		    A nested map containing the entries shown in <a class="xref" href="section-addresses.html#table-link-properties" title="Table 2.3. Link Properties">Table 2.3, “Link Properties”</a>.
+		  </td><td>
+		    Used to control the establishment of a conceptual link
+		    from the client application to or from the target/source
+		    address.
+		  </td></tr><tr><td>
+		    mode
+		  </td><td>
+		    one of: browse, consume
+		  </td><td>
+		    This option is only of relevance for source addresses
+		    that resolve to a queue. If browse is specified the
+		    messages delivered to the receiver are left on the queue
+		    rather than being removed. If consume is specified the
+		    normal behaviour applies; messages are removed from the
+		    queue once the client acknowledges their receipt.
+		  </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="table-node-properties"></a><p class="title"><b>Table 2.2. Node Properties</b></p><div class="table-contents"><table summary="Node Properties" width="100%" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>property</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td>
+		    type
+		  </td><td>
+		    topic, queue
+		  </td><td>
+		    Indicates the type of the node.
+		  </td></tr><tr><td>
+		    durable
+		  </td><td>
+		    True, False
+		  </td><td>
+		    Indicates whether the node survives a loss of
+		    volatile storage e.g. if the broker is restarted.
+		  </td></tr><tr><td>
+		    x-declare
+		  </td><td>
+		    A nested map whose values correspond to the valid fields
+		    on an AMQP 0-10 queue-declare or exchange-declare
+		    command.
+		  </td><td>
+		    These values are used to fine tune the creation or
+		    assertion process. Note however that they are protocol
+		    specific.
+		  </td></tr><tr><td>
+		    x-bindings
+		  </td><td>
+		    A nested list in which each binding is represented by
+		    a map. The entries of the map for a binding contain
+		    the fields that describe an AMQP 0-10 binding. Here is
+		    the format for x-bindings:
+
+		    <pre class="programlisting">
+		    [
+		    {
+		    exchange: &lt;exchange&gt;,
+		    queue: &lt;queue&gt;,
+		    key: &lt;key&gt;,
+		    arguments: {
+		    &lt;key_1&gt;: &lt;value_1&gt;,
+		    ...,
+		    &lt;key_n&gt;: &lt;value_n&gt; }
+		    },
+		    ...
+		    ]
+		    </pre>
+		  </td><td>
+		    In conjunction with the create option, each of these
+		    bindings is established as the address is resolved. In
+		    conjunction with the assert option, the existence of
+		    each of these bindings is verified during
+		    resolution. Again, these are protocol specific.
+		  </td></tr></tbody></table></div></div><br class="table-break"><div class="table"><a name="table-link-properties"></a><p class="title"><b>Table 2.3. Link Properties</b></p><div class="table-contents"><table summary="Link Properties" width="100%" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>option</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td>
+		    reliability
+		  </td><td>
+		    one of: unreliable, at-least-once, at-most-once, exactly-once
+		  </td><td>
+		    Reliability indicates the level of reliability that
+		    the sender or receiver.  <code class="literal">unreliable</code>
+		    and <code class="literal">at-most-once</code> are currently
+		    treated as synonyms, and allow messages to be lost if
+		    a broker crashes or the connection to a broker is
+		    lost. <code class="literal">at-least-once</code> guarantees that
+		    a message is not lost, but duplicates may be
+		    received. <code class="literal">exactly-once</code> guarantees
+		    that a message is not lost, and is delivered precisely
+		    once. Currently only <code class="literal">unreliable</code>
+		    and <code class="literal">at-least-once</code> are supported.
+		    <sup>[<a name="id595453" href="#ftn.id595453" class="footnote">a</a>]</sup>
+		  </td></tr><tr><td>
+		    durable
+		  </td><td>
+		    True, False
+		  </td><td>
+		    Indicates whether the link survives a loss of
+		    volatile storage e.g. if the broker is restarted.
+		  </td></tr><tr><td>
+		    x-declare
+		  </td><td>
+		    A nested map whose values correspond to the valid fields
+		    of an AMQP 0-10 queue-declare command.
+		  </td><td>
+		    These values can be used to customise the subscription
+		    queue in the case of receiving from an exchange. Note
+		    however that they are protocol specific.
+		  </td></tr><tr><td>
+		    x-subscribe
+		  </td><td>
+		    A nested map whose values correspond to the valid fields
+		    of an AMQP 0-10 message-subscribe command.
+		  </td><td>
+		    These values can be used to customise the subscription.
+		  </td></tr><tr><td>
+		    x-bindings
+		  </td><td>
+		    A nested list each of whose entries is a map that may
+		    contain fields (queue, exchange, key and arguments)
+		    describing an AMQP 0-10 binding.
+		  </td><td>
+		    These bindings are established during resolution
+		    independent of the create option. They are considered
+		    logically part of the linking process rather than of
+		    node creation.
+		  </td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div class="footnote"><p><sup>[<a id="ftn.id595453" href="#id595453" class="para">a</a>] </sup>If at-most-once is requested,
+		    unreliable will be used and for durable messages on
+		    durable queues there is the possibility that messages
+		    will be redelivered; if exactly-once is requested,
+		    at-least-once will be used and the application needs to
+		    be able to deal with duplicates.</p></div></td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="section" title="2.4.4. Address String Grammar"><div class="titlepage"><div><div><h3 class="title"><a name="section-address-string-bnf"></a>2.4.4. Address String Grammar</h3></div></div></div><p>This section provides a formal grammar for address strings.</p><p title="Tokens"><b>Tokens. </b>The following regular expressions define the tokens used
+	to parse address strings:</p><pre class="programlisting">
+	LBRACE: \\{
+	RBRACE: \\}
+	LBRACK: \\[
+	RBRACK: \\]
+	COLON:  :
+	SEMI:   ;
+	SLASH:  /
+	COMMA:  ,
+	NUMBER: [+-]?[0-9]*\\.?[0-9]+
+	ID:     [a-zA-Z_](?:[a-zA-Z0-9_-]*[a-zA-Z0-9_])?
+	STRING: "(?:[^\\\\"]|\\\\.)*"|\'(?:[^\\\\\']|\\\\.)*\'
+	ESC:    \\\\[^ux]|\\\\x[0-9a-fA-F][0-9a-fA-F]|\\\\u[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]
+	SYM:    [.#*%@$^!+-]
+	WSPACE: [ \\n\\r\\t]+
+	</pre><p title="Grammar"><b>Grammar. </b>The formal grammar for addresses is given below:</p><pre class="programlisting">
+	address := name [ SLASH subject ] [ ";" options ]
+	name := ( part | quoted )+
+	subject := ( part | quoted | SLASH )*
+	quoted := STRING / ESC
+	part := LBRACE / RBRACE / COLON / COMMA / NUMBER / ID / SYM
+	options := map
+	map := "{" ( keyval ( "," keyval )* )? "}"
+	keyval "= ID ":" value
+	value := NUMBER / STRING / ID / map / list
+	list := "[" ( value ( "," value )* )? "]"
+	</pre><p title="Address String Options"><b>Address String Options. </b>The address string options map supports the following parameters:</p><pre class="programlisting">
+	&lt;name&gt; [ / &lt;subject&gt; ] ; {
+	create: always | sender | receiver | never,
+	delete: always | sender | receiver | never,
+	assert: always | sender | receiver | never,
+	mode: browse | consume,
+	node: {
+	type: queue | topic,
+	durable: True | False,
+	x-declare: { ... &lt;declare-overrides&gt; ... },
+	x-bindings: [&lt;binding_1&gt;, ... &lt;binding_n&gt;]
+	},
+	link: {
+	name: &lt;link-name&gt;,
+	durable: True | False,
+	reliability: unreliable | at-most-once | at-least-once | exactly-once,
+	x-declare: { ... &lt;declare-overrides&gt; ... },
+	x-bindings: [&lt;binding_1&gt;, ... &lt;binding_n&gt;],
+	x-subscribe: { ... &lt;subscribe-overrides&gt; ... }
+	}
+	}
+	</pre><div class="itemizedlist" title="Create, Delete, and Assert Policies"><p class="title"><b>Create, Delete, and Assert Policies</b></p><p>The create, delete, and assert policies specify who should
+	  perfom the associated action:</p><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>always</em></span>: the action is performed by any messaging client</p></li><li class="listitem"><p><span class="emphasis"><em>sender</em></span>: the action is only performed by a sender</p></li><li class="listitem"><p><span class="emphasis"><em>receiver</em></span>: the action is only performed by a receiver</p></li><li class="listitem"><p><span class="emphasis"><em>never</em></span>: the action is never performed (this is the default)</p></li></ul></div><div class="itemizedlist" title="Node-Type"><p class="title"><b>Node-Type</b></p><p>The node-type is one of:</p><ul class="itemizedlist"><li class="listitem"><p><span class="emphasis"><em>topic</em></span>: in the AMQP 0-10
+	  mapping, a topic node defaults to the topic exchange, x-declare
+	  may be used to specify other exchange types</p></li><li class="listitem"><p><span class="emphasis"><em>queue</em></span>: this is the default node-type</p></li></ul></div></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.id593891" href="#id593891" class="para">2</a>] </sup>In the programs we have just seen, we used
+      <code class="literal">amq.topic</code> as the default address if none is
+      passed in. This is the name of a standard exchange that always
+      exists on an AMQP 0-10 messaging broker.</p></div><div class="footnote"><p><sup>[<a id="ftn.id593918" href="#id593918" class="para">3</a>] </sup>The terms <span class="emphasis"><em>queue</em></span> and
+      <span class="emphasis"><em>topic</em></span> here were chosen to align with
+      their meaning in JMS. These two addressing 'patterns',
+      queue and topic, are sometimes refered as point-to-point
+      and publish-subscribe. AMQP 0-10 has an exchange type
+      called a <span class="emphasis"><em>topic exchange</em></span>. When the term
+      <span class="emphasis"><em>topic</em></span> occurs alone, it refers to a
+      Messaging API topic, not the topic
+      exchange.</p></div><div class="footnote"><p><sup>[<a id="ftn.id593939" href="#id593939" class="para">4</a>] </sup>There are exceptions to this rule; for instance,
+      a receiver can use <code class="literal">browse</code> mode, which leaves
+      messages on the queue for other receivers to
+      read.</p></div><div class="footnote"><p><sup>[<a id="ftn.id593952" href="#id593952" class="para">5</a>] </sup>The AMQP 0-10 implementation is the only one
+      that currently exists.</p></div><div class="footnote"><p><sup>[<a id="ftn.id593958" href="#id593958" class="para">6</a>] </sup>In AMQP 0-10, messages are sent to
+      exchanges, and read from queues. The Messaging API also
+      allows a sender to send messages to a queue; internally,
+      Qpid implements this by sending the message to the default
+      exchange, with the name of the queue as the routing key. The
+      Messaging API also allows a receiver to receive messages
+      from a topic; internally, Qpid implements this by setting up
+      a private subscription queue for the receiver and binding
+      the subscription queue to the exchange that corresponds to
+      the topic.</p></div><div class="footnote"><p><sup>[<a id="ftn.id593988" href="#id593988" class="para">7</a>] </sup>Currently, the C++, Python, and .NET C#
+      implementations of <span class="command"><strong>drain</strong></span> and
+      <span class="command"><strong>spout</strong></span> have slightly different
+      options. This tutorial uses the C++ implementation. The
+      options will be reconciled in the near
+      future.</p></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="replay.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.3. A Simple Messaging Program in .NET C# </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.5. Sender Capacity and Replay</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>

Propchange: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-addresses.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-addresses.html
------------------------------------------------------------------------------
    svn:keywords = Rev Date

Propchange: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-addresses.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-amqp0-10-mapping.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-amqp0-10-mapping.html?rev=1368244&view=auto
==============================================================================
--- qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-amqp0-10-mapping.html (added)
+++ qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-amqp0-10-mapping.html Wed Aug  1 20:54:46 2012
@@ -0,0 +1,164 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>2.16. The AMQP 0-10 mapping</title><link rel="stylesheet" type="text/css" href="css/style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="Programming in Apache Qpid"><link rel="up" href="ch02.html" title="Chapter 2. Using the Qpid Messaging API"><link rel="prev" href="ch02s15.html" title="2.15. Logging"><link rel="next" href="Message-Groups-Guide.html" title="2.17. Using Message Groups"></head><body><div class="container" bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><DIV class="header"><DIV class="logo"><H1>Apache Qpid™</H1><H2>Open Source AMQP Messaging</H2></DIV></DIV><DIV class="menu_box"><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Apache Qpid</H3><UL><LI><A href="http://qpid.apache.org/index.html">Home</A></LI><LI><A href="http://qpid.apache.org/download.
 html">Download</A></LI><LI><A href="http://qpid.apache.org/getting_started.html">Getting Started</A></LI><LI><A href="http://www.apache.org/licenses/">License</A></LI><LI><A href="https://cwiki.apache.org/qpid/faq.html">FAQ</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Documentation</H3><UL><LI><A href="http://qpid.apache.org/documentation.html#doc-release">0.14 Release</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-trunk">Trunk</A></LI><LI><A href="http://qpid.apache.org/documentation.html#doc-archives">Archive</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Community</H3><UL><LI><A href="http://qpid.apache.org/getting_involved.html">Getting Involved</A></LI><LI><A href="http://qpid.apache.org/source_repository.html">Source Repository</A></LI><LI><A href="http://qpid.apache.org/mailing_lists.html">Mailing Lists</A></
 LI><LI><A href="https://cwiki.apache.org/qpid/">Wiki</A></LI><LI><A href="https://issues.apache.org/jira/browse/qpid">Issue Reporting</A></LI><LI><A href="http://qpid.apache.org/people.html">People</A></LI><LI><A href="http://qpid.apache.org/acknowledgements.html">Acknowledgements</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>Developers</H3><UL><LI><A href="https://cwiki.apache.org/qpid/building.html">Building Qpid</A></LI><LI><A href="https://cwiki.apache.org/qpid/developer-pages.html">Developer Pages</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About AMQP</H3><UL><LI><A href="http://qpid.apache.org/amqp.html">What is AMQP?</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV><DIV class="menu_box_top"></DIV><DIV class="menu_box_body"><H3>About Apache</H3><UL><LI><A href="http://www.apache.org">Home</A></LI><LI><A href="http://www.ap
 ache.org/foundation/sponsorship.html">Sponsorship</A></LI><LI><A href="http://www.apache.org/foundation/thanks.html">Thanks</A></LI><LI><A href="http://www.apache.org/security/">Security</A></LI></UL></DIV><DIV class="menu_box_bottom"></DIV></DIV><div class="main_text_area"><div class="main_text_area_top"></div><div class="main_text_area_body"><DIV class="breadcrumbs"><span class="breadcrumb-link"><a href="index.html">Programming in Apache Qpid</a></span> &gt; <span class="breadcrumb-link"><a href="ch02.html">Using the Qpid Messaging API</a></span> &gt; <span class="breadcrumb-node">The AMQP 0-10 mapping</span></DIV><div class="section" title="2.16. The AMQP 0-10 mapping"><div class="titlepage"><div><div><h2 class="title"><a name="section-amqp0-10-mapping"></a>2.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"><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,<sup>[<a name="id597498" href="#ftn.id597498" class="footnote">12</a>]</sup> 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 name="table-amqp0-10-message-properties"></a><p class="title"><b>Table 2.9. Mapping to AMQP 0-10 Message Properties</b></p><div class="table-contents"><table summary="Mapping to AMQP 0-10 Message Properties" width="100%" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Python API</th><th>C++ API
+	      <sup>[<a name="id597594" href="#ftn.id597594" class="footnote">a</a>]</sup>
+	      </th><th>AMQP 0-10 Property<sup>[<a name="id597609" href="#ftn.id597609" class="footnote">b</a>]</sup></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<sup>[<a name="id597669" href="#ftn.id597669" class="footnote">c</a>]</sup></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<sup>[<a name="id597694" href="#ftn.id597694" class="footnote">d</a>]</sup></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"><p><sup>[<a id="ftn.id597594" href="#id597594" class="para">a</a>] </sup>
+		  The .NET Binding for C++ Messaging provides all the
+		  message and delivery properties described in the C++ API.
+		  See  <a class="xref" href="ch05s03.html#table-Dotnet-Binding-Message" title="Table 5.13. .NET Binding for the C++ Messaging API Class: Message">Table 5.13, “.NET Binding for the C++ Messaging API Class: Message”</a> .
+		</p></div><div class="footnote"><p><sup>[<a id="ftn.id597609" href="#id597609" class="para">b</a>] </sup>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"><p><sup>[<a id="ftn.id597669" href="#id597669" class="para">c</a>] </sup>The reply_to is converted from the protocol representation into an address.</p></div><div class="footnote"><p><sup>[<a id="ftn.id597694" href="#id597694" class="para">d</a>] </sup>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" title="2.16.1. 0-10 Message Property Keys"><div class="titlepage"><div><div><h3 class="title"><a name="section-amqp0-10-message-props"></a>2.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"><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.
+              <sup>[<a name="id597863" href="#ftn.id597863" class="footnote">13</a>]</sup>
+            </p></li></ul></div><div class="example"><a name="id597874"></a><p class="title"><b>Example 2.20. Accessing the AMQP 0-10 Message Timestamp in Python</b></p><div class="example-contents"><p>
+            The following code fragment checks for and extracts the message timestamp from
+            a received message.
+          </p><pre lang="python" class="programlisting">
+	    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 name="id597894"></a><p class="title"><b>Example 2.21. Accessing the AMQP 0-10 Message Timestamp in C++</b></p><div class="example-contents"><p>
+            The same example, except in C++.
+          </p><pre lang="c++" class="programlisting">
+	    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 &lt;&lt; "Timestamp=" &lt;&lt; msg.getProperties()["x-amqp-0-10.timestamp"].asString() &lt;&lt; std::endl;
+	    }
+	    }
+          </pre></div></div><br class="example-break"></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.id597498" href="#id597498" class="para">12</a>] </sup>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"><p><sup>[<a id="ftn.id597863" href="#id597863" class="para">13</a>] </sup>
+                  This special property is currently not supported by the Qpid JMS client.
+                </p></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s15.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="Message-Groups-Guide.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">2.15. Logging </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.17. Using Message Groups</td></tr></table></div><div class="main_text_area_bottom"></div></div></div></body></html>

Propchange: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-amqp0-10-mapping.html
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-amqp0-10-mapping.html
------------------------------------------------------------------------------
    svn:keywords = Rev Date

Propchange: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/html/section-amqp0-10-mapping.html
------------------------------------------------------------------------------
    svn:mime-type = text/html

Added: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/pdf/Programming-In-Apache-Qpid-Book.pdf
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/pdf/Programming-In-Apache-Qpid-Book.pdf?rev=1368244&view=auto
==============================================================================
Binary file - no diff available.

Propchange: qpid/site/docs/books/trunk/Programming-In-Apache-Qpid-Book/pdf/Programming-In-Apache-Qpid-Book.pdf
------------------------------------------------------------------------------
    svn:mime-type = application/octet-stream



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org


Mime
View raw message