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.

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.