Chapter 4. Configuration

JMS applications use a JNDI InitialContext object obtained from an InitialContextFactory to look up JMS objects such as the connection factory. AMQ JMS provides an implementation of the InitialContextFactory in the org.apache.qpid.jms.jndi.JmsInitialContextFactory 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 three ways of achieving this: using a jndi.properties file, using a system property, or using the initial context API.

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.

java.naming.factory.initial = org.apache.qpid.jms.jndi.JmsInitialContextFactory

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.

$ java -Djava.naming.factory.initial=org.apache.qpid.jms.jndi.JmsInitialContextFactory ...

Using the initial context API

Use the JNDI initial context API to set properties programatically.

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

env.put("java.naming.factory.initial", "org.apache.qpid.jms.jndi.JmsInitialContextFactory");

InitialContext context = new InitialContext(env);

Note that you can use the same API to set the JNDI properties for connection factories, queues, and topics.

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.

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

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

connectionFactory.app1 = amqp://example.net:5672?jms.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");

Connections are configured using a connection URI. The connection URI specifies the remote host, port, and a set of configuration options, which are set as query parameters. For more information about the available options, see Chapter 5, Configuration options.

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

The scheme is amqp for unencrypted connections and amqps for SSL/TLS connections.

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

amqp://example.net:5672?jms.clientID=backend

Failover URIs

When failover is configured, the client can reconnect to another server automatically if the connection to the current server is lost. Failover URIs have the prefix failover: and contain a comma-separated list of connection URIs inside parentheses. Additional options are specified at the end.

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

For example, the following is a failover URI that can connect to either of two hosts, host1 or host2:

failover:(amqp://host1:5672,amqp://host2:5672)?jms.clientID=backend

As with the connection URI example, the client can be configured with a number of different settings using the URI in a failover configuration. These settings are detailed in Chapter 5, Configuration options, with the Section 5.5, “Failover options” section being of particular interest.

SSL/TLS Server Name Indication

When the amqps scheme is used to specify an SSL/TLS connection, the host segment from the URI can be used by the JVM’s TLS Server Name Indication (SNI) extension to communicate the desired server hostname during a TLS handshake. The SNI extension is automatically included if a fully qualified domain name (for example, "myhost.mydomain") is specified, but not when an unqualified name (for example, "myhost") or a bare IP address is used.

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 set corresponding system properties.

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

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

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");

JNDI property values can contain variables of the form ${<variable-name>}. The library resolves the variable value by searching in order in the following locations:

For example, on Linux ${HOME} resolves to the HOME environment variable, the current user’s home directory.

A default value can be supplied using the syntax ${<variable-name>:-<default-value>}. If no value for <variable-name> is found, the default value is used instead.