~~ 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.

JMS Transport

* {Content}

%{toc|section=1|fromDepth=1}

* {Transport configuration}

  Connection factories are configured using parameters in the transport description in
  <<<axis2.xml>>>. 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:

+----------------------------+
<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>
+----------------------------+

  If a connection factory named <<<default>>> (as shown above) is defined, this would be used for services which does
  not explicitly specify the connection factory that should be used. The <<<services.xml>>> 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.
  
  For the JMS sender, only the outer element is different:
  
+----------------------------+  
<transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender">
    ...
</transportSender>
+----------------------------+  

  As explained below, for the JMS sender configuration it is not mandatory (but recommended) to specify
  connection factories.
  
  The parameters that may appear in a connection factory configuration are defined as follows:
  
    [<<<java.naming.factory.initial>>>]
    REQUIRED - JNDI initial context factory class. The class must implement the java.naming.spi.InitialContextFactory interface. 
    
    [<<<java.naming.provider.url>>>]
    REQUIRED - URL of the JNDI provider
    
    [<<<transport.jms.ConnectionFactoryJNDIName>>>]
    REQUIRED - The JNDI name of the connection factory

    [<<<java.naming.security.principal>>>]
    JNDI Username

    [<<<java.naming.security.credentials>>>]
    JNDI password

    [<<<transport.Transactionality>>>]
    Desired mode of transactionality. possible values are 'none', 'local' or 'jta', while it defaults to 'none'

    [<<<transport.UserTxnJNDIName>>>]
    JNDI name to be used to require user transaction

    [<<<transport.CacheUserTxn>>>]
    Whether caching for user transactions should be enabled or not. Possible values are 'true' or 'false', while the value defaults to 'true'

    [<<<transport.jms.SessionTransacted>>>]
    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'

    [<<<transport.jms.SessionAcknowledgement>>>]
    JMS session acknowledgement mode. Possible values are AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, DUPS_OK_ACKNOWLEDGE, SESSION_TRANSACTED. Default value is AUTO_ACKNOWLEDGE

    [<<<transport.jms.ConnectionFactoryType>>>]
    Type of the connection factory. Possible values are 'queue' or 'topic' while the default value of 'queue'
    
    [<<<transport.jms.JMSSpecVersion>>>]
    JMS API version. Possible values are 1.1 or 1.0.2b, and the default API version is 1.1

    [<<<transport.jms.UserName>>>]
    The JMS connection username

    [<<<transport.jms.Password>>>]
    The JMS connection password

    [<<<transport.jms.DefaultReplyDestination>>>]
    JNDI name of the default reply destination
    
    [<<<transport.jms.DefaultReplyDestinationType>>>]
    Default type of the reply destination, if not provided the destination type will be taken as the reply destination type as well

    [<<<transport.jms.MessageSelector>>>]
    Message selector implementation

    [<<<transport.jms.SubscriptionDurable>>>]
    Whether the connection factory is subscription durable or not. Possible values are 'true' or 'false', while the value defaults to 'false'

    [<<<transport.jms.DurableSubscriberName>>>]
    Name of the durable subscriber. This is required if the above parameter is set to 'true'

    [<<<transport.jms.PubSubNoLocal>>>]
    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'

    [<<<transport.jms.CacheLevel>>>]
    JMS resource cache level. Possible values are 'none', 'connection', 'session', 'consumer', 'producer', 'auto' and defaults to 'auto'
    
    [<<<transport.jms.ReceiveTimeout>>>]
    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

    [<<<transport.jms.ConcurrentConsumers>>>]
    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

    [<<<transport.jms.MaxConcurrentConsumers>>>]
    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

    [<<<transport.jms.IdleTaskLimit>>>]
    The number of idle runs per thread before it dies out, which defaults to 10

    [<<<transport.jms.MaxMessagesPerTask>>>]
    The maximum number of successful message receipts per thread. Defaults to -1 meaning the infinity

    [<<<transport.jms.InitialReconnectDuration>>>]
    Initial reconnection attempts duration in milliseconds, which defaults to 1000ms

    [<<<transport.jms.ReconnectProgressFactor>>>]
    Factor by which the reconnection duration will be increased, which defaults to 2.

    [<<<transport.jms.MaxReconnectDuration>>>]
    Maximum reconnection duration in milliseconds, which defaults to 3600000ms (1 hr)

* {Transport listener}

** {JMS connections and message dispatching}

  Every deployed service for which the JMS transport is enabled will be associated with a
  destination (queue or topic) according to the following rules:

    * If the service has a <<<transport.jms.Destination>>> parameter, its value is interpreted
      as the JNDI name of the destination.
    
    * Otherwise the service name is used as the JNDI name of the destination.
  
  At the same time, the connection factory is determined by looking at the service parameter
  <<<transport.jms.ConnectionFactory>>>. If this parameter is not set, the default value
  <<<default>>> 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).

  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.

  The message is dispatched to an operation according to the following rules:

    * The transport looks for a service parameter <<<Operation>>>. If this parameter is not present,
      the default value <<<urn:mediate>>> is assumed.
    
    * If the service has an operation with the corresponding name, the transport predispatches
      the message to that operation.
    
    * If no such operation exists, the message will be dispatched by the Axis2 engine using the
      configured dispatchers.
  
  In addition, if the JMS message has a property named <<<SOAPAction>>>, the value of this property
  is interpreted as the SOAP action.

** {Service configuration}

  Apart from the following list most of the parameters defined in the global connection factory can be overriden at the service level as well

  [<<<transport.jms.ConnectionFactory>>> (Optional)]
  The JMS connection factory definition (from <<<axis2.xml>>>) to be used to
  listen for messages for this service.
  
  [<<<transport.jms.Destination>>> (Optional)]
  The JMS destination name (Defaults to a Queue with the service name).

  [<<<transport.jms.DestinationType>>> (Optional)]
  The JMS destination type. Accept values 'queue' or 'topic' (default: queue).
  
  [<<<transport.jms.ReplyDestination>>> (Optional)]
  The destination where a reply will be posted.
  
  [<<<transport.jms.ContentType>>> (Optional)]
  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:
  
+--------------------------------------------+
<parameter name="transport.jms.ContentType">
    <rules>
        <jmsProperty>contentType</jmsProperty>
        <jmsProperty>ctype</jmsProperty>
        <default>text/xml</default>
    </rules>
</parameter>
+--------------------------------------------+

  The rules are evaluated in turn until the first matches. The following rule types are defined:
    
    [<<<jmsProperty>>>]
    Extract the content type from the specified message property.
    
    [<<<bytesMessage>>>\
    <<<textMessage>>>]
    Match the corresponding message type. The content type is specified as the value of
    the rule, e.g. <<<\<bytesMessage\>binary/octet-stream\</bytesMessage\>>>>
    
    [<<<default>>>]
    Defines the default content type. This rule always matches and should therefore
    be the last rule in the rule set.
                    
  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:
  
+--------------------------------------------+
<parameter name="transport.jms.ContentType">
    <rules>
        <jmsProperty>Content-Type</jmsProperty>
        <bytesMessage>application/octet-stream</bytesMessage>
        <textMessage>text/plain</textMessage>
    </rules>
</parameter>
+--------------------------------------------+

  This choice preserves compatibility with previous versions of the JMS transport. Note however
  that <<<Content-Type>>> is not a valid JMS property name and will not work with some JMS providers.
  
  [<<<Wrapper>>> (Optional)]
  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 <<<text/plain>>> and
  <<<application/octet-stream>>> (which are the respective default content types for JMS text
  and binary messages).
  
  []
  
  Sample <<<services.xml>>>:
  
+--------------------------------------------+
<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>
+--------------------------------------------+

** {Message context properties for incoming messages}

  For incoming messages, the transport listener will make the following properties available in
  the message context:
  
    [<<<TRANSPORT_HEADERS>>>]
    This property will contain a map with the JMS message properties.

* {Transport sender}

** {Endpoint references}

  Endpoint references for the JMS transport must have the following form:
  
+--------------------------------------------+
jms-epr = "jms:/" jms-dest [ "?" param  *( [ "&" param ] ) ]
param = param-name "=" param-value
+--------------------------------------------+

  <<<jms-dest>>> is the JNDI name of the destination to send the message to. The parameters are
  defined as follows:

    [<<<transport.jms.ConnectionFactory>>> (Optional)]
    The JMS connection factory definition (from <<<axis2.xml>>>) to be used to send messages to
    the endpoint.
  
    [<<<transport.jms.ContentTypeProperty>>>]
    The name of the message property to store the content type of messages sent to the endpoint.
  
 All the above listed parameters under the connection factory configuration are applied to the JMS EPR as well, apart from these.
  
  If no connection factory definition is explicitly specified using the
  <<<transport.jms.ConnectionFactory>>> parameter, the JMS sender will check if the transport
  configuration contains a connection factory compatible with the other settings specified in the
  endpoint URL (<<<transport.jms.ConnectionFactoryJNDIName>>>, <<<java.naming.factory.initial>>>,
  <<<java.naming.provider.url>>>, <<<java.naming.security.principal>>> and
  <<<java.naming.security.credentials>>>). 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.
  
** {Message context properties for outcoming messages}

  For outgoing messages, the transport sender will recognize the following message context
  properties:
  
    [<<<TRANSPORT_HEADERS>>>]
    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.

  Note that all the properties are optional.
  
* {Content type detection}

  [Incoming requests]
  The content type of the message is determined according to the settings specified in
  the <<<transport.jms.ContentType>>> service parameter.
  
  [Outgoing responses]
  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.
  
  [Outgoing requests]
  The content type will be stored in the message property specified by
  the <<<transport.jms.ContentTypeProperty>>> message context property or
  the <<<transport.jms.ContentTypeProperty>>> parameter of the endpoint reference.
  
  [Incoming responses]
  The content type will be extracted from the message property that was used to
  store the content type of the outgoing request.