You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jo...@apache.org on 2010/06/17 00:01:46 UTC
svn commit: r955411 [3/10] - in /qpid/site/docs/books:
0.5/AMQP-Messaging-Broker-CPP-Book/html/
0.5/Programming-In-Apache-Qpid/html/ 0.5/Programming-In-Apache-Qpid/pdf/
0.6/AMQP-Messaging-Broker-CPP-Book/html/
0.6/Programming-In-Apache-Qpid/html/ 0.6/P...
Modified: qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s04.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s04.html?rev=955411&r1=955410&r2=955411&view=diff
==============================================================================
--- qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s04.html (original)
+++ qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s04.html Wed Jun 16 22:01:44 2010
@@ -1,21 +1,566 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>4. Logging</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="3. Addresses"><link rel="next" href="ch02s05.html" title="5. Receiving Messages from Multiple Sources"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4. Logging</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s03.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s05.html">Next</a></td></tr></table><hr></div><div class="section" title="4.
Logging"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2564815"></a>4. Logging</h2></div></div></div><p>To simplify debugging, Qpid provides a logging facility
- that prints out messaging events.</p><div class="section" title="4.1. Logging in C++"><div class="titlepage"><div><div><h3 class="title"><a name="id2564826"></a>4.1. Logging in C++</h3></div></div></div><p>The Qpidd broker and C++ clients can both use environment
- variables to enable logging. Use QPID_LOG_ENABLE to set the
- level of logging you are interested in (trace, debug, info,
- notice, warning, error, or critical):</p><pre class="screen">
-$ export QPID_LOG_ENABLE="warning+"
-</pre><p>The Qpidd broker and C++ clients use QPID_LOG_OUTPUT to
- determine where logging output should be sent. This is either a
- file name or the special values stderr, stdout, or syslog:</p><pre class="screen">
-export QPID_LOG_TO_FILE="/tmp/myclient.out"
-</pre></div><div class="section" title="4.2. Logging in Python"><div class="titlepage"><div><div><h3 class="title"><a name="id2564858"></a>4.2. Logging in Python</h3></div></div></div><p>
- The Python client library supports logging using the standard Python logging module. The easiest way to do logging is to use the <span class="command"><strong>basicConfig()</strong></span>, which reports all warnings and errors:
- </p><pre class="programlisting">from logging import basicConfig
-basicConfig()
-</pre><p>
- Qpidd also provides a convenience method that makes it easy to specify the level of logging desired. For instance, the following code enables logging at the <span class="command"><strong>DEBUG</strong></span> level:
- </p><pre class="programlisting">from qpid.log import enable, DEBUG
-enable("qpid.messaging.io", DEBUG)
-</pre><p>
- For more information on Python logging, see <a class="ulink" href="http://docs.python.org/lib/node425.html" target="_top">http://docs.python.org/lib/node425.html</a>. For more information on Qpid logging, use <span class="command"><strong>$ pydoc qpid.log</strong></span>.
- </p></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="ch02s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3. Addresses </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 5. Receiving Messages from Multiple Sources</td></tr></table></div></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>4. Addresses</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="3. A Simple Messaging Program in .NET C#"><link rel="next" href="ch02s05.html" title="5. Logging"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">4. Addresses</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s03.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s05.html">Next</a></td></tr></table><hr></div><div class="section" title="4.�
�Addresses"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-addresses"></a>4. Addresses</h2></div></div></div><p>An <em class="firstterm">address</em> is the name of a message
+ target or message source. In the programs we have just seen, we
+ used the address <code class="literal">amq.topic</code> (which is the name
+ of an exchange on an AMQP 0-10 messaging broker).
+
+ 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="id2758681" href="#ftn.id2758681" class="footnote">1</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="id2776261" href="#ftn.id2776261" class="footnote">2</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="id2748517" href="#ftn.id2748517" class="footnote">3</a>]</sup>
+
+ queues map to AMQP queues, and topics map to AMQP exchanges.
+
+ <sup>[<a name="id2781373" href="#ftn.id2781373" class="footnote">4</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="id2750500" href="#ftn.id2750500" class="footnote">5</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="id2774577"></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="id2771980"></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="4.1. Address Strings"><div class="titlepage"><div><div><h3 class="title"><a name="id2762724"></a>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 ::= <address> [ / <subject> ] [ ; <options> ]
+options ::= { <key> : <value>, ... }
+</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="ch02s04.html#section-address-string-bnf" title="4.4. Address String Grammar">Section 4.4, “Address String Grammar”</a>.</p><p>So far, the address strings in this tutorial have used
+ only addresses. The following sections show how to use
+ subjects and options.</p></div><div class="section" title="4.2. Subjects"><div class="titlepage"><div><div><h3 class="title"><a name="id2779643"></a>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, and queues do not provide filtering. This is
+ discussed in <a class="xref" href="ch02s13.html" title="13. The AMQP 0-10 mapping">Section 13, “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.
+
+ In the future, if a receiver is bound to a queue, and its
+ address contains a subject, the subject will be used as a
+ selector to filter messages.
+ </p></div><div class="example"><a name="id2766463"></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="id2776739"></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="4.3. Address String Options"><div class="titlepage"><div><div><h3 class="title"><a name="id2758496"></a>4.3. Address String Options</h3></div></div></div><p>
+ The options in an address string contain additional
+ information for the senders or receivers created for it,
+ including:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><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 that rely on the functionality of specific node types.
+ </p><p>
+ For instance, the Qpid XML exchange can use XQuery to do
+ content-based routing for XML messages, or to query
+ message data using XQuery. Queries can be specified using
+ options.
+ </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="4.3.1. assert"><div class="titlepage"><div><div><h4 class="title"><a name="id2743186"></a>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="id2764387"></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="4.3.2. create"><div class="titlepage"><div><div><h4 class="title"><a name="id2766439"></a>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="id2755517"></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"></div><div class="section" title="4.3.3. browse"><div class="titlepage"><div><div><h4 class="title"><a name="id2746592"></a>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="id2768982"></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="4.3.4. x-bindings"><div class="titlepage"><div><div><h4 class="title"><a name="id2785819"></a>4.3.4. x-bindings</h4></div></div></div><p><code class="literal">x-bindings</code> allows an address string
+ to specify properties AMQP 0-10 bindings. 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. These queries can be
+ specified in addresses using x-bindings</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="id2782446"></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 > 50
+ and $w/temperature_f - $w/dewpoint > 5
+ and $w/wind_speed_mph > 7
+ and $w/wind_speed_mph < 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">
+
+<weather>
+ <station>Raleigh-Durham International Airport (KRDU)</station>
+ <wind_speed_mph>16</wind_speed_mph>
+ <temperature_f>70</temperature_f>
+ <dewpoint>35</dewpoint>
+</weather>
+ </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='<weather>
+ <station>Raleigh-Durham International Airport (KRDU)</station>
+ <wind_speed_mph>16</wind_speed_mph>
+ <temperature_f>40</temperature_f>
+ <dewpoint>35</dewpoint>
+</weather>')
+ </pre></div></div><br class="example-break"></div><div class="section" title="4.3.5. Address String Options - Reference"><div class="titlepage"><div><div><h4 class="title"><a name="id2759254"></a>4.3.5. Address String Options - Reference</h4></div></div></div><div class="table"><a name="id2771356"></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="ch02s04.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="ch02s04.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 teh
+ queue once the client acknoweldges 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: <exchange>,
+ queue: <queue>,
+ key: <key>,
+ arguments: {
+ <key_1>: <value_1>,
+ ...,
+ <key_n>: <value_n> }
+ },
+ ...
+]
+</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.
+ </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></table></div></div><br class="table-break"></div></div><div class="section" title="4.4. Address String Grammar"><div class="titlepage"><div><div><h3 class="title"><a name="section-address-string-bnf"></a>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 [ "/" subject ] [ ";" options ]
+ name := ( part | quoted )+
+subject := ( part | quoted | "/" )*
+ 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">
+<name> [ / <subject> ] ; {
+ 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: { ... <declare-overrides> ... },
+ x-bindings: [<binding_1>, ... <binding_n>]
+ },
+ link: {
+ name: <link-name>,
+ durable: True | False,
+ reliability: unreliable | at-most-once | at-least-once | exactly-once,
+ x-declare: { ... <declare-overrides> ... },
+ x-bindings: [<binding_1>, ... <binding_n>],
+ x-subscribe: { ... <subscribe-overrides> ... }
+ }
+}
+</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" type="disc"><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" type="disc"><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 name="ftn.id2758681" href="#id2758681" class="para">1</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 name="ftn.id2776261" href="#id2776261" class="para">2</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 name="ftn.id2748517" href="#id2748517" class="para">3</a>] </sup>The AMQP 0-10 implementation is the only one
+ that currently exists.</p></div><div class="footnote"><p><sup>[<a name="ftn.id2781373" href="#id2781373" class="para">4</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 name="ftn.id2750500" href="#id2750500" class="para">5</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 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="ch02s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">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"> 5. Logging</td></tr></table></div></body></html>
Modified: qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s05.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s05.html?rev=955411&r1=955410&r2=955411&view=diff
==============================================================================
--- qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s05.html (original)
+++ qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s05.html Wed Jun 16 22:01:44 2010
@@ -1,19 +1,21 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>5. Receiving Messages from Multiple Sources</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="ch02s04.html" title="4. Logging"><link rel="next" href="ch02s06.html" title="6. Request / Response"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5. Receiving Messages from Multiple Sources</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s04.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s06.html">Next</a></td></tr></tabl
e><hr></div><div class="section" title="5. Receiving Messages from Multiple Sources"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2564922"></a>5. Receiving Messages from Multiple Sources</h2></div></div></div><p>A receiver can only read from one source, but many
- programs need to be able to read messages from many sources,
- preserving the original sequence of the messages. In the Qpid
- Messaging API, a program can ask a session for the <span class="quote">“<span class="quote">next
- receiver</span>”</span>; that is, the receiver that is responsible for
- the next available message. The following example shows how this
- is done in C++ and Python.</p><div class="example"><a name="id2564942"></a><p class="title"><b>Example 2.11. Receiving Messages from Multiple Sources</b></p><div class="example-contents"><p>C++:</p><pre class="programlisting">
-Receiver receiver1 = session.createReceiver(address1);
-Receiver receiver2 = session.createReceiver(address2);
-
-Message message = session.nextReceiver().fetch();
-session.acknowledge(); // acknowledge message receipt
-std::cout << message.getContent() << std::endl;
- </pre><p>Python:</p><pre class="programlisting">
-receiver1 = session.receiver(address1)
-receiver2 = session.receiver(address)
-message = session.next_receiver().fetch()
-print message.content
- </pre></div></div><br class="example-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s04.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="ch02s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. Logging </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 6. Request / Response</td></tr></table></div></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>5. Logging</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="ch02s04.html" title="4. Addresses"><link rel="next" href="ch02s06.html" title="6. Receiving Messages from Multiple Sources"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">5. Logging</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s04.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s06.html">Next</a></td></tr></table><hr></div><div class="section" title="5.
Logging"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2743890"></a>5. Logging</h2></div></div></div><p>To simplify debugging, Qpid provides a logging facility
+ that prints out messaging events.</p><div class="section" title="5.1. Logging in C++"><div class="titlepage"><div><div><h3 class="title"><a name="id2743901"></a>5.1. Logging in C++</h3></div></div></div><p>The Qpidd broker and C++ clients can both use environment
+ variables to enable logging. Use QPID_LOG_ENABLE to set the
+ level of logging you are interested in (trace, debug, info,
+ notice, warning, error, or critical):</p><pre class="screen">
+$ export QPID_LOG_ENABLE="warning+"
+</pre><p>The Qpidd broker and C++ clients use QPID_LOG_OUTPUT to
+ determine where logging output should be sent. This is either a
+ file name or the special values stderr, stdout, or syslog:</p><pre class="screen">
+export QPID_LOG_TO_FILE="/tmp/myclient.out"
+</pre></div><div class="section" title="5.2. Logging in Python"><div class="titlepage"><div><div><h3 class="title"><a name="id2743934"></a>5.2. Logging in Python</h3></div></div></div><p>
+ The Python client library supports logging using the standard Python logging module. The easiest way to do logging is to use the <span class="command"><strong>basicConfig()</strong></span>, which reports all warnings and errors:
+ </p><pre class="programlisting">from logging import basicConfig
+basicConfig()
+</pre><p>
+ Qpidd also provides a convenience method that makes it easy to specify the level of logging desired. For instance, the following code enables logging at the <span class="command"><strong>DEBUG</strong></span> level:
+ </p><pre class="programlisting">from qpid.log import enable, DEBUG
+enable("qpid.messaging.io", DEBUG)
+</pre><p>
+ For more information on Python logging, see <a class="ulink" href="http://docs.python.org/lib/node425.html" target="_top">http://docs.python.org/lib/node425.html</a>. For more information on Qpid logging, use <span class="command"><strong>$ pydoc qpid.log</strong></span>.
+ </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s04.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="ch02s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">4. Addresses </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 6. Receiving Messages from Multiple Sources</td></tr></table></div></body></html>
Modified: qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s06.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s06.html?rev=955411&r1=955410&r2=955411&view=diff
==============================================================================
--- qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s06.html (original)
+++ qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s06.html Wed Jun 16 22:01:44 2010
@@ -1,42 +1,27 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>6. Request / Response</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="ch02s05.html" title="5. Receiving Messages from Multiple Sources"><link rel="next" href="ch02s07.html" title="7. Maps in Message Content"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">6. Request / Response</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s05.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s07.html">Next</a></td></tr></table><hr>
</div><div class="section" title="6. Request / Response"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2564983"></a>6. Request / Response</h2></div></div></div><p>Request / Response applications use the reply-to property,
- described in <a class="xref" href="ch02s12.html#table-amqp0-10-message-properties" title="Table 2.8. Mapping to AMQP 0-10 Message Properties">Table 2.8, “Mapping to AMQP 0-10 Message Properties”</a>, to allow a server
- to respond to the client that sent a message. A server sets up a
- service queue, with a name known to clients. A client creates a
- private queue for the server's response, creates a message for a
- request, sets the request's reply-to property to the address of
- the client's response queue, and sends the request to the
- service queue. The server sends the response to the address
- specified in the request's reply-to property.
- </p><div class="example"><a name="id2579261"></a><p class="title"><b>Example 2.12. Request / Response Applications in C++</b></p><div class="example-contents"><p>This example shows the C++ code for a client and server
- that use the request / response pattern.</p><p>The server creates a service queue and waits for a
- message to arrive. If it receives a message, it sends a
- message back to the sender.</p><pre class="programlisting">Receiver receiver = session.createReceiver("service_queue; {create: always}");
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>6. Receiving Messages from Multiple Sources</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="ch02s05.html" title="5. Logging"><link rel="next" href="ch02s07.html" title="7. Request / Response"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">6. Receiving Messages from Multiple Sources</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s05.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s07.html">Next</a></td></tr></tabl
e><hr></div><div class="section" title="6. Receiving Messages from Multiple Sources"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2743998"></a>6. Receiving Messages from Multiple Sources</h2></div></div></div><p>A receiver can only read from one source, but many
+ programs need to be able to read messages from many sources,
+ preserving the original sequence of the messages. In the Qpid
+ Messaging API, a program can ask a session for the <span class="quote">“<span class="quote">next
+ receiver</span>”</span>; that is, the receiver that is responsible for
+ the next available message. The following example shows how this
+ is done in C++, Python, and .NET C#.</p><div class="example"><a name="id2744018"></a><p class="title"><b>Example 2.12. Receiving Messages from Multiple Sources</b></p><div class="example-contents"><p>C++:</p><pre class="programlisting">
+Receiver receiver1 = session.createReceiver(address1);
+Receiver receiver2 = session.createReceiver(address2);
-Message request = receiver.fetch();
-const Address&amp; address = request.getReplyTo(); // Get "reply-to" from request ...
-if (address) {
- Sender sender = session.createSender(address); // ... send response to "reply-to"
- Message response("pong!");
- sender.send(response);
- session.acknowledge();
-}
- </pre><p>The client creates a sender for the service queue, and
- also creates a response queue that is deleted when the
- client closes the receiver for the response queue. In the C++
- client, if the address starts with the character
- <code class="literal">#</code>, it is given a unique name.</p><pre class="programlisting">
-Sender sender = session.createSender("service_queue");
+Message message = session.nextReceiver().fetch();
+session.acknowledge(); // acknowledge message receipt
+std::cout << message.getContent() << std::endl;
+ </pre><p>Python:</p><pre class="programlisting">
+receiver1 = session.receiver(address1)
+receiver2 = session.receiver(address)
+message = session.next_receiver().fetch()
+print message.content
+ </pre><p>.NET C#:</p><pre class="programlisting">
+Receiver receiver1 = session.CreateReceiver(address1);
+Receiver receiver2 = session.CreateReceiver(address2);
-Address responseQueue("#response-queue; {create:always, delete:always}");
-Receiver receiver = session.createReceiver(responseQueue);
-
-Message request;
-request.setReplyTo(responseQueue);
-request.setContent("ping");
-sender.send(request);
-Message response = receiver.fetch();
-std::cout << request.getContent() << " -> " << response.getContent() << std::endl;
- </pre><p>The client sends the string <code class="literal">ping</code> to
- the server. The server sends the response
- <code class="literal">pong</code> back to the same client, using the
- <code class="varname">replyTo</code> property.</p></div></div><br class="example-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s05.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="ch02s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5. Receiving Messages from Multiple Sources </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 7. Maps in Message Content</td></tr></table></div></body></html>
+Message message = new Message();
+message = session.NextReceiver().Fetch();
+session.Acknowledge();
+Console.WriteLine("{0}", message.GetContent());
+ </pre></div></div><br class="example-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s05.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="ch02s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">5. Logging </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 7. Request / Response</td></tr></table></div></body></html>
Modified: qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s07.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s07.html?rev=955411&r1=955410&r2=955411&view=diff
==============================================================================
--- qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s07.html (original)
+++ qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s07.html Wed Jun 16 22:01:44 2010
@@ -1,87 +1,42 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>7. Maps in Message Content</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="ch02s06.html" title="6. Request / Response"><link rel="next" href="ch02s08.html" title="8. Performance"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">7. Maps in Message Content</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s06.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s08.html">Next</a></td></tr></table><hr></div><div class="sectio
n" title="7. Maps in Message Content"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-Maps"></a>7. Maps in Message Content</h2></div></div></div><p>Many messaging applications need to exchange data across
- languages and platforms, using the native datatypes of each
- programming language. AMQP provides a set of portable datatypes,
- but does not directly support a set of named type/value
- pairs. Java JMS provides the <code class="classname">MapMessage</code>
- interface, which allows sets of named type/value pairs, but does
- not provide a set of portable datatypes.</p><p>The Qpid Messaging API supports maps in message
- content. Unlike JMS, any message can contain maps. These maps
- are supported in each language using the conventions of the
- language. In Java, we implement the
- <code class="classname">MapMessage</code> interface; in Python, we
- support <code class="classname">dict</code> and
- <code class="classname">list</code> in message content; in C++, we
- provide the <code class="classname">Variant::Map</code> and
- <code class="classname">Variant::List</code> classes to represent maps
- and lists. In all languages, messages are encoded using AMQP's
- portable datatypes.
- </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Because of the differences in type systems among
- languages, the simplest way to provide portable messages is to
- rely on maps, lists, strings, 64 bit signed integers, and
- doubles for messages that need to be exchanged across languages
- and platforms.</p></div><div class="section" title="7.1. Qpid Maps in Python"><div class="titlepage"><div><div><h3 class="title"><a name="section-Python-Maps"></a>7.1. Qpid Maps in Python</h3></div></div></div><p>In Python, Qpid supports the <code class="classname">dict</code> and <code class="classname">list</code> types directly in message content. The following code shows how to send these structures in a message:</p><div class="example"><a name="id2579426"></a><p class="title"><b>Example 2.13. Sending Qpid Maps in Python</b></p><div class="example-contents"><pre class="programlisting">
-from qpid.messaging import *
-# !!! SNIP !!!
-
-content = {'Id' : 987654321, 'name' : 'Widget', 'percent' : 0.99}
-content['colours'] = ['red', 'green', 'white']
-content['dimensions'] = {'length' : 10.2, 'width' : 5.1,'depth' : 2.0};
-content['parts'] = [ [1,2,5], [8,2,5] ]
-content['specs'] = {'colors' : content['colours'],
- 'dimensions' : content['dimensions'],
- 'parts' : content['parts'] }
-message = Message(content=content)
-sender.send(message)
- </pre></div></div><br class="example-break"><p>The following table shows the datatypes that can be sent in a Python map message,
- and the corresponding datatypes that will be received by clients in Java or C++.</p><div class="table"><a name="table-Python-Maps"></a><p class="title"><b>Table 2.4. Python Datatypes in Maps</b></p><div class="table-contents"><table summary="Python Datatypes in Maps" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Python Datatype</th><th>→ C++</th><th>→ Java</th></tr></thead><tbody><tr><td>bool</td><td>bool</td><td>boolean</td></tr><tr><td>int</td><td>int64</td><td>long</td></tr><tr><td>long</td><td>int64</td><td>long</td></tr><tr><td>float</td><td>double</td><td>double</td></tr><tr><td>unicode</td><td>string</td><td>java.lang.String</td></tr><tr><td>uuid</td><td>qpid::types::Uuid</td><td>java.util.UUID</td></tr><tr><td>dict</td><td>Variant::Map</td><td>java.util.Map</td></tr><tr><td>list</td><td>Variant::List</td><td>java.util.List</td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" title="7.2. Qpid Maps in C
++"><div class="titlepage"><div><div><h3 class="title"><a name="section-cpp-Maps"></a>7.2. Qpid Maps in C++</h3></div></div></div><p>In C++, Qpid defines the the
- <code class="classname">Variant::Map</code> and
- <code class="classname">Variant::List</code> types, which can be
- encoded into message content. The following code shows how to
- send these structures in a message:</p><div class="example"><a name="id2579597"></a><p class="title"><b>Example 2.14. Sending Qpid Maps in C++</b></p><div class="example-contents"><pre class="programlisting">
-using namespace qpid::types;
-
-// !!! SNIP !!!
-
-Message message;
-Variant::Map content;
-content["id"] = 987654321;
-content["name"] = "Widget";
-content["percent"] = 0.99;
-Variant::List colours;
-colours.push_back(Variant("red"));
-colours.push_back(Variant("green"));
-colours.push_back(Variant("white"));
-content["colours"] = colours;
-
-Variant::Map dimensions;
-dimensions["length"] = 10.2;
-dimensions["width"] = 5.1;
-dimensions["depth"] = 2.0;
-content["dimensions"]= dimensions;
-
-Variant::List part1;
-part1.push_back(Variant(1));
-part1.push_back(Variant(2));
-part1.push_back(Variant(5));
-
-Variant::List part2;
-part2.push_back(Variant(8));
-part2.push_back(Variant(2));
-part2.push_back(Variant(5));
-
-Variant::List parts;
-parts.push_back(part1);
-parts.push_back(part2);
-content["parts"]= parts;
-
-Variant::Map specs;
-specs["colours"] = colours;
-specs["dimensions"] = dimensions;
-specs["parts"] = parts;
-content["specs"] = specs;
-
-encode(content, message);
-sender.send(message, true);
- </pre></div></div><br class="example-break"><p>The following table shows the datatypes that can be sent
- in a C++ map message, and the corresponding datatypes that
- will be received by clients in Java and Python.</p><div class="table"><a name="table-cpp-Maps"></a><p class="title"><b>Table 2.5. C++ Datatypes in Maps</b></p><div class="table-contents"><table summary="C++ Datatypes in Maps" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>C++ Datatype</th><th>→ Python</th><th>→ Java</th></tr></thead><tbody><tr><td>bool</td><td>bool</td><td>boolean</td></tr><tr><td>uint16</td><td>int | long</td><td>short</td></tr><tr><td>uint32</td><td>int | long</td><td>int</td></tr><tr><td>uint64</td><td>int | long</td><td>long</td></tr><tr><td>int16</td><td>int | long</td><td>short</td></tr><tr><td>int32</td><td>int | long</td><td>int</td></tr><tr><td>int64</td><td>int | long</td><td>long</td></tr><tr><td>float</td><td>float</td><td>float</td></tr><tr><td>double</td><td>float</td><td>double</td></tr><tr><td>string</td><td>unicode</td><td>java.lang.String</td></tr><tr><td>qpid::types::Uuid</td><td>uuid</td><td>java.util.UUID</t
d></tr><tr><td>Variant::Map</td><td>dict</td><td>java.util.Map</td></tr><tr><td>Variant::List</td><td>list</td><td>java.util.List</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s06.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="ch02s08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6. Request / Response </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 8. Performance</td></tr></table></div></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>7. Request / Response</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="ch02s06.html" title="6. Receiving Messages from Multiple Sources"><link rel="next" href="ch02s08.html" title="8. Maps in Message Content"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">7. Request / Response</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s06.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s08.html">Next</a></td></tr></table><hr>
</div><div class="section" title="7. Request / Response"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2744067"></a>7. Request / Response</h2></div></div></div><p>Request / Response applications use the reply-to property,
+ described in <a class="xref" href="ch02s13.html#table-amqp0-10-message-properties" title="Table 2.8. Mapping to AMQP 0-10 Message Properties">Table 2.8, “Mapping to AMQP 0-10 Message Properties”</a>, to allow a server
+ to respond to the client that sent a message. A server sets up a
+ service queue, with a name known to clients. A client creates a
+ private queue for the server's response, creates a message for a
+ request, sets the request's reply-to property to the address of
+ the client's response queue, and sends the request to the
+ service queue. The server sends the response to the address
+ specified in the request's reply-to property.
+ </p><div class="example"><a name="id2744102"></a><p class="title"><b>Example 2.13. Request / Response Applications in C++</b></p><div class="example-contents"><p>This example shows the C++ code for a client and server
+ that use the request / response pattern.</p><p>The server creates a service queue and waits for a
+ message to arrive. If it receives a message, it sends a
+ message back to the sender.</p><pre class="programlisting">Receiver receiver = session.createReceiver("service_queue; {create: always}");
+
+Message request = receiver.fetch();
+const Address&amp; address = request.getReplyTo(); // Get "reply-to" from request ...
+if (address) {
+ Sender sender = session.createSender(address); // ... send response to "reply-to"
+ Message response("pong!");
+ sender.send(response);
+ session.acknowledge();
+}
+ </pre><p>The client creates a sender for the service queue, and
+ also creates a response queue that is deleted when the
+ client closes the receiver for the response queue. In the C++
+ client, if the address starts with the character
+ <code class="literal">#</code>, it is given a unique name.</p><pre class="programlisting">
+Sender sender = session.createSender("service_queue");
+
+Address responseQueue("#response-queue; {create:always, delete:always}");
+Receiver receiver = session.createReceiver(responseQueue);
+
+Message request;
+request.setReplyTo(responseQueue);
+request.setContent("ping");
+sender.send(request);
+Message response = receiver.fetch();
+std::cout << request.getContent() << " -> " << response.getContent() << std::endl;
+ </pre><p>The client sends the string <code class="literal">ping</code> to
+ the server. The server sends the response
+ <code class="literal">pong</code> back to the same client, using the
+ <code class="varname">replyTo</code> property.</p></div></div><br class="example-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s06.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="ch02s08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">6. Receiving Messages from Multiple Sources </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 8. Maps in Message Content</td></tr></table></div></body></html>
Modified: qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s08.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s08.html?rev=955411&r1=955410&r2=955411&view=diff
==============================================================================
--- qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s08.html (original)
+++ qpid/site/docs/books/0.5/Programming-In-Apache-Qpid/html/ch02s08.html Wed Jun 16 22:01:44 2010
@@ -1,18 +1,87 @@
-<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>8. Performance</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="ch02s07.html" title="7. Maps in Message Content"><link rel="next" href="ch02s09.html" title="9. Reliability"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">8. Performance</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s07.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s09.html">Next</a></td></tr></table><hr></div><div class="section" title="8. Perfo
rmance"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2563223"></a>8. Performance</h2></div></div></div><p>
- Clients can often be made significantly faster by batching acknowledgements and setting the capacity of receivers to allow prefetch. The size of a sender's replay buffer can also affect performance.
- </p><div class="section" title="8.1. Batching Acknowledgements"><div class="titlepage"><div><div><h3 class="title"><a name="id2563236"></a>8.1. Batching Acknowledgements</h3></div></div></div><p>Many of the simple examples we have shown retrieve a message and immediately acknowledge it. Because each acknowledgement results in network traffic, you can dramatically increase performance by acknowledging messages in batches. For instance, an application can read a number of related messages, then acknowledge the entire batch, or an application can acknowledge after a certain number of messages have been received or a certain time period has elapsed. Messages are not removed from the broker until they are acknowledged, so guaranteed delivery is still available when batching acknowledgements.</p></div><div class="section" title="8.2. Prefetch"><div class="titlepage"><div><div><h3 class="title"><a name="id2563245"></a>8.2. Prefetch</h3></div></div></div><p>By default, a r
eceiver retrieves the next message from the server, one message at a time, which provides intuitive results when writing and debugging programs, but does not provide optimum performance. To create an input buffer, set the capacity of the receiver to the size of the desired input buffer; for many applications, a capacity of 100 performs well. </p><div class="example"><a name="id2622655"></a><p class="title"><b>Example 2.15. Prefetch</b></p><div class="example-contents"><p>C++</p><pre class="programlisting">
-Receiver receiver = session.createReceiver(address);
-receiver.setCapacity(100);
-Message message = receiver.fetch();
- </pre></div></div><br class="example-break"></div><div class="section" title="8.3. Sizing the Replay Buffer"><div class="titlepage"><div><div><h3 class="title"><a name="id2622677"></a>8.3. Sizing the Replay Buffer</h3></div></div></div><p>In order to guarantee delivery, a sender automatically
- keeps messages in a replay buffer until the messaging broker
- acknowledges that they have been received. The replay buffer
- is held in memory, and is never paged to disk. For most
- applications, the default size of the replay buffer works
- well. A large replay buffer requires more memory, a small
- buffer can slow down the client because it can not send new
- messages if the replay buffer is full, and must wait for
- existing sends to be acknowledged.</p><div class="example"><a name="id2622702"></a><p class="title"><b>Example 2.16. Sizing the Replay Buffer</b></p><div class="example-contents"><p>C++</p><pre class="programlisting">
-Sender sender = session.createSender(address);
-sender.setCapacity(100);
- </pre></div></div><br class="example-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s07.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="ch02s09.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7. Maps in Message Content </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 9. Reliability</td></tr></table></div></body></html>
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>8. Maps in Message Content</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><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="ch02s07.html" title="7. Request / Response"><link rel="next" href="ch02s09.html" title="9. Performance"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">8. Maps in Message Content</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s07.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Using the Qpid Messaging API</th><td width="20%" align="right"> <a accesskey="n" href="ch02s09.html">Next</a></td></tr></table><hr></div><div class="sectio
n" title="8. Maps in Message Content"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-Maps"></a>8. Maps in Message Content</h2></div></div></div><p>Many messaging applications need to exchange data across
+ languages and platforms, using the native datatypes of each
+ programming language. AMQP provides a set of portable datatypes,
+ but does not directly support a set of named type/value
+ pairs. Java JMS provides the <code class="classname">MapMessage</code>
+ interface, which allows sets of named type/value pairs, but does
+ not provide a set of portable datatypes.</p><p>The Qpid Messaging API supports maps in message
+ content. Unlike JMS, any message can contain maps. These maps
+ are supported in each language using the conventions of the
+ language. In Java, we implement the
+ <code class="classname">MapMessage</code> interface; in Python, we
+ support <code class="classname">dict</code> and
+ <code class="classname">list</code> in message content; in C++, we
+ provide the <code class="classname">Variant::Map</code> and
+ <code class="classname">Variant::List</code> classes to represent maps
+ and lists. In all languages, messages are encoded using AMQP's
+ portable datatypes.
+ </p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Because of the differences in type systems among
+ languages, the simplest way to provide portable messages is to
+ rely on maps, lists, strings, 64 bit signed integers, and
+ doubles for messages that need to be exchanged across languages
+ and platforms.</p></div><div class="section" title="8.1. Qpid Maps in Python"><div class="titlepage"><div><div><h3 class="title"><a name="section-Python-Maps"></a>8.1. Qpid Maps in Python</h3></div></div></div><p>In Python, Qpid supports the <code class="classname">dict</code> and <code class="classname">list</code> types directly in message content. The following code shows how to send these structures in a message:</p><div class="example"><a name="id2744275"></a><p class="title"><b>Example 2.14. Sending Qpid Maps in Python</b></p><div class="example-contents"><pre class="programlisting">
+from qpid.messaging import *
+# !!! SNIP !!!
+
+content = {'Id' : 987654321, 'name' : 'Widget', 'percent' : 0.99}
+content['colours'] = ['red', 'green', 'white']
+content['dimensions'] = {'length' : 10.2, 'width' : 5.1,'depth' : 2.0};
+content['parts'] = [ [1,2,5], [8,2,5] ]
+content['specs'] = {'colors' : content['colours'],
+ 'dimensions' : content['dimensions'],
+ 'parts' : content['parts'] }
+message = Message(content=content)
+sender.send(message)
+ </pre></div></div><br class="example-break"><p>The following table shows the datatypes that can be sent in a Python map message,
+ and the corresponding datatypes that will be received by clients in Java or C++.</p><div class="table"><a name="table-Python-Maps"></a><p class="title"><b>Table 2.4. Python Datatypes in Maps</b></p><div class="table-contents"><table summary="Python Datatypes in Maps" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Python Datatype</th><th>→ C++</th><th>→ Java</th></tr></thead><tbody><tr><td>bool</td><td>bool</td><td>boolean</td></tr><tr><td>int</td><td>int64</td><td>long</td></tr><tr><td>long</td><td>int64</td><td>long</td></tr><tr><td>float</td><td>double</td><td>double</td></tr><tr><td>unicode</td><td>string</td><td>java.lang.String</td></tr><tr><td>uuid</td><td>qpid::types::Uuid</td><td>java.util.UUID</td></tr><tr><td>dict</td><td>Variant::Map</td><td>java.util.Map</td></tr><tr><td>list</td><td>Variant::List</td><td>java.util.List</td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" title="8.2. Qpid Maps in C
++"><div class="titlepage"><div><div><h3 class="title"><a name="section-cpp-Maps"></a>8.2. Qpid Maps in C++</h3></div></div></div><p>In C++, Qpid defines the the
+ <code class="classname">Variant::Map</code> and
+ <code class="classname">Variant::List</code> types, which can be
+ encoded into message content. The following code shows how to
+ send these structures in a message:</p><div class="example"><a name="id2744416"></a><p class="title"><b>Example 2.15. Sending Qpid Maps in C++</b></p><div class="example-contents"><pre class="programlisting">
+using namespace qpid::types;
+
+// !!! SNIP !!!
+
+Message message;
+Variant::Map content;
+content["id"] = 987654321;
+content["name"] = "Widget";
+content["percent"] = 0.99;
+Variant::List colours;
+colours.push_back(Variant("red"));
+colours.push_back(Variant("green"));
+colours.push_back(Variant("white"));
+content["colours"] = colours;
+
+Variant::Map dimensions;
+dimensions["length"] = 10.2;
+dimensions["width"] = 5.1;
+dimensions["depth"] = 2.0;
+content["dimensions"]= dimensions;
+
+Variant::List part1;
+part1.push_back(Variant(1));
+part1.push_back(Variant(2));
+part1.push_back(Variant(5));
+
+Variant::List part2;
+part2.push_back(Variant(8));
+part2.push_back(Variant(2));
+part2.push_back(Variant(5));
+
+Variant::List parts;
+parts.push_back(part1);
+parts.push_back(part2);
+content["parts"]= parts;
+
+Variant::Map specs;
+specs["colours"] = colours;
+specs["dimensions"] = dimensions;
+specs["parts"] = parts;
+content["specs"] = specs;
+
+encode(content, message);
+sender.send(message, true);
+ </pre></div></div><br class="example-break"><p>The following table shows the datatypes that can be sent
+ in a C++ map message, and the corresponding datatypes that
+ will be received by clients in Java and Python.</p><div class="table"><a name="table-cpp-Maps"></a><p class="title"><b>Table 2.5. C++ Datatypes in Maps</b></p><div class="table-contents"><table summary="C++ Datatypes in Maps" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>C++ Datatype</th><th>→ Python</th><th>→ Java</th></tr></thead><tbody><tr><td>bool</td><td>bool</td><td>boolean</td></tr><tr><td>uint16</td><td>int | long</td><td>short</td></tr><tr><td>uint32</td><td>int | long</td><td>int</td></tr><tr><td>uint64</td><td>int | long</td><td>long</td></tr><tr><td>int16</td><td>int | long</td><td>short</td></tr><tr><td>int32</td><td>int | long</td><td>int</td></tr><tr><td>int64</td><td>int | long</td><td>long</td></tr><tr><td>float</td><td>float</td><td>float</td></tr><tr><td>double</td><td>float</td><td>double</td></tr><tr><td>string</td><td>unicode</td><td>java.lang.String</td></tr><tr><td>qpid::types::Uuid</td><td>uuid</td><td>java.util.UUID</t
d></tr><tr><td>Variant::Map</td><td>dict</td><td>java.util.Map</td></tr><tr><td>Variant::List</td><td>list</td><td>java.util.List</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s07.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="ch02s09.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7. Request / Response </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 9. Performance</td></tr></table></div></body></html>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org