| <?xml version="1.0"?> |
| <!-- |
| |
| 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 xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="JMS-Client-0-8-Binding-URL"> |
| <title>Binding URL</title> |
| |
| <para> The <emphasis>Binding URL</emphasis> syntax for addressing<footnote> |
| <para>The client also supports the <emphasis>Address/ADDR</emphasis> format. This is documented in <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="${qpidJmsClient010Book}">Using the Qpid AMQP 0-10 JMS Client</link>.</para> |
| </footnote>. It allows the specification of the bindings between a queue and an exchange, queue |
| and exchange creation arguments and some ancillary options.</para> |
| |
| <para> The format for a <emphasis>Binding URL</emphasis> is provided below <screen> |
| <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 xml: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> |
| <row xml:id="JMS-Client-0-8-Binding-URL-Options-SendEncrypted"> |
| <entry><para>sendencrypted</para></entry> |
| <entry><para>boolean </para></entry> |
| <entry><para>If true then encrypt every message sent to this address. </para></entry> |
| </row> |
| |
| <row xml:id="JMS-Client-0-8-Binding-URL-Options-EncryptedRecipients"> |
| <entry><para>encryptedrecipients</para></entry> |
| <entry><para>string </para></entry> |
| <entry><para>A semi-colon separated list of the names of the recipients who will be able to decrypt the |
| message. </para></entry> |
| </row> |
| |
| <row xml:id="JMS-Client-0-8-Binding-URL-Options-DeliveryDelay"> |
| <entry><para>deliveryDelay</para></entry> |
| <entry><para>long </para></entry> |
| <entry><para>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.</para></entry> |
| </row> |
| </tbody> |
| </tgroup> |
| </table> |
| </para> |
| |
| <section xml:id="JMS-Client-0-8-Binding-URL-Examples"> |
| <title>Binding URL Examples</title> |
| |
| <section xml: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> |
| 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> |
| 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> |
| 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 xml: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> |
| 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> |
| topic://amq.topic/hello/tmp_127_0_0_1_36973_1?routingkey='hello'&exclusive='true'&autodelete='true' |
| </screen> |
| </example> |
| </para> |
| </section> |
| |
| <section xml: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> |
| topic://amq.topic?routingkey='stocks.#' |
| topic://amq.topic?routingkey='stocks.*.ibm' |
| topic://amq.topic?routingkey='stocks.nyse.ibm' |
| </screen> |
| </para> |
| </section> |
| |
| <section xml: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> |