<div class="docbook"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">2.4. Addresses</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="JMS-Client-0-10-Configuring-JVM-Properties.html">Prev</a> </td><th align="center" width="60%">Chapter 2. Configuring the Client</th><td align="right" width="20%"> <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. 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—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 2.3. 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 2.4. 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. Address Strings</h3></div></div></div><p>So far, our examples have used address strings that | |
contain only the name of a node. An <em class="firstterm">address | |
string</em> can also contain a | |
<em class="firstterm">subject</em> and | |
<em class="firstterm">options</em>.</p><p>The syntax for an address string is:</p><pre class="programlisting"> | |
address_string ::= <address> [ / <subject> ] [ ; <options> ] | |
options ::= { <key> : <value>, ... } | |
</pre><p>Addresses, subjects, and keys are strings. Values can | |
be numbers, strings (with optional single or double quotes), | |
maps, or lists. A complete BNF for address strings appears in | |
<a class="xref" href="JMS-Client-0-10-Configuring-Addresses.html#section-address-string-bnf" title="2.4.4. Address String Grammar">Section 2.4.4, “Address String Grammar”</a>.</p><p>So far, the address strings in this tutorial have only | |
used simple names. The following sections show how to use | |
subjects and options.</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="d0e1473"></a>2.4.2. Subjects</h3></div></div></div><p>Every message has a property called | |
<em class="firstterm">subject</em>, which is analogous to the | |
subject on an email message. If no subject is specified, the | |
message's subject is null. For convenience, address strings | |
also allow a subject. If a sender's address contains a | |
subject, it is used as the default subject for the messages | |
it sends. | |
</p><p> | |
</p><p> | |
If a receiver's address contains a subject, it is used to | |
select only messages that match the subject—the matching | |
algorithm depends on the message source. 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 2.5. 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">“<span class="quote">.</span>”</span> delimiter. For instance, in a news | |
application, the sender might use subjects like | |
<code class="literal">usa.news</code>, <code class="literal">usa.weather</code>, | |
<code class="literal">europe.news</code>, or | |
<code class="literal">europe.weather</code>. | |
The receiver's subject can include wildcard characters— | |
<span class="quote">“<span class="quote">#</span>”</span> matches one or more words in the message's | |
subject, <span class="quote">“<span class="quote">*</span>”</span> matches a single word. | |
For instance, if the subject in the source address is | |
<code class="literal">*.news</code>, it matches messages with the | |
subject <code class="literal">europe.news</code> or | |
<code class="literal">usa.news</code>; if it is | |
<code class="literal">europe.#</code>, it matches messages with subjects | |
like <code class="literal">europe.news</code> or | |
<code class="literal">europe.pseudo.news</code>.</p><div class="example"><a id="d0e1584"></a><p class="title"><strong>Example 2.6. 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. 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. 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 2.7. 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. 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 2.8. 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 2.15. Node Properties">Table 2.15, “Node Properties”</a> for details.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e1768"></a>2.4.3.3. browse</h4></div></div></div><p>Some options specify message transfer semantics; for | |
instance, they may state whether messages should be consumed or | |
read in browsing mode, or specify reliability | |
characteristics. The following example uses the | |
<code class="literal">browse</code> option to receive messages without | |
removing them from a queue.</p><div class="example"><a id="d0e1776"></a><p class="title"><strong>Example 2.9. 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. x-bindings</h4></div></div></div><p>Greater control over the AMQP 0-10 binding process can | |
be achieved by including an <code class="literal">x-bindings</code> | |
option in an address string. | |
For instance, the XML Exchange is an AMQP 0-10 custom exchange | |
provided by the Apache Qpid C++ broker. It allows messages to | |
be filtered using XQuery; queries can address either message | |
properties or XML content in the body of the message. The | |
xquery is specified in the arguments field of the AMQP 0-10 | |
command. When using the messaging API an xquery can be | |
specified in and address that resolves to an XML exchange by | |
using the x-bindings property.</p><p>An instance of the XML Exchange must be added before it | |
can be used:</p><pre class="programlisting"> | |
$ qpid-config add exchange xml xml | |
</pre><p>When using the XML Exchange, a receiver provides an | |
XQuery as an x-binding argument. If the query contains a | |
context item (a path starting with <span class="quote">“<span class="quote">.</span>”</span>), then it | |
is applied to the content of the message, which must be | |
well-formed XML. For instance, <code class="literal">./weather</code> is | |
a valid XQuery, which matches any message in which the root | |
element is named <code class="literal">weather</code>. Here is an | |
address string that contains this query:</p><pre class="programlisting"> | |
xml; { | |
link: { | |
x-bindings: [{exchange:xml, key:weather, arguments:{xquery:"./weather"} }] | |
} | |
} | |
</pre><p>When using longer queries with <span class="command"><strong>drain</strong></span>, | |
it is often useful to place the query in a file, and use | |
<span class="command"><strong>cat</strong></span> in the command line. We do this in the | |
following example.</p><div class="example"><a id="d0e1824"></a><p class="title"><strong>Example 2.10. 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 > 50 | |
and $w/temperature_f - $w/dewpoint > 5 | |
and $w/wind_speed_mph > 7 | |
and $w/wind_speed_mph < 20 | |
</pre><p>We can specify this query in an x-binding to listen to messages that meet the criteria specified by the query:</p><p><span class="emphasis"><em>First Window:</em></span></p><pre class="screen"> | |
$ ./drain -f "xml; {link:{x-bindings:[{key:'weather', | |
arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}" | |
</pre><p>In another window, let's create an XML message that meets the criteria in the query, and place it in the file <code class="filename">rdu.xml</code>:</p><pre class="programlisting"> | |
<weather> | |
<station>Raleigh-Durham International Airport (KRDU)</station> | |
<wind_speed_mph>16</wind_speed_mph> | |
<temperature_f>70</temperature_f> | |
<dewpoint>35</dewpoint> | |
</weather> | |
</pre><p>Now let's use <span class="command"><strong>spout</strong></span> to send this message to the XML exchange:</p><p><span class="emphasis"><em>Second Window:</em></span></p><pre class="screen"> | |
spout --content "$(cat rdu.xml)" xml/weather | |
</pre><p>Returning to the first window, we see that the message has been received:</p><pre class="screen">$ ./drain -f "xml; {link:{x-bindings:[{exchange:'xml', key:'weather', arguments:{xquery:\"$(cat rdu.xquery )\"}}]}}" | |
Message(properties={qpid.subject:weather, spout-id:31c431de-593f-4bec-a3dd-29717bd945d3:0}, | |
content='<weather> | |
<station>Raleigh-Durham International Airport (KRDU)</station> | |
<wind_speed_mph>16</wind_speed_mph> | |
<temperature_f>40</temperature_f> | |
<dewpoint>35</dewpoint> | |
</weather>') | |
</pre></div></div><br class="example-break" /></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="d0e1861"></a>2.4.3.5. Address String Options - Reference</h4></div></div></div><div class="table"><a id="d0e1864"></a><p class="title"><strong>Table 2.14. 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 2.15. Node Properties">Table 2.15, “Node Properties”</a>. | |
</td><td> | |
Specifies properties of the node to which the address | |
refers. These are used in conjunction with the assert or | |
create options. | |
</td></tr><tr><td> | |
link | |
</td><td> | |
A nested map containing the entries shown in <a class="xref" href="JMS-Client-0-10-Configuring-Addresses.html#table-link-properties" title="Table 2.16. Link Properties">Table 2.16, “Link Properties”</a>. | |
</td><td> | |
Used to control the establishment of a conceptual link | |
from the client application to or from the target/source | |
address. | |
</td></tr><tr><td> | |
mode | |
</td><td> | |
one of: browse, consume | |
</td><td> | |
This option is only of relevance for source addresses | |
that resolve to a queue. If browse is specified the | |
messages delivered to the receiver are left on the queue | |
rather than being removed. If consume is specified the | |
normal behaviour applies; messages are removed from the | |
queue once the client acknowledges their receipt. | |
</td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="table-node-properties"></a><p class="title"><strong>Table 2.15. 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: <exchange>, | |
queue: <queue>, | |
key: <key>, | |
arguments: { | |
<key_1>: <value_1>, | |
..., | |
<key_n>: <value_n> } | |
}, | |
... | |
] | |
</pre> | |
</td><td> | |
In conjunction with the create option, each of these | |
bindings is established as the address is resolved. In | |
conjunction with the assert option, the existence of | |
each of these bindings is verified during | |
resolution. Again, these are protocol specific. | |
</td></tr></tbody></table></div></div><br class="table-break" /><div class="table"><a id="table-link-properties"></a><p class="title"><strong>Table 2.16. 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. Address String Grammar</h3></div></div></div><p>This section provides a formal grammar for address strings.</p><p><strong>Tokens. </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. </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. </strong>The address string options map supports the following parameters:</p><pre class="programlisting"> | |
<name> [ / <subject> ] ; { | |
create: always | sender | receiver | never, | |
delete: always | sender | receiver | never, | |
assert: always | sender | receiver | never, | |
mode: browse | consume, | |
node: { | |
type: queue | topic, | |
durable: True | False, | |
x-declare: { ... <declare-overrides> ... }, | |
x-bindings: [<binding_1>, ... <binding_n>] | |
}, | |
link: { | |
name: <link-name>, | |
durable: True | False, | |
reliability: unreliable | at-most-once | at-least-once | exactly-once, | |
x-declare: { ... <declare-overrides> ... }, | |
x-bindings: [<binding_1>, ... <binding_n>], | |
x-subscribe: { ... <subscribe-overrides> ... } | |
} | |
} | |
</pre><div class="itemizedlist"><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> </td><td align="center" width="20%"><a accesskey="u" href="JMS-Client-0-10-Configuring.html">Up</a></td><td align="right" width="40%"> <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. JVM Properties </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%"> 2.5. Logging</td></tr></table></div></div> |