JMS Transport

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.

Apache Axis2