JMS Setup Guide

This document explains how to setup the JMS transport sender and listener as required by the samples. An Apache ActiveMQ instance is used as the JMS provider for the samples.

Contents

Introduction

Apache Synapse has exceptional support for JMS (Java Message Service). It uses JNDI to connect to JMS brokers, and therefore works with any JMS provider that supports JNDI. Synapse has been successfully tested with the following well-known JMS providers.

  • Apache ActiveMQ
  • Apache Qpid (AMQP)
  • IBM WebsphereMQ
  • SwiftMQ
  • WebLogic

All the JMS related samples that come with Synapse assumes ActiveMQ to be the JMS broker. But they can be executed with any other JMS provider by making a few simple changes to the JMS transport configuration in Synapse.

This article explains how to enable and setup the JMS transport for Synapse, the sample Axis2 server and the sample client programs. Since the samples are mainly focusing on ActiveMQ, much of this discussion will also be biased towards Apache ActiveMQ.

Prerequisites

First we need to install and start a JMS broker. The actual installation procedure of the JMS broker may vary depending on the broker application. If ActiveMQ is used as the JMS broker, you can install and run the broker by following 3 simple steps given below.

  1. Download the latest Apache ActiveMQ binary distribution
  2. Extract the downloaded archive to a suitable location on the local disk
  3. Switch to the 'bin' directory of the installation and execute the startup script

Next we need to deploy the JMS client libraries into Synapse. Client libraries are also specific to the JMS broker being used. These jar files are usually available in the binary distribution of the JMS broker. Third party libraries such as JMS client libraries are deployed into Synapse by simply copying them into the 'lib' directory of Synapse. Therefore if we are to use ActiveMQ as the JMS broker, the following jar files which can be found in the 'lib' directory of ActiveMQ installation, should be copied into the 'lib' directory of Synapse.

ActiveMQ 5.8.0 and above

  • activemq-broker-x.x.x.jar
  • activemq-client-x.x.x.jar
  • activemq-kahadb-store-x.x.x.jar
  • geronimo-jms_1.1_spec-1.1.1.jar
  • geronimo-j2ee-management_1.1_spec-1.0.1.jar
  • geronimo-jta_1.0.1B_spec-1.0.1.jar
  • hawtbuf-1.9.jar
  • Slf4j-api-1.6.6.jar
  • activeio-core-x.x.x.jar (available in AMQ_HOME/lib/optional folder)

Earlier version of ActiveMQ

  • activemq-core-x.x.x.jar
  • geronimo-j2ee-management_1.0_spec-1.0.jar
  • geronimo-jms_1.1_spec-1.1.1.jar

Now we are all set to enable the JMS transport receiver and sender for Synapse and other sample applications.

Enabling JMS Support in Synapse

The JMS transport of Synapse consists of two main components.

  • JMS transport receiver (JMS listener)
  • JMS transport sender (JMS sender)

Enabling the JMS Listener

If we want Synapse to receive messages from a JMS destination, then we should enable the JMS transport receiver of Synapse. This can be done by editing the axis2.xml file in the repository/conf directory and uncommenting the following XML fragment which defines the JMS transport receiver configuration.

<!--Uncomment this and configure as appropriate for JMS transport support, after setting up your JMS environment (e.g. ActiveMQ)--> <transportReceiver name="jms" class="org.apache.synapse.transport.jms.JMSListener"> <parameter name="myTopicConnectionFactory" locked="false"> <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter> <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">TopicConnectionFactory</parameter> </parameter> <parameter name="myQueueConnectionFactory" locked="false"> <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter> <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter> </parameter> <parameter name="default" locked="false"> <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter> <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter> <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter> </parameter> </transportReceiver>

Please note that above configuration is for the AcitveMQ broker. If you are using some other JMS provider, then the values of the parameters should be changed accordingly.

Enabling the JMS Sender

If you want to configure Synapse to send out JMS messages, then the JMS transport sender must be enabled. This is done by uncommenting the following section in the repository/conf/axis2.xml file.

<transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender">

Generally JMS transport sender is enabled by default in Synapse.

Synapse also comes with a simple Ant script that can be used to easily setup and enable the JMS transport in Synapse. To try this out go to the samples/util directory and execute the following command.

ant setupActiveMQ -Dactivemq.home=<ActiveMQ home directory>

This will copy the necessary dependencies into Synapse and update the axis2.xml file accordingly. Instead of providing the ActiveMQ installation path as a system property, you can opt to set the ACTIVEMQ_HOME environment variable too.

Enabling JMS Support in Axis2 Server

Some of the Synapse samples involve Synapse sending messages to the Axis2 server over JMS. For that we should enable the JMS transport listener and the sender for the Axis2 server (sender is used to send back responses). Provided that all the prerequisites are met, this can be done by uncommenting the JMS transport receiver and sender configurations in the samples/axis2Server/repository/conf/axis2.xml file. You will find that JMS sender is enabled for the Axis2 server by default.

You can also execute the following command from the samples/util directory to enable the JMS transport for Axis2 in an automated fashion.

ant setupActiveMQ -Daxis2.xml=../axis2Server/repository/conf/axis2.xml

As in the case of Synapse, the default JMS listener configurations given in the above axis2.xml file are for ActiveMQ. For other brokers, configuration should be updated accordingly.

Enabling JMS Support in Axis2 Client

In some sample scenarios we have to send JMS requests using the Axis2 client. In such cases we should enable the JMS transport sender for the sample client. This can be done by uncommenting the JMS sender configuration in the samples/axis2Client/client_repo/conf/axis2.xml file. Generally this is enabled by default and so you only need to meet the prerequisites described above.