1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
|
<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"
[
<!ENTITY % entities SYSTEM "commonEntities.xml">
%entities;
]>
<!--
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="JMS-Client-0-8-Binding-URL">
<title>Binding URL</title>
<para> The <emphasis>Binding URL</emphasis> syntax is the only addressing syntax supported by the
Qpid JMS client for AMQP 0-8, 0-9 and 0-9-1. It allows to specify the bindings that define the
relationship between a queue and an exchange, queue and exchange creation arguments and client
behaviour. </para>
<para> The format for a <emphasis>Binding URL</emphasis> is provided below <screen><![CDATA[
<Exchange Class>://<Exchange Name>/[<Destination>]/[<Queue>][?<option>='<value>'[&<option>='<value>']]
]]></screen> where <itemizedlist>
<listitem>
<para><emphasis>Exchange Class</emphasis>, specifies the type of the exchange, for example,
<emphasis>direct</emphasis>,<emphasis>topic</emphasis>,<emphasis>fanout</emphasis>, etc.
</para>
</listitem>
<listitem>
<para><emphasis>Exchange Name</emphasis>, specifies the name of the exchange, for example,
<emphasis>amq.direct</emphasis>,<emphasis>amq.topic</emphasis>, etc. </para>
</listitem>
<listitem>
<para><emphasis>Destination</emphasis>, is an optional part of <emphasis>Binding
URL</emphasis>. It can be used to specify a routing key with the non direct exchanges if
an option <emphasis>routingkey</emphasis> is not specified. If both
<emphasis>Destination</emphasis> and option <emphasis>routingkey</emphasis> are
specified, then option <emphasis>routingkey</emphasis> has precedence. </para>
</listitem>
<listitem>
<para><emphasis>Queue</emphasis>, is an optional part of <emphasis>Binding URL</emphasis> to
specify a queue name for JMS queue destination. It is ignored in JMS topic destinations.
Queue names may consist of any mixture of digits, letters, and underscores </para>
</listitem>
<listitem>
<para><emphasis>Options</emphasis>, key-value pairs separated by '=' character specifying
queue and exchange creation arguments, routing key, client behaviour, etc. </para>
</listitem>
</itemizedlist>
</para>
<important>
<title>Binding URL option quoting</title>
<para>Take care with the quoting surrounding option values. Each option value
<emphasis>must</emphasis> be surrounded with single quotes ('). </para>
</important>
<para> The following <emphasis>Binding URL</emphasis> options are currently defined: <table
pgwide="1">
<title>Binding URL options </title>
<tgroup cols="3">
<thead>
<row>
<entry>Option</entry>
<entry>Type</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><para>durable</para></entry>
<entry><para>boolean </para></entry>
<entry><para>Queue durability flag. If it is set to <emphasis>true</emphasis>, a durable
queue is requested to create. The durable queue should be stored on the Broker and
remained there after Broker restarts until it is explicitly deleted. This option has
no meaning for JMS topic destinations, as by nature a topic destination only exists
when a subscriber is connected. If durability is required for topic destinations,
the durable subscription should be created.</para></entry>
</row>
<row>
<entry><para>exclusive</para></entry>
<entry><para>boolean </para></entry>
<entry><para>Queue exclusivity flag. The client cannot use a queue that was declared as
exclusive by another still-open connection.</para></entry>
</row>
<row>
<entry><para>autodelete</para></entry>
<entry><para>boolean </para></entry>
<entry><para>Queue auto-deletion flag. If it is set to <emphasis>true</emphasis> on
queue creation, the queue is deleted if there are no remaining
subscribers.</para></entry>
</row>
<row>
<entry><para>exchangeautodelete</para></entry>
<entry><para>boolean </para></entry>
<entry><para>Exchange auto-deletion flag.</para></entry>
</row>
<row>
<entry><para>exchangedurable</para></entry>
<entry><para>boolean </para></entry>
<entry><para>Exchange durability flag. If it is set to <emphasis>true</emphasis> when
creating a new exchange, the exchange will be marked as durable. Durable exchanges
should remain active after Broker restarts. Non-durable exchanges are deleted on
following Broker restart.</para></entry>
</row>
<row>
<entry><para>routingkey</para></entry>
<entry><para>string </para></entry>
<entry>
<para> Defines the value of the binding key to bind a queue to the exchange. It is
always required to specify for JMS topic destinations. If routing key option is not
set in <emphasis>Binding URL</emphasis> and direct exchange class is specified, the
queue name is used as a routing key. <emphasis>MessagePublisher</emphasis> uses
routing key to publish messages onto exchange. </para>
</entry>
</row>
<row>
<entry><para>browse</para></entry>
<entry><para>boolean </para></entry>
<entry><para>If set to <emphasis>true</emphasis> on a destination for a message
consumer, such consumer can only read messages on the queue but cannot consume them.
The consumer behaves like a queue browser in this case.</para></entry>
</row>
<row id="JMS-Client-0-8-Binding-URL-Options-RejectBehaviour">
<entry><para>rejectbehaviour</para></entry>
<entry><para>string </para></entry>
<entry><para>Defines the reject behaviour for the re-delivered messages. If set to
'SERVER' the client delegates the requeue/DLQ decision to the server. If this option
is not specified, the messages won't be moved to the DLQ (or dropped) when delivery
count exceeds the maximum. </para></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<section id="JMS-Client-0-8-Binding-URL-Examples">
<title>Binding URL Examples</title>
<section id="JMS-Client-0-8-Binding-URL-JMS-Queues" role="h4">
<title>Binding URLs for declaring of JMS Queues</title>
<para>The Qpid client Binding URLs for JMS queue destinations can be declared using direct
exchange (Mostly it is a pre-defined exchange with a name "amq.direct". Also, custom direct
exchanges can be used.): <screen><![CDATA[
direct://amq.direct//<Queue Name>
]]></screen>
</para>
<para>The Binding URLs for destinations created with calls to
<emphasis>Session.createQueue(String)</emphasis> can be expressed as <screen><![CDATA[
direct://amq.direct//<Queue Name>?durable='true'
]]></screen> The durability flag is set to <emphasis>true</emphasis> in such destinations. </para>
<example>
<title>Binding URL examples for JMS queues</title>
<screen><![CDATA[
direct://amq.direct//myNonDurableQueue
direct://amq.direct//myDurableQueue?durable='true'
direct://amq.direct//myAnotherQueue?durable='true'&routingkey='myqueue'
direct://amq.direct//myQueue?durable='true'&routingkey='myqueue'&rejectbehaviour='server'
direct://custom.direct//yetAnotherQueue
]]></screen>
</example>
</section>
<section id="JMS-Client-0-8-Binding-URL-JMS-Topics" role="h4">
<title>Binding URLs for declaring of JMS Topics</title>
<para>The Binding URLs for JMS queue destinations can be declared using topic exchange (A
pre-defined exchange having name "amq.topic" is used mainly. However, custom topic exchanges
can be used as well): <screen><![CDATA[
topic://amq.topic//<Queue name>?routingkey='<Topic Name>'&exclusive='true'&autodelete='true'
]]></screen>
</para>
<para>The Binding URLs for a topic destination created with calls to
<emphasis>Session.createTopic("hello")</emphasis> is provided below: <example>
<title>Binding URL examples for JMS topics</title>
<screen><![CDATA[
topic://amq.topic/hello/tmp_127_0_0_1_36973_1?routingkey='hello'&exclusive='true'&autodelete='true'
]]></screen>
</example>
</para>
</section>
<section id="JMS-Client-0-8-Binding-URL-Topics-Wildcards" role="h4">
<title>Wildcard characters in routing keys for topic destinations</title>
<para> AMQP exchanges of class <emphasis>topic</emphasis> can route messages to the queues
using special matches containing wildcard characters (a "#" matches one or more words, a "*"
matches a single word). The routing keys words are separated with a "." delimiter to
distinguish words for matching. Thus, if a consumer application specifies a routing key in
the destination like "usa.#", it should receive all the messages matching to that routing
key. For example, "usa.boston", "usa.new-york", etc. </para>
<para> The examples of the <emphasis>Binding URLs</emphasis> having routing keys with
wildcards characters are provided below: <screen><![CDATA[
topic://amq.topic?routingkey='stocks.#'
topic://amq.topic?routingkey='stocks.*.ibm'
topic://amq.topic?routingkey='stocks.nyse.ibm'
]]></screen>
</para>
</section>
<section id="JMS-Client-0-8-Binding-URL-Extra-Examples" role="h4">
<title>More Examples</title>
<table>
<title>Binding URL examples</title>
<tgroup cols="2">
<thead>
<row>
<entry>Binding URL</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><para>fanout://amq.fanout//myQueue</para></entry>
<entry><para>Binding URL binding queue "myQueue" to predefined "amq.fanout" exchange
of class "fanout"</para></entry>
</row>
<row>
<entry><para>topic://custom.topic//anotherQueue?routingkey='aq'</para></entry>
<entry><para>Binding URL binding queue "anotherQueue" to the exchange with name
"custom.topic" of class "topic" using binding key "aq".</para></entry>
</row>
</tbody>
</tgroup>
</table>
</section>
</section>
</chapter>
|
