| <!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>
|
| <title>Axis2 Transports - </title>
|
| <style type="text/css" media="all">
|
| @import url("./css/maven-base.css");
|
| @import url("./css/maven-theme.css");
|
| @import url("./css/site.css");
|
| </style>
|
| <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
|
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
|
| </head>
|
| <body class="composite">
|
| <div id="banner">
|
| <a href="../transports" id="bannerLeft">
|
|
|
|
|
|
|
| </a>
|
| <a href="http://www.apache.org" id="bannerRight">
|
|
|
| <img src="images/asfLogo.jpg" alt="" />
|
|
|
| </a>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| <div id="breadcrumbs">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <div class="xleft">
|
| Last Published: 07 Dec 2009
|
| </div>
|
| <div class="xright"> <a href="http://www.apache.org/" class="externalLink">Apache</a>
|
| |
|
| <a href="../../">WebServices</a>
|
| |
|
| <a href="../">Commons</a>
|
| |
|
| <a href="../../axis2/">Axis2</a>
|
| |
|
| <a href="http://synapse.apache.org/" class="externalLink">Synapse</a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| <div id="leftColumn">
|
| <div id="navcolumn">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <h5>Axis2 Transports</h5>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="index.html">About</a>
|
| </li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <li class="expanded">
|
| <a href="download_index.html">Downloads</a>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="download.cgi">Releases</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="source-repository.html">Source Code</a>
|
| </li>
|
| </ul>
|
| </li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <li class="expanded">
|
| <a href="docs_index.html">Documentation</a>
|
| <ul>
|
|
|
| <li class="none">
|
| <strong>JMS Transport</strong>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="mail.html">Mail Transport</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="tcp-transport.html">TCP Transport</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="sms.html">SMS Transport</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="apidocs/index.html">Java Doc</a>
|
| </li>
|
| </ul>
|
| </li>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| <li class="expanded">
|
| <a href="project-info.html">Project Information</a>
|
| <ul>
|
|
|
| <li class="none">
|
| <a href="mail-lists.html">Mailing Lists</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="building.html">Building</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="issue-tracking.html">Issue Tracking</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="dependencies.html">Dependencies</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="dependency-convergence.html">Dependency Convergence</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="dependency-management.html">Dependency Management</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="plugins.html">Plugins</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="plugin-management.html">Plugin Management</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="team-list.html">Project Team</a>
|
| </li>
|
|
|
| <li class="none">
|
| <a href="project-summary.html">Project Summary</a>
|
| </li>
|
| </ul>
|
| </li>
|
| </ul>
|
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
|
| <img alt="Built by Maven" src="./images/logos/maven-feather.png"></img>
|
| </a>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| </div>
|
| </div>
|
| <div id="bodyColumn">
|
| <div id="contentBox">
|
| <div class="section"><h2>JMS Transport</h2> |
| <div class="section"><h3><a name="Content">Content</a></h3> |
| <ul><li><a href="#Content">Content</a></li> |
| <li><a href="#Transport_configuration">Transport configuration</a></li> |
| <li><a href="#Transport_listener">Transport listener</a><ul><li><a href="#JMS_connections_and_message_dispatching">JMS connections and message dispatching</a></li> |
| <li><a href="#Service_configuration">Service configuration</a></li> |
| <li><a href="#Message_context_properties_for_incoming_messages">Message context properties for incoming messages</a></li> |
| </ul> |
| </li> |
| <li><a href="#Transport_sender">Transport sender</a><ul><li><a href="#Endpoint_references">Endpoint references</a></li> |
| <li><a href="#Message_context_properties_for_outcoming_messages">Message context properties for outcoming messages</a></li> |
| </ul> |
| </li> |
| <li><a href="#Content_type_detection">Content type detection</a></li> |
| </ul> |
| </div> |
| <div class="section"><h3><a name="Transport_configuration">Transport configuration</a></h3> |
| <p>Connection factories are configured using parameters in the transport description in <tt>axis2.xml</tt>. The syntax is the same for the transport listener and sender. For example, the following configuration sets up the JMS listener with three connection factories:</p> |
| <div class="source"><pre><transportReceiver name="jms" class="org.apache.axis2.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></pre> |
| </div> |
| <p>If a connection factory named <tt>default</tt> (as shown above) is defined, this would be used for services which does not explicitly specify the connection factory that should be used. The <tt>services.xml</tt> of a service should indicate the connection factory and the destination name to be associated with. If a destination is not specified, the implementation would create a JMS Queue with the service name. The JMS destination should ideally be created and administered through the JMS provider utilities.</p> |
| <p>For the JMS sender, only the outer element is different:</p> |
| <div class="source"><pre><transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"> |
| ... |
| </transportSender></pre> |
| </div> |
| <p>As explained below, for the JMS sender configuration it is not mandatory (but recommended) to specify connection factories.</p> |
| <p>The parameters that may appear in a connection factory configuration are defined as follows:</p> |
| <dl><dt><tt>java.naming.factory.initial</tt></dt> |
| <dd> REQUIRED - JNDI initial context factory class. The class must implement the java.naming.spi.InitialContextFactory interface. </dd> |
| <dt><tt>java.naming.provider.url</tt></dt> |
| <dd> REQUIRED - URL of the JNDI provider</dd> |
| <dt><tt>transport.jms.ConnectionFactoryJNDIName</tt></dt> |
| <dd> REQUIRED - The JNDI name of the connection factory</dd> |
| <dt><tt>java.naming.security.principal</tt></dt> |
| <dd> JNDI Username</dd> |
| <dt><tt>java.naming.security.credentials</tt></dt> |
| <dd> JNDI password</dd> |
| <dt><tt>transport.Transactionality</tt></dt> |
| <dd> Desired mode of transactionality. possible values are 'none', 'local' or 'jta', while it defaults to 'none'</dd> |
| <dt><tt>transport.UserTxnJNDIName</tt></dt> |
| <dd> JNDI name to be used to require user transaction</dd> |
| <dt><tt>transport.CacheUserTxn</tt></dt> |
| <dd> Whether caching for user transactions should be enabled or not. Possible values are 'true' or 'false', while the value defaults to 'true'</dd> |
| <dt><tt>transport.jms.SessionTransacted</tt></dt> |
| <dd> Whether the JMS session be transacted or not. Possible values are 'true' or 'false', while the value defaults to 'true' if the transactionality is 'local'</dd> |
| <dt><tt>transport.jms.SessionAcknowledgement</tt></dt> |
| <dd> JMS session acknowledgement mode. Possible values are AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED. Default value is AUTO_ACKNOWLEDGE</dd> |
| <dt><tt>transport.jms.ConnectionFactoryType</tt></dt> |
| <dd> Type of the connection factory. Possible values are 'queue' or 'topic' while the default value of 'queue'</dd> |
| <dt><tt>transport.jms.JMSSpecVersion</tt></dt> |
| <dd> JMS API version. Possible values are 1.1 or 1.0.2b, and the default API version is 1.1</dd> |
| <dt><tt>transport.jms.UserName</tt></dt> |
| <dd> The JMS connection username</dd> |
| <dt><tt>transport.jms.Password</tt></dt> |
| <dd> The JMS connection password</dd> |
| <dt><tt>transport.jms.DefaultReplyDestination</tt></dt> |
| <dd> JNDI name of the default reply destination</dd> |
| <dt><tt>transport.jms.DefaultReplyDestinationType</tt></dt> |
| <dd> Default type of the reply destination, if not provided the destination type will be taken as the reply destination type as well</dd> |
| <dt><tt>transport.jms.MessageSelector</tt></dt> |
| <dd> Message selector implementation</dd> |
| <dt><tt>transport.jms.SubscriptionDurable</tt></dt> |
| <dd> Whether the connection factory is subscription durable or not. Possible values are 'true' or 'false', while the value defaults to 'false'</dd> |
| <dt><tt>transport.jms.DurableSubscriberName</tt></dt> |
| <dd> Name of the durable subscriber. This is required if the above parameter is set to 'true'</dd> |
| <dt><tt>transport.jms.PubSubNoLocal</tt></dt> |
| <dd> Whether the messages should be published by the same connection they were received. Possible values are 'true' or 'false', while the value defaults to 'false'</dd> |
| <dt><tt>transport.jms.CacheLevel</tt></dt> |
| <dd> JMS resource cache level. Possible values are 'none', 'connection', 'session', 'consumer', 'producer', 'auto' and defaults to 'auto'</dd> |
| <dt><tt>transport.jms.ReceiveTimeout</tt></dt> |
| <dd> Time to wait for a JMS message during polling. Set this parameter value to a negative integer to wait indefinitely. Set to zero to prevent waiting and the default value is 1000ms</dd> |
| <dt><tt>transport.jms.ConcurrentConsumers</tt></dt> |
| <dd> Number of concurrent threads to be started to consume messages when polling. Defaults to 1, and the value should be a positive integer. For topics it has to be always 1</dd> |
| <dt><tt>transport.jms.MaxConcurrentConsumers</tt></dt> |
| <dd> Maximum number of concurrent threads to use during polling. Defaults to 1, and the value should be a positive integer. For topics it has to be always 1</dd> |
| <dt><tt>transport.jms.IdleTaskLimit</tt></dt> |
| <dd> The number of idle runs per thread before it dies out, which defaults to 10</dd> |
| <dt><tt>transport.jms.MaxMessagesPerTask</tt></dt> |
| <dd> The maximum number of successful message receipts per thread. Defaults to -1 meaning the infinity</dd> |
| <dt><tt>transport.jms.InitialReconnectDuration</tt></dt> |
| <dd> Initial reconnection attempts duration in milliseconds, which defaults to 1000ms</dd> |
| <dt><tt>transport.jms.ReconnectProgressFactor</tt></dt> |
| <dd> Factor by which the reconnection duration will be increased, which defaults to 2.</dd> |
| <dt><tt>transport.jms.MaxReconnectDuration</tt></dt> |
| <dd> Maximum reconnection duration in milliseconds, which defaults to 3600000ms (1 hr)</dd> |
| </dl> |
| </div> |
| <div class="section"><h3><a name="Transport_listener">Transport listener</a></h3> |
| <div class="section"><h4><a name="JMS_connections_and_message_dispatching">JMS connections and message dispatching</a></h4> |
| <p>Every deployed service for which the JMS transport is enabled will be associated with a destination (queue or topic) according to the following rules:</p> |
| <ul><li>If the service has a <tt>transport.jms.Destination</tt> parameter, its value is interpreted as the JNDI name of the destination.</li> |
| <li>Otherwise the service name is used as the JNDI name of the destination.</li> |
| </ul> |
| <p>At the same time, the connection factory is determined by looking at the service parameter <tt>transport.jms.ConnectionFactory</tt>. If this parameter is not set, the default value <tt>default</tt> is assumed. The value of this parameter is interpreted as a logical identifier for the connection factory configuration defined in the transport configuration (see above).</p> |
| <p>It follows that JMS destinations are statically bound to services. Therefore the transport always predispatches incoming messages to the service the destination is bound to.</p> |
| <p>The message is dispatched to an operation according to the following rules:</p> |
| <ul><li>The transport looks for a service parameter <tt>Operation</tt>. If this parameter is not present, the default value <tt>urn:mediate</tt> is assumed.</li> |
| <li>If the service has an operation with the corresponding name, the transport predispatches the message to that operation.</li> |
| <li>If no such operation exists, the message will be dispatched by the Axis2 engine using the configured dispatchers.</li> |
| </ul> |
| <p>In addition, if the JMS message has a property named <tt>SOAPAction</tt>, the value of this property is interpreted as the SOAP action.</p> |
| </div> |
| <div class="section"><h4><a name="Service_configuration">Service configuration</a></h4> |
| <p>Apart from the following list most of the parameters defined in the global connection factory can be overriden at the service level as well</p> |
| <dl><dt><tt>transport.jms.ConnectionFactory</tt> (Optional)</dt> |
| <dd> The JMS connection factory definition (from <tt>axis2.xml</tt>) to be used to listen for messages for this service.</dd> |
| <dt><tt>transport.jms.Destination</tt> (Optional)</dt> |
| <dd> The JMS destination name (Defaults to a Queue with the service name).</dd> |
| <dt><tt>transport.jms.DestinationType</tt> (Optional)</dt> |
| <dd> The JMS destination type. Accept values 'queue' or 'topic' (default: queue).</dd> |
| <dt><tt>transport.jms.ReplyDestination</tt> (Optional)</dt> |
| <dd> The destination where a reply will be posted.</dd> |
| <dt><tt>transport.jms.ContentType</tt> (Optional)</dt> |
| <dd> Specifies how the transport listener should determine the content type of received messages. This can either be a simple string value, in which case the transport listener assumes that the received messages always have the specified content type, or a set of rules as in the following example:<div class="source"><pre><parameter name="transport.jms.ContentType"> |
| <rules> |
| <jmsProperty>contentType</jmsProperty> |
| <jmsProperty>ctype</jmsProperty> |
| <default>text/xml</default> |
| </rules> |
| </parameter></pre> |
| </div> |
| <p>The rules are evaluated in turn until the first matches. The following rule types are defined:</p> |
| <dl><dt><tt>jmsProperty</tt></dt> |
| <dd> Extract the content type from the specified message property.</dd> |
| <dt><tt>bytesMessage</tt><br /> |
| <tt>textMessage</tt></dt> |
| <dd> Match the corresponding message type. The content type is specified as the value of the rule, e.g. <tt><bytesMessage>binary/octet-stream</bytesMessage></tt></dd> |
| <dt><tt>default</tt></dt> |
| <dd> Defines the default content type. This rule always matches and should therefore be the last rule in the rule set.</dd> |
| </dl> |
| <p>If none of the rules matches, an error is triggered and the message is not processed. The default value for this property corresponds to the following set of rules:</p> |
| <div class="source"><pre><parameter name="transport.jms.ContentType"> |
| <rules> |
| <jmsProperty>Content-Type</jmsProperty> |
| <bytesMessage>application/octet-stream</bytesMessage> |
| <textMessage>text/plain</textMessage> |
| </rules> |
| </parameter></pre> |
| </div> |
| <p>This choice preserves compatibility with previous versions of the JMS transport. Note however that <tt>Content-Type</tt> is not a valid JMS property name and will not work with some JMS providers.</p> |
| </dd> |
| <dt><tt>Wrapper</tt> (Optional)</dt> |
| <dd> The wrapper element for pure text or binary messages. Note that this parameter is actually not JMS specific but recognized by the message builders for <tt>text/plain</tt> and <tt>application/octet-stream</tt> (which are the respective default content types for JMS text and binary messages).</dd> |
| </dl> |
| <p>Sample <tt>services.xml</tt>:</p> |
| <div class="source"><pre><service name="echo"> |
| <transports> |
| .... |
| <transport>jms</transport> |
| </transports> |
| ... |
| <parameter name="transport.jms.ConnectionFactory" locked="true">myTopicConnectionFactory</parameter> |
| <parameter name="transport.jms.Destination" locked="true">dynamicTopics/something.TestTopic</parameter> |
| </service></pre> |
| </div> |
| </div> |
| <div class="section"><h4><a name="Message_context_properties_for_incoming_messages">Message context properties for incoming messages</a></h4> |
| <p>For incoming messages, the transport listener will make the following properties available in the message context:</p> |
| <dl><dt><tt>TRANSPORT_HEADERS</tt></dt> |
| <dd> This property will contain a map with the JMS message properties.</dd> |
| </dl> |
| </div> |
| </div> |
| <div class="section"><h3><a name="Transport_sender">Transport sender</a></h3> |
| <div class="section"><h4><a name="Endpoint_references">Endpoint references</a></h4> |
| <p>Endpoint references for the JMS transport must have the following form:</p> |
| <div class="source"><pre>jms-epr = "jms:/" jms-dest [ "?" param *( [ "&" param ] ) ] |
| param = param-name "=" param-value</pre> |
| </div> |
| <p><tt>jms-dest</tt> is the JNDI name of the destination to send the message to. The parameters are defined as follows:</p> |
| <dl><dt><tt>transport.jms.ConnectionFactory</tt> (Optional)</dt> |
| <dd> The JMS connection factory definition (from <tt>axis2.xml</tt>) to be used to send messages to the endpoint.</dd> |
| <dt><tt>transport.jms.ContentTypeProperty</tt></dt> |
| <dd> The name of the message property to store the content type of messages sent to the endpoint.</dd> |
| </dl> |
| <p>All the above listed parameters under the connection factory configuration are applied to the JMS EPR as well, apart from these.</p> |
| <p>If no connection factory definition is explicitly specified using the <tt>transport.jms.ConnectionFactory</tt> parameter, the JMS sender will check if the transport configuration contains a connection factory compatible with the other settings specified in the endpoint URL (<tt>transport.jms.ConnectionFactoryJNDIName</tt>, <tt>java.naming.factory.initial</tt>, <tt>java.naming.provider.url</tt>, <tt>java.naming.security.principal</tt> and <tt>java.naming.security.credentials</tt>). If a matching configuration is found, the sender will reuse the cached JMS objects related to that configuration. Otherwise it will execute the JNDI lookup and open a new connection. In that case the connection will be closed immediately after sending the message.</p> |
| </div> |
| <div class="section"><h4><a name="Message_context_properties_for_outcoming_messages">Message context properties for outcoming messages</a></h4> |
| <p>For outgoing messages, the transport sender will recognize the following message context properties:</p> |
| <dl><dt><tt>TRANSPORT_HEADERS</tt></dt> |
| <dd> The transport expects a map as value for this property. The entries of this map will be set as properties on the outgoing JMS message.</dd> |
| </dl> |
| <p>Note that all the properties are optional.</p> |
| </div> |
| </div> |
| <div class="section"><h3><a name="Content_type_detection">Content type detection</a></h3> |
| <dl><dt>Incoming requests</dt> |
| <dd> The content type of the message is determined according to the settings specified in the <tt>transport.jms.ContentType</tt> service parameter.</dd> |
| <dt>Outgoing responses</dt> |
| <dd> If the content type of the request was determined using the value of a message property, the content type of the response will stored in the same message property.</dd> |
| <dt>Outgoing requests</dt> |
| <dd> The content type will be stored in the message property specified by the <tt>transport.jms.ContentTypeProperty</tt> message context property or the <tt>transport.jms.ContentTypeProperty</tt> parameter of the endpoint reference.</dd> |
| <dt>Incoming responses</dt> |
| <dd> The content type will be extracted from the message property that was used to store the content type of the outgoing request.</dd> |
| </dl> |
| </div> |
| </div> |
|
|
| </div>
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| <div id="footer">
|
| <div class="xright">©
|
| 2004-2009
|
|
|
| The Apache Software Foundation
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| </div>
|
| <div class="clear">
|
| <hr/>
|
| </div>
|
| </div>
|
| </body>
|
| </html>
|
