Using the AMQ JMS Client

AMQ JMS supports the following industry-recognized standards and network protocols:

AMQ JMS supports the OS and language versions listed below. For more information, see Red Hat AMQ 7 Supported Configurations.

AMQ JMS is supported in combination with the following AMQ components and versions:

This section introduces the core API entities and describes how they operate together.

AMQ JMS sends and receives messages. Messages are transferred between connected peers using message producers and consumers. Producers and consumers are established over sessions. Sessions are established over connections. Connections are created by connection factories.

A sending peer creates a producer to send messages. The producer has a destination that identifies a target queue or topic at the remote peer. A receiving peer creates a consumer to receive messages. Like the producer, the consumer has a destination that identifies a source queue or topic at the remote peer.

A destination is either a queue or a topic. In JMS, queues and topics are client-side representations of named broker entities that hold messages.

A queue implements point-to-point semantics. Each message is seen by only one consumer, and the message is removed from the queue after it is read. A topic implements publish-subscribe semantics. Each message is seen by multiple consumers, and the message remains available to other consumers after it is read.

See the JMS tutorial for more information.

The sudo command

In this document, sudo is used for any command that requires root privileges. Exercise caution when using sudo because any changes can affect the entire system. For more information about sudo, see Using the sudo command.

File paths

In this document, all file paths are valid for Linux, UNIX, and similar operating systems (for example, /home/andrea). On Microsoft Windows, you must use the equivalent Windows paths (for example, C:\Users\andrea).

Variable text

This document contains code blocks with variables that you must replace with values specific to your environment. Variable text is enclosed in arrow braces and styled as italic monospace. For example, in the following command, replace <project-dir> with the value for your environment:

$ cd <project-dir>

Configure your Maven environment to download the client library from the Red Hat Maven repository.

The client is now available in your Maven project.

As an alternative to the online repository, AMQ JMS can be installed to your local filesystem as a file-based Maven repository.

The resulting local directory is referred to as <source-dir> throughout this document.

The Hello World example creates a connection to the broker, sends a message containing a greeting to the queue queue, and receives it back. On success, it prints the received message to the console.

For example, running it on Linux results in the following output:

$ java -cp "target/classes/:target/dependency/*" org.apache.qpid.jms.example.HelloWorld
Hello world!

The source code for the example is in the <source-dir>/qpid-jms-examples/src/main/java directory. The JNDI and logging configuration is in the <source-dir>/qpid-jms-examples/src/main/resources directory.

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.

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.

Applications using JMS typically use JNDI to obtain the ConnectionFactory and Destination objects used by the application. This keeps the configuration separate from the program and insulates it from the particular client implementation.

For the purpose of using these examples, a file named jndi.properties should be placed on the classpath to configure the JNDI context, as detailed previously.

The contents of the jndi.properties file should match what is shown below, which establishes that the client’s InitialContextFactory implementation should be used, configures a ConnectionFactory to connect to a local server, and defines a destination queue named queue.

# Configure the InitialContextFactory class to use
java.naming.factory.initial = org.apache.qpid.jms.jndi.JmsInitialContextFactory

# Configure the ConnectionFactory
connectionfactory.myFactoryLookup = amqp://localhost:5672

# Configure the destination
queue.myDestinationLookup = queue

This example first creates a JNDI Context, uses it to look up a ConnectionFactory and Destination, creates and starts a Connection using the factory, and then creates a Session. Then a MessageProducer is created to the Destination, and a message is sent using it. The Connection is then closed, and the program exits.

A runnable variant of this Sender example is in the <source-dir>/qpid-jms-examples directory, along with the Hello World example covered previously in Chapter 3, Getting started.

package org.jboss.amq.example;

import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.DeliveryMode;
import javax.jms.Destination;
import javax.jms.ExceptionListener;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageProducer;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.naming.Context;
import javax.naming.InitialContext;

public class Sender {
  public static void main(String[] args) throws Exception {
    try {
      Context context = new InitialContext(); 1

      ConnectionFactory factory = (ConnectionFactory) context.lookup("myFactoryLookup");
      Destination destination = (Destination) context.lookup("myDestinationLookup"); 2

      Connection connection = factory.createConnection("<username>", "<password>");
      connection.setExceptionListener(new MyExceptionListener());
      connection.start(); 3

      Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); 4

      MessageProducer messageProducer = session.createProducer(destination); 5

      TextMessage message = session.createTextMessage("Message Text!"); 6
      messageProducer.send(message, DeliveryMode.NON_PERSISTENT,
                           Message.DEFAULT_PRIORITY, Message.DEFAULT_TIME_TO_LIVE); 7

      connection.close(); 8
    } catch (Exception exp) {
      System.out.println("Caught exception, exiting.");
      exp.printStackTrace(System.out);
      System.exit(1);
    }
  }

  private static class MyExceptionListener implements ExceptionListener {
    @Override
    public void onException(JMSException exception) {
      System.out.println("Connection ExceptionListener fired, exiting.");
      exception.printStackTrace(System.out);
      System.exit(1);
    }
  }
}

Note that this is only an example. A real-world application would typically use a long-lived MessageProducer and send many messages using it over time. Opening and then closing a Connection, Session, and MessageProducer per message is generally not efficient.

This example starts by creating a JNDI Context, using it to look up a ConnectionFactory and Destination, creating and starting a Connection using the factory, and then creates a Session. Then a MessageConsumer is created for the Destination, a message is received using it, and its contents are printed to the console. The Connection is then closed and the program exits. The same JNDI configuration is used as in the sending example.

An executable variant of this Receiver example is contained within the examples directory of the client distribution, along with the Hello World example covered previously in Chapter 3, Getting started.

package org.jboss.amq.example;

import javax.jms.Connection;
import javax.jms.ConnectionFactory;
import javax.jms.Destination;
import javax.jms.ExceptionListener;
import javax.jms.JMSException;
import javax.jms.Message;
import javax.jms.MessageConsumer;
import javax.jms.Session;
import javax.jms.TextMessage;
import javax.naming.Context;
import javax.naming.InitialContext;

public class Receiver {
  public static void main(String[] args) throws Exception {
    try {
      Context context = new InitialContext(); 1

      ConnectionFactory factory = (ConnectionFactory) context.lookup("myFactoryLookup");
      Destination destination = (Destination) context.lookup("myDestinationLookup"); 2

      Connection connection = factory.createConnection("<username>", "<password>");
      connection.setExceptionListener(new MyExceptionListener());
      connection.start(); 3

      Session session = connection.createSession(false, Session.AUTO_ACKNOWLEDGE); 4

      MessageConsumer messageConsumer = session.createConsumer(destination); 5

      Message message = messageConsumer.receive(5000); 6

      if (message == null) { 7
        System.out.println("A message was not received within given time.");
      } else {
        System.out.println("Received message: " + ((TextMessage) message).getText());
      }

      connection.close(); 8
    } catch (Exception exp) {
      System.out.println("Caught exception, exiting.");
      exp.printStackTrace(System.out);
      System.exit(1);
    }
 }

  private static class MyExceptionListener implements ExceptionListener {
    @Override
    public void onException(JMSException exception) {
      System.out.println("Connection ExceptionListener fired, exiting.");
      exception.printStackTrace(System.out);
      System.exit(1);
    }
  }
}

Note that this is only an example. A real-world application would typically use a long-lived MessageConsumer and receive many messages using it over time. Opening and then closing a Connection, Session, and MessageConsumer for each message is generally not efficient.

SSL/TLS connections can be configured to use a native OpenSSL implementation for improved performance. To use OpenSSL, the transport.useOpenSSL option must be enabled, and an OpenSSL support library must be available on the classpath.

To use the system-installed OpenSSL libraries on Red Hat Enterprise Linux, install the openssl and apr RPM packages and add the following dependency to your POM file:

<dependency>
  <groupId>io.netty</groupId>
  <artifactId>netty-tcnative</artifactId>
  <version>2.0.34.Final-redhat-00001</version>
  <classifier>linux-x86_64-fedora</classifier>
</dependency>

A list of OpenSSL library implementations is available from the Netty project.

The client can be configured to authenticate using Kerberos when used with an appropriately configured server. To enable Kerberos, use the following steps.

The precise configuration used will depend on how you wish the credentials to be established for the connection, and the particular LoginModule in use. For details of the Oracle Krb5LoginModule, see the Oracle Krb5LoginModule class reference. For details of the IBM Java 8 Krb5LoginModule, see the IBM Krb5LoginModule class reference.

It is possible to configure a LoginModule to establish the credentials to use for the Kerberos process, such as specifying a principal and whether to use an existing ticket cache or keytab. If, however, the LoginModule configuration does not provide the means to establish all necessary credentials, it may then request and be passed the username and password values from the client Connection object if they were either supplied when creating the Connection using the ConnectionFactory or previously configured via its URI options.

Note that Kerberos is supported only for authentication purposes. Use SSL/TLS connections for encryption.

The following connection URI options can be used to influence the Kerberos authentication process.

Similar to the amqp. and transport. options detailed previously, these options must be specified on a per-host basis or as all-host nested options in a failover URI.

Messaging systems use message acknowledgment to track if the goal of sending a message is truly accomplished.

When a message is sent, there is a period of time after the message is sent and before it is acknowledged (the message is "in flight"). If the network connection is lost during that time, the status of the message delivery is unknown, and the delivery might require special handling in application code to ensure its completion.

The sections below describe the conditions for message delivery when connections fail.

Non-transacted producer with an unacknowledged delivery

If a message is in flight, it is sent again after reconnect, provided a send timeout is not set and has not elapsed.

No user action is required.

Transacted producer with an uncommitted transaction

If a message is in flight, it is sent again after reconnect. If the send is the first in a new transaction, then sending continues as normal after reconnect. If there are previous sends in the transaction, then the transaction is considered failed, and any subsequent commit operation throws a TransactionRolledBackException.

To ensure delivery, the user must resend any messages belonging to a failed transaction.

Transacted producer with a pending commit

If a commit is in flight, then the transaction is considered failed, and any subsequent commit operation throws a TransactionRolledBackException.

To ensure delivery, the user must resend any messages belonging to a failed transaction.

Non-transacted consumer with an unacknowledged delivery

If a message is received but not yet acknowledged, then acknowledging the message produces no error but results in no action by the client.

Because the received message is not acknowledged, the producer might resend it. To avoid duplicates, the user must filter out duplicate messages by message ID.

Transacted consumer with an uncommitted transaction

If an active transaction is not yet committed, it is considered failed, and any pending acknowledgments are dropped. Any subsequent commit operation throws a TransactionRolledBackException.

The producer might resend the messages belonging to the transaction. To avoid duplicates, the user must filter out duplicate messages by message ID.

Transacted consumer with a pending commit

If a commit is in flight, then the transaction is considered failed. Any subsequent commit operation throws a TransactionRolledBackException.

The producer might resend the messages belonging to the transaction. To avoid duplicates, the user must filter out duplicate messages by message ID.

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

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.

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.

AMQP messages are composed using the AMQP type system. Having this common format is one of the reasons AMQP clients in different languages are able to interoperate with each other. This section serves to document behaviour around the AMQP payloads sent and received by the client in relation to the various JMS Message types used, to aid in using the client along with other AMQP clients.

AMQ Broker is designed to interoperate with AMQP 1.0 clients. Check the following to ensure the broker is configured for AMQP messaging:

AMQ Interconnect works with any AMQP 1.0 client. Check the following to ensure the components are configured correctly: