qpid/doc/book/src/Binding-URL-Format.xml

<?xml version="1.0" encoding="utf-8"?>

<!--
 
 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.
 
-->

<section id="BindingURLFormat">
  <title>
      Binding URL Format
    </title>
            <programlisting>
&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;']]
</programlisting>
          <para>
            This URL format is used for two purposes in the code base. The
            broker uses this in the XML configuration file to create and bind
            queues at broker startup. It is also used by the client as a
            destination.
          </para><para>
            This format was used because it allows an explicit description of
            exchange and queue relationship.
          </para><para>
            The Exchange Class is not normally required for client connection
            as clients only publish to a named exchange however if exchanges
            are being dynamically instantiated it will be required. The class
            is required for the server to instantiate an exchange.
          </para><para>
            There are a number of options that are currently defined:
          </para><table><title/><tgroup cols="3">
            <tbody>
              <row>
                <entry>
                  Option
                </entry>
                <entry>
                  type
                </entry>
                <entry>
                  Description
                </entry>
              </row>
              <row>
                <entry>
                  exclusive
                </entry>
                <entry>
                  boolean
                </entry>
                <entry>
                  Is this an exclusive connection
                </entry>
              </row>
              <row>
                <entry>
                  autodelete
                </entry>
                <entry>
                  boolean
                </entry>
                <entry>
                  Should this queue be deleted on client disconnection
                </entry>
              </row>
              <row>
                <entry>
                  durable
                </entry>
                <entry>
                  boolean
                </entry>
                <entry>
                  Create a durable queue
                </entry>
              </row>
              <row>
                <entry>
                  clientid
                </entry>
                <entry>
                  string
                </entry>
                <entry>
                  Use the following client id
                </entry>
              </row>
              <row>
                <entry>
                  subscription
                </entry>
                <entry>
                  boolean
                </entry>
                <entry>
                  Create a subscription to this destination
                </entry>
              </row>
              <row>
                <entry>
                  routingkey
                </entry>
                <entry>
                  string
                </entry>
                <entry>
                  Use this value as the routing key
                </entry>
              </row>
            </tbody>
          </tgroup></table><para>
            Using these options in conjunction with the Binding URL format
            should allow future expansion as new and custom exchange types
            are created.
          </para><para>
            The URL format requires <emphasis>that at least one</emphasis> Queue or
            routingkey option be present on the URL.
          </para><para>
            The routingkey would be used to encode a topic as shown in the
            examples section below.
          </para>

	  <section role="h4" id="BindingURLFormat-Examples">
	    <title>
	      Examples
	    </title>

<example>
<title> Queues</title>
          <para>
            A queue can be created in QPID using the following URL format.
          </para><para>
            direct://amq.direct//&lt;Queue Name&gt;
          </para><para>
            For example: direct://amq.direct//simpleQueue
          </para><para>
            Queue names may consist of any mixture of digits, letters, and
            underscores.
          </para>
</example>
<example>
<title>Topics</title>
          <para>
            A topic can be created in QPID using the following URL format.
          </para><para>
            topic://amq.topic/&lt;Topic Subscription&gt;/
          </para><para>
            The topic subscription may only contain the letters A-Z and a-z
            and digits 0-9.
          </para>
            <programlisting>
direct://amq.direct/SimpleQueue
direct://amq.direct/UnusuallyBoundQueue?routingkey='/queue'
topic://amq.topic?routingkey='stocks.#'
topic://amq.topic?routingkey='stocks.nyse.ibm'
</programlisting>
</example>
<!--h4--></section>
</section>