LATEST VERSION: 3.6.5 - CHANGELOG
Pivotal RabbitMQ v3.x

Installing and Configuring JMS Client for Pivotal RabbitMQ

This chapter describes how to install and configure the JMS Client for Pivotal RabbitMQ.

Install the JMS Client Software and Enable the Topic Selector Plug-in

The JMS Client for Pivotal RabbitMQ is distributed in a ZIP or compressed TAR file.

Download and Install JMS Client for Pivotal RabbitMQ

  1. From the Pivotal RabbitMQ product page, click Downloads.
  2. Download the rabbitmq-jms-package-version-client-and-plugin.tar.gz or rabbitmq-jms-package-version-client-and-plugin.zip file.
  3. Extract the archive to a directory on your computer, using the unzip or tar command, or another suitable archive utility.

For information about using the JMS Client for RabbitMQ libraries with an application server or in a Web application, see Configure JMS Applications to Use JMS Client for Pivotal RabbitMQ.

Enable the Pivotal RabbitMQ Topic Selector Plug-in

The topic selector plug-in is included with Pivotal RabbitMQ. Like any RabbitMQ plugin, you need to enable the plug-in in order to use it.

  1. Enable the plug-in using the rabbitmq-plugins command:

    $ rabbitmq-plugins enable rabbitmq_jms_topic_exchange 
    

    Note that the plug-in name, rabbit_jms_topic_exchange, is not the same as the file name.

  2. Restart the RabbitMQ server to activate the plug-in.

Refer to Plug-ins for assistance with the rabbitmq-plugins command.

Configure JMS Applications to Use JMS Client for Pivotal RabbitMQ

To enable JMS Client for Pivotal RabbitMQ in a JEE container, you must install the supplied library files in the container and then define JMS resources in the container’s naming system so that JMS clients can look them up. The methods for accomplishing these tasks are container-specific. Instructions for setting up the JMS Client for RabbitMQ in a Pivotal tc Server runtime instance are included here. For other JEE containers, refer to the vendors’ documentation.

Installing the JMS Client for RabbitMQ Libraries

The JMS Client for RabbitMQ requires the following libraries to be in the Java classpath when the JMS application executes:

  • rabbitmq-jms-version.jar
  • amqp-client-version.jar
  • geronimo-jms_1.1_spec-1.1.1.jar

The files are in the JMS Client for RabbitMQ distribution. The rabbitmq-jms-version.jar is in the root directory of the expanded distribution archive, and the other two files are in the dependencies subdirectory.

With Pivotal tc Server, you can choose one of two options for placing these JAR files in the classpath:

  1. Copy the files into the lib directory of the tc Runtime instance, $CATALINA_HOME/lib.

    If you choose this option, any application executing on the tc Runtime instance can use JMS Client for RabbitMQ.

  2. Copy the files into the WEB-INF/lib directory in the Web application.

    If you choose this option, the JMS Client for RabbitMQ libraries are only available to that Web application.

After you restart the tc Runtime instance or redeploy the Web application, the JAR files are available to the application on the classpath. The next step is to set up the JMS objects the application expects to find in the container.

Defining JMS Objects in JNDI

The RMQConnectionFactory object has properties/attributes that can be set on Resource or Spring bean definitions. These include the host and virtualHost values of the connections created.

To configure JMS objects in containers like Pivotal tc Server and Apache Tomcat, you add a <Resource> element in a configuration file. For example, a JNDI ConnectionFactory <Resource/> could be defined as follows:

<Resource   name="jms/ConnectionFactory" 
            type="javax.jms.ConnectionFactory" 
         factory="com.rabbitmq.jms.admin.RMQObjectFactory" 
        username="guest" 
        password="guest" 
     virtualHost="/" 
            host="localhost" 
             ssl="true"/>

Here is the equivalent Spring bean example:

<bean id="jmsConnectionFactory" class="com.rabbitmq.jms.admin.RMQConnectionFactory" >
  <property name="username" value="guest" /> 
  <property name="password" value="guest" /> 
  <property name="virtualHost" value="/" /> 
  <property name="host" value="localhost" /> 
  <property name="ssl" value="true" /> 
</bean>

The following table lists all of the attributes/properties that are available.

Attribute/Property JNDI only? Description
name JNDI only Name in JNDI.
type JNDI only Name of the JMS interface the object implements, usually javax.jms.ConnectionFactory. Other choices are javax.jms.QueueConnectionFactory and javax.jms.TopicConnectionFactory. You can also use the name of the (common) implementation class, com.rabbitmq.jms.admin.RMQConnectionFactory.
factory JNDI only JMS Client for RabbitMQ ObjectFactory class, always com.rabbitmq.jms.admin.RMQObjectFactory.
username Name to use to authenticate a connection with the RabbitMQ broker. The default is “guest”.
password Password to use to authenticate a connection with the RabbitMQ broker. The default is “guest”.
virtualHost RabbitMQ virtual host within which the application will operate. The default is “/”.
host Host on which RabbitMQ is running. The default is “localhost”.
port RabbitMQ port used for connections. The default is “5672” unless this is an SSL connection, in which case the default is “5671”.
ssl Whether to use an SSL connection to RabbitMQ. The default is “false”.
uri The AMQP URI string used to establish a RabbitMQ connection. The value can encode the host, port, userid, password and virtualHost in a single string. Both ‘amqp’ and ‘amqps’ schemes are accepted. See the AMQP URI specificationon the public RabbitMQ site for details. Note: this property sets other properties and the set order is unspecified.

JMS and AMQP Destination Interoperability

An interoperability feature, introduced in Pivotal JMS Client for RabbitMQ 1.1, allows you to define JMS ‘amqp’ destinations that read and/or write to non-JMS RabbitMQ resources

A JMS destination can be defined so that a JMS application can send Messages to a predefined RabbitMQ 'destination’ (exchange/routing key) using the JMS API in the normal way. The messages are written “in the clear,” which means that any AMQP client can read them without having to understand the internal format of Java JMS messages. Only BytesMessages and TextMessages can be written in this way.

Similarly, a JMS destination can be defined that reads messages from a a predefined RabbitMQ queue. A JMS application can then read these messages using the JMS API. JMS Client for RabbitMQ packs them up into JMS Messages automatically. Messages read in this way are, by default, BytesMessages, but individual messages can be marked TextMessage (by adding an AMQP message property called “JMSType” whose value is “TextMessage”), which will interpret the byte-array payload as a UTF8 encoded String and return them as TextMessages.

A single 'amqp’ destination can be defined for both reading and writing.

When messages are sent to an 'amqp’ Destination, JMS message properties are mapped onto AMQP headers and properties as appropriate. For example, the JMSPriority property converts to the priority property for the AMQP message. (It is also set as a header with the name “JMSPriority”.) User-defined properties are set as named message header values, provided they are boolean, numeric or String types.

When reading from an 'amqp’ Destination, values are mapped back to JMS message properties, except that any explicit JMS property set as a message header overrides the natural AMQP header value, unless this would misrepresent the message. For example, JMSDeliveryMode cannot be overridden in this way.

JMS 'amqp’ RMQDestination Constructor

The com.rabbitmq.jms.admin package contains the RMQDestination class, which implements Destination in the JMS interface. This is extended with a new constructor:

public RMQDestination(String destinationName, String amqpExchangeName, 
                      String amqpRoutingKey, String amqpQueueName);
Description

Creates a destination for JMS for RabbitMQ mapped onto an AMQP resource.

Parameters
  • destinationName – the name of the queue destination
  • amqpExchangeName – the exchange name for the map resource
  • amqpRoutingKey – the routing key for the mapped resource
  • amqpQueueName– the queue name of the mapped resource

Applications that declare destinations in this way can use them directly, or store them in a JNDI provider for JMS applications to retrieve. Such destinations are non-temporary, queue destinations.

JMS AMQP Destination XML Definitions

The RMQDestination object has the following new instance fields:

  • amqpboolean, indicates if this is an AMQP destination (if true); the default is false.
  • amqpExchangeNameString, the AMQP exchange name to use when sending messages to this destination, if amqp is true; the default is null.
  • amqpRoutingKeyString, the AMQP routing key to use when sending messages to this destination, if amqp is true; the default is null.
  • amqpQueueNameString, the AMQP queue name to use when reading messages from this destination, if amqp is true; the default is null.

There are getters and setters for these fields, which means that a JNDI <Resource/> definition or a Spring bean definition can use them, for example:

  <Resource   name="jms/Queue"
              type="javax.jms.Queue"
           factory="com.rabbitmq.jms.admin.RMQObjectFactory"
   destinationName="myQueue"
              amqp="true"
     amqpQueueName="rabbitQueueName"
  />

This is the equivalent Spring bean example:

  <bean id="jmsDestination" class="com.rabbitmq.jms.admin.RMQDestination" >
    <property name="destinationName" value="myQueue" />
    <property name="amqp"            value="true" />
    <property name="amqpQueueName"   value="rabbitQueueName" />
  </bean>

Following is a complete list of the attributes/properties that are available:

Attribute/Property Name JNDI Only? Description
name JNDI only Name in JNDI.
type JNDI only Name of the JMS interface the object implements, usually javax.jms.Queue. Other choices are javax.jms.Topic and javax.jms.Destination. You can also use the name of the (common) implementation class, com.rabbitmq.jms.admin.RMQDestination.
factory JNDI only JMS Client for RabbitMQ ObjectFactory class, always com.rabbitmq.jms.admin.RMQObjectFactory.
amqp true” means this is an ‘amqp’ destination. Default “false”.
ampqExchangeName Name of the AMQP exchange to publish messages to when an ‘amqp’ destination. This exchange must exist when messages are published.
amqpRoutingKey The routing key to use when publishing messages when an ‘amqp’ destination.
amqpQueueName Name of the AMQP queue to receive messages from when an ‘amqp’ destination. This queue must exist when messages are received.
destinationName Name of the JMS destination.

Configuring Logging for the JMS Client

Beginning with release 1.0.1, JMS Client for RabbitMQ logs messages using SLF4J (Simple Logging Façade for Java). SLF4J delegates to a logging framework, such as Apache log4j or JDK 1.4 logging (java.util.logging). If no other logging framework is enabled, SLF4J defaults to a built-in, no-op, logger. See the SLF4J documentation for a list of the logging frameworks SLF4J supports.

The target logging framework is configured at deployment time by adding an SLF4J binding for the framework to the classpath. For example, the log4j SLF4J binding is in the slf4j-log4j12-version.jar file, which is a part of the SLF4J distribution. To direct JMS client messages to log4j, for example, add the following JARs to the classpath:

  • slf4j-api-1.7.5.jar
  • slf4j-log4j12-1.7.5.jar
  • log4j.jar

The SLF4J API is backwards compatible, so you can use use any version of SLF4J. Version 1.7.5 or higher is recommended. The SLF4J API and bindings, however, must be from the same SLF4J version.

No additional SLF4J configuration is required, once the API and binding JAR files are in the classpath. However, the target framework may have configuration files or command-line options. Refer to the documentation for the target logging framework for configuration details.

What’s Next?

For details of Pivotal RabbitMQ’s implementation of the JMS API, see Pivotal RabbitMQ Implementation of JMS API.