doc/jms-client-0-8/src/docbkx/JMS-Client-Binding-URL.xml

<?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>
&lt;Exchange Class&gt;://&lt;Exchange Name&gt;/[&lt;Destination&gt;]/[&lt;Queue&gt;][?&lt;option&gt;='&lt;value&gt;'[&amp;&lt;option&gt;='&lt;value&gt;']]
    </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//&lt;Queue Name&gt;
         </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//&lt;Queue Name&gt;?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'&amp;routingkey='myqueue'
direct://amq.direct//myQueue?durable='true'&amp;routingkey='myqueue'&amp;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//&lt;Queue name&gt;?routingkey='&lt;Topic Name&gt;'&amp;exclusive='true'&amp;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'&amp;exclusive='true'&amp;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>