path: root/qpid/doc/book/src/High-Level-API.xml

<?xml version='1.0' encoding='utf-8' ?>

<!--
 
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 
-->

<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<chapter id="high-level-client-api">
  <title>Qpid High Level Client API</title>

  <para>The Apache Qpid High Level Client API is a reliable,
  asynchronous messaging API that is similar to Java JMS, but designed
  to support programming in other commonly used programming languages,
  and to support cross-platform messaging using the AMQP protocol. It
  is currently implemented for C++ and Python. The addressing
  mechanisms it defines can also be used in Java JMS.</para>

  <para>Unlike earlier Qpid APIs, the High Level Client API does not
  expose the details of the underlying messaging protocol or the
  software components defined by the protocol. Instead, it defines a
  declarative syntax for addressing messaging components; to use it
  with a given messaging protocol, a protocol mapping must be defined.
  This specification provides a mapping to AMQP 0-10. At this point,
  AMQP 1.0 is not yet final, but we expect that applications written
  using the High Level Client API can be migrated to AMQP 1.0 with
  minimal changes, and applications that do not need to configure
  messaging components can be used without change. 
  </para>

  <para>The Qpid High Level Client API programming model is very
  similar to the Java JMS programming model. Here are the most
  important classes in the high level programming model:
  </para>

  <itemizedlist>

    <listitem><para>A <emphasis>connection</emphasis> represents a
    network connection. The parameters for the network connection are
    specified using a URL-based syntax when the connection is
    opened.</para></listitem>

    <listitem><para>A <emphasis>session</emphasis> represents the
    interface between a <emphasis>messaging client</emphasis> and a
    <emphasis>messaging broker</emphasis>. A session is created by a
    connection.</para></listitem>

    <listitem><para>An <emphasis>address</emphasis> is a string that
    represents a node on a messaging broker. In the AMQP 0-10 mapping,
    an address represents either an exchange or a queue. In the AMQP
    1.0 mapping, an address will represent an AMQP 1.0 node. Most
    addresses are simple names. An extended address can also specify
    options.</para></listitem>

    <listitem><para>A <emphasis>sender</emphasis> is a messaging
    client that sends <emphasis>message</emphasis>s to a destination
    on a <emphasis>messaging broker</emphasis>. A sender is created by
    a session.</para></listitem>

    <listitem><para>A <emphasis>receiver</emphasis> is a messaging
    client that receives <emphasis>message</emphasis>s from a
    source on a <emphasis>Messaging Broker</emphasis>. A Receiver
    is created by a Session.</para></listitem>

  </itemizedlist>

  <section>
    <title>A Simple Sender and Receiver in C++</title>

    <para>This section shows the code for two programs. One is a
    simple sender, the other is a simple receiver.</para>

    <section>
      <title>Connections and Sessions</title>

    <para>Both of these programs use the same skeleton, which includes
    the headers that define the Connection, Message, Receiver, Sender,
    and Session objects. The code in <methodname>main()</methodname>
    opens a connection using a URL that identifies a messaging broker,
    creates a session, and catches any errors that occur during
    messaging:</para>


<programlisting><![CDATA[
#include <qpid/messaging/Connection.h>
#include <qpid/messaging/Message.h>
#include <qpid/messaging/Receiver.h>
#include <qpid/messaging/Sender.h>
#include <qpid/messaging/Session.h>

#include <iostream>

using namespace qpid::messaging;

int main() {

    Connection connection;
    try {
        connection.open("amqp:tcp:127.0.0.1:5672");
        Session session = connection.newSession();

	/* #### Main body of messaging code goes here #### */

        connection.close();
        return 0;
    } catch(const std::exception& error) {
        std::cout << error.what() << std::endl;
        connection.close();
    }
    return 1;   
}]]></programlisting>

  </section>

  <section>
    <title>A Message Sender</title>
  <para>The sender program creates a Sender object that sends messages
  to <varname>message_queue</varname>, which happens to be a queue on
  on AMQP 0-10 messaging broker.</para>

<programlisting><![CDATA[
        Sender sender = session.createSender("message_queue");

	for (int i=0; i<5; i++) {
            std::stringstream content;
            content << "Message " << i;
            sender.send(Message(content.str()));
	}
	sender.close();
}]]></programlisting>

    <para> The AMQP 0-10 mapping implements this by sending messages
    to the default exchange, with <varname>message_queue</varname> as
    the routing key.</para>

  </section>
  <section>
    <title>A Message Receiver</title>

  <para>The receiver program creates a Receiver object, reads messages
  from <varname>message_queue</varname>, acknowledging them so the
  messaging broker knows they have been received and can be safely
  removed from the queue, and prints them:</para>

<programlisting><![CDATA[
        Receiver receiver = session.createReceiver("message_queue");

	Message message;
	int timeout = 1000;  /* in milliseconds */
	while (receiver.fetch(message, timeout)) {
	  std::cout << message.getContent();
	  session.acknowledge();
	}
	receiver.close();
]]></programlisting>

   <para>The <methodname>Receiver::fetch()</methodname> method can be
   used with or without a timeout. In either case, it is guaranteed to
   receive any messages on the queue. Here, the timeout is used in
   case <command>sender</command> is publishing at the same time
   message are being read.</para>

  </section>

  </section>

  <section>
    <title>Addresses</title>


    <para>As we have seen, an address is a string that identifies
    objects on the messaging broker. There are two kinds of
    addresses. A <firstterm>simple address</firstterm> is a name. An
    <firstterm>extended address</firstterm> can also have a
    <firstterm>subject</firstterm> and
    <firstterm>options</firstterm>.</para>

    <para>The syntax for an address is:</para>

<programlisting><![CDATA[
address ::=  <name> [ / <subject> ] [ ; <options> ]
options ::=  { <key> : <value>, ... }
]]></programlisting>

    <para>Names, subjects, and keys are strings.</para>

    <para>Values can be numbers, strings (with optional single or double quotes), maps, or lists.</para>

    <para>In most cases, queues, bindings, and exchanges are
    configured externally with management tools. Qpid High Level API
    clients send to and receive from these queues and exchanges.</para>

    <para>In AMQP 0-10, messages are sent to exchanges, and received
    from queues. The Qpid High Level Client API allows programs to
    send to or receive from any node. To make this possible, the
    mapping defines the semantics of sending and receiving for all
    AMQP 0-10 exchange types and queues as follows:

    <itemizedlist>
      <listitem><para>When a Sender sends a message to an exchange,
      the transfer destination is set to the exchange name, and the
      routing key is set to the value of the address
      subject.</para></listitem>
      <listitem><para>When a Receiver receives messages from an
      exchange, the API automatically creates a subscription queue and
      binds it to the exchange. If the address contains a subject,
      then it is used as the binding key. If the address does not
      contain a subject, then the binding key depends on the exchange
      type:
      <itemizedlist>
	<listitem><para>topic exchange: wildcard match</para></listitem>
	<listitem><para>direct exchange: error &mdash; the address must specify a subject</para></listitem>
	<listitem><para>fanout: none</para></listitem>
	</itemizedlist></para>
	<para>The subscription queue's <varname>durability</varname>
	and <varname>autodelete</varname> properties can be set
	using options.</para>
      </listitem>
      <listitem><para>When a Sender sends a message to a queue, the
      message is sent to the AQMP 0-10 default queue, using the name
      of the queue as the routing key.</para></listitem>
      <listitem><para>When a Receiver receives messages from a queue,
      it is treated as a normal AMQP 0-10 queue subscription. The
      <varname>accept-mode</varname> property can be set using
      options.</para></listitem>
    </itemizedlist>
    </para>

    <para>The following sections describe the various kinds of
    addresses in detail. The examples in these sections use the
    <command>qpid-config</command> utility to configure AMQP 0-10
    queues and exchanges, send messages using
    <command>drain</command>, and receive messages using
    <command>spout</command>. The source code for
    <command>drain</command> and <command>spout</command> is available
    in both C++ and Python, and can be found in the examples directory
    for each language. These programs can use any address as a source
    or a destination, and have many command line options to configure
    behavior&mdash;use the <command>-h</command> option for
    documentation on these options.</para>


    <section>
      <title>Simple Addresses</title>

    <para>If an address contains only a name, it resolves to a named
    node. On AMQP 0-10, a named node maps to a queue or an exchange with
    the same name.
    <note>
      <para>Address resolution is not yet well-defined if a queue and
      an exchange have the same name. This is a known problem, and is
      being resolved.</para>
    </note></para>

    <example>
      <title>Simple Addresses</title>

      <para>Create a queue with qpid-config, send a message using
      spout, and read it using drain:</para>

      <screen>
$ qpid-config add queue hello-world
$ ./spout -a hello-world
$ ./drain -a hello-world

Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='')
      </screen>

      <para>Exchanges and queues are addressed in exactly the same way
      in the Qpid High Level Client API. If we delete the queue named
      <literal>hello-world</literal> and create an exchange with the
      same name, we can write to and read from the exchange in the
      same way as for the queue:</para>

      <screen>
$ qpid-config del queue hello-world
$ qpid-config add exchange topic hello-world
$ ./spout -a hello-world
$ ./drain -a hello-world
$
      </screen>

      <para>However, in AMQP 0-10, exchanges discard messages if no
      queue is bound to the exchange, unlike queues, which store
      messages until they are retrieved.  Because of this, no messages
      were output in the above screen. If <command>drain</command> is
      called before <command>spout</command>, a Receiver is created
      for the exchange, which also creates a subscription queue and a
      binding. Run <command>drain</command> in one terminal window
      using <literal>-t</literal> to specify a timeout in seconds, and
      run <command>spout</command> in another window to send a message
      for <command>drain</command> to receive.</para>

      
      
      <para><emphasis>First Window:</emphasis></para>

      <screen>
$ ./drain -a hello-word -t 30
      </screen>
      

      <para><emphasis>Second Window:</emphasis></para>

      <screen>
$ ./spout -a hello-word
      </screen>

      <para>Once <command>spout</command> has sent a message, return
      to the first window to see the output from
      <command>drain</command>:</para>

      <screen>
Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='')
      </screen>

      <para>You can run <command>drain</command> in several separate
      windows; each will create a subscription for the exchange, and
      each will receive all messages sent to the exchange.</para>

    </example>
    </section>
    
    <section>
      <title>Subjects</title>
      <para>Subjects are used to classify messages.</para>

      <para>A Sender's subject is assigned to each message that it
      sends (this can be overridden by specifying a subject directly
      on the message). In the AMQP 0-10 mapping, the message's subject
      is used as the routing key for all messages sent to the
      messaging broker. If a Sender is bound to an AMQP 0-10 exchange,
      it sends messages to that exchange. If a Sender is bound to an
      AMQP 0-10 queue, the message is sent to the default
      exchange.</para>

      <para>A Receiver's subject is used to filter messages; only
      messages with a subject that matches the Receiver's subject will
      be received. If a Receiver's name resolves to an AMQP 0-10
      exchange, the subject is used as a binding key for the
      corresponding AMQP 0-10 exchange type.
      </para>

      <note>
	<para>The C++ implementation of the Qpid messaging broker does
	not currently support selectors, so a Receiver's subject does
	not filter messages if the Receiver's address resolves to a
	queue.</para>
      </note>

      <section>
	  <title>Direct Exchanges</title>

	  <para>In an AMQP 0-10 direct exchange, messages are routed
	  to queues if the routing key exactly matches the binding
	  key. In the High Level Client API, if a Sender and a
	  Receiver are bound to the same exchange, the Receiver will
	  receive messages if the Sender's subject matches the
	  Receiver's subject.</para>

	  <para>Let's create a direct exchange and listen for messages
	  whose subject is <literal>sports</literal>:</para>

	  <para><emphasis>First Window:</emphasis></para>
	  <screen>
$ qpid-config add exchange direct direct-exchange
$ ./drain -a direct-exchange/sports -t 30
	  </screen>

	  <para>In a second window, let's send messages to the
	  exchange we created:</para>

	  <para><emphasis>Second Window:</emphasis></para>
	  <screen>
$ ./spout -a direct-exchange/sports
$ ./spout -a direct-exchange/news
	  </screen>

	  <para>Now look at the first window, and you will see the
	  message with the subject <literal>sports</literal> has been
	  received, but not the message with the subject
	  <literal>news</literal>:</para>

	  <screen>
Message(properties={qpid.subject:sports, spout-id:9441674e-a157-4780-a78e-f7ccea998291:0}, content='')
	  </screen>

	  <para>If you run <command>drain</command> in multiple
	  windows using the same subject, all instances of
	  <command>drain</command> receive the messages for that
	  subject.</para>

      </section>
      <section>
	  <title>Topic Exchanges</title>

	  <para>An AMQP 0-10 topic exchange uses routing keys that
	  contain multiple words separated by a <quote>.</quote>
	  delimiter. For instance, in a news application, a Sender's
	  subject might be <literal>usa.news</literal>,
	  <literal>usa.weather</literal>,
	  <literal>europe.news</literal>, or
	  <literal>europe.weather</literal>. A Receiver's subject can
	  include wildcard characters&mdash; <quote>#</quote> matches
	  one or more words in the message's subject, <quote>*</quote>
	  matches a single word. For instance, if the Receiver's
	  subject is <literal>*.news</literal>, it matches messages
	  with the subject <literal>europe.news</literal> or
	  <literal>usa.news</literal>; if the Receiver's subject is
	  <literal>europe.#</literal>, it matches messages with
	  subjects like <literal>europe.news</literal> or
	  <literal>europe.pseudo.news</literal>.</para>

	  <para>Let's create a topic exchange and listen for messages
	  whose subject is <literal>news</literal>:</para>

	  <para><emphasis>First Window:</emphasis></para>

	  <screen>
$ qpid-config add exchange topic topic-exchange
$ ./drain -a topic-exchange/news -t 30
          </screen>

	  <para>In a second window, let's send messages to the
	  exchange we created:</para>

	  <para><emphasis>Second Window:</emphasis></para>
	  <screen>
$ ./spout -a topic-exchange/news
$ ./spout -a topic-exchange/sports
	  </screen>


	  <para>Now look at the first window, and you will see the
	  message with the subject <literal>news</literal> has been
	  received, but not the message with the subject
	  <literal>sports</literal>:</para>

	  <screen>
Message(properties={qpid.subject:news, spout-id:bafefb74-c5be-4a8b-9e4b-45f7a855e250:0}, content='')
	  </screen>


	  <para>Now let's use the topic exchange with wildcards in the
	  Receiver and multi-word keys in the Sender. This time, let's
	  use two-word keys. The Receiver uses the subject
	  <literal>*.news</literal> to listen for messages in which
	  the second word of the key is
	  <literal>news</literal>:</para>


	  <para><emphasis>First Window:</emphasis></para>

	  <screen>
$ ./drain -a topic-exchange/*.news -t 30
	  </screen>

	  <para>Now let's send messages using several different
	  two-word keys:</para>

	  <para><emphasis>Second Window:</emphasis></para>

	  <screen>
$ ./spout -a topic-exchange/usa.news
$ ./spout -a topic-exchange/usa.sports
$ ./spout -a topic-exchange/europe.sports
$ ./spout -a topic-exchange/europe.news
$ 
	  </screen>

	  <para>Now look at the first window, and you will see the
	  messages with <literal>news</literal> in the second word of
	  the key have been received:</para>

	  <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='')
	  </screen>

	  <para>Finally, let's use the <literal>#</literal> wildcard
	  in the Receiver to match any number of words in the key. The
	  Receiver uses the key <literal>#.news</literal> to listen
	  for messages in which the last word of the key is
	  <literal>news</literal>, no matter how many words are in the
	  key:</para>

	  <para><emphasis>First Window:</emphasis></para>

	  <screen>
$ ./drain -a topic-exchange/#.news -t 30
	  </screen>

	  <para>Now let's send messages using a variety of different
	  multi-word keys:</para>

	  <para><emphasis>Second Window:</emphasis></para>

	  <screen>
$ ./spout -a topic-exchange/news
$ ./spout -a topic-exchange/sports
$ ./spout -a topic-exchange/usa.news
$ ./spout -a topic-exchange/usa.sports
$ ./spout -a topic-exchange/usa.faux.news
$ ./spout -a topic-exchange/usa.faux.sports
	  </screen>

	  <para>Now look at the first window, and you will see the
	  messages with <literal>news</literal> in the last word of
	  the key have been received:</para>

	  <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='')
	  </screen>

	</section>

	<section>
	  <title>Fanout Exchanges</title>

	  <para>A fanout exchange ignores the subject, and no
	  filtering is done.</para>

	  <para>Let's create a fanout exchange and listen for
	  messages.  We will use the subject <literal>news</literal>
	  in the Receiver to demonstrate that this subject is not
	  actually used to filter messages:</para>


	  <para><emphasis>First Window:</emphasis></para>

	  <screen>
$ qpid-config add exchange fanout fanout-exchange
$ ./drain -a fanout-exchange/news -t 30
	  </screen>

	  <para>Now let's send a message using a different
	  subject:</para>

	  <para><emphasis>Second Window:</emphasis></para>

	  <screen>
$ ./spout -a fanout-exchange/sports
	  </screen>

	  <para>Returning to the first window, we see that the message
	  was received even though the Receiver's subject was
	  different from the Sender's subject:</para>

	  <screen>
Message(properties={qpid.subject:sports, spout-id:931399a1-27fc-471c-8dbe-3048260f9441:0}, content='')
	  </screen>

	  <para>This happens because of the routing semantics of the AMQP 0-10 fanout exchange.</para>

	</section>

	</section>
	<section>
	  <title>Queues</title>

	  <para>If a Sender is bound to a queue, its messages are sent
	  to the default exchange using the queue's name as the
	  routing key. If a Receiver is bound to a queue, it receives
	  messages from the queue.</para>

	  <para>Let's create a queue and listen for messages on it.</para>

	  <para><emphasis>First Window:</emphasis></para>

	  <screen>
$ ./qpid-config add queue amqp010-queue
$ ./drain -a amqp010-queue -t 30
	  </screen>

	  <para>Now let's send some messages. The subject is not used for routing purposes.</para>
	  <screen>
$ ./spout -a amqp010-queue/news
$ ./spout -a amqp010-queue
	  </screen>

	  <para>Now look at the first window, and you will see that
	  both messages have been received:</para>

	  <screen>
Message(properties={qpid.subject:news, spout-id:6c769437-60be-4bc0-9bf6-5a77cb6ba65f:0}, content='')
Message(properties={spout-id:c8ab5013-a19e-4f54-967c-797c8ad6568b:0}, content='')
	  </screen>

	</section>


	<!-- ### match exchange? -->

	<section>
	  <title>Custom Exchanges</title>
	
	  <para>AMQP 0-10 also supports custom exchanges. The
	  Qpid messaging broker includes the XML Exchange, which uses an
	  XQuery to filter messages based on message properties and XML
	  message content.</para>

<!-- ### Do drain / spout support the XML Exchange? -->

	</section>

    </section>


    <section>
      <title>Extended Address Options</title>
<!-- #### Not a good name. The options don't configure the address. 

Not sure how best to fix this. One possibility is to change the names of the non-terminals.

Instead of:

address ::= <name> [ / <subject> ] [ ; <options> ]
options ::=  { <key> : <value>, ... }

We could use something along these lines:

configuration ::= <address> [ / <subject> ] [ ; <options> ]
options ::=  { <key> : <value>, ... }

We could then have tables showing the available options. Some of these would be client configuration options, others would specify broker host/port/connection, etc. 

-->


      <para>Extended Address Options are parameters that affect the behavior of Senders and Receivers.</para>

      <para>Some of these options specify aspects of the resolution process; for instance, they may make assertions that must be satisfied in order for resolution to succeed, or they may state that the node should be created if it does not already exist.</para>

      <para>Let's use <command>drain</command> and <command>spout</command> to show how this works. First, let's use the <literal>assert</literal> option to insist that an address must resolve to a queue.  In the High Level Client API, a node is either a queue or a topic. A queue is used the same way as in AMQP 0-10, but for consistency with Java JMS, a topic node is the same thing AMQP 0-10 calls an exchange.(In this section, we will use the term <quote>topic node</quote> for a High Level Client API topic node, and <quote>AMQP 0-10 topic exchange</quote> for the exchange type that has the same name.) </para>

      <para>AMQP 0-10 has several built-in exchanges that are predeclared: <literal>amq.topic</literal>, <literal>amq.direct</literal>, <literal>amq.match</literal>, and <literal>amq.fanout</literal>. To the High Level Exchange, any of these exchanges is considered a topic node. Let's use <command>drain</command>, and assert that  <literal>amq.fanout</literal> is a topic node:</para>

      <screen>$ ./drain -a "amq.fanout; { assert: always, node: { type: topic }}"</screen>

      <para>The address resolves succesfully. No exception is raised, because a topic node named <literal>amq.fanout</literal> exists. Now let's assert that <literal>amq.fanout</literal> is a queue node:</para>

      <screen>$ ./drain -a "amq.fanout; { assert: always, node: { type: queue }}"
2010-04-09 14:01:35 warning Exception received from broker: not-found: not-found: Queue not found: amq.fanout (qpid/broker/SessionAdapter.cpp:753) [caused by 0 \x08:\x01]
Queue amq.fanout does not exist</screen>

      <para>An exception was raised because there is no queue named <literal>amq.fanout</literal>, so address resolution failed.</para>


      <para>Now let's use the <literal>create</literal> option with <command>drain</command>, telling it to create the queue <literal>xoxox</literal> if it does not already exist:</para>

      <para><emphasis>First Window:</emphasis></para>
      <screen>$ ./drain -a "xoxox ; {create: always}" -t 30</screen>

      <para>In previous examples, we created the queue before listening for messages on it. Using <literal>create: always</literal>, the queue is automatically created if it does not exist. Now we can send messages to this queue:</para>

      <para><emphasis>Second Window:</emphasis></para>
      <screen>$ ./drain -a "xoxox ; {create: always}" -t 30</screen>

      <para>Returning to the first window, we see that <command>drain</command> has received this message:</para>

      <screen>Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='')</screen>

<!--
TODO: Add some x-declare, x-subscribe, link, x-bindings examples
-->


<!--
  In all the above cases, the address is resolved to an existing node.


  If you want the node to be auto-created, then you can do the
  following. By default nonexistent nodes are assumed to be queues::

    my-queue; {create: always}

  You can customize the properties of the queue::

    my-queue; {create: always, node: {durable: True}}

  You can create a topic instead if you want::

    my-queue; {create: always, node: {type: topic}}

  You can assert that the address resolves to a node with particular
  properties::

    my-transient-topic; {
      assert: always,
      node: {
        type: topic,
        durable: False
      }
    }


; {create: always}'
spout 'hello-whirled; {assert: always, node: {type: topic}}'
SH: spout 'small-world; {create: always, node: {type: topic}}'
SH: spout 'cruel-world; {create: always, node: {type: topic, x-declare: {type: direct}}}'
SH1: drain -f 'world-news; {create: always, node: {x-declare: {bindings: ["small-world/news.#", "hello-world/news.#", "cruel-world/news"]}}}'

SH: spout small-world/news.local
-->

      <para>Other options specify message transfer semantics; for instance, they may state whether messages should be consumed or read in browsing mode, or specify reliability characteristics. For instance, we can use browse mode to receive messages without removing them from the queue, thus allowing other Readers to receive them:</para>

      <screen>
$ ./drain 'hello-queue; {mode: browse}'
      </screen>

<!--
TODO: Add some reliability option examples
-->



      <table>
	<title>Extended Address Options</title>
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>option</entry>
	      <entry>parameters</entry>
	      <entry>semantics</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>
		assert
	      </entry>
	      <entry>
		node
	      </entry>
	      <entry>
		Asserts that the node properties are satisfied for a
		node. If they are not, node resolution fails and an
		exception is raised. <!-- ### Which exception -->
	      </entry>
	    </row>

	    <row>
	      <entry>
		create
	      </entry>
	      <entry>
		node (optional)
	      </entry>
	      <entry>
		Creates the node if it does not exist. No error is raised if the node does exist.
	      </entry>
	    </row>
	    <row>
	      <entry>
		delete
	      </entry>
	      <entry>
		N/A
	      </entry>
	      <entry>
		Delete the node when the Sender or Receiver is closed.
	      </entry>
	    </row>
	    <row>
	      <entry>
		reliability
	      </entry>
	      <entry>
		unreliable, at-least-once, at-most-once, exactly-once
	      </entry>
	      <entry>
	      </entry>
	    </row>
	    <row>
	      <entry>
		mode
	      </entry>
	      <entry>
		browse, consume
	      </entry>
	      <entry>
	      </entry>
	    </row>
	    <row>
	      <entry>
		reconnect
	      </entry>
	      <entry>
	        True, False
	      </entry>
	      <entry>
		Transparently reconnect if the connection is lost.
	      </entry>
	    </row>
	    <row>
	      <entry>
		reconnect_timeout
	      </entry>
	      <entry>
		N
	      </entry>
	      <entry>
		Total number of seconds to continue reconnection attempts before giving up and raising an exception.
	      </entry>
	    </row>
	    <row>
	      <entry>
		reconnect_limit
	      </entry>
	      <entry>
		N
	      </entry>
	      <entry>
		Maximum number of reconnection attempts before giving up and raising an exception.
	      </entry>
	    </row>
	    <row>
	      <entry>
		reconnect_interval_min
	      </entry>
	      <entry>
		N
	      </entry>
	      <entry>
		Minimum number of seconds between reconnection attempts. The first reconnection attempt is made immediately; if that fails, the first reconnection delay is set to the value of <literal>reconnect_interval_min</literal>; if that attempt fails, the reconnection interval increases exponentially until a reconnection attempt succeeds or <literal>reconnect_interval_max</literal> is reached.
	      </entry>
	    </row>
	    <row>
	      <entry>
		reconnect_interval_max
	      </entry>
	      <entry>
		N
	      </entry>
	      <entry>
		Maximum reconnection interval.
	      </entry>
	    </row>
	    <row>
	      <entry>
		reconnection_interval
	      </entry>
	      <entry>
		N
	      </entry>
	      <entry>
		Sets both <literal>reconnection_interval_min</literal> and <literal>reconnection_interval_max</literal> to the same value.
	      </entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>


      <table>
	<title>Node Properties</title>
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>property</entry>
	      <entry>parameters</entry>
	      <entry>semantics</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>
		type
	      </entry>
	      <entry>
		topic, queue
	      </entry>
	      <entry>
	      </entry>
	    </row>
	    <row>
	      <entry>
		durable
	      </entry>	       
	      <entry>
		True, False
	      </entry>
	      <entry>
	      </entry>
	    </row>
	    <row>
	      <entry>
		x-declare
	      </entry>
	      <entry>
		unrestricted map
	      </entry>
	      <entry>
                If the property is defined in the underlying protocol (AMQP 0-10), the values and semantics are defined by the protocol. Otherwise, values are added to the arguments map used to declare topics<footnote><para>The High Level Client API, like Java JMS, uses the term topic to refer to what AMQP 0-10 calls an exchange. One kind of AMQP 0-10 exchange is called a topic exchange, that is not what is meant here.</para></footnote> or queues.
	      </entry>
	    </row>
	  </tbody>
	</tgroup>
      </table>



     <table>
	<title>x-declare properties for AMQP 0-10</title>
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>property</entry>
	      <entry>parameters</entry>
	      <entry>semantics</entry>
	    </row>
	  </thead>
	  <tbody>
	    <row>
	      <entry>
		type
	      </entry>
	      <entry>
		direct, topic, fanout, header, xml
	      </entry>
	      <entry>
                The AMQP 0-10 exchange type. 		
	      </entry>
	    </row>
	    <row>
	      <entry>
		bindings
	      </entry>
	      <entry>
		["exchange/binding-key", ... ] 
	      </entry>
	      <entry>
		This property is used to create bindings for queues. If the Address does not resolve to a queue, an error is raised. 
	      </entry>
	    </row>
	  </tbody>
	</tgroup>
     </table>


  </section>


  <section>
    <title>Messaging Properties</title>

    <para>This section shows how Qpid High Level Client API message
    properties are mapped to AMQP message properties and delivery
    properties.</para>

    <para>Request-response applications frequently use a reply-to property to tell a server where to send a response. The following code shows how a server extracts the reply-to property and uses it to set the address to respond to a client.</para>

    <programlisting>
            Message request = receiver.fetch();
            const Address&amp; address = request.getReplyTo(); <lineannotation>Get "reply-to" field from request ...</lineannotation>
            if (address) {
                Sender sender = session.createSender(address); <lineannotation>... and use it as the address to send response</lineannotation>
                std::string s = request.getContent();
                std::transform(s.begin(), s.end(), s.begin(), toupper);
                Message response(s);
                sender.send(response);
                std::cout &lt;&lt; "Processed request: "
                          &lt;&lt; request.getContent()
                          &lt;&lt; " -> "
                          &lt;&lt; response.getContent() &lt;&lt; std::endl;
                session.acknowledge();
    </programlisting>

    <para>In the following table, <varname>msg</varname> refers to the
    Message class defined in the High Level Client API,
    <varname>mp</varname> refers to an AMQP 0-10
    <varname>message-properties</varname> struct, and
    <varname>dp</varname> refers to an AMQP 0-10
    <varname>delivery-properties</varname> struct.</para>

     <table>
       <title>Mapping to AMQP 0-10 Message Properties</title>
       <tgroup cols="3">
	 <thead>
	   <row>
	     <entry>Python API</entry>
	     <entry>C++ API</entry>
	     <entry>AMQP 0-10 Property</entry>
	   </row>
	 </thead>
	 <tbody>
	   <row>
	     <entry>msg.id</entry><entry>msg.{get,set}MessageId()</entry><entry>mp.message_id</entry>
	   </row>
	   <row>
	     <entry>msg.to</entry><entry>- -</entry><entry>mp.application_headers["qpid.to"]</entry>
	   </row>
	   <row>
	     <entry>msg.subject</entry><entry>msg.{get,set}Subject()</entry><entry>mp.application_headers["qpid.subject"]</entry>
	   </row>
	   <row>
	     <entry>msg.user_id</entry><entry>msg.{get,set}UserId()</entry><entry>mp.user_id</entry>
	   </row>
	   <row>
	     <entry>msg.reply_to</entry><entry>msg.{get,set}ReplyTo()</entry><entry>mp.reply_to<footnote><para>The reply_to is converted from the protocol representation into an address.</para></footnote></entry>
	   </row>
	   <row>
	     <entry>msg.correlation_id</entry><entry>msg.{get,set}CorrelationId()</entry><entry>mp.correlation_id</entry>
	   </row>
	   <row>
	     <entry>msg.durable</entry><entry>msg.{get,set}Durable()</entry><entry>dp.delivery_mode == delivery_mode.persistent<footnote><para>Note that msg.durable is a boolean, not an enum.</para></footnote></entry>
	   </row>
	   <row>
	     <entry>msg.priority</entry><entry>msg.{get,set}Priority()</entry><entry>dp.priority</entry>
	   </row>
	   <row>
	     <entry>msg.ttl</entry><entry>msg.{get,set}Ttl()</entry><entry>dp.ttl</entry>
	   </row>
	   <row>
	     <entry>msg.redelivered</entry><entry>msg.isRedelivered()</entry><entry>dp.redelivered</entry>
	   </row>
	   <row><entry>msg.properties</entry><entry>msg.{get,set}Headers()</entry><entry>mp.application_headers</entry>
	   </row>
	   <row>
	     <entry>msg.content_type</entry><entry>msg.{get,set}ContentType()</entry><entry>mp.content_type</entry>
	   </row>
	 </tbody>
       </tgroup>
     </table>

<!--
Examples - do client / server, pub-sub here...
-->

  </section>
</chapter>

<!--
     - client code remains exactly the same, but routing behavior
       changes
     - exchanges drop messages if nobody is listening, so we need to
       start drain first
     - drain will exit immediately if the source is empty (note that
       this is actually a semantic guarantee provided by the API, we
       know for a fact that the source is empty when drain/fetch
       reports it, no fudge factor timeout is required [this assumes
       nobody is concurrently publishing of course])
     - drain -f invokes blocking fetch (you could use a timeout here also)

SH: spout -c 10 hello-queue
SH: drain 'hello-queue; {mode: browse}'
SH: drain 'hello-queue; {mode: browse}'
SH: drain 'hello-queue; {mode: consume}'
SH: drain 'hello-queue; {mode: consume}'
     - durable: True/False (currently only for receivers from topics/exchanges)
SH: # durable demo???
     - no-local: True/False (only for receivers from topics/exchanges)
SH: #- filter: XXX
-->
<!--
SH: #spout 'hello-whirled; {assert: always, node: {type: topic}}'
SH: spout 'small-world; {create: always, node: {type: topic}}'
SH: qpid-config exchanges
SH: spout 'cruel-world; {create: always, node: {type: topic, x-declare: {type: direct}}}'
SH: qpid-config exchanges
SH1: drain -f 'world-news; {create: always, node: {x-declare: {bindings: ["small-world/news.#", "hello-world/news.#", "cruel-world/news"]}}}'
-->