Google Git
Sign in
apache / qpid-site / 4461686423fa437279655313089bde1fa1a60dbe / . / content / releases / qpid-jms-amqp-0-x-6.3.1 / jms-amqp-0-10-book / JMS-Client-0-10-Configuring-Addresses.html
blob: 7f6883773b4e4993714b29945710caea8756e72e [file] [log] [blame]
<!DOCTYPE html>
<!--
-
- 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.
-
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<title>2.4.&#160;Addresses - Apache Qpid&#8482;</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
<link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
<script type="text/javascript">var _deferredFunctions = [];</script>
<script type="text/javascript" src="/deferred.js" defer="defer"></script>
<!--[if lte IE 8]>
<link rel="stylesheet" href="/ie.css" type="text/css"/>
<script type="text/javascript" src="/html5shiv.js"></script>
<![endif]-->
<!-- Redirects for `go get` and godoc.org -->
<meta name="go-import"
content="qpid.apache.org git https://git-wip-us.apache.org/repos/asf/qpid-proton.git"/>
<meta name="go-source"
content="qpid.apache.org
https://github.com/apache/qpid-proton/blob/go1/README.md
https://github.com/apache/qpid-proton/tree/go1{/dir}
https://github.com/apache/qpid-proton/blob/go1{/dir}/{file}#L{line}"/>
</head>
<body>
<div id="-content">
<div id="-top" class="panel">
<a id="-menu-link"><img width="16" height="16" src="" alt="Menu"/></a>
<a id="-search-link"><img width="22" height="16" src="" alt="Search"/></a>
<ul id="-global-navigation">
<li><a id="-logotype" href="/index.html">Apache Qpid<sup>&#8482;</sup></a></li>
<li><a href="/documentation.html">Documentation</a></li>
<li><a href="/download.html">Download</a></li>
<li><a href="/discussion.html">Discussion</a></li>
</ul>
</div>
<div id="-menu" class="panel" style="display: none;">
<div class="flex">
<section>
<h3>Project</h3>
<ul>
<li><a href="/overview.html">Overview</a></li>
<li><a href="/components/index.html">Components</a></li>
<li><a href="/releases/index.html">Releases</a></li>
</ul>
</section>
<section>
<h3>Messaging APIs</h3>
<ul>
<li><a href="/proton/index.html">Qpid Proton</a></li>
<li><a href="/components/jms/index.html">Qpid JMS</a></li>
<li><a href="/components/messaging-api/index.html">Qpid Messaging API</a></li>
</ul>
</section>
<section>
<h3>Servers and tools</h3>
<ul>
<li><a href="/components/broker-j/index.html">Broker-J</a></li>
<li><a href="/components/cpp-broker/index.html">C++ broker</a></li>
<li><a href="/components/dispatch-router/index.html">Dispatch router</a></li>
</ul>
</section>
<section>
<h3>Resources</h3>
<ul>
<li><a href="/dashboard.html">Dashboard</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/qpid/Index">Wiki</a></li>
<li><a href="/resources.html">More resources</a></li>
</ul>
</section>
</div>
</div>
<div id="-search" class="panel" style="display: none;">
<form action="http://www.google.com/search" method="get">
<input type="hidden" name="sitesearch" value="qpid.apache.org"/>
<input type="text" name="q" maxlength="255" autofocus="autofocus" tabindex="1"/>
<button type="submit">Search</button>
<a href="/search.html">More ways to search</a>
</form>
</div>
<div id="-middle" class="panel">
<ul id="-path-navigation"><li><a href="/index.html">Home</a></li><li><a href="/releases/index.html">Releases</a></li><li><a href="/releases/qpid-jms-amqp-0-x-6.3.1/index.html">Qpid JMS AMQP 0-x 6.3.1</a></li><li><a href="/releases/qpid-jms-amqp-0-x-6.3.1/jms-amqp-0-10-book/index.html">Apache Qpid JMS Client for AMQP 0-10</a></li><li>2.4.&#160;Addresses</li></ul>
<div id="-middle-content">
<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">2.4.&#160;Addresses</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-10-Configuring-JVM-Properties.html">Prev</a>&#160;</td><th align="center" width="60%">Chapter&#160;2.&#160;Configuring the Client</th><td align="right" width="20%">&#160;<a accesskey="n" href="JMS-Client-0-10-Configuring-Logging.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="JMS-Client-0-10-Configuring-Addresses"></a>2.4.&#160;Addresses</h2></div></div></div><p>An <em class="firstterm">address</em> is the name of a message
target or message source.
<a class="footnote" href="#ftn.d0e1273" id="d0e1273"><sup class="footnote">[1]</sup></a>
The methods that create senders and receivers require an
address. The details of sending to a particular target or
receiving from a particular source are then handled by the
sender or receiver. A different target or source can be used
simply by using a different address.
</p><p>An address resolves to a <em class="firstterm">node</em>. The
Qpid Messaging API recognises two kinds of nodes,
<em class="firstterm">queues</em> and <em class="firstterm">topics</em>
<a class="footnote" href="#ftn.d0e1291" id="d0e1291"><sup class="footnote">[2]</sup></a>.
A queue stores each message until it has been received and
acknowledged, and only one receiver can receive a given message
<a class="footnote" href="#ftn.d0e1307" id="d0e1307"><sup class="footnote">[3]</sup></a>.
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,
<a class="footnote" href="#ftn.d0e1314" id="d0e1314"><sup class="footnote">[4]</sup></a>
queues map to AMQP queues, and topics map to AMQP exchanges.
<a class="footnote" href="#ftn.d0e1318" id="d0e1318"><sup class="footnote">[5]</sup></a>
</p><p>In the rest of this tutorial, we present many examples
using two programs that take an address as a command line
parameter. <span class="command"><strong>spout</strong></span> sends messages to the
target address, <span class="command"><strong>drain</strong></span> receives messages from
the source address. The source code is available in C++, Python, and
.NET C# and can be found in the examples directory for each
language. These programs can use any address string as a source
or a destination, and have many command line options to
configure behavior&#8212;use the <span class="command"><strong>-h</strong></span> option
for documentation on these options.
<a class="footnote" href="#ftn.d0e1333" id="d0e1333"><sup class="footnote">[6]</sup></a>
The examples in this tutorial also use the
<span class="command"><strong>qpid-config</strong></span> utility to configure AMQP 0-10
queues and exchanges on a Qpid broker.
</p><div class="example"><a id="d0e1346"></a><p class="title"><strong>Example&#160;2.3.&#160;Queues</strong></p><div class="example-contents"><p>Create a queue with <span class="command"><strong>qpid-config</strong></span>, send a message using
<span class="command"><strong>spout</strong></span>, and read it using <span class="command"><strong>drain</strong></span>:</p><pre class="screen">
$ qpid-config add queue hello-world
$ ./spout hello-world
$ ./drain hello-world
Message(properties={spout-id:c877e622-d57b-4df2-bf3e-6014c68da0ea:0}, content='')
</pre><p>The queue stored the message sent by <span class="command"><strong>spout</strong></span> and delivered
it to <span class="command"><strong>drain</strong></span> when requested.</p><p>Once the message has been delivered and and acknowledged
by <span class="command"><strong>drain</strong></span>, it is no longer available on the queue. If we run
<span class="command"><strong>drain</strong></span> one more time, no messages will be retrieved.</p><pre class="screen">
$ ./drain hello-world
$
</pre></div></div><br class="example-break" /><div class="example"><a id="d0e1380"></a><p class="title"><strong>Example&#160;2.4.&#160;Topics</strong></p><div class="example-contents"><p>This example is similar to the previous example, but it
uses a topic instead of a queue.</p><p>First, use <span class="command"><strong>qpid-config</strong></span> to remove the queue
and create an exchange with the same name:</p><pre class="screen">
$ qpid-config del queue hello-world
$ qpid-config add exchange topic hello-world
</pre><p>Now run <span class="command"><strong>drain</strong></span> and <span class="command"><strong>spout</strong></span> the same way we did in the previous example:</p><pre class="screen">
$ ./spout hello-world
$ ./drain hello-world
$
</pre><p>Topics deliver messages immediately to any interested
receiver, and do not store messages. Because there were no
receivers at the time <span class="command"><strong>spout</strong></span> sent the
message, it was simply discarded. When we ran
<span class="command"><strong>drain</strong></span>, there were no messages to
receive.</p><p>Now let's run <span class="command"><strong>drain</strong></span> first, using the
<code class="literal">-t</code> option to specify a timeout in seconds.
While <span class="command"><strong>drain</strong></span> is waiting for messages,
run <span class="command"><strong>spout</strong></span> in another window.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
$ ./drain -t 30 hello-word
</pre><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
$ ./spout hello-word
</pre><p>Once <span class="command"><strong>spout</strong></span> has sent a message, return
to the first window to see the output from
<span class="command"><strong>drain</strong></span>:</p><pre class="screen">
Message(properties={spout-id:7da2d27d-93e6-4803-8a61-536d87b8d93f:0}, content='')
</pre><p>You can run <span class="command"><strong>drain</strong></span> in several separate
windows; each creates a subscription for the exchange, and
each receives all messages sent to the exchange.</p></div></div><br class="example-break" /><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="d0e1449"></a>2.4.1.&#160;Address Strings</h3></div></div></div><p>So far, our examples have used address strings that
contain only the name of a node. An <em class="firstterm">address
string</em> can also contain a
<em class="firstterm">subject</em> and
<em class="firstterm">options</em>.</p><p>The syntax for an address string is:</p><pre class="programlisting">
address_string ::= &lt;address&gt; [ / &lt;subject&gt; ] [ ; &lt;options&gt; ]
options ::= { &lt;key&gt; : &lt;value&gt;, ... }
</pre><p>Addresses, subjects, and keys are strings. Values can
be numbers, strings (with optional single or double quotes),
maps, or lists. A complete BNF for address strings appears in
<a class="xref" href="JMS-Client-0-10-Configuring-Addresses.html#section-address-string-bnf" title="2.4.4.&#160;Address String Grammar">Section&#160;2.4.4, &#8220;Address String Grammar&#8221;</a>.</p><p>So far, the address strings in this tutorial have only
used simple names. The following sections show how to use
subjects and options.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="d0e1473"></a>2.4.2.&#160;Subjects</h3></div></div></div><p>Every message has a property called
<em class="firstterm">subject</em>, which is analogous to the
subject on an email message. If no subject is specified, the
message's subject is null. For convenience, address strings
also allow a subject. If a sender's address contains a
subject, it is used as the default subject for the messages
it sends.
</p><p>
</p><p>
If a receiver's address contains a subject, it is used to
select only messages that match the subject&#8212;the matching
algorithm depends on the message source. In AMQP 0-10, each exchange
type has its own matching algorithm.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Currently, a receiver bound to a queue ignores subjects,
receiving messages from the queue without filtering. Support
for subject filtering on queues will be implemented soon.
</p></div><div class="example"><a id="d0e1487"></a><p class="title"><strong>Example&#160;2.5.&#160;Using subjects</strong></p><div class="example-contents"><p>In this example we show how subjects affect message
flow.</p><p>First, let's use <span class="command"><strong>qpid-config</strong></span> to create a topic exchange.</p><pre class="screen">
$ qpid-config add exchange topic news-service
</pre><p>Now we use drain to receive messages from <code class="literal">news-service</code> that match the subject <code class="literal">sports</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
$ ./drain -t 30 news-service/sports
</pre><p>In a second window, let's send messages to <code class="literal">news-service</code> using two different subjects:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
$ ./spout news-service/sports
$ ./spout news-service/news
</pre><p>Now look at the first window, the message with the
subject <code class="literal">sports</code> has been received, but not
the message with the subject <code class="literal">news</code>:</p><pre class="screen">
Message(properties={qpid.subject:sports, spout-id:9441674e-a157-4780-a78e-f7ccea998291:0}, content='')
</pre><p>If you run <span class="command"><strong>drain</strong></span> in multiple
windows using the same subject, all instances of
<span class="command"><strong>drain</strong></span> receive the messages for that
subject.</p></div></div><br class="example-break" /><p>The AMQP exchange type we are using here,
<code class="literal">amq.topic</code>, can also do more sophisticated
matching.
A sender's subject can contain multiple words separated by a
<span class="quote">&#8220;<span class="quote">.</span>&#8221;</span> delimiter. For instance, in a news
application, the sender might use subjects like
<code class="literal">usa.news</code>, <code class="literal">usa.weather</code>,
<code class="literal">europe.news</code>, or
<code class="literal">europe.weather</code>.
The receiver's subject can include wildcard characters&#8212;
<span class="quote">&#8220;<span class="quote">#</span>&#8221;</span> matches one or more words in the message's
subject, <span class="quote">&#8220;<span class="quote">*</span>&#8221;</span> matches a single word.
For instance, if the subject in the source address is
<code class="literal">*.news</code>, it matches messages with the
subject <code class="literal">europe.news</code> or
<code class="literal">usa.news</code>; if it is
<code class="literal">europe.#</code>, it matches messages with subjects
like <code class="literal">europe.news</code> or
<code class="literal">europe.pseudo.news</code>.</p><div class="example"><a id="d0e1584"></a><p class="title"><strong>Example&#160;2.6.&#160;Subjects with multi-word keys</strong></p><div class="example-contents"><p>This example uses drain and spout to demonstrate the
use of subjects with two-word keys.</p><p>Let's use <span class="command"><strong>drain</strong></span> with the subject
<code class="literal">*.news</code> to listen for messages in which
the second word of the key is
<code class="literal">news</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
$ ./drain -t 30 news-service/*.news
</pre><p>Now let's send messages using several different
two-word keys:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
$ ./spout news-service/usa.news
$ ./spout news-service/usa.sports
$ ./spout news-service/europe.sports
$ ./spout news-service/europe.news
</pre><p>In the first window, the messages with
<code class="literal">news</code> in the second word of the key have
been received:</p><pre class="screen">
Message(properties={qpid.subject:usa.news, spout-id:73fc8058-5af6-407c-9166-b49a9076097a:0}, content='')
Message(properties={qpid.subject:europe.news, spout-id:f72815aa-7be4-4944-99fd-c64c9747a876:0}, content='')
</pre><p>Next, let's use <span class="command"><strong>drain</strong></span> with the
subject <code class="literal">#.news</code> to match any sequence of
words that ends with <code class="literal">news</code>.</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
$ ./drain -t 30 news-service/#.news
</pre><p>In the second window, let's send messages using a
variety of different multi-word keys:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
$ ./spout news-service/news
$ ./spout news-service/sports
$ ./spout news-service/usa.news
$ ./spout news-service/usa.sports
$ ./spout news-service/usa.faux.news
$ ./spout news-service/usa.faux.sports
</pre><p>In the first window, messages with
<code class="literal">news</code> in the last word of the key have been
received:</p><pre class="screen">
Message(properties={qpid.subject:news, spout-id:cbd42b0f-c87b-4088-8206-26d7627c9640:0}, content='')
Message(properties={qpid.subject:usa.news, spout-id:234a78d7-daeb-4826-90e1-1c6540781eac:0}, content='')
Message(properties={qpid.subject:usa.faux.news, spout-id:6029430a-cfcb-4700-8e9b-cbe4a81fca5f:0}, content='')
</pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="d0e1649"></a>2.4.3.&#160;Address String Options</h3></div></div></div><p>
The options in an address string can contain additional
information for the senders or receivers created for it,
including:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Policies for assertions about the node to which an address
refers.
</p><p>
For instance, in the address string <code class="literal">my-queue;
{assert: always, node:{ type: queue }}</code>, the node
named <code class="literal">my-queue</code> must be a queue; if not,
the address does not resolve to a node, and an exception
is raised.
</p></li><li class="listitem"><p>
Policies for automatically creating or deleting the node to which an address refers.
</p><p>
For instance, in the address string <code class="literal">xoxox ; {create: always}</code>,
the queue <code class="literal">xoxox</code> is created, if it does
not exist, before the address is resolved.
</p></li><li class="listitem"><p>
Extension points that can be used for sender/receiver configuration.
</p><p>
For instance, if the address for a receiver is
<code class="literal">my-queue; {mode: browse}</code>, the receiver
works in <code class="literal">browse</code> mode, leaving messages
on the queue so other receivers can receive them.
</p></li><li class="listitem"><p>
Extension points providing more direct control over the underlying protocol.
</p><p>
For instance, the <code class="literal">x-bindings</code> property
allows greater control over the AMQP 0-10 binding process
when an address is resolved.
</p></li></ul></div><p>
Let's use some examples to show how these different kinds of
address string options affect the behavior of senders and
receives.
</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e1698"></a>2.4.3.1.&#160;assert</h4></div></div></div><p>
In this section, we use the <code class="literal">assert</code> option
to ensure that the address resolves to a node of the required
type.
</p><div class="example"><a id="d0e1706"></a><p class="title"><strong>Example&#160;2.7.&#160;Assertions on Nodes</strong></p><div class="example-contents"><p>Let's use <span class="command"><strong>qpid-config</strong></span> to create a
queue and a topic.</p><pre class="screen">
$ qpid-config add queue my-queue
$ qpid-config add exchange topic my-topic
</pre><p>
We can now use the address specified to drain to assert that it is
of a particular type:
</p><pre class="screen">
$ ./drain 'my-queue; {assert: always, node:{ type: queue }}'
$ ./drain 'my-queue; {assert: always, node:{ type: topic }}'
2010-04-20 17:30:46 warning Exception received from broker: not-found: not-found: Exchange not found: my-queue (../../src/qpid/broker/ExchangeRegistry.cpp:92) [caused by 2 \x07:\x01]
Exchange my-queue does not exist
</pre><p>
The first attempt passed without error as my-queue is indeed a
queue. The second attempt however failed; my-queue is not a
topic.
</p><p>
We can do the same thing for my-topic:
</p><pre class="screen">
$ ./drain 'my-topic; {assert: always, node:{ type: topic }}'
$ ./drain 'my-topic; {assert: always, node:{ type: queue }}'
2010-04-20 17:31:01 warning Exception received from broker: not-found: not-found: Queue not found: my-topic (../../src/qpid/broker/SessionAdapter.cpp:754) [caused by 1 \x08:\x01]
Queue my-topic does not exist
</pre></div></div><br class="example-break" /><p>Now let's use the <code class="literal">create</code> option to
create the queue <code class="literal">xoxox</code> if it does not already
exist:</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e1734"></a>2.4.3.2.&#160;create</h4></div></div></div><p>In previous examples, we created the queue before
listening for messages on it. Using <code class="literal">create:
always</code>, the queue is automatically created if it
does not exist.</p><div class="example"><a id="d0e1742"></a><p class="title"><strong>Example&#160;2.8.&#160;Creating a Queue Automatically</strong></p><div class="example-contents"><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">$ ./drain -t 30 "xoxox ; {create: always}"</pre><p>Now we can send messages to this queue:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">$ ./spout "xoxox ; {create: always}"</pre><p>Returning to the first window, we see that <span class="command"><strong>drain</strong></span> has received this message:</p><pre class="screen">Message(properties={spout-id:1a1a3842-1a8b-4f88-8940-b4096e615a7d:0}, content='')</pre></div></div><br class="example-break" /><p>The details of the node thus created can be controlled by further options within the node. See <a class="xref" href="JMS-Client-0-10-Configuring-Addresses.html#table-node-properties" title="Table&#160;2.15.&#160;Node Properties">Table&#160;2.15, &#8220;Node Properties&#8221;</a> for details.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e1768"></a>2.4.3.3.&#160;browse</h4></div></div></div><p>Some options specify message transfer semantics; for
instance, they may state whether messages should be consumed or
read in browsing mode, or specify reliability
characteristics. The following example uses the
<code class="literal">browse</code> option to receive messages without
removing them from a queue.</p><div class="example"><a id="d0e1776"></a><p class="title"><strong>Example&#160;2.9.&#160;Browsing a Queue</strong></p><div class="example-contents"><p>
Let's use the browse mode to receive messages without
removing them from the queue. First we send three messages to the
queue:
</p><pre class="screen">
$ ./spout my-queue --content one
$ ./spout my-queue --content two
$ ./spout my-queue --content three
</pre><p>Now we use drain to get those messages, using the browse option:</p><pre class="screen">
$ ./drain 'my-queue; {mode: browse}'
Message(properties={spout-id:fbb93f30-0e82-4b6d-8c1d-be60eb132530:0}, content='one')
Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='two')
Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three')
</pre><p>We can confirm the messages are still on the queue by repeating the drain:</p><pre class="screen">
$ ./drain 'my-queue; {mode: browse}'
Message(properties={spout-id:fbb93f30-0e82-4b6d-8c1d-be60eb132530:0}, content='one')
Message(properties={spout-id:ab9e7c31-19b0-4455-8976-34abe83edc5f:0}, content='two')
Message(properties={spout-id:ea75d64d-ea37-47f9-96a9-d38e01c97925:0}, content='three')
</pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e1791"></a>2.4.3.4.&#160;x-bindings</h4></div></div></div><p>Greater control over the AMQP 0-10 binding process can
be achieved by including an <code class="literal">x-bindings</code>
option in an address string.
For instance, the XML Exchange is an AMQP 0-10 custom exchange
provided by the Apache Qpid C++ broker. It allows messages to
be filtered using XQuery; queries can address either message
properties or XML content in the body of the message. The
xquery is specified in the arguments field of the AMQP 0-10
command. When using the messaging API an xquery can be
specified in and address that resolves to an XML exchange by
using the x-bindings property.</p><p>An instance of the XML Exchange must be added before it
can be used:</p><pre class="programlisting">
$ qpid-config add exchange xml xml
</pre><p>When using the XML Exchange, a receiver provides an
XQuery as an x-binding argument. If the query contains a
context item (a path starting with <span class="quote">&#8220;<span class="quote">.</span>&#8221;</span>), then it
is applied to the content of the message, which must be
well-formed XML. For instance, <code class="literal">./weather</code> is
a valid XQuery, which matches any message in which the root
element is named <code class="literal">weather</code>. Here is an
address string that contains this query:</p><pre class="programlisting">
xml; {
link: {
x-bindings: [{exchange:xml, key:weather, arguments:{xquery:"./weather"} }]
}
}
</pre><p>When using longer queries with <span class="command"><strong>drain</strong></span>,
it is often useful to place the query in a file, and use
<span class="command"><strong>cat</strong></span> in the command line. We do this in the
following example.</p><div class="example"><a id="d0e1824"></a><p class="title"><strong>Example&#160;2.10.&#160;Using the XML Exchange</strong></p><div class="example-contents"><p>This example uses an x-binding that contains queries, which filter based on the content of XML messages. Here is an XQuery that we will use in this example:</p><pre class="programlisting">
let $w := ./weather
return $w/station = 'Raleigh-Durham International Airport (KRDU)'
and $w/temperature_f &gt; 50
and $w/temperature_f - $w/dewpoint &gt; 5
and $w/wind_speed_mph &gt; 7
and $w/wind_speed_mph &lt; 20
</pre><p>We can specify this query in an x-binding to listen to messages that meet the criteria specified by the query:</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen">
$ ./drain -f "xml; {link:{x-bindings:[{key:'weather',
arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}"
</pre><p>In another window, let's create an XML message that meets the criteria in the query, and place it in the file <code class="filename">rdu.xml</code>:</p><pre class="programlisting">
&lt;weather&gt;
&lt;station&gt;Raleigh-Durham International Airport (KRDU)&lt;/station&gt;
&lt;wind_speed_mph&gt;16&lt;/wind_speed_mph&gt;
&lt;temperature_f&gt;70&lt;/temperature_f&gt;
&lt;dewpoint&gt;35&lt;/dewpoint&gt;
&lt;/weather&gt;
</pre><p>Now let's use <span class="command"><strong>spout</strong></span> to send this message to the XML exchange:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen">
spout --content "$(cat rdu.xml)" xml/weather
</pre><p>Returning to the first window, we see that the message has been received:</p><pre class="screen">$ ./drain -f "xml; {link:{x-bindings:[{exchange:'xml', key:'weather', arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}"
Message(properties={qpid.subject:weather, spout-id:31c431de-593f-4bec-a3dd-29717bd945d3:0},
content='&lt;weather&gt;
&lt;station&gt;Raleigh-Durham International Airport (KRDU)&lt;/station&gt;
&lt;wind_speed_mph&gt;16&lt;/wind_speed_mph&gt;
&lt;temperature_f&gt;40&lt;/temperature_f&gt;
&lt;dewpoint&gt;35&lt;/dewpoint&gt;
&lt;/weather&gt;')
</pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e1861"></a>2.4.3.5.&#160;Address String Options - Reference</h4></div></div></div><div class="table"><a id="d0e1864"></a><p class="title"><strong>Table&#160;2.14.&#160;Address String Options</strong></p><div class="table-contents"><table border="1" summary="Address String Options" width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>option</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td>
assert
</td><td>
one of: always, never, sender or receiver
</td><td>
Asserts that the properties specified in the node option
match whatever the address resolves to. If they do not,
resolution fails and an exception is raised.
</td></tr><tr><td>
create
</td><td>
one of: always, never, sender or receiver
</td><td>
Creates the node to which an address refers if it does
not exist. No error is raised if the node does
exist. The details of the node may be specified in the
node option.
</td></tr><tr><td>
delete
</td><td>
one of: always, never, sender or receiver
</td><td>
Delete the node when the sender or receiver is closed.
</td></tr><tr><td>
node
</td><td>
A nested map containing the entries shown in <a class="xref" href="JMS-Client-0-10-Configuring-Addresses.html#table-node-properties" title="Table&#160;2.15.&#160;Node Properties">Table&#160;2.15, &#8220;Node Properties&#8221;</a>.
</td><td>
Specifies properties of the node to which the address
refers. These are used in conjunction with the assert or
create options.
</td></tr><tr><td>
link
</td><td>
A nested map containing the entries shown in <a class="xref" href="JMS-Client-0-10-Configuring-Addresses.html#table-link-properties" title="Table&#160;2.16.&#160;Link Properties">Table&#160;2.16, &#8220;Link Properties&#8221;</a>.
</td><td>
Used to control the establishment of a conceptual link
from the client application to or from the target/source
address.
</td></tr><tr><td>
mode
</td><td>
one of: browse, consume
</td><td>
This option is only of relevance for source addresses
that resolve to a queue. If browse is specified the
messages delivered to the receiver are left on the queue
rather than being removed. If consume is specified the
normal behaviour applies; messages are removed from the
queue once the client acknowledges their receipt.
</td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="table-node-properties"></a><p class="title"><strong>Table&#160;2.15.&#160;Node Properties</strong></p><div class="table-contents"><table border="1" summary="Node Properties" width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>property</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td>
type
</td><td>
topic, queue
</td><td>
Indicates the type of the node.
</td></tr><tr><td>
durable
</td><td>
True, False
</td><td>
Indicates whether the node survives a loss of
volatile storage e.g. if the broker is restarted.
</td></tr><tr><td>
x-declare
</td><td>
A nested map whose values correspond to the valid fields
on an AMQP 0-10 queue-declare or exchange-declare
command.
</td><td>
These values are used to fine tune the creation or
assertion process. Note however that they are protocol
specific.
</td></tr><tr><td>
x-bindings
</td><td>
A nested list in which each binding is represented by
a map. The entries of the map for a binding contain
the fields that describe an AMQP 0-10 binding. Here is
the format for x-bindings:
<pre class="programlisting">
[
{
exchange: &lt;exchange&gt;,
queue: &lt;queue&gt;,
key: &lt;key&gt;,
arguments: {
&lt;key_1&gt;: &lt;value_1&gt;,
...,
&lt;key_n&gt;: &lt;value_n&gt; }
},
...
]
</pre>
</td><td>
In conjunction with the create option, each of these
bindings is established as the address is resolved. In
conjunction with the assert option, the existence of
each of these bindings is verified during
resolution. Again, these are protocol specific.
</td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="table-link-properties"></a><p class="title"><strong>Table&#160;2.16.&#160;Link Properties</strong></p><div class="table-contents"><table border="1" summary="Link Properties" width="100%"><colgroup><col /><col /><col /></colgroup><thead><tr><th>option</th><th>value</th><th>semantics</th></tr></thead><tbody><tr><td>
reliability
</td><td>
one of: unreliable, at-least-once, at-most-once, exactly-once
</td><td>
Reliability indicates the level of reliability that
the sender or receiver. <code class="literal">unreliable</code>
and <code class="literal">at-most-once</code> are currently
treated as synonyms, and allow messages to be lost if
a broker crashes or the connection to a broker is
lost. <code class="literal">at-least-once</code> guarantees that
a message is not lost, but duplicates may be
received. <code class="literal">exactly-once</code> guarantees
that a message is not lost, and is delivered precisely
once. Currently only <code class="literal">unreliable</code>
and <code class="literal">at-least-once</code> are supported.
<a class="footnote" href="#ftn.d0e2016" id="d0e2016"><sup class="footnote">[a]</sup></a>
</td></tr><tr><td>
durable
</td><td>
True, False
</td><td>
Indicates whether the link survives a loss of
volatile storage e.g. if the broker is restarted.
</td></tr><tr><td>
x-declare
</td><td>
A nested map whose values correspond to the valid fields
of an AMQP 0-10 queue-declare command.
</td><td>
These values can be used to customise the subscription
queue in the case of receiving from an exchange. Note
however that they are protocol specific.
</td></tr><tr><td>
x-subscribe
</td><td>
A nested map whose values correspond to the valid fields
of an AMQP 0-10 message-subscribe command.
</td><td>
These values can be used to customise the subscription.
</td></tr><tr><td>
x-bindings
</td><td>
A nested list each of whose entries is a map that may
contain fields (queue, exchange, key and arguments)
describing an AMQP 0-10 binding.
</td><td>
These bindings are established during resolution
independent of the create option. They are considered
logically part of the linking process rather than of
node creation.
</td></tr><tr><td>
delay
</td><td>
long
</td><td>
The delay (in milliseconds) between the time a message is sent by a MessageProducer, and
the earliest time it becomes visible to consumers on any queue onto which it has been placed. Note that
this value only has an affect on brokers which support the feature (currently only the Apache Qpid
Broker-J), and only on queues where delivery delay has been enabled.
</td></tr></tbody><tbody class="footnotes"><tr><td colspan="3"><div class="footnote" id="ftn.d0e2016"><p><a class="para" href="#d0e2016"><sup class="para">[a] </sup></a>If at-most-once is requested,
unreliable will be used and for durable messages on
durable queues there is the possibility that messages
will be redelivered; if exactly-once is requested,
at-least-once will be used and the application needs to
be able to deal with duplicates.</p></div></td></tr></tbody></table></div></div><br class="table-break" /></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="section-address-string-bnf"></a>2.4.4.&#160;Address String Grammar</h3></div></div></div><p>This section provides a formal grammar for address strings.</p><p><strong>Tokens.&#160;</strong>The following regular expressions define the tokens used
to parse address strings:</p><pre class="programlisting">
LBRACE: \\{
RBRACE: \\}
LBRACK: \\[
RBRACK: \\]
COLON: :
SEMI: ;
SLASH: /
COMMA: ,
NUMBER: [+-]?[0-9]*\\.?[0-9]+
ID: [a-zA-Z_](?:[a-zA-Z0-9_-]*[a-zA-Z0-9_])?
STRING: "(?:[^\\\\"]|\\\\.)*"|\'(?:[^\\\\\']|\\\\.)*\'
ESC: \\\\[^ux]|\\\\x[0-9a-fA-F][0-9a-fA-F]|\\\\u[0-9a-fA-F][0-9a-fA-F][0-9a-fA-F][0-9a-fA-F]
SYM: [.#*%@$^!+-]
WSPACE: [ \\n\\r\\t]+
</pre><p><strong>Grammar.&#160;</strong>The formal grammar for addresses is given below:</p><pre class="programlisting">
address := name [ SLASH subject ] [ ";" options ]
name := ( part | quoted )+
subject := ( part | quoted | SLASH )*
quoted := STRING / ESC
part := LBRACE / RBRACE / COLON / COMMA / NUMBER / ID / SYM
options := map
map := "{" ( keyval ( "," keyval )* )? "}"
keyval "= ID ":" value
value := NUMBER / STRING / ID / map / list
list := "[" ( value ( "," value )* )? "]"
</pre><p><strong>Address String Options.&#160;</strong>The address string options map supports the following parameters:</p><pre class="programlisting">
&lt;name&gt; [ / &lt;subject&gt; ] ; {
create: always | sender | receiver | never,
delete: always | sender | receiver | never,
assert: always | sender | receiver | never,
mode: browse | consume,
node: {
type: queue | topic,
durable: True | False,
x-declare: { ... &lt;declare-overrides&gt; ... },
x-bindings: [&lt;binding_1&gt;, ... &lt;binding_n&gt;]
},
link: {
name: &lt;link-name&gt;,
durable: True | False,
reliability: unreliable | at-most-once | at-least-once | exactly-once,
x-declare: { ... &lt;declare-overrides&gt; ... },
x-bindings: [&lt;binding_1&gt;, ... &lt;binding_n&gt;],
x-subscribe: { ... &lt;subscribe-overrides&gt; ... }
}
}
</pre><div class="itemizedlist"><p class="title"><strong>Create, Delete, and Assert Policies</strong></p><p>The create, delete, and assert policies specify who should
perfom the associated action:</p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>always</em></span>: the action is performed by any messaging client</p></li><li class="listitem"><p><span class="emphasis"><em>sender</em></span>: the action is only performed by a sender</p></li><li class="listitem"><p><span class="emphasis"><em>receiver</em></span>: the action is only performed by a receiver</p></li><li class="listitem"><p><span class="emphasis"><em>never</em></span>: the action is never performed (this is the default)</p></li></ul></div><div class="itemizedlist"><p class="title"><strong>Node-Type</strong></p><p>The node-type is one of:</p><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>topic</em></span>: in the AMQP 0-10
mapping, a topic node defaults to the topic exchange, x-declare
may be used to specify other exchange types</p></li><li class="listitem"><p><span class="emphasis"><em>queue</em></span>: this is the default node-type</p></li></ul></div></div><div class="footnotes"><br /><hr style="width:100; text-align:left;margin-left: 0" /><div class="footnote" id="ftn.d0e1273"><p><a class="para" href="#d0e1273"><sup class="para">[1] </sup></a>In the programs we have just seen, we used
<code class="literal">amq.topic</code> as the default address if none is
passed in. This is the name of a standard exchange that always
exists on an AMQP 0-10 messaging broker.</p></div><div class="footnote" id="ftn.d0e1291"><p><a class="para" href="#d0e1291"><sup class="para">[2] </sup></a>The terms <span class="emphasis"><em>queue</em></span> and
<span class="emphasis"><em>topic</em></span> here were chosen to align with
their meaning in JMS. These two addressing 'patterns',
queue and topic, are sometimes refered as point-to-point
and publish-subscribe. AMQP 0-10 has an exchange type
called a <span class="emphasis"><em>topic exchange</em></span>. When the term
<span class="emphasis"><em>topic</em></span> occurs alone, it refers to a
Messaging API topic, not the topic
exchange.</p></div><div class="footnote" id="ftn.d0e1307"><p><a class="para" href="#d0e1307"><sup class="para">[3] </sup></a>There are exceptions to this rule; for instance,
a receiver can use <code class="literal">browse</code> mode, which leaves
messages on the queue for other receivers to
read.</p></div><div class="footnote" id="ftn.d0e1314"><p><a class="para" href="#d0e1314"><sup class="para">[4] </sup></a>The AMQP 0-10 implementation is the only one
that currently exists.</p></div><div class="footnote" id="ftn.d0e1318"><p><a class="para" href="#d0e1318"><sup class="para">[5] </sup></a>In AMQP 0-10, messages are sent to
exchanges, and read from queues. The Messaging API also
allows a sender to send messages to a queue; internally,
Qpid implements this by sending the message to the default
exchange, with the name of the queue as the routing key. The
Messaging API also allows a receiver to receive messages
from a topic; internally, Qpid implements this by setting up
a private subscription queue for the receiver and binding
the subscription queue to the exchange that corresponds to
the topic.</p></div><div class="footnote" id="ftn.d0e1333"><p><a class="para" href="#d0e1333"><sup class="para">[6] </sup></a>Currently, the C++, Python, and .NET C#
implementations of <span class="command"><strong>drain</strong></span> and
<span class="command"><strong>spout</strong></span> have slightly different
options. This tutorial uses the C++ implementation. The
options will be reconciled in the near
future.</p></div></div></div><div class="navfooter"><hr /><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="JMS-Client-0-10-Configuring-JVM-Properties.html">Prev</a>&#160;</td><td align="center" width="20%"><a accesskey="u" href="JMS-Client-0-10-Configuring.html">Up</a></td><td align="right" width="40%">&#160;<a accesskey="n" href="JMS-Client-0-10-Configuring-Logging.html">Next</a></td></tr><tr><td align="left" valign="top" width="40%">2.3.&#160;JVM Properties&#160;</td><td align="center" width="20%"><a accesskey="h" href="JMS-Client-0-10-Book.html">Home</a></td><td align="right" valign="top" width="40%">&#160;2.5.&#160;Logging</td></tr></table></div></div>
<hr/>
<ul id="-apache-navigation">
<li><a href="http://www.apache.org/">Apache</a></li>
<li><a href="http://www.apache.org/licenses/">License</a></li>
<li><a href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
<li><a href="http://www.apache.org/foundation/thanks.html">Thanks!</a></li>
<li><a href="/security.html">Security</a></li>
<li><a href="http://www.apache.org/"><img id="-apache-feather" width="48" height="14" src="" alt="Apache"/></a></li>
</ul>
<p id="-legal">
Apache Qpid, Messaging built on AMQP; Copyright &#169; 2015
The Apache Software Foundation; Licensed under
the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache
License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton,
Proton, Apache, the Apache feather logo, and the Apache Qpid
project logo are trademarks of The Apache Software
Foundation; All other marks mentioned may be trademarks or
registered trademarks of their respective owners
</p>
</div>
</div>
</div>
</body>
</html>