Chapter 4. Configuration

JMS applications use a JNDI InitialContext obtained from an InitialContextFactory to look up JMS objects such as ConnectionFactory. The client provides an implementation of the InitialContextFactory in the org.apache.qpid.jms.jndi.JmsInitialContextFactory class. You can configure it three different ways.

Configuring an InitialContext using a jndi.properties file

If you include a file named jndi.properties on the classpath and set the java.naming.factory.initial property value to org.apache.qpid.jms.jndi.JmsInitialContextFactory, the client InitialContextFactory implementation is discovered when the InitialContext object is instantiated.

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

The particular ConnectionFactory, Queue, and Topic objects that you want the Context to contain are configured as properties either directly within the jndi.properties file or in a separate file whose path is referenced in jndi.properties using the java.naming.provider.url property. The syntax for these properties is detailed below.

Configuring an InitialContext using system properties

If you set the java.naming.factory.initial system property to the value org.apache.qpid.jms.jndi.JmsInitialContextFactory, the client InitialContextFactory implementation is discovered when the InitialContext object is instantiated.

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

The particular ConnectionFactory, Queue, and Topic objects that you want the context to contain are configured as properties in a file, the path to which is passed using the java.naming.provider.url system property. The syntax for these properties is detailed below.

Configuring an InitialContext programmatically

You can configure the InitialContext directly by setting an environment variable on a Hashtable environment object.

Hashtable<Object, Object> env = new Hashtable<Object, Object>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "org.apache.qpid.jms.jndi.JmsInitialContextFactory");
javax.naming.Context context = new javax.naming.InitialContext(env);

The particular ConnectionFactory, Queue, and Topic objects that you want the context to contain are configured as properties (the syntax for which is detailed below) either directly within the environment Hashtable or in a separate file whose path is referenced using the java.naming.provider.url property within the environment Hashtable.

JNDI property syntax

The property syntax used in the properties file or environment Hashtable is as follows:

For more details about the connection URI, see the next section.

As an example, consider the following properties that define a ConnectionFactory, Queue, and Topic.

connectionfactory.myFactoryLookup = amqp://localhost:5672
queue.myQueueLookup = queueA
topic.myTopicLookup = topicA

These objects could then be looked up from a Context as follows.

ConnectionFactory factory = (ConnectionFactory) context.lookup("myFactoryLookup");
Queue queue = (Queue) context.lookup("myQueueLookup");
Topic topic = (Topic) context.lookup("myTopicLookup");

Variable expansion

The JNDI property values can contain variables of the form ${<variable-name>}. The library searches for the value 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.

A ConnectionFactory is configured using a connection URI.

amqp[s]://host:port[?option=value[&option2=value...]]

The available connection settings are detailed in the Section 4.3, “Connection URI options” section.

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

failover:(amqp://host1:port[,amqp://host2:port...])[?option=value[&option2=value...]]

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 below, with the Section 4.3.5, “Failover options” section being of particular interest.

When the amqps scheme is used to specify an SSL/TLS connection, the hostname segment from the URI can be used by the JVM’s TLS SNI (Server Name Indication) 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.

AMQ JMS has a range of security-related configuration options that can be leveraged according to your application’s needs.

Basic user credentials such as username and password should be passed directly to the ConnectionFactory when creating the Connection within the application. However, if you are using the no-argument factory method, it is also possible to supply user credentials in the connection URI. For more information, see the Section 4.3.1, “JMS options” section.

Another common security consideration is use of SSL/TLS. The client connects to servers over an SSL/TLS transport when the amqps URI scheme is specified in the connection URI, with various options available to configure behavior. For more information, see the Section 4.3.3, “SSL/TLS transport options” section.

In concert with the earlier items, it may be desirable to restrict the client to allow use of only particular SASL mechanisms from those that may be offered by a server, rather than selecting from all it supports. For more information, see the Section 4.3.4, “AMQP options” section.

Applications calling getObject() on a received ObjectMessage may wish to restrict the types created during deserialization. Note that message bodies composed using the AMQP type system do not use the ObjectInputStream mechanism and therefore do not require this precaution. For more information, see the the section called “Deserialization policy options” section.

<dependency>
  <groupId>io.netty</groupId>
  <artifactId>netty-tcnative</artifactId>
  <version>2.0.25.Final-redhat-00001</version>
</dependency>

The client uses the SLF4J API, enabling users to select a particular logging implementation based on their needs. For example, users can provide the slf4j-log4j binding to select the Log4J implementation. More details on SLF4J are available from its website.

The client uses Logger names residing within the org.apache.qpid.jms hierarchy, which you can use to configure a logging implementation based on your needs.

When debugging, it is sometimes useful to enable additional protocol trace logging from the Qpid Proton AMQP 1.0 library. There are two ways to achieve this.

You can also configure the client to emit low-level tracing of input and output bytes. To enable this, add the option transport.traceBytes=true to your connection URI and configure the org.apache.qpid.jms.transports.netty.NettyTcpTransport logger to log level DEBUG.

The client offers distributed tracing based on the Jaeger implementation of the OpenTracing standard. Use the following steps to enable tracing in your application:

To view the traces your application captures, use the Jaeger Getting Started to run the Jaeger infrastructure and console.

The client supports two additional session acknowledgement modes beyond those defined in the JMS specification.

Individual acknowledge

In this mode, messages must be acknowledged individually by the application using the Message.acknowledge() method used when the session is in CLIENT_ACKNOWLEDGE mode. Unlike with CLIENT_ACKNOWLEDGE mode, only the target message is acknowledged. All other delivered messages remain unacknowledged. The integer value used to activate this mode is 101.

connection.createSession(false, 101);

No acknowledge

In this mode, messages are accepted at the server before being dispatched to the client, and no acknowledgment is performed by the client. The client supports two integer values to activate this mode, 100 and 257.

connection.createSession(false, 100);