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

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>

<!--
   
   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.
   
  -->

<chapter id="client-api-tutorial">
  <title>Using Qpid for Messaging</title>

  <section>
    <title>Supported APIs</title>
    
    <para>Apache Qpid is a reliable, asynchronous messaging system that
      supports the AMQP messaging protocol in several common programming
      languages.   
    </para>

    <itemizedlist>
      <listitem>
        <para>
          On the Java platform, Qpid uses the
          established <ulink url="http://java.sun.com/products/jms/">Java JMS
            API</ulink>. 
        </para>
      </listitem>
      <listitem>
        <para>
          On the .NET platform, Qpid defines
          a <ulink url="http://qpid.apache.org/wcf.html">WCF
            binding</ulink>.
        </para>
      </listitem>
      <listitem>
        <para>
          For Python and C++, Qpid defines its own
          messaging API which is conceptually similar in each supported
          language.
        </para>
      </listitem>
      <listitem>
        <para>
          Support for this API in Ruby will be added
          soon<footnote><para>Ruby currently uses an API that is closely tied
              to the AMQP version.</para></footnote>.
        </para>
      </listitem>
    </itemizedlist>
  </section>
   
  <section>
    <title>Using the Qpid messaging API</title>

    <para>The Qpid messaging API is quite simple, consisting of only a
      handful of core classes.
    </para>

    <itemizedlist>

      <listitem>
        <para>
          A <firstterm>message</firstterm> consists of a standard set
          of fields (e.g. <literal>subject</literal>,
          <literal>reply-to</literal>), an application-defined set of
          properties, and message content (the main body of the
          message).
        </para>
      </listitem>
      
      <listitem>
        <para>
          A <firstterm>connection</firstterm> represents a network
          connection to a remote endpoint.
        </para>
      </listitem>
      
      <listitem>
        <para>
          A <firstterm>session</firstterm> provides a sequentially
          ordered context for sending and receiving
          <emphasis>messages</emphasis>. A session is obtained from a
          connection.
        </para>
      </listitem>
      
      <listitem>
        <para>
	  A <firstterm>sender</firstterm> sends messages to a target
	  using the <literal>sender.send</literal> method. A sender is
	  obtained from a session for a given target address.
        </para>
      </listitem>
      
      <listitem>
        <para>
	  A <firstterm>receiver</firstterm> receives messages from a
	  source using the <literal>receiver.fetch</literal> method.
	  A receiver is obtained from a session for a given source
	  address.
        </para>
      </listitem>
      
    </itemizedlist>

    <para>
      The following sections show how to use these classes in a
      simple messaging program.
    </para>

    <section>
      <title>A Simple Messaging Program in C++</title>

      <para>The following C++ program shows how to create a connection,
        create a session, send messages using a sender, and receive
        messages using a receiver.</para>

	<example>
	  <title>"Hello world!" in C++</title>
	  <programlisting lang="c++"><![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(int argc, char** argv) {
    std::string broker = argc > 1 ? argv[1] : "localhost:5672";
    std::string address = argc > 2 ? argv[2] : "amq.topic";
    Connection connection(broker);
    try {
        connection.open();
        Session session = connection.createSession();

        Receiver receiver = session.createReceiver(address);
        Sender sender = session.createSender(address);

        sender.send(Message("Hello world!"));

        Message message = receiver.fetch(Duration::SECOND * 1);
        std::cout << message.getContent() << std::endl;
        session.acknowledge();
        
        connection.close();
        return 0;
    } catch(const std::exception& error) {
        std::cerr << error.what() << std::endl;
        connection.close();
        return 1;   
    }
}]]></programlisting>
      </example>


    </section>

    <section>
      <title>A Simple Messaging Program in Python</title>

      <para>The following Python program shows how to create a
        connection, create a session, send messages using a sender, and
        receive messages using a receiver.</para>

	<example>
	  <title>"Hello world!" in Python</title>
	  <programlisting lang="python"><![CDATA[
import sys
from qpid.messaging import *

broker =  "localhost:5672" if len(sys.argv)<2 else sys.argv[1]
address = "amq.topic" if len(sys.argv)<3 else sys.argv[2]

connection = Connection(broker)

try:
  connection.open()
  session = connection.session()

  sender = session.sender(address)
  receiver = session.receiver(address)

  sender.send(Message("Hello world!"));

  message = receiver.fetch(timeout=1)
  print message.content
  session.acknowledge() # acknowledge message receipt

except MessagingError,m:
  print m
finally:
  connection.close()
]]></programlisting>
	</example>

    </section>
    <section>
      <title>Addresses</title>
      
      <para>An <firstterm>address</firstterm> is the name of a message
      target or message source. In the programs we have just seen, we
      used the address <literal>amq.topic</literal> (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.
      </para>

      <para>An address resolves to a <firstterm>node</firstterm>. The
      Qpid messaging API recognises two kinds of nodes,
      <firstterm>queues</firstterm> and <firstterm>topics</firstterm>.

	   <footnote><para>The terms <emphasis>queue</emphasis> and
	   <emphasis>topic</emphasis> 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 <emphasis>topic exchange</emphasis>. When the term
	   <emphasis>topic</emphasis> occurs alone, it refers to a
	   messaging API topic, not the topic
	   exchange.</para></footnote>.

      A queue stores each message until it has been received and
      acknowledged, and only one receiver can receive a given message
      <footnote><para>There are exceptions to this rule; for instance,
      a receiver can use <literal>browse</literal> mode, which leaves
      messages on the queue for other receivers to
      read.</para></footnote>

      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,
      
          <footnote><para>The AMQP 0-10 implementation is the only one
          that currently exists.</para></footnote>

      queues map to AMQP queues, and topics map to AMQP exchanges.

          <footnote><para>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.</para></footnote>
      </para>

      <para>In the rest of this tutorial, we present many examples
      using two programs that take an address as a command line
      parameter.  <command>spout</command> sends messages to the
      target address, <command>drain</command> receives messages from
      the source address.  The source code is available in both C++
      and Python, 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&mdash;use the <command>-h</command> option
      for documentation on these options. 

      <footnote><para>Currently, the Python and C++
      implementations of <command>drain</command> and
      <command>spout</command> have slightly different
      options. This tutorial uses the C++ implementation. The
      options will be reconciled in the near
      future.</para></footnote>


      The examples in this tutorial also use the
      <command>qpid-config</command> utility to configure AMQP 0-10
      queues and exchanges on a Qpid broker.
      </para>


      <example>
        <title>Queues</title>

        <para>Create a queue with <command>qpid-config</command>, send a message using
          <command>spout</command>, and read it using <command>drain</command>:</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>The queue stored the message sent by <command>spout</command> and delivered
        it to <command>drain</command> when requested.</para>

	<para>Once the message has been delivered and and acknowledged
	by <command>drain</command>, it is no longer available on the queue. If we run
	<command>drain</command> one more time, no messages will be retrieved.</para>

        <screen>
$ ./drain -a hello-world
$
	</screen>

      </example>

      <example>
	<title>Topics</title>

	<para>This example is similar to the previous example, but it
	uses a topic instead of a queue.</para>

	<para>First, use <command>qpid-config</command> to remove the queue
	and create an exchange with the same name:</para>

        <screen>
$ qpid-config del queue hello-world
$ qpid-config add exchange topic hello-world
        </screen>

	<para>Now run <command>drain</command> and <command>spout</command> the same way we did in the previous example:</para>

	<screen>
$ ./spout -a hello-world
$ ./drain -a hello-world
$
        </screen>

        <para>Topics deliver messages immediately to any interested
        receiver, and do not store messages. Because there were no
        receivers at the time <command>spout</command> sent the
        message, it was simply discarded. When we ran
        <command>drain</command>, there were no messages to
        receive.</para>

	<para>Now let's run <command>drain</command> first, using the
	<literal>-t</literal> option to specify a timeout in seconds.
	While <command>drain</command> is waiting for messages,
	run <command>spout</command> in another window.</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>
	<title>Address Strings</title>

	<para>So far, our examples have used address strings that
	contain only the name of a node. An <firstterm>address
	string</firstterm> can also contain a
	<firstterm>subject</firstterm> and
	<firstterm>options</firstterm>.</para>
      
	<para>The syntax for an address string is:</para>
      
	<programlisting><![CDATA[
address_string ::=  <address> [ / <subject> ] [ ; <options> ]
options ::=  { <key> : <value>, ... }
]]></programlisting>
      
	<para>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
	<xref linkend="section-address-string-bnf"/>.</para>


	<para>So far, the address strings in this tutorial have used
	only addresses. The following sections show how to use
	subjects and options.</para>

      </section>

      <section>
	<title>Subjects</title>


	<para>Every message has a property called
	<firstterm>subject</firstterm>, 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&mdash;the matching
	algorithm depends on the message source.
      </para>

      <para>
	In AMQP 0-10, each exchange type has its own matching
	algorithm, and queues do not provide filtering. This is
	discussed in <xref linkend="section-amqp0-10-mapping"/>.
      </para>

      <note>
	<para>
	  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.
	</para>
      </note>


      <example>
        <title>Using subjects</title>

        <para>In this example we will show how subjects affect message
        flow.</para>

        <para>First, let's use <command>qpid-config</command> to create a topic exchange.</para>

        <screen>
$ qpid-config add exchange topic news-service
        </screen>

        <para>Now we will use drain to receive messages from <literal>news-service</literal> that match the subject <literal>sports</literal>.</para>
        <para><emphasis>First Window:</emphasis></para>
        <screen>
$ ./drain -a news-service/sports -t 30
        </screen>

        <para>In a second window, let's send messages to <literal>news-service</literal> using two different subjects:</para>

        <para><emphasis>Second Window:</emphasis></para>
        <screen>
$ ./spout -a news-service/sports
$ ./spout -a news-service/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>
      </example>
        

        <para>The AMQP exchange type we are using here,
        <literal>amq.topic</literal>, can also do more sophisticated
        matching.

	A sender's subject can contain multiple words separated by a
	<quote>.</quote> delimiter. For instance, in a news
	application, the sender might use subjects like
	<literal>usa.news</literal>, <literal>usa.weather</literal>,
	<literal>europe.news</literal>, or
	<literal>europe.weather</literal>. 

	The 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 subject in the source address is
	<literal>*.news</literal>, it matches messages with the
	subject <literal>europe.news</literal> or
	<literal>usa.news</literal>; if it is
	<literal>europe.#</literal>, it matches messages with subjects
	like <literal>europe.news</literal> or
	<literal>europe.pseudo.news</literal>.</para>

	  <example>
	    <title>Subjects with multi-word keys</title>

	    <para>This example uses drain and spout to demonstrate the
	    use of subjects with two-word keys.</para>

	    <para>Let's use <command>drain</command> with 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 news-service/*.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 news-service/usa.news
$ ./spout -a news-service/usa.sports
$ ./spout -a news-service/europe.sports
$ ./spout -a news-service/europe.news
	    </screen>

	    <para>In the first window, 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>Next, let's use <command>drain</command> with the
	    subject <literal>#.news</literal> to match any sequence of
	    words that ends with <literal>news</literal>.</para>

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

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

	    <para>In the second window, let's send messages using a
	    variety of different multi-word keys:</para>

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

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

        <para>In the first window, 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>
      </example>

    </section>

    <section>
      <title>Address String Options</title>

      <para>
        The options in an address string contain additional
        information for the senders or receivers created for it,
        including:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            Policies for assertions about the node to which an address
            refers.
	  </para>
	  <para>
	    For instance, in the address string <literal>my-queue;
	    {assert: always, node:{ type: queue }}</literal>, the node
	    named <literal>my-queue</literal> must be a queue; if not,
	    the address does not resolve to a node, and an exception
	    is raised.
          </para>
        </listitem>
        <listitem>
          <para>
            Policies for automatically creating or deleting the node to which an address refers.
	  </para>
	  <para>
	    For instance, in the address string <literal>xoxox ; {create: always}</literal>, 
	    the queue <literal>xoxox</literal> is created, if it does
	    not exist, before the address is resolved.
          </para>
        </listitem>
        <listitem>
          <para>
            Extension points that can be used for sender/receiver configuration.
	  </para>
	  <para>
	    For instance, if the address for a receiver is
	    <literal>my-queue; {mode: browse}</literal>, the receiver
	    works in <literal>browse</literal> mode, leaving messages
	    on the queue so other receivers can receive them.
          </para>
        </listitem>
      </itemizedlist>


      <para>
        Let's use some examples to show how these different kinds of
        address string options affect the behavior of senders and
        receives.
      </para>
      
      
      <para>
	First, let's use the <literal>assert</literal> option to
	ensure that the address resolves to a node of the required
	type.
      </para>


      <example>
	<title>Assertions on Nodes</title>

	<para>Let's use <command>qpid-config</command> to create a
        queue and a topic.</para>

	<screen>
$ qpid-config add queue my-queue
$ qpid-config add exchange topic my-topic
	</screen>
      
	<para>
        We can now use the address specified to drain to assert that it is
        of a particular type:
	</para>

	<screen>
$ ./drain -a 'my-queue; {assert: always, node:{ type: queue }}'
$ ./drain -a '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
	</screen>

	<para>
        The first attempt passed without error as my-queue is indeed a
        queue. The second attempt however failed; my-queue is not a
        topic.
	</para>
      
	<para>
        We can do the same thing for my-topic:
	</para>

	<screen>
$ ./drain -a 'my-topic; {assert: always, node:{ type: topic }}'
$ ./drain -a '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
	</screen>
      </example>

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

      <example>
	<title>Creating a Queue Automatically</title>

	<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>$ ./spout -a "xoxox ; {create: always}"</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>
      </example>

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

      <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. The following example uses the
      <literal>browse</literal> option to receive messages without
      removing them from a queue.</para>

      <example>
        <title>Browsing a Queue</title>
        <para>
          Let's use the browse mode to receive messages without
          removing them from the queue. First we send three messages to the
          queue:
        </para>
        <screen>
$ ./spout -a my-queue --content one
$ ./spout -a my-queue --content two
$ ./spout -a my-queue --content three
        </screen>
        
        <para>Now we use drain to get those messages, using the browse option:</para>
        <screen>
$ ./drain -a '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')
        </screen>
        
        <para>We can confirm the messages are still on the queue by repeating the drain:</para>
        <screen>
$ ./drain -a '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')
        </screen>
      </example>

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

      <table>
        <title>Address Options</title>
        <tgroup cols="3">
          <thead>
	    <row>
	      <entry>option</entry>
	      <entry>value</entry>
	      <entry>semantics</entry>
	    </row>
          </thead>
          <tbody>
	    <row>
	      <entry>
	        assert
	      </entry>
	      <entry>
	        one of: always, never, sender or receiver
	      </entry>
	      <entry>
	        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. <!-- ###
	                                                          Which exception -->
	      </entry>
	    </row>

	    <row>
	      <entry>
	        create
	      </entry>
	      <entry>
                one of: always, never, sender or receiver
	      </entry>
	      <entry>
	        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.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        delete
	      </entry>
	      <entry>
                one of: always, never, sender or receiver
	      </entry>
	      <entry>
	        Delete the node when the sender or receiver is closed.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        node
	      </entry>
	      <entry>
	        A nested map containing the entries shown in <xref linkend="table-node-properties"/>.
	      </entry>
	      <entry>
                Specifies properties of the node to which the address
                refers. These are used in conjunction with the assert or
                create options.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        link
	      </entry>
	      <entry>
	        A nested map containing the entries shown in <xref linkend="table-link-properties"/>.
	      </entry>
	      <entry>
                Used to control the establishment of a conceptual link
                from the client application to or from the target/source
                address.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        mode
	      </entry>
	      <entry>
	        one of: browse, consume
	      </entry>
	      <entry>
                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.
	      </entry>
	    </row>
          </tbody>
        </tgroup>
      </table>


      <table id="table-node-properties">
        <title>Node Properties</title>
        <tgroup cols="3">
          <thead>
	    <row>
	      <entry>property</entry>
	      <entry>value</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>
                Indicates whether the node will survive a loss of
                volatile storage e.g. if the broker is restarted.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        x-declare
	      </entry>
	      <entry>
	        A nested map whose values correspond to the valid fields
	        on an AMQP 0-10 queue-declare or exchange-declare
	        command.
	      </entry>
	      <entry>
                These values are used to fine tune the creation or
                assertion process. Note however that they are protocol
                specific.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        x-bindings
	      </entry>
	      <entry>
	        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, using the following format:
<programlisting><![CDATA[
{
 exchange: <exchange>,
 queue: <queue>,
 key: <key>,
 arguments: <arguments>
}
]]></programlisting>

	      </entry>
	      <entry>
                In conjunction with the create option, each of these
	        bindings will be established as the address is
	        resolved. In conjunction with the assert option, the
	        existence of each of these bindings will be verified
	        during resolution. Again, these are protocol specific.
	      </entry>
	    </row>
          </tbody>
        </tgroup>
      </table>

      <table id="table-link-properties">
        <title>Link Properties</title>
        <tgroup cols="3">
          <thead>
	    <row>
	      <entry>option</entry>
	      <entry>value</entry>
	      <entry>semantics</entry>
	    </row>
          </thead>
          <tbody>
	    <row>
	      <entry>
	        reliability
	      </entry>
	      <entry>
	        one of: unreliable, at-least-once, at-most-once, exactly-once
	      </entry>
	      <entry>
	      </entry>
	    </row>
	    <row>
	      <entry>
	        durable
	      </entry>	       
	      <entry>
	        True, False
	      </entry>
	      <entry>
                Indicates whether the link will survive a loss of
                volatile storage e.g. if the broker is restarted.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        x-declare
	      </entry>
	      <entry>
	        A nested map whose values correspond to the valid fields
	        of an AMQP 0-10 queue-declare command.
	      </entry>
	      <entry>
                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.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        x-subscribe
	      </entry>
	      <entry>
	        A nested map whose values correspond to the valid fields
	        of an AMQP 0-10 message-subscribe command.
	      </entry>
	      <entry>
                These values can be used to customise the subscription.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        x-bindings
	      </entry>
	      <entry>
	        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.
	      </entry>
	      <entry>
                These bindings will be established during resolution
                independent of the create option. They are considered
                logically part of the linking process rather than of
                node creation.
	      </entry>
	    </row>
          </tbody>
        </tgroup>
      </table>

    </section>


  <section id="section-address-string-bnf">
    <title>Address String Grammar</title>

    <para>This section provides a formal grammar for address strings.</para>

    <formalpara>
      <title>Tokens</title>
      <para>The following regular expressions define the tokens used
      to parse address strings:</para></formalpara>
<programlisting><![CDATA[
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]+
]]></programlisting>

    <formalpara>
      <title>Grammar</title>
      <para>The formal grammar for addresses is given below:</para>
    </formalpara>

    <programlisting><![CDATA[
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 )* )? "]"
   ]]></programlisting>


    <para>The address string options map supports the following parameters:</para>


    <programlisting><![CDATA[
<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> ... }
  }
}
]]></programlisting>


    <itemizedlist>
      <title>Create, Delete, and Assert Policies</title>
      <para>The create, delete, and assert policies specify who should
      perfom the associated action:</para>
      <listitem><para><emphasis>always</emphasis>: the action will be performed by any messaging client</para></listitem>
      <listitem><para><emphasis>sender</emphasis>: the action will only be performed by a sender</para></listitem>
      <listitem><para><emphasis>receiver</emphasis>: the action will only be performed by a receiver</para></listitem>
      <listitem><para><emphasis>never: the action will never be performed (this is the default)</emphasis></para></listitem>
    </itemizedlist>

    <itemizedlist>
      <title>Node-Type</title>
      <para>The node-type is one of:</para>
       <listitem><para><emphasis>topic</emphasis>: in the AMQP 0-10
       mapping, a topic node defaults to the topic exchange, x-declare
       may be used to specify other exchange types</para></listitem>
       <listitem><para><emphasis>queue</emphasis>: this is the default node-type</para></listitem>
    </itemizedlist>
  </section>


</section>

    <section>
      <title>Reconnect and Failover</title>
      <para>Connections in the Qpid messaging API support automatic
      reconnection. The following table lists some of the connection
      properties that control this. See the reference documentation
      for details on how to set these on connections fro each
      langauge.</para>
      <table>
        <title>Connection properties</title>
        <tgroup cols="3">
          <thead>
	    <row>
	      <entry>property</entry>
	      <entry>value</entry>
	      <entry>semantics</entry>
	    </row>
          </thead>
          <tbody>
	    <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 reconnect 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 reconnect interval.
	      </entry>
	    </row>
	    <row>
	      <entry>
	        reconnect_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>
    </section>

  <section id="section-amqp0-10-mapping">
    <title>The AMQP 0-10 mapping</title>

    <para>
      This section describes the AMQP 0-10 mapping for the Qpid
      messaging API.
    </para>
    <para>
        The interaction with the broker triggered by creating a sender
        or receiver depends on what the specified address resolves
        to. Where the node type is not specified in the address, the
        client queries the broker to determine whether it refers to a
        queue or an exchange.
    </para>
    <para>
        When sending to a queue, the queue's name is set as the
        routing key and the message is transfered to the default (or
        nameless) exchange. When sending to an exchange, the message
        is transfered to that exchange and the routing key is set to
        the message subject if one is specified. A default subject may
        be specified in the target address. The subject may also be
        set on each message individually to override the default if
        required. In each case any specified subject is also added as
        a qpid.subject entry in the application-headers field of the
        message-properties.
      </para>
      <para>
        When receiving from a queue, any subject in the source address
        is currently ignored. The client sends a message-subscribe
        request for the queue in question. The accept-mode is
        determined by the reliability option in the link properties;
        for unreliable links the accept-mode is none, for reliable
        links it is explicit. The default for a queue is reliable. The
        acquire-mode is determined by the value of the mode option. If
        the mode is set to browse the acquire mode is not-acquired,
        otherwise it is set to pre-acquired. The exclusive and
        arguments fields in the message-subscribe command can be
        controlled using the x-subscribe map.
      </para>
      <para>
        When receiving from an exchange, the client creates a
        subscription queue and binds that to the exchange. The
        subscription queue's arguments can be specified using the
        x-declare map within the link properties. The reliability
        option determines most of the other parameters. If the
        reliability is set to unreliable then an auto-deleted,
        exclusive queue is used meaning that if the client or
        connection fails messages may be lost. For exactly-once the
        queue is not set to be auto-deleted. The durability of the
        subscription queue is determined by the durable option in the
        link properties. The binding process depends on the type of
        the exchange the source address resolves to.
      </para>

      <itemizedlist>
        <listitem>
          <para>
            For a topic exchange, if no subject is specified and no
            x-bindings are defined for the link, the subscription
            queue will by be bound using a wildcard matching any
            routing key (thus satisfying the expectation that any
            message sent to that address will be received from it). If
            a subject is specified in the source address however, it
            will be used for the binding key (this means that the
            subject in the source address may be a binding pattern
            incuding wildcards).
          </para>
        </listitem>
        <listitem>
          <para>
            For a fanout exchange the binding key is irrelevant to
            matching. A receiver created from a source address that
            resolves to a fanout exchange will receive all messages
            sent to that exchange regardless of any subject the source
            address may contain. An x-bindings element in the link
            properties should be used if there is any need to set the
            arguments to the bind.
          </para>
        </listitem>
        <listitem>
          <para>
            A source address that resolves to a direct exchange must
            either contain a subject or must include a value for the
            x-bindings option in the link properties. This is because
            there is no way to receive all messages sent to an
            exchange of that type. The subject specified will be used
            as the binding key (this means it must match the message
            subject exactly).
          </para>
        </listitem>
        <listitem>
          <para>
            For a headers exchange, if no subject is specified the
            binding arguments will simply contain an x-match entry an
            no other entries, causing all messages to match. If a
            subject is specified then the binding arguments will
            contain an x-match entry set to all and an entry for
            qpid.subject whose value is the subject in the source
            address (this means the subject in the source address must
            match the message subject exactly). For more control the
            x-bindings element in the link properties must be used.
          </para>
        </listitem>
        <listitem>
          <para>
            For the XML exchange,<footnote><para>Note that the XML
            exchange is not a standard AMQP exchange type. It is a
            Qpid extension and is currently only supported by the C++
            broker.</para></footnote> if a subject is specified it is
            used as the bidning key and an xquery is defined that will
            match any message with that value for qpid.subject. Again
            this means that only messages whose subject exactly match
            that specified in the source address will be received. For
            more control the x-bindings element in the link properties
            must be used. A source address that resolves to the XML
            exchange must contain either a subject or an x-bindings
            element in the link properties as there is no way at
            present to receive any message regardless of routing key.
          </para>
        </listitem>
      </itemizedlist>

      <para>
        If an x-bindings list is present in the link options a binding
        is created for each element within that list. Each element is
        a nested map that may contain values named queue, exchange,
        key or arguments. If the queue value is absent the queue name
        the address resolves to is implied. If the exchange value is
        absent the exchange name the address resolves to is implied.
      </para>

      <para>The following table shows how Qpid Messaging API message
        properties are mapped to AMQP 0-10 message properties and
        delivery properties. In this table <varname>msg</varname>
        refers to the Message class defined in the Qpid Messaging 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<footnote><para>In these entries, <literal>mp></literal> refers to an AMQP message property, and <literal>dp</literal> refers to an AMQP delivery property.</para></footnote></entry>
	    </row>
          </thead>
          <tbody>
	    <row>
	      <entry>msg.id</entry><entry>msg.{get,set}MessageId()</entry><entry>mp.message_id</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.{get,set}Redelivered()</entry><entry>dp.redelivered</entry>
	    </row>
	    <row><entry>msg.properties</entry><entry>msg.{get,set}Properties()</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>
      
    </section>
  </section>


  <section id="QpidJMS">
    <title>Using the Qpid JMS client</title>
    <section>
      <title>A Simple Messaging Program in Java JMS</title>
      
      <para>The following program shows how to use address strings and
        JNDI for Qpid programs that use Java JMS.</para>

      <para>This program uses a JNDI file that defines a connection
      factory for the broker we are using, and the address of the
      topic exchange node that we will bind the sender and receiver
      to. (The syntax of a ConnectionURL is given in <xref
      linkend="QpidJNDI"/>.)</para>

      <example>
	<title>JNDI Properties File for "Hello world!" example</title>
      <programlisting><![CDATA[
java.naming.factory.initial 
  = org.apache.qpid.jndi.PropertiesFileInitialContextFactory

# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.qpidConnectionfactory 
  = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'
# destination.[jndiname] = [address_string]
destination.topicExchange = amq.topic
]]></programlisting>
      </example>

      <para>In the Java JMS code, we use create a JNDI context, use the context to find a connection factory and create and start a connection, create a session, and create a destination that corresponds to the topic exchange. Then we create a sender and a receiver, send a message with the sender, and receive it with the receiver. This code should be straightforward for anyone familiar with Java JMS.</para>

      <example>
	<title>"Hello world!" in Java</title>
	<programlisting lang="java"><![CDATA[
package org.apache.qpid.example.jmsexample.hello;

import javax.jms.*;
import javax.naming.Context;
import javax.naming.InitialContext;
import java.util.Properties;

public class Hello {

  public Hello() {
  }

  public static void main(String[] args) {
    Hello producer = new Hello();
    producer.runTest();
  }

  private void runTest() {
    try {
      Properties properties = new Properties();
      properties.load(this.getClass().getResourceAsStream("hello.properties"));
      Context context = new InitialContext(properties);

      ConnectionFactory connectionFactory 
                    = (ConnectionFactory) context.lookup("qpidConnectionfactory");
      Connection connection = connectionFactory.createConnection();
      connection.start();

      Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE);
      Destination destination = (Destination) context.lookup("topicExchange");

      MessageProducer messageProducer = session.createProducer(destination);
      MessageConsumer messageConsumer = session.createConsumer(destination);

      TextMessage message = session.createTextMessage("Hello world!");
      messageProducer.send(message);

      message = (TextMessage)messageConsumer.receive();
      System.out.println(message.getText());

      connection.close();
      context.close();
    }
    catch (Exception exp) {
      exp.printStackTrace();
    }
  }
}
]]></programlisting>
      </example>

    </section>

    <section id="QpidJNDI">
      <title>Apache Qpid JNDI Properties for AMQP Messaging</title>


      <para>
	Apache Qpid defines JNDI properties that can be used to
	specify the parameters for a connection. Here is a typical
	JNDI properties file:
      </para>

      <example>
	<title>JNDI Properties File</title>
    <programlisting><![CDATA[
java.naming.factory.initial 
  = org.apache.qpid.jndi.PropertiesFileInitialContextFactory

# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.qpidConnectionfactory 
  = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'
# destination.[jndiname] = [address_string]
destination.topicExchange = amq.topic
]]></programlisting>
      </example>

      <para>The following sections describe the JNDI properties that Qpid uses.</para>

      
      <section>
        <title>JNDI Properties for Apache Qpid</title>
        <para>
	  Apache Qpid supports the properties shown in the following table:
        </para>
        <table>
	  <title>JNDI Properties supported by Apache Qpid</title>
	  <tgroup cols="2">
	    <thead>
	      <row>
	        <entry>
		  Property
	        </entry>
	        <entry>
		  Purpose
	        </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
	        <entry>
		  connectionfactory.&lt;jndiname&gt;
	        </entry>
	        <entry>
		  <para>
		    The Connection URL that the connection factory will use to perform connections.
		  </para>
	        </entry>
	      </row>
	      <row>
	        <entry>
		  queue.&lt;jndiname&gt;
	        </entry>
	        <entry>
		  <para>
		    A JMS queue, which is implemented as an amq.direct exchange in Apache Qpid.
		  </para>
	        </entry>
	      </row>
	      <row>
	        <entry>
		  topic.&lt;jndiname&gt;
	        </entry>
	        <entry>
		  <para>
		    A JMS topic, which is implemented as an amq.topic exchange in Apache Qpid.
		  </para>
	        </entry>
	      </row>
	      <row>
	        <entry>
		  destination.&lt;jndiname&gt;
	        </entry>
	        <entry>
		  <para>
		    Can be used for defining all amq destinations,
		    queues, topics and header matching, using an
		    address string.  

		    <footnote><para>Binding URLs, which were used in
		    earlier versions of the Qpid Java JMS client, can
		    still be used instead of address
		    strings.</para></footnote>
		  </para>
	        </entry>
	      </row>
	    </tbody>
	  </tgroup>
        </table>
      </section>
      
      <section>
        <title>Connection URLs</title>
        <para>
	  In JNDI properties, a Connection URL specifies properties for a connection. The format for a Connection URL is:
        </para>
        
        <programlisting>amqp://[&lt;user&gt;:&lt;pass&gt;@][&lt;clientid&gt;]&lt;virtualhost&gt;[?&lt;option&gt;=&#39;&lt;value&gt;&#39;[&amp;&lt;option&gt;=&#39;&lt;value&gt;&#39;]]
        </programlisting>
        <para>
	  For instance, the following Connection URL specifies a user name, a password, a client ID, a virtual host ("test"), a broker list with a single broker, and a TCP host with the host name <quote>localhost</quote> using port 5672:
        </para>
        
        <programlisting>amqp://username:password@clientid/test?brokerlist=&#39;tcp://localhost:5672&#39;
        </programlisting>
        <para>
	  Apache Qpid supports the following properties in Connection URLs:
        </para>
        <table>
	  <title>Connection URL Properties</title>
	  <tgroup cols="3">
	    <thead>
	      <row>
	        <entry>
		  Option
	        </entry>
	        <entry>
		  Type
	        </entry>
	        <entry>
		  Description
	        </entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
	        <entry>
		  brokerlist
	        </entry>
	        <entry>
		  see below
	        </entry>
	        <entry>
		  The broker to use for this connection. In the current release, precisely one broker must be specified.
	        </entry>
	      </row>
	      <row>
	        <entry>
		  maxprefetch
	        </entry>
	        <entry>
		  --
	        </entry>
	        <entry>
		  The maximum number of pre-fetched messages per destination.
	        </entry>
	      </row>
	      <row>
	        <entry>
		  sync_persistence
	        </entry>
	        <entry>
		  false
	        </entry>
	        <entry>
		  When true, a sync command is sent after every persistent message to guarantee that it has been received.
	        </entry>
	      </row>
	    </tbody>
	  </tgroup>
        </table>
        <para>
	  Broker lists are specified using a URL in this format:
        </para>
        
        <programlisting>brokerlist=&lt;transport&gt;://&lt;host&gt;[:&lt;port&gt;]
        </programlisting>
        <para>
	  For instance, this is a typical broker list:
        </para>
        
        <programlisting>brokerlist=&#39;tcp://localhost:5672&#39;
        </programlisting>
      </section>
    </section>    
  </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)
  -->