Chapter 4. Configuration

This chapter describes the process for binding the AMQ Core Protocol JMS implementation to your JMS application and setting configuration options.

JMS uses the Java Naming Directory Interface (JNDI) to register and look up API implementations and other resources. This enables you to write code to the JMS API without tying it to a particular implementation.

Configuration options are exposed as query parameters on the connection URI. Some of the options are also exposed as corresponding set and get methods on the ConnectionFactory implementation object.

4.1. Configuring the initial context factory

JMS applications use a JNDI InitialContext object obtained from an InitialContextFactory to look up JMS objects such as the connection factory. AMQ Core Protocol JMS provides an implementation of the InitialContextFactory in the org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory class.

The InitialContextFactory implementation is discovered when the InitialContext object is instantiated: 

javax.naming.Context context = new javax.naming.InitialContext();

To find an implementation, JNDI must be configured in your environment. There are two main ways of achieving this, using a jndi.properties file or using a system property.

Using a jndi.properties file

Create a file named jndi.properties and place it on the Java classpath. Add a property with the key java.naming.factory.initial.

Example: Setting the JNDI initial context factory using a jndi.properties file

java.naming.factory.initial = org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory

In Maven-based projects, the jndi.properties file is placed in the <project-dir>/src/main/resources directory.

Using a system property

Set the java.naming.factory.initial system property.

Example: Setting the JNDI initial context factory using a system property

$ java -Djava.naming.factory.initial=org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory ...

4.2. Configuring the connection factory

The JMS connection factory is the entry point for creating connections. It uses a connection URI that encodes your application-specific configuration settings.

To set the factory name and connection URI, create a property in the format below. You can store this configuration in a jndi.properties file or set the corresponding system property.

The JNDI property format for connection factories

connectionFactory.<factory-name> = <connection-uri>

For example, this is how you might configure a factory named app1:

Example: Setting the connection factory in a jndi.properties file

connectionFactory.app1 = tcp://example.net:61616?clientID=backend

You can then use the JNDI context to look up your configured connection factory using the name app1: 

ConnectionFactory factory = (ConnectionFactory) context.lookup("app1");

4.3. Connection URIs

A connection factory is configured using a connection URI in the following format:

The connection URI format

tcp://<host>:<port>[?<option>=<value>[&<option>=<value>...]]

For example, the following is a connection URI that connects to host example.net at port 61616 and sets the client ID to backend:

Example: A connection URI

tcp://example.net:61616?clientID=backend

Failover URIs take the following form:

The failover URI format

(<connection-uri>[,<connection-uri>])[?<option>=<value>[&<option>=<value>...]]

The available connection options are described in the following sections.

4.4. JMS options

user
The user name used to authenticate the connection.
password
The password used to authenticate the connection.
clientID
The client ID that is applied to the connection.
groupID
The group ID that is applied to all produced messages.
autoGroup
If enabled, generated a random group ID and apply it to all produced messages.
cacheDestinations
If enabled, cache destination lookups. It is disabled by default.
blockOnDurableSend
If enabled, when sending non-transacted durable messages, block until the remote peer acknowledges receipt. It is enabled by default.
blockOnNonDurableSend
If enabled, when sending non-transacted non-durable messages, block until the remote peer acknowledges receipt. It is disabled by default.
blockOnAcknowledge
If enabled, when acknowledging non-transacted received messages, block until the remote peer confirms acknowledgment. It is disabled by default.
dupsOkBatchSize
When using the DUPS_OK_ACKNOWLEDGE acknowledgment mode, the size in bytes of acknowledgment batches. The default is 1048576 (1 MiB).
preAcknowledge
If enabled, acknowledge messages as soon as they are sent and before delivery is complete. This provides "at most once" delivery. It is disabled by default.

4.5. TCP options

tcpNoDelay
If enabled, do not delay and buffer TCP sends. It is enabled by default.
tcpSendBufferSize
The send buffer size in bytes. The default is 32768 (32 KiB).
tcpReceiveBufferSize
The receive buffer size in bytes. The default is 32768 (32 KiB).
writeBufferLowWaterMark
The limit in bytes below which the write buffer becomes writable. The default is 32768 (32 KiB).
writeBufferHighWaterMark
The limit in bytes above which the write buffer becomes non-writable. The default is 131072 (128 KiB).

4.6. SSL/TLS options

sslEnabled
If enabled, use SSL/TLS to authenticate and encrypt connections. It is disabled by default.
keyStorePath
The path to the SSL/TLS key store. A key store is required for mutual SSL/TLS authentication. If unset, the value of the javax.net.ssl.keyStore system property is used.
keyStorePassword
The password for the SSL/TLS key store. If unset, the value of the javax.net.ssl.keyStorePassword system property is used.
trustStorePath
The path to the SSL/TLS trust store. If unset, the value of the javax.net.ssl.trustStore system property is used.
trustStorePassword
The password for the SSL/TLS trust store. If unset, the value of the javax.net.ssl.trustStorePassword system property is used.
trustAll
If enabled, trust the provided server certificate implicitly, regardless of any configured trust store. It is disabled by default.
verifyHost
If enabled, verify that the connection hostname matches the provided server certificate. It is disabled by default.
enabledCipherSuites
A comma-separated list of cipher suites to enable. If unset, the JVM default ciphers are used.
enabledProtocols
A comma-separated list of SSL/TLS protocols to enable. If unset, the JVM default protocols are used.

4.7. Core Protocol options

clientFailureCheckPeriod
The time in milliseconds between checks for dead connections. The default is 30000 (30 seconds). -1 disables checking.
connectionTTL
The time in milliseconds after which the connection is failed if the server sends no ping packets. The default is 60000 (1 minute). -1 disables the timeout.
consumerWindowSize
The size in bytes of the per-consumer message prefetch buffer. The default is 1048576 (1 MiB). -1 means no limit. 0 disables prefetching.
consumerMaxRate
The maximum number of messages to consume per second. The default is -1, meaning no limit.
producerWindowSize
The requested size in bytes for credit to produce more messages. This limits the total amount of data in flight at one time. The default is 1048576 (1 MiB). -1 means no limit.
producerMaxRate
The maximum number of messages to produce per second. The default is -1, meaning no limit.
transactionBatchSize
When receiving messsages in a transaction, the size in bytes of acknowledgment batches. The default is 1048576 (1 MiB).

4.8. Failover options

reconnnectAttempts
The number of reconnection attempts allowed before reporting the connection as failed. The default is -1, meaning no limit.
initialConnectAttempts
The number of reconnection attempts allowed before the first successful connection and before the client discovers the broker topology. The default is 0, meaning only one attempt is allowed.
failoverOnInitialConnection
If enabled, attempt to connect to the backup server if the initial connection fails. It is disabled by default.

4.9. Discovery options

ha
If enabled, track changes in the topology of HA brokers. The host and port from the URI is used only for the initial connection. After initial connection, the client receives the current failover endpoints and any updates resulting from topology changes. It is disabled by default.
useTopologyForLoadBalancing
If enabled, use the cluster topology for connection load balancing. It is enabled by default.

4.10. Large message options

The client can enable large message support by setting a value for the property minLargeMessageSize. Any message larger than minLargeMessageSize is considered a large message.

minLargeMessageSize
The minimum size in bytes at which a message is treated as a large message. The default is 102400 (100 KiB).
compressLargeMessages

If enabled, compress large messages, as defined by minLargeMessageSize. It is disabled by default.

Note

If the compressed size of a large message is less than the value of minLargeMessageSize, the message is sent as a regular message. Therefore, it is not written to the broker’s large-message data directory.

4.11. Configuring JNDI resources

4.11.1. Configuring queue and topic names

JMS provides the option of using JNDI to look up deployment-specific queue and topic resources.

To set queue and topic names in JNDI, create properties in the following format. Either place this configuration in a jndi.properties file or define corresponding system properties.

The JNDI property format for queues and topics

queue.<queue-lookup-name> = <queue-name>
topic.<topic-lookup-name> = <topic-name>

For example, the following properties define the names jobs and notifications for two deployment-specific resources:

Example: Setting queue and topic names in a jndi.properties file

queue.jobs = app1/work-items
topic.notifications = app1/updates

You can then look up the resources by their JNDI names: 

Queue queue = (Queue) context.lookup("jobs");
Topic topic = (Topic) context.lookup("notifications");

4.11.2. Setting JNDI properties programatically

As an alternative to using a jndi.properties file or system properties to configure JNDI, you can define properties programatically using the JNDI initial context API.

Example: Setting JNDI properties programatically

Hashtable<Object, Object> env = new Hashtable<>();

env.put("java.naming.factory.initial", "org.apache.activemq.artemis.jndi.ActiveMQInitialContextFactory");
env.put("connectionFactory.app1", "tcp://example.net:61616?clientID=backend");
env.put("queue.jobs", "app1/work-items");
env.put("topic.notifications", "app1/updates");

InitialContext context = new InitialContext(env);