AMQ JMS gives you all of the features of JMS with the power of AMQP.

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

AMQ JMS supports the following OS and language versions. See Red Hat JBoss AMQ 7 Supported Configurations for more information.

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.

This document uses the following conventions for the sudo command and file paths.

The sudo Command

In this document, sudo is used for any command that requires root privileges. You should always exercise caution when using sudo, as any changes can affect the entire system.

For more information about using sudo, see The sudo Command.

About the Use of File Paths in this Document

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

To begin installation, use your subscription to access AMQ distribution archives and package repositories.

To compile the examples or your own application, make sure you have Apache Maven installed.

The client uses Apache Maven as its build tool.

To build and run the client examples, or to use the client in dependent Maven application builds, you must first configure Maven to discover a repository for the client. To do so, you must update or create the Maven settings.xml file. It is typically located at one of the following locations.

The client can be accessed by configuring Maven in one of two ways depending on your needs:

The example programs require a running broker with a queue named queue. Follow these steps to define the queue and start the broker.

Use Maven to build the examples by running the following command in the INSTALL_DIR/examples directory.

mvn clean package dependency:copy-dependencies -DincludeScope=runtime -DskipTests

Run the HelloWorld example by using one of the following commands.

Linux:   java -cp "target/classes/:target/dependency/*" org.apache.qpid.jms.example.HelloWorld
Windows: java -cp "target\classes\;target\dependency\*" org.apache.qpid.jms.example.HelloWorld

The HelloWorld example creates a connection to the broker, creates a MessageConsumer and MessageProducer for the queue called queue, sends a Hello world! TextMessage, receives it, and prints its contents to the terminal.

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 can be found in the INSTALL_DIR/src/main/java directory, with the JNDI and logging configuration found in the INSTALL_DIR/src/main/resources directory.

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

A ConnectionFactory is configured using a connection URI.

amqp[s]://hostname: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 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.

The client uses the SLF4J API, allowing users to select a particular logging implementation based on their needs by supplying an SLF4J binding, such as slf4j-log4j, in order to use Log4J. 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 some issues, it can sometimes be useful to enable additional protocol trace logging from the Qpid Proton AMQP 1.0 library. There are two ways to achieve this.

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 as per the format described previously establishes that the client’s InititalContextFactory 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 INSTALL_DIR/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("myQueueLookup"); 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.

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.