21.2. QPID AMQP 1.0 JMS Client Connection URLs
The basic format of the qpid-jms client's Connection URI is as follows:
amqp://hostname:port[?option=value[&option2=value...]]
The client can be configured with a number of different settings using the URI while defining the
ConnectionFactory, these are detailed in the following tables.
The options below apply to the behavior of the JMS objects such as
Connection, Session, MessageConsumer and MessageProducer.
| Option | Description |
|---|---|
jms.username
|
User name value used to authenticate the connection
|
jms.password
|
The password value used to authenticate the connection
|
jms.clientID
|
The ClientID value that is applied to the connection.
|
jms.forceAsyncSend
|
Configures whether all Messages sent from a
MessageProducer are sent asynchronously or only those Message that qualify such as Messages inside a transaction or non-persistent messages.
|
jms.alwaysSyncSend
|
Override all asynchronous send conditions and always sends every Message from a
MessageProducer synchronously.
|
jms.sendAcksAsync
|
Causes all Message acknowledgments to be sent asynchronously.
|
jms.localMessageExpiry
|
Controls whether
MessageConsumer instances will locally filter expired Messages or deliver them. By default this value is set to true and expired messages will be filtered.
|
jms.localMessagePriority
|
If enabled pre-fetched messages are reordered locally based on their given Message priority value. Default is false.
|
jms.validatePropertyNames
|
If message property names should be validated as valid Java identifiers. Default is
true.
|
jms.queuePrefix
|
Optional prefix value added to the name of any Queue created from a JMS Session.
|
jms.topicPrefix
|
Optional prefix value added to the name of any Topic created from a JMS Session.
|
jms.closeTimeout
|
Timeout value that controls how long the client waits on Connection close before returning. (By default the client waits 15 seconds for a normal close completion event).
|
jms.connectTimeout
|
Timeout value that controls how long the client waits on Connection establishment before returning with an error. (By default the client waits 15 seconds for a connection to be established before failing).
|
jms.clientIDPrefix
|
Optional prefix value that is used for generated Client ID values when a new Connection is created for the JMS
ConnectionFactory. The default prefix is ID:.
|
jms.connectionIDPrefix
|
Optional prefix value that is used for generated Connection ID values when a new Connection is created for the JMS
ConnectionFactory. This connection ID is used when logging some information from the JMS Connection object so a configurable prefix can make breadcrumbing the logs easier. The default prefix is ID:.
|
The values below control how many messages the remote peer can send to the client and be held in a pre-fetch buffer for each consumer instance.
| Option | Description |
|---|---|
jms.prefetchPolicy.queuePrefetch
|
defaults to
1000
|
jms.prefetchPolicy.topicPrefetch
|
defaults to
1000
|
jms.prefetchPolicy.queueBrowserPrefetch
|
defaults to
1000
|
jms.prefetchPolicy.durableTopicPrefetch
|
defaults to
1000
|
jms.prefetchPolicy.all
|
used to set all prefetch values at once.
|
The
RedeliveryPolicy parameter controls how redelivered messages are handled on the client.
| Option | Description |
|---|---|
jms.redeliveryPolicy.maxRedeliveries | Controls when an incoming message is rejected based on the number of times it has been redelivered, the default value is disabled (-1). A value of zero (0) would indicate no message redeliveries are accepted, a value of five (5) would allow a message to be redelivered five times. |
When connected to a remote using plain TCP these options configure the behavior of the underlying socket. These options are appended to the connection URI along with the other configuration options, for example:
amqp://localhost:5672?jms.clientID=foo&transport.connectTimeout=30000
| Option | Description |
|---|---|
transport.sendBufferSize
|
default is
64k
|
transport.receiveBufferSize
|
default is
64k
|
transport.trafficClass
|
default is
0
|
transport.connectTimeout
|
default is
60 seconds
|
transport.soTimeout
|
default is
-1
|
transport.soLinger
|
default is
-1
|
transport.tcpKeepAlive
|
default is
false
|
transport.tcpNoDelay
|
default is
true
|
The SSL Transport extends the TCP Transport and is enabled using the amqps URI scheme. Because the SSL Transport extends the functionality of the TCP based Transport, all the TCP Transport options are valid on an SSL Transport URI.
A simple SSL based client URI is shown below:
amqps://localhost:5673
| Option | Description |
|---|---|
transport.keyStoreLocation
|
The default is to read from the system property
javax.net.ssl.keyStore
|
transport.keyStorePassword
|
The default is to read from the system property
javax.net.ssl.keyStorePassword
|
transport.trustStoreLocation
|
The default is to read from the system property
javax.net.ssl.trustStore
|
transport.trustStorePassword
|
The default is to read from the system property
javax.net.ssl.keyStorePassword
|
transport.storeType
|
The type of trust store being used. Default is
JKS.
|
transport.contextProtocol
|
The protocol argument used when getting an SSLContext. Default is
TLS.
|
transport.enabledCipherSuites
|
The cipher suites to enable, comma separated. No default, meaning the context default ciphers are used. Any disabled ciphers are removed from this.
|
transport.disabledCipherSuites
|
The cipher suites to disable, comma separated. Ciphers listed here are removed from the enabled ciphers. No default.
|
transport.enabledProtocols
|
The protocols to enable, comma separated. No default, meaning the context default protocols are used. Any disabled protocols are removed from this.
|
transport.disabledProtocols
|
The protocols to disable, comma separated. Protocols listed here are removed from the enabled protocols. Default is
SSLv2Hello,SSLv3.
|
transport.trustAll
|
Whether to trust the provided server certificate implicitly, regardless of any configured trust store. Defaults to
false.
|
transport.verifyHost
|
Whether to verify that the hostname being connected to matches with the provided server certificate. Defaults to
true.
|
transport.keyAlias
|
The alias to use when selecting a keypair from the keystore if required to send a client certificate to the server. No default.
|
| Option | Description |
|---|---|
amqp.idleTimeout
|
The idle timeout in milliseconds after which the connection will be failed if the peer sends no AMQP frames. Default is
60000.
|
amqp.vhost
|
The
vhost to connect to. Used to populate the SASL and Open hostname fields. Default is the main hostname from the Connection URI.
|
amqp.saslLayer
|
Controls whether connections use a SASL layer or not. Default is
true.
|
amqp.saslMechanisms
|
Which SASL mechanism(s) the client allows selection of, if offered by the server and usable with the configured credentials. Comma separated if specifying more than 1 mechanism. Default is to allow selection from all the clients supported mechanisms, which are currently
EXTERNAL, CRAM-MD5, PLAIN, and ANONYMOUS.
|
amqp.maxFrameSize
|
The max-frame-size value in bytes that is advertised to the peer. Default is
1048576.
|
With failover enabled the client can reconnect to a different broker automatically when the connection to the current connection is lost for some reason. The failover URI is always initiated with the
failover prefix and a list of URIs for the brokers is contained inside a set of parentheses.
The
jms. options are applied to the overall failover URI, outside the parentheses, and affect the JMS Connection object for its lifetime.
The URI for failover looks something like the following:
failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=foo&failover.maxReconnectAttempts=20
The individual broker details within the parentheses can use the
transport. or amqp. options defined earlier, with these being applied as each host is connected to:
failover:(amqp://host1:5672?amqp.option=value,amqp://host2:5672?transport.option=value)?jms.clientID=foo
| Option | Description |
|---|---|
failover.initialReconnectDelay
|
The amount of time the client will wait before the first attempt to reconnect to a remote peer. The default value is zero (
0), meaning the first attempt happens immediately.
|
failover.reconnectDelay
|
Controls the delay between successive reconnection attempts, defaults to
10 milliseconds. If the backoff option is not enabled this value remains constant.
|
failover.maxReconnectDelay
|
The maximum time that the client will wait before attempting a reconnect. This value is only used when the backoff feature is enabled to ensure that the delay does not grow too large. Defaults to
30 seconds as the max time between connect attempts.
|
failover.useReconnectBackOff
|
Controls whether the time between reconnection attempts grows based on a configured multiplier. This option defaults to
true.
|
failover.reconnectBackOffMultiplier
|
The multiplier used to grow the reconnection delay value, defaults to
2.0d.
|
failover.maxReconnectAttempts
|
The number of reconnection attempts allowed before reporting the connection as failed to the client. The default is no limit or (
-1).
|
failover.startupMaxReconnectAttempts
|
For a client that has never connected to a remote peer before this option control how many attempts are made to connect before reporting the connection as failed. The default is to use the value of
maxReconnectAttempts.
|
failover.warnAfterReconnectAttempts
|
Controls how often the client will log a message indicating that failover reconnection is being attempted. The default is to log every
10 connection attempts.
|
The failover URI also supports defining 'nested' options as a means of specifying AMQP and transport option values applicable to all the individual nested broker URI's, which can be useful to avoid repetition.
This is accomplished using the same
transport. and amqp. URI options outlined earlier for a non-failover broker URI but prefixed with failover.nested.. For example, to apply the same value for the amqp.vhost option to every broker connected to you might have a URI like:
failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=foo&failover.nested.amqp.vhost=myhost
The client has an optional Discovery module, which provides a customized failover layer where the broker URIs to connect to are not given in the initial URI, but discovered as the client operates via associated discovery agents. There are currently two discovery agent implementations, a file watcher that loads URIs from a file, and a multicast listener that works with ActiveMQ 5 brokers which have been configured to broadcast their broker addresses for listening clients.
The general set of failover related options when using discovery are the same as those detailed earlier, with the main prefix updated from failover. to discovery., and with the 'nested' options prefix used to supply URI options common to all the discovered broker URIs bring updated from
failover.nested. to discovery.discovered. For example, without the agent URI details, a general discovery URI might look like:
discovery:(<agent-uri>)?discovery.maxReconnectAttempts=20&discovery.discovered.jms.clientID=foo
To use the file watcher discovery agent, utilize an agent URI of the form:
discovery:(file:///path/to/monitored-file?updateInterval=60000)
The URI option for the file watcher discovery agent is
updateInterval. It controls the frequency in milliseconds which the file is inspected for change. The default value is 30000.
To use the multicast discovery agent with an ActiveMQ 5 broker, utilize an agent URI of the form:
discovery:(multicast://default?group=default)
Note that the use of default as the host in the multicast agent URI above is a special value (that is substituted by the agent with the default
239.255.2.3:6155). You may change this to specify the actual IP and port in use with your multicast configuration.
The URI option for the multicast discovery agent is
group. It controls which multicast group messages are listened for on. The default value is default.
