Mule : Configuring Jms

Mule : Configuring Jms This page last changed on Oct 20, 2006 by andrew. This page descibes the specifics for setting up various Jms Servers in Mule. For more information about all Mule Jms configuration go here. The following Jms server configurations are described - ActiveMQ JBoss MQ Joram OpenJms Oracle AQ SeeBeyond SonicMQ Spirit Wave Tibco EMS UberMQ Weblogic Jms IBM WebSphere MQ 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. To configure a default embedded broker. <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). You can pass in any provider specific configuration using the connectionFactoryProperties property on the JmsConnector. These will get set on the ConnectionFactory implementation. 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> Configure ActiveMQ from Spring: activemq-spring.xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www./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:///dtd/activemq.dtd"> <beans> <broker> <connector> <serverTransport uri="vm://localhost"/> </connector> <persistence> <vmPersistence/> </persistence> </broker> </beans> JBoss MQ To configure a JBoss Jms connector for Mule use the following - <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. Connection Credentials If you use user creditials to connect to JBossMQ make sure that the user has the 'guest' role assigned to it. This will ensure that there are no issues if Temporary Topics or Queues (i.e. in RemoteSync calls) are used. 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. As of Oracle 9i, only the JMS 1.0.2b specification is supported.   Properties In addition to the properties available for the standard Jms Provider, the Oracle JMS Provider adds the following properties: Property Description Default Required url The JDBC URL for the Oracle database, for example jdbc:oracle:oci:@myhost. The user and password may be specified in the URL itself, for example jdbc:oracle:oci:scott/tiger@myhost, in which case the (standard JMS Provider) properties username and password are not required.     yes multipleSessionsPerConnection Some versions of Oracle do not support more than one JMS session per connection. In this case we need to open a new connection for each session to avoid the following error: JMS-106: Cannot have more than one open Session on a JMSConnection false no payloadFactory If the queue's payload is an ADT (Oracle Advanced Data Type), the appropriate payload factory must be specified in the endpoint's properties.   no Transformers In addition to the transformers available for the standard Jms Provider, the Oracle JMS Provider adds the following transformers, found in org.mule.vendor.oracle.jms.transformers. Transformer Description StringToXMLMessage Expects a string containing properly-formed XML. Creates a JMS message whose payload is Oracle's native XML data type. XMLMessageToDOM Expects a JMS message whose payload is Oracle's native XML data type. Returns the XML as a W3C Document (DOM). XMLMessageToStream Expects a JMS message whose payload is Oracle's native XML data type. Returns the XML as an InputStream. XMLMessageToString Expects a JMS message whose payload is Oracle's native XML data type. Returns the XML as a String. The default transformers are the same as the standard JMS Provider (JMSMessageToObject and ObjectToJMSMessage). Example Configuration The following is an example configuration using the Oracle JMS Provider: <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. oaq://my.queue or oaq://topic:my.topic   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. oaq://XML_QUEUE?url=jdbc:oracle:oci:scott/tiger@myhost   Refer to the unit tests for more examples on how to use the provider. Dependencies The Oracle JMS Provider requires the following Oracle libraries, which should be included in your Oracle installation: ojdbc14.jar aqapi13.jar jmscommon.jar xdb.jar (only required for native XML support) xmlparserv2.jar (only required for native XML support) These jars are included in the distribution. 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. The tests assume that your Oracle user has sufficient privileges to create and drop queues in the database.     Roadmap (TO DO) Internationalization of messages Test with Oracle 10g (has only been tested with Oracle 9i) Test with other ADT types (has only been tested with XMLType) Test with topics (has only been tested with queues) Test with Oracle JDBC Thin Driver (has only been tested with the OCI driver) Add XA support SonicMQ Configuration tested with versions 6.1 and 7.0. <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> Thanks to Knut Lerpold for contributing this configuration. 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: com.stc.jmsis.jar fscontext.jar providerutil.jar jms.jar jta.jar log4j.jar log4j.properties Thanks to Brian Kalbfus for contributing this configuration. IBM WebSphere MQ To configure a WebSphere MQ Jms connector for Mule you will need to do the following - Set up a Connection Factory in the WAS admin console Confiure a Jms Connector in Mule to use the Connection Factory. Set up the Connection Factory Under WAS Admin Console > Resources > WebSphere MQ JMS Provider > WebSphere MQ Queue Connection Factories Set the following properties - Name: Connection Factory JNDI Name: jms/ConnectionFactory Queue Manager: (Your QMGR Here) Host, Port, etc. Mule Configuration Add the following connector 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 You will also need the following IBM Websphere jars on your classpath: com.ibm.mq.jar com.ibm.mqjms.jar connector.jar If you are using WAS, refer to this discussion for some known limitations. 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 The following demonstrates how to configure Mule to use the Tibco Enterprise Message Server (EMS) with authentication in place. <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> Durable Subscribers When using durable subscribers Mule automatically sets the Jms clientId on the connection, if not explicitly set. Joram complains if the clientId is set, so you need to tell Mule not to set it by setting the clientId on the JmsConnector to "". 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; } }

Document generated by Confluence on Nov 27, 2006 10:27