Mule : Configuring Jms

This page descibes the specifics for setting up various Jms Servers in Mule. For more information about all Mule Jms configuration go here.

If you have configuration for a Jms server not listed here or there is a mistake on this page please raise a JIRA to get the document updated. Thanks.

JMS Endpoint URIs and JNDI destinations

Some JNDI implementations treat dot (.) and forward slash symbols differently in destination names, so jms://order/incoming may not be the same as jms://order.incoming, but the former will not give you the order/incoming destination, but incoming. If you are dealing with such a server (JBoss is known to behave this way), here is a trick to help you:

jms:////order/incoming

For topics, add the standard prefix, so it takes the following form:

jms:////topic:order/incoming

Note: If using JBoss, remember to omit the queue/ and topic/ from the full JNDI name.

See Mule Endpoint URIs for reference. and JmsEndpointTestCase for some more examples.

The following are just examples and configuration values will change depending on your application environment.

ActiveMQ

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>
        <property name="specification" value="1.1"/>
        <property name="connectionFactoryJndiName" value="ConnectionFactory"/>
        <property name="jndiInitialFactory"
                  value="org.activemq.jndi.ActiveMQInitialContextFactory"/>
        <map name="connectionFactoryProperties">
            <property name="brokerURL" value="vm://localhost"/>
            <property name="brokerXmlConfig"
                      value="classpath:/org/mule/test/activemq-config.xml"/>
        </map>
    </properties>
</connector>

The specification property tells Mule to use the Jms 1.1 specification, which is the specification ActiveMQ supports. To disable queue persistence, you'll need to specify it in ActiveMQ configuration file (see below).

To configure ActiveMQ on a specific brokerUrl or from an ActiveMQ configuration file use the following (Spring version)

mule-config.xml

<!-- Give this container a name in case you have more than one container,
     e.g. Spring, Plexus, JNDI, EJB, etc. You can safely omit it if you
     don't have these requirements.
-->
<container-context className="org.mule.extras.spring.SpringContainerContext"
                   name="spring">
    <properties>
        <property name="configFile" value="classpath:/org/mule/test/activemq-spring.xml"/>
    </properties>
</container-context>

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>
        <property name="specification" value="1.1"/>
        <!-- The container name must be the same as above in
             container-context element or empty (then the first available
             one will be used.
        -->  
        <container-property name="connectionFactory"
                            reference="activeMqConnectionFactory"
                            container="spring"
    </properties>
</connector>

activemq-spring.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
    <bean id="activeMqConnectionFactory" class="org.activemq.ActiveMQConnectionFactory">
        <property name="brokerURL" value="vm://localhost"/>
        <property name="brokerXmlConfig"
                  value="classpath:/org/mule/test/activemq-config.xml"/>
        <!-- More properties you want set on ActiveMQConnectionFactory -->
    </bean>
</beans>

Your ActiveMQ config is a standard one. E.g. to use in-JVM messaging without persistent queues (very useful for testing) the file will be as follows:

activemq-config.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE beans PUBLIC  "-//ACTIVEMQ//DTD//EN" "http://activemq.org/dtd/activemq.dtd">

<beans>
    <broker>
        <connector>
            <serverTransport uri="vm://localhost"/>
        </connector>

        <persistence>
            <vmPersistence/>
        </persistence>
    </broker>
</beans>

JBoss MQ

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>
        <property name="jndiInitialFactory"
          value="org.jnp.interfaces.NamingContextFactory"/>
       <property name="jndiProviderUrl" value="jnp://localhost/"/>
       <property name="connectionFactoryJndiName" value="java:/ConnectionFactory"/>
    </properties>
</connector>

Any provider-specific properties can be passed to the InitialContext for this connector using the jndiProviderProperties attribute. Use connectionFactoryProperties to set JBoss-specific properties on the ConnectionFactory.

OpenJms

The following example configuration describes how to configure a MUle JmsConnector for OpenJms. You will probably need to change the connectionFactoryJndiName to one that is configured from your OpenJms configuration.

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>
        <property name="connectionFactoryJndiName" value="QueueConnectionFactory"/>
        <property name="jndiInitialFactory" 
         value="org.exolab.jms.jndi.InitialContextFactory"/>
        <property name="jndiProviderUrl" value="tcp://localhost:3035"/>
    </properties>
</connector>

UberMQ

Todo. If you are using Mule with Uber MQ please contact us with your configuration and any tips to getting Uber MQ and Mule working together. Thanks!

WebLogic Jms

The configuration shown is for Weblogic 8.1 but should work with previous versions.

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>	    
        <property name="specification" value="1.0.2b"/>
        <property name="connectionFactoryJndiName"
            value="yourConnectionFactory" />
        <property name="jndiInitialFactory" 
	   value="weblogic.jndi.WLInitialContextFactory"/>
        <property name="jndiProviderUrl" value="t3://localhost:7001"/>
    </properties>
</connector>

Oracle Advanced Queuing (AQ)

There are some tricks to getting Oracle AQ working with Mule because the AQ implementation veers from the Jms specification when creating Connection Factories. The big difference is that Oracle uses a db-centric queue model meaning that really when you create a Connection you are creating a Oracle Jdbc connection. This connector will let Mule talk via the Jms API to a queue in an oracle database without using Jndi. (oracle standard edition disables exporting a queue to a repository).
This connector can be used to send a jms message when table data changes.

The Oracle JMS Provider extends the standard Mule Jms Provider with functionality specific to Oracle's JMS implementation based on Advanced Queueing (Oracle AQ).

The javadoc for this transport provider can be found here. And the Source Xref can be found here.

The Oracle JMS Provider adds support for queues with ADT (Advanced Data Type) payloads, including Oracle's native XML data type

Unlike the standard JMS Provider, the Oracle JMS Provider does not require a JNDI provider to use.

Properties

In addition to the properties available for the standard Jms Provider, the Oracle JMS Provider adds the following properties:

Transformers

The default transformers are the same as the standard JMS Provider (JMSMessageToObject and ObjectToJMSMessage).

Example Configuration

<mule-configuration id="TestConfiguration" version="1.0">
    <connector name="oracleJmsConnector" className="org.mule.providers.oracle.jms.OracleJmsConnector">
        <properties>
           <property name="url" value="jdbc:oracle:oci:@myhost" />
        <property name="username" value="scott" />
      <property name="password" value="tiger" />
  </properties>
    </connector>
    <transformers>
        <transformer name="StringToXMLMessage"
             className="org.mule.providers.oracle.jms.transformers.StringToXMLMessage"
             returnClass="oracle.jms.AdtMessage" />
        <transformer name="XMLMessageToString"
             className="org.mule.providers.oracle.jms.transformers.XMLMessageToString"
             returnClass="java.lang.String" />
    </transformers>
    <global-endpoints>
   <endpoint name="XmlQueue" address="oaq://XML_QUEUE" transformers="StringToXMLMessage" />
    </global-endpoints>
    <model name="Test Model">
        <mule-descriptor name="XML-Driven UMO" implementation="com.foo.MyUMO">
      <inbound-router>
                    <endpoint address="oaq://XML_QUEUE" transformers="XMLMessageToString">
              <properties>
                        <property name="payloadFactory" value="oracle.xdb.XMLTypeFactory" />
                </properties>
               </endpoint>
         </inbound-router>
        </mule-descriptor>
    </model>
</mule-configuration>

Endpoints

Oracle AQ endpoints are expressed in the same way as Jms endpoints except the protocol is different.

You can define an Oracle AQ endpoint without declaring the connector (as shown above), by including all necessary information on the endpoint uri i.e.

Dependencies

The Oracle JMS Provider requires the following Oracle libraries, which should be included in your Oracle installation:

Unit Tests

The unit tests consist of two test suites: UnitTestSuite.java and IntegrationTestSuite.java. Only the integration test suite requires a live Oracle database.
In order to run the integration tests, you must edit the settings in file src/test/java/org/mule/providers/oracle/jms/TestConfig.java according to your Oracle database.

Roadmap (TO DO)

SonicMQ

<connector name="jmsSonicMQConnector" className="org.mule.providers.jms.JmsConnector">
	<properties>
		<property name="specification" value="1.1"/>
		<property name="connectionFactoryJndiName" value="sonic-cf"/>
		<property name="jndiInitialFactory" value="com.sonicsw.jndi.mfcontext.MFContextFactory"/>
		<property name="jndiProviderUrl" value="tcp://localhost:2506"/>

		<!-- Optional values for the factory -->
		<map name="connectionFactoryProperties">
			<property name="clientID" value="clientIDString"/>
			<property name="connectID" value="connectIDString"/>
			<property name="connectionURLs" value="somURLStrings here"/>
			<property name="defaultUser" value="userString"/>
			<property name="defaultPassword" value="passwordString"/>
			<property name="prefetchCount" value="10"/>
			<property name="prefetchThreshold" value="10"/>
			<property name="faultTolerant" value="true"/>
			<property name="persistentDelivery" value="true"/>
			<property name="loadBalancing" value="true"/>
			<property name="sequential" value="false"/>
		</map>


		<map name="jndiProviderProperties">
			<property name="com.sonicsw.jndi.mfcontext.domain" value="Domain1"/>
			<property name="java.naming.security.principal" value="Administrator"/>
			<property name="java.naming.security.credentials" value="Administrator"/>
			<!-- optional, default is 30sec -->
			<property name="com.sonicsw.jndi.mfcontext.idleTimeout" value="5000"/>
		</map>


		<property name="username" value="Administrator"/>
		<property name="password" value="Administrator"/>

	</properties>


</connector>

SeeBeyond

The configuration provided is for the SeeBeyond ICAN IQManager JMS Server. Note the values in [ ] (square brackets), these should be replaced by values relevant to your installation.

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>	    
        <property name="jndiInitialFactory" 
	          value="com.stc.is.naming.NamingContextFactory"/>
        <!-- port 18006 is the default, change it in the SeeBeyond designer -->
        <property name="jndiProviderUrl" value="[ServerName]:18006"/>
        <property name="connectionFactoryJndiName"
                  value="/jms/connectionfactory/queue/[LogicalHostName]_[JMS iqManager Name]" />
    </properties>
</connector>

For a topic, the connectionFactoryJndiName would be /jms/connectionfactory/topic/[LogicalHostName]_[JMS iqManager Name].

You will need the following jars and files from the Java ApiKit on your classpath:

IBM WebSphere MQ

To configure a WebSphere MQ Jms connector for Mule you will need to do the following -

Set up the Connection Factory

Under WAS Admin Console >
Resources > WebSphere MQ JMS Provider > WebSphere MQ Queue Connection Factories

Mule Configuration

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>
        <property name="specification" value="1.1"/>
        <property name="jndiInitialFactory"   
                   value="com.ibm.websphere.naming.WsnInitialContextFactory"/>
        <property name="connectionFactoryJndiName" value="jms/ConnectionFactory"/>
    </properties>
</connector>

Note that WebSphere MQ v5.3 requires at least Fix Pack 6 (CSD06) applied for JMS 1.1 support. Earlier levels must set the specification property to 1.0.2b.
The latest WebSphere MQ Fix Packs can be downloaded here: http://www-1.ibm.com/support/docview.wss?uid=swg27006037

Spirit Wave

The following demonstrates how to configure Mule to use the SpiritWave Jms server.

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>
        <property name="connectionFactoryJndiName" value="ConnectionFactory"/>
        <property name="jndiInitialFactory" 
                  value="com.spirit.core.util.builder.JNDIResolver"/>
        <map name="jndiProviderProperties">
            <property name="messageChannels" value="tcp://localhost:50607"/>
            <property name="driverName" value="SpiritWave"/>
        </map>   
    </properties>
</connector>

Tibco EMS

<connector name="jmsConnector" className="org.mule.providers.jms.JmsConnector">
        <properties>
            <property name="jndiProviderUrl" value="tibjmsnaming://<ip or hostname>:port"/>
            <property name="connectionFactoryJndiName" value="QueueConnectionFactory"/>
            <map name="jndiProviderProperties">
                <property name="java.naming.factory.initial" value="com.tibco.tibjms.naming.TibjmsInitialContextFactory"/>

                <!-- These are JNDI authentication -->
                <property name="java.naming.security.principal" value="<username>"/>
                <property name="java.naming.security.credentials"value="<password>/>
            </map>

            <!-- These are used for Queue-level access authentication -->
            <property name="username" value="<username>"/>
            <property name="password" value="<password>"/>

        </properties>
    </connector>

Joram Jms

Using Joram with Mule is a little less straight forward that the other Jms servers if you do not have a Jndi context set up for your connections and destinations. If you have Jndi set up you can use the following-

<connector name="JMSConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>
        <property name="connectionFactoryJndiName" value="QueueConnectionFactory"/>
        <property name="specification" value="1.1"/>
        <property name="jndiDestinations" value="true"/>
        <property name="connectionFactoryJndiName" value="ConnectionFactory"/>
        <property name="jndiInitialFactory" 
             value="fr.dyade.aaa.jndi2.client.NamingContextFactory"/>
        <map name="jndiProviderProperties">
            <property name="java.naming.factory.host" value="localhost"/>
            <property name="java.naming.factory.port" value="16400"/>
        </map>
    </properties>
</connector>

If you do not have Jndi set up you need to manually create a Jndi Initial Context. You can do this by adding a Mule property factory (like the one listed below). Your configuration will look something like -

<connector name="JMSConnector" className="org.mule.providers.jms.JmsConnector">
    <properties>
        <property name="connectionFactoryJndiName" value="QueueConnectionFactory"/>
        <property name="specification" value="1.1"/>
        <property name="jndiDestinations" value="true"/>
        <list name="jndiQueues">
            <entry value="exception.queue"/>
        </list>
        <property-factory name="jndiContext" value="com.foo.joram.JoramInitialContextFactory"/>
    </properties>
</connector>

The Jndi property factory class will look like the following, though you may want to add support for other Joram properties.

JoramInitialContextFactory.java

public class JoramTest implements PropertyFactory
{
    public Object create(Map properties) throws Exception
    {
        String connectionFactoryJndiName = (String) properties.get("connectionFactoryJndiName");
        if (connectionFactoryJndiName == null)
        {
            throw new InitialisationException(
               "connectionFactoryJndiName must be set");
        }
        // Connecting to JORAM server:
        AdminModule.connect("root", "root", 60);

        //Create anonymous user if security is not required
        User user = User.create("anonymous", "anonymous");
        // Creating the JMS administered objects:
        javax.jms.ConnectionFactory connFactory = TcpConnectionFactory.create();

        // Binding objects in JNDI:
        //Create Jndi Queues
        javax.naming.Context jndiCtx = new javax.naming.InitialContext();
        jndiCtx.bind(connectionFactoryJndiName, connFactory);
        List queues = (List)properties.get("jndiQueues");
        if(queues!=null) {
            Queue queue;
            String name;
            for (Iterator iterator = queues.iterator(); iterator.hasNext();)
            {
                name = (String) iterator.next();
                queue = (Queue) Queue.create(0);
                // Setting free access to the queue:
                queue.setFreeReading();
                queue.setFreeWriting();
                jndiCtx.bind(name, queue);
            }
        }

        //Create Jndi Topics
        List topics = (List)properties.get("jndiTopics");
        if(topics!=null) {
            Topic topic;
            String name;
            for (Iterator iterator = topics.iterator(); iterator.hasNext();)
            {
                name = (String) iterator.next();
                topic = (Topic) Topic.create(0);
                // Setting free access to the queue:
                topic.setFreeReading();
                topic.setFreeWriting();
                jndiCtx.bind(name, topic);
            }
        }
        AdminModule.disconnect();
        return jndiCtx;
    }
}