<!--
  ~ 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.
  -->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="generator" content=
"HTML Tidy for Windows (vers 14 June 2007), see www.w3.org" />
<meta http-equiv="content-type" content="" />
<title>JMS Transport</title>
<link href="../css/axis-docs.css" rel="stylesheet" type="text/css"
media="all" />
</head>
<body lang="en" xml:lang="en">
<a name="configTransport" id="configTransport"></a>
<h1>JMS Transport</h1>
<p>This document is all about the JMS (Java Messaging Service)
Transport support in Apache Axis2, and how it should be
configured.</p>
<h2>Contents</h2>
<ul>
<li><a href="#CommonsHTTPTransportSender">Overview</a></li>
<li><a href="#timeout_config">Configuration</a></li>
<li><a href="#writing_services">Writing Services to Use the JMS
Transport</a></li>
</ul>
<a name="CommonsHTTPTransportSender" id=
"CommonsHTTPTransportSender"></a>
<h2>Overview</h2>
<p>A new Java Messaging Service (JMS) transport implementation has
been added to Axis2 to overcome some drawbacks of the previous JMS
implementation. One of the enhancements provided with this new
implementation is the ability to <strong>assign custom JMS
destination names or existing JMS destinations to Axis2 services
being deployed</strong>.</p>
<a name="timeout_config" id="timeout_config"></a>
<h2>Configuration</h2>
<p>To use the JMS transport, the axis2.xml configuration must be
setup as follows, in order to configure the JMSListener and the JMS
Sender</p>
<pre>
<strong>axis2.xml</strong>
    &lt;transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener"&gt;
      &lt;parameter name="default"&gt;
        &lt;parameter name="java.naming.factory.initial"&gt;org.apache.activemq.jndi.ActiveMQInitialContextFactory&lt;/parameter&gt;
        &lt;parameter name="java.naming.provider.url"&gt;tcp://localhost:61616&lt;/parameter&gt;
        &lt;parameter name="transport.jms.ConnectionFactoryJNDIName"&gt;QueueConnectionFactory&lt;/parameter&gt;
      &lt;/parameter&gt;
    &lt;/transportReceiver&gt;

    &lt;transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/&gt;
</pre>
<p>The JMS transport receiver configuration allows you to define
the default connection factory (named as "default" ~
JMSConstants.DEFAULT_CONFAC_NAME) for use by Axis2 services using
the JMS transport. This connection factory will be used by any
service that does not explicitly specify a connection factory name
in its services.xml file. The configuration required to associate a
(local) Axis2 connection factory to an actual implementation must
be provided as shown above. To specify the JNDI URL, the initial
context factory class and the JNDI name of the actual JMS
connection factory is used. You can also specify the parameters
"java.naming.security.principal" and
"java.naming.security.credentials", if required, to access the
actual connection factory. The example shown above uses an ActiveMQ
JMS implementation.</p>
<pre>
<strong>axis2.xml</strong>
  &lt;parameter name="myTopicConnectionFactory"&gt;
</pre>
<pre>
    &lt;parameter name="java.naming.factory.initial"&gt;org.apache.activemq.jndi.ActiveMQInitialContextFactory&lt;/parameter&gt;
</pre>
<pre>
    &lt;parameter name="java.naming.provider.url"&gt;tcp://localhost:61616&lt;/parameter&gt;
</pre>
<pre>
    &lt;parameter name="transport.jms.ConnectionFactoryJNDIName"&gt;TopicConnectionFactory&lt;/parameter&gt;
</pre>
<pre>
  &lt;/parameter&gt;
</pre>
<p>If it is required or applicable, you are free to define
additional (local) connection factories to Axis2 as shown above,
which your services can use. For a service to specify that such a
connection factory should be used, its services.xml may specify the
following configuration parameter:</p>
<pre>
services.xml  
  &lt;parameter name="transport.jms.ConnectionFactory" locked="true"&gt;myTopicConnectionFactory&lt;/parameter&gt;
</pre>
<p><strong>Note:</strong> Depending on your JMS implementation, you
will need to make available all the required libraries for your
Axis2 instance. This example assumes you are using an ActiveMQ
instance. To run the given code samples, it is required to make the
following JAR files available: activeio-core-3.0-beta1.jar,
activemq-core-4.0-RC2.jar,
geronimo-j2ee-management_1.0_spec-1.0.jar at a minimum. It also
requires you to start ActiveMQ separately from Axis2, and then
provide the appropriate configuration settings (e.g. URL) to
Axis2.</p>
<p>During initialization, the JMS Listener creates a dedicated JMS
message processor for each connection factory defined, and utilizes
a shared thread pool to process the received messages.</p>
<p>A service on an Axis2 instance is deployed on all the started
transports by default, unless a list of transports is specified in
its services.xml file. Hence, if a service must only be deployed on
JMS, you should specify it on the services.xml as follows:</p>
<pre>
  &lt;transports&gt; 
    &lt;transport&gt;jms&lt;/transport&gt; 
  &lt;/transports&gt;
</pre>
<p>If the services.xml does not provide an explicit JMS destination
name, it is assumed that the service will listen for messages on a
JMS <strong>Queue</strong> by the same name as the <strong>name of
the service</strong>. If an explicit connection factory definition
name has not been specified, it is assumed that the "default"
connection factory definition configured within the transport
receiver is used. To provide a custom JMS destination name and
connection factory, the services.xml file provides the following
optional parameters.</p>
<pre>
  &lt;parameter name="transport.jms.ConnectionFactory" locked="true"&gt;myTopicConnectionFactory&lt;/parameter&gt;
  &lt;parameter name="transport.jms.Destination" locked="true"&gt;dynamicTopics/something.TestTopic&lt;/parameter&gt;
</pre>
<a name="writing_services" id="writing_services"></a>
<h2>Writing Services to Use the JMS Transport</h2>
<p>This section assumes that you are already familiar with <a href=
"xmlbased-server.html">writing service implementations</a> for
Axis2, and provides information on how to write your own service
implementations to be exposed over JMS.</p>
<p><strong>Echo - Service implementation and
services.xml</strong></p>
<p>This sample demonstrates a very simple service which is to be
exposed over JMS. It does not specify a custom connection factory
name, and hence uses the default value as specified in the JMS
transport listener configuration. It also does not specify a custom
destination name, and hence would listen to messages over a JMS
Queue named "Echo" (which is the name of the service). This service
will be exposed over all defined Axis2 transports, and the
resulting URL for the service over JMS will be:</p>
<p>
jms:/echo?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&amp;java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&amp;java.naming.provider.url=tcp://localhost:61616</p>
<pre>
<strong>Echo.java</strong>
</pre>
<pre>
  public class Echo {
</pre>
<pre>
    public String echoString(String in) {
</pre>
<pre>
      return in;
</pre>
<pre>
    }
</pre>
<pre>
    public String echoString1(String in) {
</pre>
<pre>
      return "echoString1 " + in;
</pre>
<pre>
    }
</pre>
<pre>
    public String echoString2(String in) {
</pre>
<pre>
      return "echoString2 " + in;
</pre>
<pre>
    }
</pre>
<pre>
  }
</pre>
<pre>
<strong>services.xml</strong>
</pre>
<pre>
  &lt;service name="echo"&gt;
</pre>
<pre>
    &lt;description&gt;Echo Service&lt;/description&gt;
</pre>
<pre>
    &lt;messageReceivers&gt;
</pre>
<pre>
      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
</pre>
<pre>
        class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/&gt;
</pre>
<pre>
      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
</pre>
<pre>
        class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/&gt;
</pre>
<pre>
    &lt;/messageReceivers&gt;
</pre>
<pre>
    &lt;parameter name="ServiceClass" locked="true"&gt;Echo&lt;/parameter&gt;
</pre>
<pre>
&lt;/service&gt;
</pre>
<p><strong>Echo2 - Service implementation and
services.xml</strong></p>
<p>This example shows a simple service which specifies that it
should only be exposed over the JMS transport, and that the custom
connection factory named "myTopcConnectionFactory" should be used
to listen for requests at the JMS destination named
"dynamicTopics/something.TestTopic". The JMS URL to access this
service is:</p>
<p>
jms:/dynamicTopics/something.TestTopic?transport.jms.ConnectionFactoryJNDIName=TopicConnectionFactory&amp;java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&amp;java.naming.provider.url=tcp://localhost:61616&amp;java.naming.security.principal=system&amp;java.naming.security.credentials=manager</p>
<pre>
<strong>Echo2.java</strong>
</pre>
<pre>
  public class Echo2 {
</pre>
<pre>
    public String echoString(String in) {
</pre>
<pre>
      return in;
</pre>
<pre>
    }
</pre>
<pre>
  }
</pre>
<pre>
<strong>services.xml</strong>
</pre>
<pre>
  &lt;service name="echo"&gt;
</pre>
<pre>
    &lt;transports&gt;
</pre>
<pre>
      &lt;transport&gt;jms&lt;/transport&gt;
</pre>
<pre>
    &lt;/transports&gt;
</pre>
<pre>
    &lt;description&gt;Echo2 Service&lt;/description&gt;
</pre>
<pre>
    &lt;messageReceivers&gt;
</pre>
<pre>
      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
</pre>
<pre>
        class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/&gt;
</pre>
<pre>
      &lt;messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
</pre>
<pre>
        class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/&gt;
</pre>
<pre>
    &lt;/messageReceivers&gt;
</pre>
<pre>
    &lt;parameter name="ServiceClass" locked="true"&gt;Echo2&lt;/parameter&gt;
</pre>
<pre>
    &lt;parameter name="transport.jms.ConnectionFactory" locked="true"&gt;myTopicConnectionFactory&lt;/parameter&gt;
</pre>
<pre>
    &lt;parameter name="transport.jms.Destination" locked="true"&gt;dynamicTopics/something.TestTopic&lt;/parameter&gt;
</pre>
<pre>
  &lt;/service&gt;
</pre>
<pre>
 
</pre>
<h2>Starting up the Axis2 JMS transport</h2>
<p>The Axis2 standalone binary distribution ships with an Axis2
Server, which starts up all the transports that are configured as
per the axis2.xml. Hence, configure the JMS transport in your
axis2.xml, and use the axis2server.bat or the axis2server.sh to
start the JMS transport.</p>
</body>
</html>
