diff options
Diffstat (limited to 'qpid/doc/book/src/Connection-URL-Format.xml')
| -rw-r--r-- | qpid/doc/book/src/Connection-URL-Format.xml | 387 |
1 files changed, 387 insertions, 0 deletions
diff --git a/qpid/doc/book/src/Connection-URL-Format.xml b/qpid/doc/book/src/Connection-URL-Format.xml new file mode 100644 index 0000000000..cb772487cd --- /dev/null +++ b/qpid/doc/book/src/Connection-URL-Format.xml @@ -0,0 +1,387 @@ +<?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://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']] + </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&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='<broker url>[;<broker url>]' +</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> +<transport>://<host>[:<port>][?<option>='<value>'[&<option>='<value>']] +</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='<method>[?<options>]' +</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'&failover='roundrobin' +amqp://guest:guest@/test?brokerlist='vm://:1;vm://:2'&failover='roundrobin?cyclecount='20'' +amqp://guest:guest@client/test?brokerlist='tcp://localhost;tcp://redundant-server:5673?ssl='true''&failover='roundrobin' +amqp://guest:guest@/test?brokerlist='vm://:1'&failover='nofailover' +</programlisting> + +<!--h3--></section> +</section> |