| <?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> |
