JMS Transport

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.