Menu Search
Chapter 7. Connection URLs
Prev   Next

Chapter 7. 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:

Table 7.1. 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.

sync_publish String

If the value is 'all' the client library waits for confirmation before returning from a send(), and if the send is unsuccessful the send() will throw a JMSException. (Note this option requires an extension to the AMQP protocol and will only work against a broker of the 0.32 release or later.)

sync_client_ack Boolean

If set true, for sessions using Session#CLIENT_ACKNOWLEDGE, a sync command is sent after every message Message#acknowledge(). This ensure that the client awaits the successful processing of the acknowledgement by server before continuing.

If false, the sync is not performed. This will improve performance but will mean duplicate messages are more likely to be received following a failure.

Defaults to true.

Note: You can also set the default 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 Section 5.5.2, “Close When No Route”.

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.

compressMessagesBoolean

Controls whether the client will compress messages before they they are sent.

messageCompressionThresholdSizeInteger

The payload size beyond which the client will start to compress message payloads.

populateJMSXUserIDboolean

Controls whether a MessageProducer will populate the JMSXUserID value for each sent message using the authenticated username from the connection. It is set to true by default.


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 separated by semicolons (;). If so, the connection is made to the first broker in the list that is available.

Example 7.1. 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.

Table 7.2. 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.

sasl_mechs - A space separated list of SASL mechanisms which may be used. If not present then any method offered by the broker may be used. For secure applications, we suggest SCRAM-SHA-256. The ANONYMOUS mechanism is not secure. The PLAIN mechanism is secure only when used together with SSL. 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.
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_server must be set to the host for the SASL server, e.g. sasl.com.
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.
trusted_certs_path String Path to a file containing trusted peer certificates(in PEM or DER format). Used when supplying the trust information for TLS client auth using PEM/DER files rather than a Java KeyStore.
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.
client_cert_path String Path to the client certificate file (in PEM or DER format). Used as an alternative to using a Java KeyStore to hold key information for TLS client auth. When used, the client_cert_priv_key_path must also be supplied.
client_cert_priv_key_path String Path to the client certificate private key file (in PEM or DER format). Used when supplying the key information for TLS client auth using PEM/DER files rather than a Java KeyStore.
client_cert_intermediary_cert_path String Path to a file containing any intermediary certificates (in PEM or DER format). Used when supplying the key information for TLS client auth using PEM/DER files rather than a Java KeyStore. Only required where intermediary certificates are required in the certificate chain.
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 This option is used for turning on/off hostname verification when using SSL. It is set to 'true' by default. You can disable verification by setting it to 'false': ssl_verify_hostname='false'.
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.
encryption_trust_store String Path to trust store. Used when using Message Encryption this path is used for the trust store containing the X509 Certificates of potential recipients.
encyrption_trust_store_password String Trust store password. Password used to open the Message Encryption trust store.
encryption_remote_trust_store String Remote Trust Store. The address of a message source on the broker which will be used to obtain a trust store containing the X509 Certificates of potential recipients of encrypted messages.
encryption_key_store String Path to key store. Used when using Message Encryption this path is used for the key store containing the certificates and private keys for all the identities which this client can decrypt.
encyrption_key_store_password String Key store password. Password used to open the Message Encryption key store.

Prev   Next
6.4. Destination Home Chapter 8. Binding URL

Apache Qpid, Messaging built on AMQP; Copyright © 2015 The Apache Software Foundation; Licensed under the Apache License, Version 2.0; Apache Qpid, Qpid, Qpid Proton, Proton, Apache, the Apache feather logo, and the Apache Qpid project logo are trademarks of The Apache Software Foundation; All other marks mentioned may be trademarks or registered trademarks of their respective owners