Contact Us 1-800-596-4880
  1. Homepage
  2. Mule Runtime (3.2)
  3. Reference Materials for Mule ESB 3
  4. = Reference Materials for Mule ESB 3

  5. JMS Transport Reference

JMS Transport Reference

Introduction

JMS (Java Message Service) is a widely-used API for Message Oriented Middleware. It allows communication between different components of a distributed application to be loosely coupled, reliable, and asynchronous.

JMS supports two models for messaging:

Queues - point-to-point Topics - publish and subscribe

Mule’s JMS transport allows you to easily send and receive messages to queues and topics for any message service which implements the JMS specification.

Namespace and Syntax

XML namespace:

xmlns:jms "http://www.mulesoft.org/schema/mule/jms"

XML schema location:

http://www.mulesoft.org/schema/mule/jms/3.2/mule-jms.xsd

Schema Structure

Connector syntax:

<jms:connector name="myConnector" specification="1.1" connectionFactory-ref="myConnectionFactory" username="myuser" password="mypass"/>

Endpoint syntax:

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

Considerations

In the point-to-point or queuing model, a sender posts messages to a particular queue and a receiver reads messages from the queue. Here, the sender knows the destination of the message and posts the message directly to the receiver’s queue. It is characterized by the following:

  • Only one consumer gets the message

  • The producer does not have to be running at the time the consumer consumes the message, nor does the consumer need to be running at the time the message is sent

  • Every message successfully processed is acknowledged by the consumer

The publish/subscribe model supports publishing messages to a particular message topic. Subscribers may register interest in receiving messages on a particular message topic. In this model, neither the publisher nor the subscriber know about each other. A good analogy for this is an anonymous bulletin board. The following are characteristics of this model:

  • Multiple consumers (or none) will receive the message

  • There is a timing dependency between publishers and subscribers. The publisher has to create a message topic for clients to subscribe.

  • The subscriber has to remain continuously active to receive messages, unless it has established a durable subscription. In that case, messages published while the subscriber is not connected will be redistributed whenever it reconnects.

Features

  • Supports both versions of the JMS specification: 1.0.2b and 1.1

  • Supports queues and topics, durable or non-durable subscriptions

  • ConnectionFactory and Queues/Topics can be looked up via JNDI

  • Supports local (JMS), distributed (XA), and multi-resource

  • Tested with a variety of JMS providers

  • Vendor-specific configuration available for popular providers

To see JMS with Mule in action (using ActiveMQ), take a look at the Error Handler Example (available in the full Mule distribution).

WebSphere MQ

Mule Enterprise includes an enhanced transport for WebSphereMQ which is recommended if you are using WebSphereMQ as your JMS provider.

Mule MQ

If you are trying to select a JMS provider for your Mule application, you might consider which is an enterprise-class JMS implementation officially supported by MuleSoft.

Usage

Declaring the Namespace

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

JMS namespace

<mule ...cut...   xmlns:jms="http://www.mulesoft.org/schema/mule/jms"   xsi:schemaLocation=" ...cut...     http://www.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/3.2/mule-jms.xsd">

Configuring the Connector

There are several attributes available on the connector, most of which are optional. Refer to the schema documentation below for complete information.

Connector attributes

<jms:connector name="myConnector"               acknowledgementMode="DUPS_OK_ACKNOWLEDGE"               clientId="myClient"               durable="true"               noLocal="true"               persistentDelivery="true"               maxRedelivery="5"               cacheJmsSessions="true"               eagerConsumer="false"               specification="1.1"               numberOfConsumers="7"               username="myuser"               password="mypass" />

Configuring the ConnectionFactory

One of the most important attributes is connectionFactory-ref. This is a reference to the ConnectionFactory object which creates new connections for your JMS provider. The object must implement the interface javax.jms.ConnectionFactory.

ConnectionFactory

<spring:bean name="connectionFactory" class="com.foo.FooConnectionFactory"/><jms:connector name="jmsConnector1" connectionFactory-ref="connectionFactory" />

There are also a few attributes which allow you to look up the ConnectionFactory from a JNDI Context:

ConnectionFactory from JNDI

<jms:connector name="jmsConnector"    jndiInitialFactory="com.sun.jndi.ldap.LdapCtxFactory"    jndiProviderUrl="ldap://localhost:10389/"    jndiProviderProperties-ref="providerProperties"    connectionFactoryJndiName="cn=ConnectionFactory,dc=example,dc=com" />

Configuring the Endpoints

Queues

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

Topics

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

By default, Mule’s subscription to a topic is non-durable (i.e., it will only receive messages while connected to the topic). You can make topic subscriptions durable by setting the durable attribute on the connector.

When using a durable subscription, the JMS server requires a durable name to identify each subscriber. By default, Mule generates the durable name in the format mule.<connector name>.<topic name>. If you want to specify the durable name yourself, you can do so using the durableName attribute on the endpoint.

Durable Topic

<jms:connector name="jmsTopicConnector" durable="true"/><jms:inbound-endpoint topic="some.topic" durableName="sub1" /><jms:inbound-endpoint topic="some.topic" durableName="sub2" /><jms:inbound-endpoint topic="some.topic" durableName="sub3" />

Number of consumers

In the case of a topic, the number of consumers on the endpoint will be set to one. You can override this by setting numberOfConcurrentTransactedReceivers or numberOfConsumers on the connector.

Transformers

The default transformers applied to JMS endpoints are as follows: inbound = JMSMessageToObject response = ObjectToJMSMessage outbound = ObjectToJMSMessage

These will automatically transform to/from the standard JMS message types:

javax.jms.TextMessage - java.lang.Stringjavax.jms.ObjectMessage - java.lang.Objectjavax.jms.BytesMessage - byte[]javax.jms.MapMessage - java.util.Mapjavax.jms.StreamMessage - java.io.InputStream

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"/>

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

Changes in JmsConnector

There are some property changes in the JmsConnector definition. Some properties are now deprecated as they should be defined in a JndiNameResolver and then using that JndiNameResolver in the JmsConnector.

Deprecated properties in JmsConnector:

  • jndiContext

  • jndiInitialFactory

  • jndiProviderUrl

  • jndiProviderProperties-ref

Added property:

  • jndiNameResolver: used to set a proper JndiNameResolver. Can be set using the default-jndi-name-resolver or custom-jndi-name-resolver tags inside the JmsConnector definition.

JMS Selectors

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

JMS Selector

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

JMS Header Properties

Once a JMS message is received by Mule, the standard JMS headers such as JMSCorrelationID and JMSRedelivered are made available as properties on the MuleMessage object.

Retrieving JMS Headers

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 Transactional Polling

The Enterprise version of the JMS transport can be configured for transactional polling using the TransactedPollingJmsMessageReceiver.

Transactional Polling

<jms:connector ...cut...>     <service-overrides transactedMessageReceiver="com.mulesoft.mule.transport.jms.TransactedPollingJmsMessageReceiver" /></jms:connector><jms:inbound-endpoint queue="my.queue">     <properties>          <spring:entry key="pollingFrequency" value="5000" /> ❶     </properties></jms:inbound-endpoint>

❶ Each receiver polls with a 5 second interval

Example Configurations

Example configuration

<mule ...cut...  xmlns:jms="http://www.mulesoft.org/schema/mule/jms"  xsi:schemaLocation="...cut...    http://www.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/3.2/mule-jms.xsd"> ❶    <spring:bean name="connectionFactory" class="com.foo.FooConnectionFactory"/>    <jms:connector name="jmsConnector" connectionFactory-ref="connectionFactory" username="myuser" password="mypass" />    <flow name="MyFlow">        <jms:inbound-endpoint queue="in" />        <component class="com.foo.MyComponent" />        <jms:outbound-endpoint queue="out" />    </flow></mule>

❶ Import the JMS schema namespace

Example configuration with transactions

<mule ...cut...  xmlns:jms="http://www.mulesoft.org/schema/mule/jms"  xsi:schemaLocation="...cut...    http://www.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/3.2/mule-jms.xsd">    <spring:bean name="connectionFactory" class="com.foo.FooConnectionFactory"/>    <jms:connector name="jmsConnector" connectionFactory-ref="connectionFactory" username="myuser" password="mypass" />    <flow name="MyFlow">        <jms:inbound-endpoint queue="in">            <jms:transaction action="ALWAYS_BEGIN" /> ❶        </jms:inbound-endpoint>        <component class="com.foo.MyComponent" />        <jms:outbound-endpoint queue="out">            <jms:transaction action="ALWAYS_JOIN" /> ❶        </jms:outbound-endpoint>    </flow></mule>

❶ Local JMS transaction

Example configuration with exception strategy

<mule ...cut...  xmlns:jms="http://www.mulesoft.org/schema/mule/jms"  xsi:schemaLocation="...cut...    http://www.mulesoft.org/schema/mule/jms http://www.mulesoft.org/schema/mule/jms/3.2/mule-jms.xsd">    <spring:bean name="connectionFactory" class="com.foo.FooConnectionFactory"/>    <jms:connector name="jmsConnector" connectionFactory-ref="connectionFactory" username="myuser" password="mypass" />    <flow name="MyFlow">        <jms:inbound-endpoint queue="in">            <jms:transaction action="ALWAYS_BEGIN" />        </jms:inbound-endpoint>        <component class="com.foo.MyComponent" />        <jms:outbound-endpoint queue="out">            <jms:transaction action="ALWAYS_JOIN" />        </jms:outbound-endpoint>        <default-exception-strategy>            <commit-transaction exception-pattern="com.foo.ExpectedExceptionType"/> ❶            <jms:outbound-endpoint queue="dead.letter"> ❷                <jms:transaction action="JOIN_IF_POSSIBLE" />            </jms:outbound-endpoint>        </default-exception-strategy>    </flow></mule>

❶ Set exception-pattern="*" to catch all exception types ❷ Implements a Dead letter queue for erroneous messages

Example configuration using Service

<mule ...cut...    <spring:bean name="connectionFactory" class="com.foo.FooConnectionFactory"/>    <jms:connector name="jmsConnector" connectionFactory-ref="connectionFactory" username="myuser" password="mypass" />    <model>        <service name="MyService"> ❶            <inbound>                <jms:inbound-endpoint queue="in" />            </inbound>            <component class="com.foo.MyComponent" />            <outbound>                <pass-through-router>                    <jms:outbound-endpoint queue="out" />                </pass-through-router>            </outbound>        </service>    </model></mule>

❶ New implementations are recommended to use flows, but Mule 2.x users are more familiar with <service>.

Vendor-specific Configuration

Mule Enterprise includes an enhanced transport for WebSphereMQ which is recommended if you are using WebSphereMQ as your JMS provider.

Mule MQ is an enterprise-class JMS implementation officially supported by MuleSoft and has tight integration with Mule.

ActiveMQ is also widely-used with Mule and has simplified configuration.

Information for configuring other JMS providers can be found here. Beware that some of this information may be out-of-date.

Configuration Reference

Connector

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

Attributes of <connector…​>

Name Type Required Default Description

connectionFactory-ref

string

no

Reference to the connection factory, which is required for non-vendor JMS configurations.

redeliveryHandlerFactory-ref

string

no

Reference to the redelivery handler.

acknowledgementMode

enumeration

no

AUTO_ACKNOWLEDGE

The acknowledgement mode to use: AUTO_ACKNOWLEDGE, CLIENT_ACKNOWLEDGE, or DUPS_OK_ACKNOWLEDGE.

clientId

string

no

The ID of the JMS client.

durable

boolean

no

Whether to make all topic subscribers durable.

noLocal

boolean

no

If set to true, a subscriber will not receive messages that were published by its own connection.

persistentDelivery

boolean

no

If set to true, the JMS provider logs the message to stable storage as it is sent so that it can be recovered if delivery is unsuccessful. A client marks a message as persistent if it feels that the application will have problems if the message is lost in transit. A client marks a message as non-persistent if an occasional lost message is tolerable. Clients use delivery mode to tell a JMS provider how to balance message transport reliability/throughput. Delivery mode only covers the transport of the message to its destination. Retention of a message at the destination until its receipt is acknowledged is not guaranteed by a PERSISTENT delivery mode. Clients should assume that message retention policies are set administratively. Message retention policy governs the reliability of message delivery from destination to message consumer. For example, if a client’s message storage space is exhausted, some messages as defined by a site specific message retention policy may be dropped. A message is guaranteed to be delivered once-and-only-once by a JMS Provider if the delivery mode of the message is persistent and if the destination has a sufficient message retention policy.

honorQosHeaders

boolean

no

If set to true, the message’s QoS headers are honored. If false (the default), the connector settings override the message headers.

maxRedelivery

integer

no

The maximum number of times to try to redeliver a message. Use -1 to accept messages with any redelivery count.

cacheJmsSessions

boolean

no

Whether to cache and re-use the JMS session object instead of recreating the connection each time. NOTE: meant for non-transactional use ONLY.

eagerConsumer

boolean

no

Whether to create a consumer right when the connection is created instead of using lazy instantiation in the poll loop.

specification

enumeration

no

1.0.2b

The JMS specification to use: 1.0.2b (the default) or 1.1

username

string

no

The user name for the connection

password

string

no

The password for the connection

numberOfConsumers

integer

no

The number of concurrent consumers that will be used to receive JMS messages. (Note: If you use this attribute, you should not configure the 'numberOfConcurrentTransactedReceivers', which has the same effect.)

jndiInitialFactory

string

no

The initial factory class to use when connecting to JNDI. DEPRECATED: use jndiNameResolver-ref propertie to configure this value.

jndiProviderUrl

string

no

The URL to use when connecting to JNDI. DEPRECATED: use jndiNameResolver-ref propertie to configure this value.

jndiProviderProperties-ref

string

no

Reference to a Map that contains additional provider properties. DEPRECATED: use jndiNameResolver-ref propertie to configure this value.

connectionFactoryJndiName

string

no

The name to use when looking up the connection factory from JNDI.

jndiDestinations

boolean

no

Set this attribute to true if you want to look up queues or topics from JNDI instead of creating them from the session.

forceJndiDestinations

boolean

no

If set to true, Mule fails when a topic or queue cannot be retrieved from JNDI. If set to false, Mule will create a topic or queue from the JMS session if the JNDI lookup fails.

disableTemporaryReplyToDestinations

boolean

no

If this is set to false (the default), when Mule performs request/response calls a temporary destination will automatically be set up to receive a response from the remote JMS call.

embeddedMode

boolean

no

false

Some application servers, like WebSphere AS, don’t allow certain methods to be called on JMS objects, effectively limiting available features. Embedded mode tells Mule to avoid those whenever possible. Default is false.

Child Elements of <connector…​>

Name Cardinality Description

abstract-jndi-name-resolver

0..1

A placeholder for jndi-name-resolver strategy elements.

Custom connector

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

Inbound endpoint

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

Attributes of <inbound-endpoint…​>

Name Type Required Default Description

durableName

string

no

(As of 2.2.2) Allows the name for the durable topic subscription to be specified.

queue

string

no

The queue name. This attribute cannot be used with the topic attribute (the two are exclusive).

topic

string

no

The topic name. The "topic:" prefix will be added automatically. This attribute cannot be used with the queue attribute (the two are exclusive).

disableTemporaryReplyToDestinations

boolean

no

If this is set to false (the default), when Mule performs request/response calls a temporary destination will automatically be set up to receive a response from the remote JMS call.

Child Elements of <inbound-endpoint…​>

Name Cardinality Description

mule:abstract-xa-transaction

0..1

selector

0..1

Outbound endpoint

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

Attributes of <outbound-endpoint…​>

Name Type Required Default Description

queue

string

no

The queue name. This attribute cannot be used with the topic attribute (the two are exclusive).

topic

string

no

The topic name. The "topic:" prefix will be added automatically. This attribute cannot be used with the queue attribute (the two are exclusive).

disableTemporaryReplyToDestinations

boolean

no

If this is set to false (the default), when Mule performs request/response calls a temporary destination will automatically be set up to receive a response from the remote JMS call.

Child Elements of <outbound-endpoint…​>

Name Cardinality Description

mule:abstract-xa-transaction

0..1

selector

0..1

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.

No Child Elements of <jmsmessage-to-object-transformer…​>

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.

No Child Elements of <object-to-jmsmessage-transformer…​>

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.

No Child Elements of <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.

No Child Elements of <client-ack-transaction…​>

Selector

Attributes of <selector…​>

Name Type Required Default Description

expression

string

yes

The expression to search for in the property.

No Child Elements of <selector…​>

Property filter

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

XML Schema

Import the XML schema for this module as follows:

xmlns:jms="http://www.mulesoft.org/schema/mule/jms"xsi:schemaLocation="http://www.mulesoft.org/schema/mule/jms  http://www.mulesoft.org/schema/mule/jms/3.2/mule-jms.xsd"

Complete schema reference documentation.

Javadoc

Javadoc for this transport can be found here.

Maven

If you are using Maven to build your application, use the following groupId/artifactId to include this module as a dependency:

<dependency>  <groupId>org.mule.transports</groupId>  <artifactId>mule-transport-jms</artifactId></dependency>

Notes

The 1.0.2b specification has the limitation of only supporting queues or topics for each ConnectionFactory. If you need both, configure two separate connectors, one that references a QueueConnectionFactory, and another that references a TopicConnectionFactory. You can then use the connector-ref attribute to disambiguate the endpoints.

Workaround for 1.0.2b spec.

<spring:bean name="queueConnectionFactory" class="com.foo.QueueConnectionFactory"/><spring:bean name="topicConnectionFactory" class="com.foo.TopicConnectionFactory"/><jms:connector name="jmsQueueConnector" connectionFactory-ref="queueConnectionFactory" /><jms:connector name="jmsTopicConnector" connectionFactory-ref="topicConnectionFactory" /><jms:outbound-endpoint queue="my.queue1" connector-ref="jmsQueueConnector"/><jms:outbound-endpoint queue="my.queue2" connector-ref="jmsQueueConnector"/><jms:inbound-endpoint topic="my.topic" connector-ref="jmsTopicConnector"/>