JMS Transport

Table of Contents

Click here to expand...

This page describes the JMS transport, which provides a standard JMS 1.0.2b and 1.1 connector. This connector exposes all features defined in the 1.0.2b/1.1 specification. It also provides links to information on configuring various types of JMS, such as ActiveMQ. Note that if you are using Oracle AQ, you can use the JMS transport without any special configuration if you are using Oracle 10 or later. For details, see the example on the [Mule Cookbook].

For information on managing JMS local and distributed (XA) transactions, as well as multi-resource transactions (for Mule Enterprise Edition users), see Transaction Management.

Additionally, the Error Handler Example and Loan Broker Example demonstrate using the Active MQ connector and various JMS transformers.

The Javadoc for the JMS transport can be found here .

JMS Configuration

This section provides general information about JMS configuration with Mule. For links to information on specific JMS servers, see Configuring Specific JMS Servers below.

Declaring the Namespace

To use the JMS transport, you must declare the JMS namespace in the header of the Mule configuration file. You can then configure the JMS connector and endpoints. For example:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core/2.2"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:spring="http://www.springframework.org/schema/beans"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:jms="http://www.mulesource.org/schema/mule/jms/2.2"
       xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
       http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util-2.5.xsd
       http://www.mulesource.org/schema/mule/core/2.2 http://www.mulesource.org/schema/mule/core/2.2/mule.xsd
       http://www.mulesource.org/schema/mule/jms/2.2 http://www.mulesource.org/schema/mule/jms/2.2/mule-jms.xsd">

    <spring:bean name="connectionFactory" class="org.mule.transport.jms.test.TestConnectionFactory"/>
    
    <spring:bean name="redeliveryHandlerFactory" class="org.mule.transport.jms.test.TestRedeliveryHandlerFactory"/>
    
    <jms:connector name="jmsConnector1"
                   acknowledgementMode="DUPS_OK_ACKNOWLEDGE"
                   clientId="myClient"
                   durable="true"
                   noLocal="true"
                   persistentDelivery="true"
                   maxRedelivery="5"
                   cacheJmsSessions="true"
                   eagerConsumer="false"
                   specification="1.1"
                   numberOfConsumers="7"
                   connectionFactory-ref="connectionFactory"
                   redeliveryHandlerFactory-ref="redeliveryHandlerFactory"
                   username="myuser"
                   password="mypass"/>
...

Using Topics, Queues, or Both

When specifying a destination name in a URI, and JNDI destinations are not being used, the default destination created is a queue. For example, the following JMS endpoint will manifest itself as a JMS queue called my.destination.

jms://my.destination

To make this destination a topic instead of a queue, you must prepend the destination name with topic: in the URI. In transport-specific endpoints, you set the topic and queue attributes explicitly. For example:

jms://topic:my.destination

or

<jms:inbound-endpoint topic="my.destination"/>
<jms:outbound-endpoint queue="my.destination"/>

If you are using a JMS 1.1 compliant server, you can use the same JMS connector for both queues and topics. If you are using a JMS 1.0.2b server, and you want to use both queues and topics in your Mule configuration, you must create two JMS connectors: one with a JNDI connection factory that references a QueueConnectionFactory, and another that references a TopicConnectionfactory. Each JMS endpoint must reference the correct connector depending on whether the destination is a topic or a queue. To specify the connector on a JMS endpoint, you add the connector parameter to the URI or the connector-ref attribute on a transport-specific endpoint:

jms://my.destination?connector=jmsQueueConnector
jms://topic:my.destination?connector=jmsTopicConnector

or

<jms:outbound-endpoint queue="my.destination" connector-ref="jmsQueueConnector"/>
<jms:inbound-endpoint topic="my.destination" connector-ref="jmsTopicConnector"/>

If the endpoint is configured as topic, number of consumers on this endpoint will be limited to one. If numberOfConcurrentTransactedReceivers or numberOfConsumers is set on the connector, Mule will override it.

Specifying Additional Information

When creating JMS connectors, more information is needed such as ConnectionFactory JNDI details. This information can be set as parameters on the URI, but this can get difficult to manage and read. The recommend approach is described in Looking Up JMS Objects from JNDI below.

Configuring Transactional Polling

To periodically read data from an external resource, you can set up a Quartz inbound endpoint that passes the message to a JMS outbound endpoint. As of Mule enterprise edition 2.2.4, this approach supports transactions and multi-resource transactions.

For example, in the following configuration, an inbound endpoint polls a WMQ resource every five seconds and passes the results to a JMS endpoint. Both the WMQ and JMS endpoints are configured with multi-resource transactions:

<?xml version="1.0" encoding="UTF-8"?>
<mule xmlns="http://www.mulesource.org/schema/mule/core"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xmlns:spring="http://www.springframework.org/schema/beans"
      xmlns:jms="http://www.mulesource.org/schema/mule/jms"
      xmlns:quartz="http://www.mulesource.org/schema/mule/quartz"
      xmlns:wmq="http://www.mulesource.org/schema/mule/ee/wmq"
      xmlns:ee="http://www.mulesource.org/schema/mule/ee/core"
      xsi:schemaLocation="
       http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd
       http://www.mulesource.org/schema/mule/core http://www.mulesource.org/schema/mule/core/3.0/mule.xsd
       http://www.mulesource.org/schema/mule/ee/core http://www.mulesource.org/schema/mule/ee/core/3.0/mule-ee.xsd
       http://www.mulesource.org/schema/mule/jms http://www.mulesource.org/schema/mule/jms/3.0/mule-jms.xsd
       http://www.mulesource.org/schema/mule/quartz http://www.mulesource.org/schema/mule/quartz/3.0/mule-quartz.xsd
       http://www.mulesource.org/schema/mule/ee/wmq http://www.mulesource.org/schema/mule/ee/wmq/3.0/mule-wmq-ee.xsd">

<wmq:connector name="wmqConnector"
                   hostName="174.129.235.61"
                   port="1414"
                   disableTemporaryReplyToDestinations="true"
                   queueManager="QM_dev"
                   targetClient="NONJMS_MQ"
                   transportType="CLIENT_MQ_TCPIP"
                   specification="1.1"
                   numberOfConsumers="10"
                   username=""
                   password="">
        <service-overrides
            transactedMessageReceiver="com.mulesource.mule.transport.jms.TransactedPollingJmsMessageReceiver" />
    </wmq:connector>

    <wmq:endpoint name="wmqInbound" queue="myQueue.in" connector-ref="wmqConnector">
        <ee:multi-transaction action="ALWAYS_BEGIN"/>
    </wmq:endpoint>

    <jms:activemq-connector name="amqConnector"
                            specification="1.1"
                            brokerURL="tcp://localhost:61616">
        <ee:retry-simple-policy asynchronous="true" count="1"/>
    </jms:activemq-connector>

     <model name="Multi-TX Test Model">

        <service name="pollingTrigger">
            <inbound>
                <wmq:inbound-endpoint ref="wmqInbound" connector-ref="wmqConnector">
                    <properties>
                        <!-- Each receiver polls with a 5 second interval -->
                        <spring:entry key="pollingFrequency" value="5000"/>
                    </properties>
                </wmq:inbound-endpoint>
            </inbound>

            <outbound>
                <pass-through-router enableCorrelation='NEVER'>
                    <jms:outbound-endpoint queue="myQueue.out" connector-ref="amqConnector">
                        <ee:multi-transaction action="ALWAYS_JOIN"/>
                    </jms:outbound-endpoint>
                </pass-through-router>
            </outbound>

        </service>
    </model>
</mule>

JMS Selectors

You can set a JMS selector as a filter on an endpoint. The JMS selector simply sets the filter expression on the consumer.

<jms:endpoint queue="important.queue" connector-ref="...">
    <jms:selector expression="JMSPriority=9"/>
</jms:endpoint>

Durable Subscribers

You can use durable subscribers by setting the durable attribute on the JMS connector. This attribute tells the connector to make all topic subscribers durable (it does not apply to queues). You can override the connector's durable attribute at the endpoint level. For example, you can set durable to false on the connector and set it to true just on the endpoints that require it.

<jms:connector name="jmsTopicConnector" durable="false"/>
...
<jms:inbound-endpoint topic=durable.topic" connector-ref="jmsTopicConnector">
    <property key="durable" value="true"/>
</endpoint>

When using a durable subscription, the JMS server requires a durable name to identify this subscriber. By default, Mule generates the durable name in the following format:

mule.<connector name>.<topic name>

If you want to set the durable name yourself, you can set the durableName property on the endpoint.

<jms:inbound-endpoint topic="durable.topic" connector-ref="jmsTopicConnector">
    <property key="durable" value="true"/>
    <property key="durableName" value="myDurableSubscription"/>
</jms:inbound-endpoint>

The URI equivalent would be:

jms://topic:durable.topic?durableName=myDurableSubscription

Overloading JMS Behavior

Some JMS servers require a different sequence of calls when creating JMS resources. For example, [Oracle's Advanced Queuing]requires that the connection is started before listeners can be registered. In this scenario the user can overload the JmsSupport class to customize the way JMS resources are initialized. Configuring this customization requires that you tell the JMS connector to use a custom JmsSupport class.

<spring:bean id="customJmsSupport" class="org.foo.jms.CustomJmsSupport"/>

<jms:connector name="jmsConnector">
    <property key="jmsSupport" ref="customJmsSupport"/>
</jms:connector>

For more information about configuring specific JMS servers, see Configuring Specific JMS Servers below.

Looking Up JMS Objects from JNDI

If you have configured a JNDI context on the connector, you can also look up queues/topics via JNDI using the jndiDestinations attribute. If a queue/topic cannot be found via JNDI, it will be created using the existing JMS session unless you also set the forceJndiDestinations attribute.

There are two different ways to configure the JNDI settings:

1. Using connector properties (deprecated):

   <jms:connector name="jmsConnector"
       jndiInitialFactory="com.sun.jndi.ldap.LdapCtxFactory"
       jndiProviderUrl="ldap://localhost:10389/"
       connectionFactoryJndiName="cn=ConnectionFactory,dc=example,dc=com"
       jndiDestinations="true"
       forceJndiDestinations="true"/>

2. Using a JndiNameResolver
   A JndiNameResolver defines a strategy for lookup objects by name using JNDI. The strategy contains a lookup method that receives a name and returns the object associated to that name.

At the moment, there are two simple implementations of that interface:

SimpleJndiNameResolver: uses a JNDI context instance to search for the names. That instance is maintained opened during the full lifecycle of the name resolver.

CachedJndiNameResolver: uses a simple cache in order to store previously resolved names. A JNDI context instance is created for each request that is sent to the JNDI server and then the instance is freed. The cache can be cleaned up restarting the name resolver.

Default JNDI name resolver example: define the name resolver using the default-jndi-name-resolver tag and then add the appropriate properties to it.

<jms:activemq-connector name="jmsConnector"
                            jndiDestinations="true"
                            connectionFactoryJndiName="ConnectionFactory">
        <jms:default-jndi-name-resolver
                jndiInitialFactory="org.apache.activemq.jndi.ActiveMQInitialContextFactory"
                jndiProviderUrl="vm://localhost?broker.persistent=false&amp;broker.useJmx=false"
                jndiProviderProperties-ref="providerProperties"/>
    </jms:activemq-connector>

Custom JNDI name resolver example: define the name resolver using the custom-jndi-name-resolver tag, then add the appropriate property values using the Spring's property format.

    <jms:activemq-connector name="jmsConnector"
                            jndiDestinations="true"
                            connectionFactoryJndiName="ConnectionFactory">
        <jms:custom-jndi-name-resolver class="org.mule.transport.jms.jndi.CachedJndiNameResolver">
            <spring:property name="jndiInitialFactory" value="org.apache.activemq.jndi.ActiveMQInitialContextFactory"/>
            <spring:property name="jndiProviderUrl"
                             value="vm://localhost?broker.persistent=false&amp;broker.useJmx=false"/>
            <spring:property name="jndiProviderProperties" ref="providerProperties"/>
        </jms:custom-jndi-name-resolver>
    </jms:activemq-connector>

Returning the Original Message as a Reply

(As of Mule enterprise edition 2.2.3) If you do not set a reply-to address, and you have disabled the temporary reply-to, you can return the original message as a reply. To configure this behavior, you set disableTemporaryReplyToDestinations and returnOriginalMessageAsReply to true as Spring properties on the connector or endpoint:

<jms:connector ...>
  <spring:property name="disableTemporaryReplyToDestinations" value="true" />
  <spring:property name="returnOriginalMessageAsReply" value="true" />
</jms:connector>

or

<jms:endpoint ...>
  <properties>
    <spring:entry key="disableTemporaryReplyToDestinations" value="true" />
    <spring:entry key="returnOriginalMessageAsReply" value="true" />
  </properties>
</jms:endpoint>

JMS Transformers

Transformers for the JMS provider can be found at org.mule.transport.jms.transformers .

JMS Header Properties

When the message is received and transformed, all the message properties are still available via the MuleMessage object. To access standard JMS properties such as JMSCorrelationID and JMSRedelivered, simply use the property name, as shown in the following example:

String corrId = (String) muleMessage.getProperty("JMSCorrelationID");
boolean redelivered =  muleMessage.getBooleanProperty("JMSRedelivered");

You can access any custom header properties on the message in the same way.

Configuring Specific JMS Servers

The following links describe how to set up various JMS servers in Mule. Note that the configurations provided are just examples. Configuration values will change depending on your application environment.

• ActiveMQ
• FioranoMQ
• JBoss MQ
• Mule MQ
• OpenJms
• Open MQ
• [Oracle AQ]
• SeeBeyond
• SonicMQ
• Sun JMS Grid
• SwiftMQ
• Tibco EMS
• WebLogic JMS

Additionally, if you are using Mule Enterprise Edition, you can use the Mule WMQ Transport to integrate with WebSphere MQ.

Schema Reference

Connector The connector element configures a generic connector for sending and receiving messages over JMS queues.

Attributes of <connector...>

Child Elements of <connector...>

Custom Connector The custom-connector element configures a custom connector for sending and receiving messages over JMS queues.

Attributes of <custom-connector...>

Child Elements of <custom-connector...>

Activemq Connector The activemq-connector element configures an ActiveMQ version of the JMS connector.

Attributes of <activemq-connector...>

Activemq Xa Connector The activemq-xa-connector element configures an ActiveMQ version of the JMS connector with XA transaction support.

Attributes of <activemq-xa-connector...>

Weblogic Connector The weblogic-connector element configures a WebLogic version of the JMS connector.

Attributes of <weblogic-connector...>

Child Elements of <weblogic-connector...>

Transaction The transaction element configures a transaction. Transactions allow a series of operations to be grouped together so that they can be rolled back if a failure occurs. Set the action (such as ALWAYS_BEGIN or JOIN_IF_POSSIBLE) and the timeout setting for the transaction.

Client Ack Transaction The client-ack-transaction element configures a client acknowledgment transaction, which is identical to a transaction but with message acknowledgements. There is no notion of rollback with client acknowledgement, but this transaction can be useful for controlling how messages are consumed from a destination.

Jmsmessage To Object Transformer The jmsmessage-to-object-transformer element configures a transformer that converts a JMS message into an object by extracting the message payload.

Object To Jmsmessage Transformer The object-to-jmsmessage-transformer element configures a transformer that converts an object into one of five types of JMS messages, depending on the object passed in: java.lang.String -> javax.jms.TextMessage, byte[] -> javax.jms.BytesMessage, java.util.Map (primitive types) -> javax.jms.MapMessage, java.io.InputStream (or java.util.List of primitive types) -> javax.jms.StreamMessage, and java.lang.Serializable including java.util.Map, java.util.List, and java.util.Set objects that contain serializable objects (including primitives) -> javax.jms.ObjectMessage.

Inbound Endpoint The inbound-endpoint element configures an endpoint on which JMS messages are received.

Attributes of <inbound-endpoint...>

Outbound Endpoint The inbound-endpoint element configures an endpoint to which JMS messages are sent.

Attributes of <outbound-endpoint...>

Endpoint The endpoint element configures a global JMS endpoint definition.

Attributes of <endpoint...>

Property Filter The property-filter element configures a filter that allows you to filter messages based on a JMS property.

Attributes of <property-filter...>