| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <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"> |
| <a name="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> |
| |
| <p><i>Send your feedback or questions to: <a |
| href="mailto:axis-dev@ws.apache.org?subject=[Axis2]">axis-dev@ws.apache.org</a></i>. |
| (Subscription details are available on the <a |
| href="http://ws.apache.org/axis2/mail-lists.html">Axis2 site</a>.) Kindly |
| prefix subject with [Axis2].</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"></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"></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> |
| <transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener"> |
| <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> |
| |
| <transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/></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> |
| <parameter name="myTopicConnectionFactory" locked="false"></pre> |
| <pre> <parameter name="java.naming.factory.initial" locked="false">org.apache.activemq.jndi.ActiveMQInitialContextFactory</parameter></pre> |
| <pre> <parameter name="java.naming.provider.url" locked="false">tcp://localhost:61616</parameter></pre> |
| <pre> <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">TopicConnectionFactory</parameter></pre> |
| <pre> </parameter></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 |
| <parameter name="transport.jms.ConnectionFactory" locked="true">myTopicConnectionFactory</parameter></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> <transports> |
| <transport>jms</transport> |
| </transports></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> <parameter name="transport.jms.ConnectionFactory" locked="true">myTopicConnectionFactory</parameter> |
| <parameter name="transport.jms.Destination" locked="true">dynamicTopics/something.TestTopic</parameter></pre> |
| <a name="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, |
| which are 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&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&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></pre> |
| <pre><strong>services.xml</strong></pre> |
| <pre> <service name="echo"></pre> |
| <pre> <description>Echo Service</description></pre> |
| <pre> <messageReceivers></pre> |
| <pre> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"</pre> |
| <pre> class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/></pre> |
| <pre> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"</pre> |
| <pre> class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/></pre> |
| <pre> </messageReceivers></pre> |
| <pre> <parameter name="ServiceClass" locked="true">Echo</parameter></pre> |
| <pre></service></pre> |
| |
| <p></p> |
| |
| <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&java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&java.naming.provider.url=tcp://localhost:61616&java.naming.security.principal=system&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></pre> |
| <pre><strong>services.xml</strong></pre> |
| <pre> <service name="echo"></pre> |
| <pre> <transports></pre> |
| <pre> <transport>jms</transport></pre> |
| <pre> </transports></pre> |
| <pre> <description>Echo2 Service</description></pre> |
| <pre> <messageReceivers></pre> |
| <pre> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"</pre> |
| <pre> class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver"/></pre> |
| <pre> <messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"</pre> |
| <pre> class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/></pre> |
| <pre> </messageReceivers></pre> |
| <pre> <parameter name="ServiceClass" locked="true">Echo2</parameter></pre> |
| <pre> <parameter name="transport.jms.ConnectionFactory" locked="true">myTopicConnectionFactory</parameter></pre> |
| <pre> <parameter name="transport.jms.Destination" locked="true">dynamicTopics/something.TestTopic</parameter></pre> |
| <pre> </service></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> |