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
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
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
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
Using a system property
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
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
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
For example, the following is a connection URI that connects to host
example.net at port
61616 and sets the client ID to
Example: A connection URI
Failover URIs take the following form:
The failover URI format
The available connection options are described in the following sections.
4.4. JMS options
- The user name used to authenticate the connection.
- The password used to authenticate the connection.
- The client ID that is applied to the connection.
- The group ID that is applied to all produced messages.
- If enabled, generated a random group ID and apply it to all produced messages.
- If enabled, cache destination lookups. It is disabled by default.
- If enabled, when sending non-transacted durable messages, block until the remote peer acknowledges receipt. It is enabled by default.
- If enabled, when sending non-transacted non-durable messages, block until the remote peer acknowledges receipt. It is disabled by default.
- If enabled, when acknowledging non-transacted received messages, block until the remote peer confirms acknowledgment. It is disabled by default.
When using the
DUPS_OK_ACKNOWLEDGEacknowledgment mode, the size in bytes of acknowledgment batches. The default is 1048576 (1 MiB).
- 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
- If enabled, do not delay and buffer TCP sends. It is enabled by default.
- The send buffer size in bytes. The default is 32768 (32 KiB).
- The receive buffer size in bytes. The default is 32768 (32 KiB).
- The limit in bytes below which the write buffer becomes writable. The default is 32768 (32 KiB).
- The limit in bytes above which the write buffer becomes non-writable. The default is 131072 (128 KiB).
4.6. SSL/TLS options
- If enabled, use SSL/TLS to authenticate and encrypt connections. It is disabled by default.
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.keyStoresystem property is used.
The password for the SSL/TLS key store. If unset, the value of the
javax.net.ssl.keyStorePasswordsystem property is used.
The path to the SSL/TLS trust store. If unset, the value of the
javax.net.ssl.trustStoresystem property is used.
The password for the SSL/TLS trust store. If unset, the value of the
javax.net.ssl.trustStorePasswordsystem property is used.
- If enabled, trust the provided server certificate implicitly, regardless of any configured trust store. It is disabled by default.
- If enabled, verify that the connection hostname matches the provided server certificate. It is disabled by default.
- A comma-separated list of cipher suites to enable. If unset, the JVM default ciphers are used.
- A comma-separated list of SSL/TLS protocols to enable. If unset, the JVM default protocols are used.
4.7. Core Protocol options
- The time in milliseconds between checks for dead connections. The default is 30000 (30 seconds). -1 disables checking.
- 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.
- The size in bytes of the per-consumer message prefetch buffer. The default is 1048576 (1 MiB). -1 means no limit. 0 disables prefetching.
- The maximum number of messages to consume per second. The default is -1, meaning no limit.
- 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.
- The maximum number of messages to produce per second. The default is -1, meaning no limit.
- When receiving messsages in a transaction, the size in bytes of acknowledgment batches. The default is 1048576 (1 MiB).
4.8. Failover options
- The number of reconnection attempts allowed before reporting the connection as failed. The default is -1, meaning no limit.
- 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.
- If enabled, attempt to connect to the backup server if the initial connection fails. It is disabled by default.
4.9. Discovery options
- 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.
- 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.
- The minimum size in bytes at which a message is treated as a large message. The default is 102400 (100 KiB).
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
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);