# Connection URLs

In JNDI properties, a Connection URL specifies options for a connection. The format for a Connection URL is:

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

For instance, the following Connection URL specifies a user name, a password, a client ID, a virtual host ("test"), a broker list with a single broker: a TCP host with the host name localhost using port 5672:

    amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672'

Connection option quoting

Take care with the quoting surrounding option values. Each option value must be surrounded with single quotes (').

The Connection URL supports the following options:

Connection URL Options

Option | Type | Description
--- | --- | ---
brokerlist | see below | List of one or more broker addresses.
maxprefetch | integer | The maximum number of pre-fetched messages per Session. If not specified, default value of 500 is used. Note: You can also set the default per-session prefetch value on a client-wide basis by configuring the client using Java system properties.
use_legacy_map_msg_format | Boolean | If you are using JMS Map messages and deploying a new client with any JMS client older than 0.8 release, you must set this to true to ensure the older clients can understand the map message encoding.
failover | {'singlebroker' | 'roundrobin' , | 'nofailover' | '<class>'} | This option controls failover behaviour. The method `singlebroker` uses only the first broker in the list, `roundrobin` will try each broker given in the broker list until a connection is established, `nofailover` disables all retry and failover logic. Any other value is interpreted as a classname which must implement the `org.apache.qpid.jms.failover.FailoverMethod` interface. The broker list options `retries` and `connectdelay` (described below) determine the number of times a connection to a broker will be retried and the length of time to wait between successive connection attempts before moving on to the next broker in the list. The failover option `cyclecount` controls the number of times to loop through the list of available brokers before finally giving up. Defaults to `roundrobin` if the brokerlist contains multiple brokers, or `singlebroker` otherwise.
closeWhenNoRoute | boolean | See .
ssl | boolean | If `ssl='true'`, use SSL for all broker connections. Overrides any per-broker settings in the brokerlist (see below) entries. If not specified, the brokerlist entry for each given broker is used to determine whether SSL is used. Introduced in version 0.22.

Broker lists are specified using a URL in this format:

    brokerlist=<transport>://<host>[:<;port>](?<param>='<value>')(&<param>='<value>')*

For instance, this is a typical broker list:

    brokerlist='tcp://localhost:5672'

A broker list can contain more than one broker address; if so, the connection is made to the first broker in the list that is available.

Broker Lists

A broker list can specify properties to be used when connecting to the broker. This broker list specifies options for configuring heartbeating

    amqp://guest:guest@test/test?brokerlist='tcp://ip1:5672?heartbeat='5''

This broker list specifies some SSL options

    amqp://guest:guest@test/test?brokerlist='tcp://ip1:5672?ssl='true'&ssl_cert_alias='cert1''

This broker list specifies two brokers using the connectdelay and retries broker options. It also illustrates the failover connection URL property.

    amqp://guest:guest@/test?failover='roundrobin?cyclecount='2''
    	  &brokerlist='tcp://ip1:5672?retries='5'&connectdelay='2000';tcp://ip2:5672?retries='5'&connectdelay='2000''

Broker option quoting

Take care with the quoting surrounding broker option values. Each broker option value must be surrounded with their own single quotes ('). This is in addition to the quotes surround the connection option value.

The following broker list options are supported.

Broker List Options

Option | Type | Description
--- | --- | ---
heartbeat | Long | Frequency of heartbeat messages (in seconds). A value of 0 disables heartbeating. For compatibility with old client configuration, option `idle_timeout` (in milliseconds) is also supported.
ssl | Boolean | If `ssl='true'`, the JMS client will encrypt the connection to this broker using SSL. This can also be set/overridden for all brokers using the Connection URL option `ssl`.
trust_store | String | Path to trust store. Used when using SSL and the Broker's certificate is signed by a private-CA (or a self-signed certificate),
trust_store_password | String | Trust store password. Password used to open the trust store.
key_store | String | Path to key store . Used when using SSL and the client must authenticate using client-auth. If the store contains more than one certificate, `ssl_cert_alias` must be used to identify the certificate that the client must present to the Broker.
key_store_password | String | Key store password. Password used to open the key store.
ssl_cert_alias | String | If multiple certificates are present in the keystore, the alias will be used to extract the correct certificate.
ssl_verify_hostname | Boolean | When using SSL you can enable hostname verification by using `ssl_verify_hostname='true'` in the broker URL.
retries | Integer | The number of times to retry connection to each broker in the broker list. Defaults to 1.
connectdelay | integer | Length of time (in milliseconds) to wait before attempting to reconnect. Defaults to 0.
connecttimeout | integer | Length of time (in milliseconds) to wait for the socket connection to succeed. A value of 0 represents an infinite timeout, i.e. the connection attempt will block until established or an error occurs. Defaults to 30000.
tcp_nodelay | Boolean | If `tcp_nodelay='true'`, TCP packet batching is disabled. Defaults to true since Qpid 0.14.