path: root/qpid/doc/book/src/Connection-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="Connection-URL-Format">
  <title>
    Connection URL Format
  </title>

    <section role="h4" id="ConnectionURLFormat-Format">
      <title>
	Format
      </title>
      <programlisting>
amqp://[&lt;user&gt;:&lt;pass&gt;@][&lt;clientid&gt;]&lt;virtualhost&gt;[?&lt;option&gt;='&lt;value&gt;'[&amp;&lt;option&gt;='&lt;value&gt;']]
      </programlisting>
      <para>
	The connection url defines the values that are common across
	the cluster of brokers. The virtual host is second in the list
	as the AMQP specification demands that it start with a '/'
	otherwise it be more readable to be swapped with
	clientid. There is currently only one required option and that
	is the <emphasis>brokerlist</emphasis> option. In addition the
	following options are recognised.  </para>
<!--h4--></section>


	<section role="h4" id="ConnectionURLFormat-WorkedExample">

	  <title> Worked Example </title>
	


	  <para> You could use a URL which looks something like this:
	  </para>

<programlisting>
amqp://guest:guest@client1/development?brokerlist='tcp://localhost:5672'
</programlisting>

	  <para> Breaking this example down, here's what it all
	  means: </para>

	  <itemizedlist>
	  <listitem><para> amqp = the protocol we're using
	  </para></listitem>

	  <listitem><para> guest:guest@localhost = username:password@clientid
	  where the clientid is the name of your server (used under
	  the covers but don't worry about this for now). Always use
	  the guest:guest combination at the moment.</para></listitem>

	  <listitem><para> development = the name of the virtualhost, where the
	  virtualhost is a path which acts as a namespace. You can
	  effectively use any value here so long as you're consistent
	  throughout. The virtualhost must start with a slash "/" and
	  continue with names separated by slashes. A name consists of
	  any combination of at least one of [A-Za-z0-9] plus zero or
	  more of [.-_+!=:].  </para></listitem>

	  <listitem><para>brokerlist = this is the host address and port for
	  the broker you want to connect to. The connection factory
	  will assume tcp if you don't specify a transport
	  protocol. The port also defaults to 5672. Naturally you have
	  to put at least one broker in this list.  </para></listitem>

	  </itemizedlist>

	  <para> This example is not using failover so only provides
	  one host for the broker. If you do wish to connect using
	  failover you can provide two (or more) brokers in the
	  format: </para>

	  <para>
	  brokerlist='tcp://host1&amp;tcp://host2:5673' </para>

	  <para>The default failover setup will automatically retry
	  each broker once after a failed connection. If the
	  brokerlist contains more than one server then these servers
	  are tried in a round robin.  Details on how to modifiy this
	  behaviour will follow soon !  </para>

	<!--h4-->
	</section>

	<section role="h4"
	id="ConnectionURLFormat-Options">

	  <title> Options</title>

	<table>
	  <title>Connection URL Options</title>
	  <tgroup cols="3">
            <tbody>
              <row>
                <entry>
                  Option
                </entry>
                <entry>
                  Default
                </entry>
                <entry>
                  Description
                </entry>
              </row>
              <row>
                <entry>
                  brokerlist
                </entry>
                <entry>
                  see below
                </entry>
                <entry>
                  The list of brokers to use for this connection
                </entry>
              </row>
              <row>
                <entry>
                  failover
                </entry>
                <entry>
                  see below
                </entry>
                <entry>
                  The type of failover method to use with the broker list.
                </entry>
              </row>
              <row>
                <entry>
                  maxprefetch
                </entry>
                <entry>
                  5000
                </entry>
                <entry>
                  The maximum number of messages to prefetch from the broker.
                </entry>
              </row>
            </tbody>
          </tgroup></table>
<!--h4--></section>

<section role="h4" id="ConnectionURLFormat-Brokerlistoption">
  <title> Brokerlist option </title>
            <programlisting>
brokerlist='&lt;broker url&gt;[;&lt;broker url&gt;]'
</programlisting>
          <para>
            The broker list defines the various brokers that can be used for
            this connection. A minimum of one broker url is required
            additional URLs are semi-colon(';') delimited.
          </para>
<!--h4--></section>

<section role="h4" id="ConnectionURLFormat-BrokerURLformat">

<title> Broker URL format </title>

            <programlisting>
&lt;transport&gt;://&lt;host&gt;[:&lt;port&gt;][?&lt;option&gt;='&lt;value&gt;'[&amp;&lt;option&gt;='&lt;value&gt;']]
</programlisting>
          <para>
            There are currently quite a few default values that can be
            assumed. This was done so that the current client examples would
            not have to be re-written. The result is if there is no
            transport, 'tcp' is assumed and the default AMQP port of 5672 is
            used if no port is specified.
          </para><table><title>Broker URL- Transport</title>
	  <tgroup cols="1">
            <tbody>
              <row>
                <entry>
                  Transport
                </entry>
              </row>
              <row>
                <entry>
                  tcp
                </entry>
              </row>
              <row>
                <entry>
                  vm
                </entry>
              </row>
            </tbody>
          </tgroup></table><para>
            Currently only 'tcp' and 'vm' transports are supported. Each
            broker can take have additional options that are specific to that
            broker. The following are currently implemented options. To add
            support for further transports the
            ''client.transportTransportConnection'' class needs updating
            along with the parsing to handle the transport.
          </para>
	  <table><title>Broker URL - Connection Options</title>
	  <tgroup cols="3">
            <tbody>
              <row>
                <entry>
                  Option
                </entry>
                <entry>
                  Default
                </entry>
                <entry>
                  Description
                </entry>
              </row>
              <row>
                <entry>
                  retries
                </entry>
                <entry>
                  1
                </entry>
                <entry>
                  The number of times to retry connection to this Broker
                </entry>
              </row>
              <row>
                <entry>
                  ssl
                </entry>
                <entry>
                  false
                </entry>
                <entry>
                  Use ssl on the connection
                </entry>
              </row>
              <row>
                <entry>
                  connecttimeout
                </entry>
                <entry>
                  30000
                </entry>
                <entry>
                  How long in (milliseconds) to wait for the connection to
                  succeed
                </entry>
              </row>
              <row>
                <entry>
                  connectdelay
                </entry>
                <entry>
                  none
                </entry>
                <entry>
                  How long in (milliseconds) to wait before attempting to
                  reconnect
                </entry>
              </row>
            </tbody>
          </tgroup></table>
<!--h4--></section>

	  <section role="h4" id="ConnectionURLFormat-Brokerlistfailoveroption">
	    
	    <title> Brokerlist failover option </title>
            <programlisting>
failover='&lt;method&gt;[?&lt;options&gt;]'
</programlisting>
          <para>
            This option controls how failover occurs when presented with a
            list of brokers. There are only two methods currently implemented
            but interface qpid.jms.failover.FailoverMethod can be
            used for defining further methods.
          </para><para>
            Currently implemented failover methods.
          </para><table><title>Broker List - Failover Options</title><tgroup cols="2">
            <tbody>
              <row>
                <entry>
                  Method
                </entry>
                <entry>
                  Description
                </entry>
              </row>
              <row>
                <entry>
                  singlebroker
                </entry>
                <entry>
                  This will only use the first broker in the list.
                </entry>
              </row>
              <row>
                <entry>
                  roundrobin
                </entry>
                <entry>
                  This method tries each broker in turn.
                </entry>
              </row>
              <row>
                <entry>
                  nofailover
                </entry>
                <entry>
                  [New in 0.5] This method disables all retry and failover
                  logic.
                </entry>
              </row>
            </tbody>
          </tgroup></table><para>
            The current defaults are naturally to use the 'singlebroker' when
            only one broker is present and the 'roundrobin' method with
            multiple brokers. The '''method''' value in the URL may also be
            any valid class on the classpath that implements the
            FailoverMethod interface.
          </para><para>
            The 'nofailover' method is useful if you are using a 3rd party
            tool such as Mule that has its own reconnection strategy that you
            wish to use.
          </para>

          <table>
	    <title>Broker List - Failover Options</title>
	  <tgroup cols="3">
            <tbody>
              <row>
                <entry>
                  Option
                </entry>
                <entry>
                  Default
                </entry>
                <entry>
                  Description
                </entry>
              </row>
              <row>
                <entry>
                  cyclecount
                </entry>
                <entry>
                  1
                </entry>
                <entry>
                  The number of times to loop through the list of available
                  brokers before failure.
                </entry>
              </row>
            </tbody>
          </tgroup></table><para>
            <emphasis>Note:</emphasis> Default was changed from 0 to 1 in Release 0.5
          </para>
<!--h4--></section>

	  <section role="h3" id="ConnectionURLFormat-SampleURLs">

	    <title>
	      Sample URLs
	    </title>
            <programlisting>
amqp:///test?brokerlist='localhost'
amqp:///test?brokerlist='tcp://anotherhost:5684?retries='10''
amqp://guest:guest@/test?brokerlist='vm://:1;vm://:2'&amp;failover='roundrobin'
amqp://guest:guest@/test?brokerlist='vm://:1;vm://:2'&amp;failover='roundrobin?cyclecount='20''
amqp://guest:guest@client/test?brokerlist='tcp://localhost;tcp://redundant-server:5673?ssl='true''&amp;failover='roundrobin'
amqp://guest:guest@/test?brokerlist='vm://:1'&amp;failover='nofailover'
</programlisting>

<!--h3--></section>
</section>