20.5. Connection URLs
In JNDI properties, a Connection URL specifies properties 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, and a TCP host with the host name localhost using port 5672:
amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672'
Apache Qpid supports the following properties in Connection URLs:
| Option | Type | Description |
|---|---|---|
brokerlist
|
The broker to use for this connection. In the current release, precisely one broker must be specified.
| |
max_prefetch
|
Integer
|
The maximum number of pre-fetched messages per destination.
|
sync_publish
|
{'persistent' | 'transient' | 'all' | ''}
|
A sync command is sent after every persistent or transient message to guarantee that it has been received.
persistent sets this behavior for persistent messages.
transient sets this behavior for transient messages only.
all syncs both type of messages, however the default behavior '' also has the same effect.
|
sync_ack
|
Boolean
|
A sync command is sent after every acknowledgment to guarantee that it has been received.
|
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.7 release, you must set this to
true to ensure the older clients can understand the map message encoding.
|
failover
| {'roundrobin' | 'failover_exchange' | 'singlebroker' | 'nofailover' | '<class>'}
|
|
ssl |
Boolean
|
If
ssl='true', use SSL for all broker connections. Overrides any per-broker settings in the brokerlist entries. If not specified, the brokerlist entry for each given broker is used to determine whether SSL is used.
|
Broker list URL
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 URL:
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. In general, it is better to use the failover exchange when using multiple brokers, since it allows applications to fail over if a broker goes down.
Example 20.1. Broker Lists
A broker list can specify properties to be used when connecting to the broker, such as security options. This broker list specifies options for a Kerberos connection using GSSAPI:
amqp://guest:guest@test/test?sync_ack='true' &brokerlist='tcp://ip1:5672?sasl_mechs='GSSAPI''
This broker list specifies SSL options:
amqp://guest:guest@test/test?sync_ack='true' &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''
The following broker list URL options are supported:
| Option | Type | Description |
|---|---|---|
idle_timeout
|
Integer
|
Frequency of idle_timeout messages (in seconds)
|
sasl_mechs
|
--
|
For secure applications, we suggest
CRAM-MD5, DIGEST-MD5, or GSSAPI. The ANONYMOUS method is not secure. The PLAIN method is secure only when used together with SSL. For Kerberos, sasl_mechs must be set to GSSAPI, sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/, and sasl_server must be set to the host for the SASL server, e.g. sasl.com. SASL External is supported using SSL certification, e.g. ssl='true'&sasl_mechs='EXTERNAL'
|
sasl_encryption
|
Boolean
|
If
sasl_encryption='true', the JMS client attempts to negotiate a security layer with the broker using GSSAPI to encrypt the connection. Note that for this to happen, GSSAPI must be selected as the sasl_mech.
|
ssl
|
Boolean
|
If
ssl='true', the JMS client will encrypt the connection using SSL.
|
tcp_nodelay
|
Boolean
|
If
tcp_nodelay='true', TCP packet batching is disabled.
|
sasl_protocol
|
--
|
Used only for Kerberos.
sasl_protocol must be set to the principal for the qpidd broker, e.g. qpidd/
|
sasl_server
|
--
|
For Kerberos,
sasl_mechs must be set to GSSAPI, sasl_server must be set to the host for the SASL server, e.g. sasl.com.
|
trust_store
|
String
|
Path to Kerberos trust store
|
trust_store_password
|
String
|
Kerberos trust store password
|
key_store
|
String
|
Path to Kerberos key store
|
key_store_password
|
String
|
Kerberos key store password
|
ssl_verify_hostname
|
Boolean
|
When using SSL you can enable hostname verification by using "
ssl_verify_hostname=true" in the broker URL.
|
ssl_cert_alias
|
String
|
If multiple certificates are present in the keystore, the alias will be used to extract the correct certificate.
|
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. |
