<?xml version="1.0" encoding="ISO-8859-1" ?>
<!--
  ~  Licensed to the Apache Software Foundation (ASF) under one
  ~  or more contributor license agreements.  See the NOTICE file
  ~  distributed with this work for additional information
  ~  regarding copyright ownership.  The ASF licenses this file
  ~  to you under the Apache License, Version 2.0 (the
  ~  "License"); you may not use this file except in compliance
  ~  with the License.  You may obtain a copy of the License at
  ~
  ~   http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  -->

<document>
    <properties>
        <title>Apache Synapse - JMS Setup Guide</title>
    </properties>
    <body>
        <section name="JMS Setup Guide">
            <p>
                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.
            </p>
        </section>
        <section name="Contents">
            <ul>
                <li><a href="#intro">Introduction</a></li>
                <li><a href="#pre">Prerequisites</a></li>
                <li>
                    <a href="#synapse">Enabling JMS Support in Synapse</a>
                    <ul>
                        <li><a href="#listener">Enabling the JMS Listener</a></li>
                        <li><a href="#sender">Enabling the JMS Sender</a></li>
                    </ul>
                </li>
                <li><a href="#server">Enabling JMS Support in Axis2 Server</a></li>
                <li><a href="#client">Enabling JMS Support in Axis2 Client</a></li>
                <li><a href="#amqp">Configure Synapse for AMQP Transport</a></li>
            </ul>
        </section>
        <section name="Introduction" id="intro">
            <p>
                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.
            </p>
            <ul>
                <li>Apache ActiveMQ</li>
                <li>Apache Qpid (AMQP)</li>
                <li>IBM WebsphereMQ</li>
                <li>SwiftMQ</li>
                <li>WebLogic</li>
            </ul>
            <p>
                All the JMS related samples that come with Synapse assumes <a href="http://activemq.apache.org">ActiveMQ</a>
                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.
            </p>
            <p>
                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.
            </p>
        </section>
        <section name="Prerequisites" id="pre">
            <p>
                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.
            </p>
            <ol>
                <li><a href="http://activemq.apache.org/download.html">Download</a> the latest Apache ActiveMQ binary distribution</li>
                <li>Extract the downloaded archive to a suitable location on the local disk</li>
                <li>Switch to the 'bin' directory of the installation and execute the startup script</li>
            </ol>
            <p>
                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.
            </p>
            <p> ActiveMQ 5.8.0 and above </p>
            <ul>
                <li>activemq-broker-x.x.x.jar</li>
                <li>activemq-client-x.x.x.jar</li>
                <li>activemq-kahadb-store-x.x.x.jar </li>
                <li>geronimo-jms_1.1_spec-1.1.1.jar</li>
                <li>geronimo-j2ee-management_1.1_spec-1.0.1.jar</li>
                <li>geronimo-jta_1.0.1B_spec-1.0.1.jar</li>
                <li>hawtbuf-1.9.jar</li>
                <li>Slf4j-api-1.6.6.jar</li>
                <li>activeio-core-x.x.x.jar (available in AMQ_HOME/lib/optional folder)</li>
            </ul>

            <p> Earlier version of ActiveMQ </p>
            <ul>
                <li>activemq-core-x.x.x.jar</li>
                <li>geronimo-j2ee-management_1.0_spec-1.0.jar</li>
                <li>geronimo-jms_1.1_spec-1.1.1.jar</li>
            </ul>
            <p>
                Now we are all set to enable the JMS transport receiver and sender for Synapse and
                other sample applications.
            </p>
        </section>
        <section name="Enabling JMS Support in Synapse" id="synapse">
            <p>
                The JMS transport of Synapse consists of two main components.
            </p>
            <ul>
                <li>JMS transport receiver (JMS listener)</li>
                <li>JMS transport sender (JMS sender)</li>
            </ul>
            <subsection name="Enabling the JMS Listener" id="listener">
                <p>
                    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.
                </p>
                <div class="xmlConf">&lt;!--Uncomment this and configure as appropriate for JMS transport support, after setting up your JMS environment (e.g. ActiveMQ)--&gt;
&lt;transportReceiver name="jms" class="org.apache.synapse.transport.jms.JMSListener"&gt;
    &lt;parameter name="myTopicConnectionFactory" locked="false"&gt;
            &lt;parameter name="java.naming.factory.initial" locked="false"&gt;org.apache.activemq.jndi.ActiveMQInitialContextFactory&lt;/parameter&gt;
            &lt;parameter name="java.naming.provider.url" locked="false"&gt;tcp://localhost:61616&lt;/parameter&gt;
            &lt;parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false"&gt;TopicConnectionFactory&lt;/parameter&gt;
    &lt;/parameter&gt;

    &lt;parameter name="myQueueConnectionFactory" locked="false"&gt;
            &lt;parameter name="java.naming.factory.initial" locked="false"&gt;org.apache.activemq.jndi.ActiveMQInitialContextFactory&lt;/parameter&gt;
            &lt;parameter name="java.naming.provider.url" locked="false"&gt;tcp://localhost:61616&lt;/parameter&gt;
            &lt;parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false"&gt;QueueConnectionFactory&lt;/parameter&gt;
    &lt;/parameter&gt;

    &lt;parameter name="default" locked="false"&gt;
            &lt;parameter name="java.naming.factory.initial" locked="false"&gt;org.apache.activemq.jndi.ActiveMQInitialContextFactory&lt;/parameter&gt;
            &lt;parameter name="java.naming.provider.url" locked="false"&gt;tcp://localhost:61616&lt;/parameter&gt;
            &lt;parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false"&gt;QueueConnectionFactory&lt;/parameter&gt;
    &lt;/parameter&gt;
&lt;/transportReceiver&gt;</div>
                <p>
                    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.
                </p>
            </subsection>
            <subsection name="Enabling the JMS Sender" id="sender">
                <p>
                    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.
                </p>
                <div class="xmlConf">&lt;transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"&gt;</div>
                <p>
                    Generally JMS transport sender is enabled by default in Synapse.
                </p>
                <p>
                    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.
                </p>
                <div class="command">ant setupActiveMQ -Dactivemq.home=<i>&lt;ActiveMQ home directory&gt;</i></div>
                <p>
                    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.
                </p>
            </subsection>
        </section>
        <section name="Enabling JMS Support in Axis2 Server" id="server">
            <p>
                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.
            </p>
            <p>
                You can also execute the following command from the samples/util directory to
                enable the JMS transport for Axis2 in an automated fashion.
            </p>
            <div class="command">ant setupActiveMQ -Daxis2.xml=../axis2Server/repository/conf/axis2.xml</div>
            <p>
                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.
            </p>
        </section>
        <section name="Enabling JMS Support in Axis2 Client" id="client">
            <p>
                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.
            </p>
        </section>
    </body>
</document>