Chapter 5. Configuration options

These options control the behaviour of JMS objects such as Connection, Session, MessageConsumer, and MessageProducer.

Prefetch policy options

Prefetch policy determines how many messages each MessageConsumer fetches from the remote peer and holds in a local "prefetch" buffer.

The value of prefetch can affect the distribution of messages to multiple consumers on a queue or shared subscription. A higher value can result in larger batches sent at once to each consumer. To achieve more even round-robin distribution, use a lower value.

Redelivery policy options

Redelivery policy controls how redelivered messages are handled on the client.

Message ID policy options

Message ID policy controls the data type of the message ID assigned to messages sent from the client.

Presettle policy options

Presettle policy controls when a producer or consumer instance is configured to use AMQP presettled messaging semantics.

Deserialization policy options

Deserialization policy provides a means of controlling which Java types are trusted to be deserialized from the object stream while retrieving the body from an incoming ObjectMessage composed of serialized Java Object content. By default all types are trusted during an attempt to deserialize the body. The default deserialization policy provides URI options that allow specifying a whitelist and a blacklist of Java class or package names.

When connected to a remote server using plain TCP, the following options specify the behavior of the underlying socket. These options are appended to the connection URI along with any other configuration options.

amqp://localhost:5672?jms.clientID=foo&transport.connectTimeout=30000

The complete set of TCP transport options is listed below.

The SSL/TLS transport is enabled by using the amqps URI scheme. Because the SSL/TLS transport extends the functionality of the TCP-based transport, all of the TCP transport options are valid on an SSL/TLS transport URI.

amqps://myhost.mydomain:5671

The complete set of SSL/TLS transport options is listed below.

The following options apply to aspects of behavior related to the AMQP wire protocol.

Failover URIs start with the prefix failover: and contain a comma-separated list of connection URIs inside parentheses. Additional options are specified at the end. Options prefixed with jms. are applied to the overall failover URI, outside of parentheses, and affect the Connection object for its lifetime.

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. These are applied as each host is connected to.

failover:(amqp://host1:5672?amqp.option=value,amqp://host2:5672?transport.option=value)?jms.clientID=foo

All of the configuration options for failover are listed below.

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 URIs. 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 the following:

failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=foo&failover.nested.amqp.vhost=myhost

The client has an optional discovery module that provides a customized failover layer where the broker URIs to connect to are not given in the initial URI but instead are discovered by interacting with a discovery agent. 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.x brokers that are 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 changed from failover. to discovery., and with the nested prefix used to supply URI options common to all the discovered broker URIs. For example, without the agent URI details, a general discovery URI might look like the following:

discovery:(<agent-uri>)?discovery.maxReconnectAttempts=20&discovery.discovered.jms.clientID=foo

To use the file watcher discovery agent, create an agent URI like the following:

discovery:(file:///path/to/monitored-file?updateInterval=60000)

The URI options for the file watcher discovery agent are listed below.

To use the multicast discovery agent with an ActiveMQ 5.x broker, create an agent URI like the following:

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 can change this to specify the actual IP address and port in use with your multicast configuration.

The URI option for the multicast discovery agent is listed below.