| <!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"> | |
| <h1><a name="configTransport">JMS Transport</a></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">axis-dev@ws.apache.org</a></i>. Prefix | |
| subject with [Axis2]. To subscribe to mailing list see <a | |
| href="http://ws.apache.org/axis2/mail-lists.html">here.</a></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 JMS or Java Messaging Service transport implementation has been | |
| added to Axis2 to overcome some drawbacks of the previous JMS implementation. | |
| Some 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 | |
| would be used by any service which does not explicitly specify a connection | |
| factory name in its services.xml. 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, initial context factory class and | |
| the JNDI name of the actual JMS connection factory is to be used. You may | |
| 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 may 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 required libraries to your Axis2 instance. This example | |
| assumes you are using an ActiveMQ instance. To run the given code samples, it | |
| was required to make available the following JAR files: | |
| 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 received messages.</p> | |
| <p>A service on an Axis2 instance is deployed on all started transports by | |
| default, unless a list of transports are specified in its services.xml. | |
| 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 be used. To provide a | |
| custom JMS destination name and connection factory, the services.xml could | |
| provide 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 to enable you 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" 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 would 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> | |
| <pre>The Axis2 standalone binary distribution ships with an Axis2 Server, which starts up all of 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.</pre> | |
| </body> | |
| </html> |