This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • Connection URL Format
Skip to end of metadata
Go to start of metadata

This page is out of date and should not be used. Please refer to the Qpid JMS client books for up to date documentation.

Format

amqp://[<user>:<pass>@][<clientid>]<virtualhost>[?<option>='<value>'[&<option>='<value>']]

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 brokerlist option. In addition the following options are recognised.

Worked Example

You could use a URL which looks something like this:

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

Breaking this example down, here's what it all means:

amqp = the protocol we're using

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.

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 [.-_+!=:].

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.

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:

brokerlist='tcp://host1&tcp://host2:5673'

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 !

Options

Option

Default

Description

brokerlist

see below

The list of brokers to use for this connection

failover

see below

The type of failover method to use with the broker list.

maxprefetch

5000

The maximum number of messages to prefetch from the broker.

Brokerlist option

brokerlist='<broker url>[;<broker url>]'

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.

Broker URL format

<transport>://<host>[:<port>][?<option>='<value>'[&<option>='<value>']]

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.

Transport

tcp

vm

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.

Option

Default

Description

retries

1

The number of times to retry connection to this Broker

ssl

false

Use ssl on the connection

connecttimeout

30000

How long in (milliseconds) to wait for the connection to succeed

connectdelay

none

How long in (milliseconds) to wait before attempting to reconnect

Brokerlist failover option

failover='<method>[?<options>]'

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.

Currently implemented failover methods.

Method

Description

singlebroker

This will only use the first broker in the list.

roundrobin

This method tries each broker in turn.

nofailover

[New in 0.5] This method disables all retry and failover logic.

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.

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.

Options

Option

Default

Description

cyclecount

1

The number of times to loop through the list of available brokers before failure.

Note: Default was changed from 0 to 1 in Release 0.5

Sample URLs

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'
  • No labels