URI structure - 6.3

Talend ESB Service Developer Guide

EnrichVersion
6.3
EnrichProdName
Talend Data Fabric
Talend Data Services Platform
Talend ESB
Talend MDM Platform
Talend Open Studio for ESB
Talend Real-Time Big Data Platform
task
Design and Development
Installation and Upgrade
EnrichPlatform
Talend ESB

Basically, the URI structure of a SOAP over JMS address looks like the following structure:

jms:<variant>:<destination_name>?jndiInitialContextFactory=<context_factory_class_name>&jndiConnectionFactoryName=
<connection_factory_name>&jndiURL=<JMS_broker_URL>

Where:

  • variant can have the following values:

    VariantDescription
    jndiDestination name is a jndi queue name
    jndi-topicDestination name is a jndi topic name
    queueDestination is a queue name resolved using JMS
    topicDestination is a topic name resolved using JMS
  • destination_name is basically the queue or topic name.

  • context_factory_class_name is the class name of a JNDI context factory which will be used to resolve a factory which creates connections to the broker.

  • connection_factory_name is a platform-specific connection factory name (differs for Active MQ and Websphere MQ)

  • JMS_broker_URL is a URL which will be used by the context resolve or create connection factory and destination objects.

But CXF provides the possibility to specify further JMS parameters:

Query ParameterDefault ValueDescription
conduitIdSelectorPrefix If set then this string will be the prefix for all correlation ids the conduit creates and also be used in the selector for listening to replies
deliveryModePERSISTENT

NON_PERSISTENT messages will kept only in memory

PERSISTENT messages will be saved to disk

durableSubscriptionClientId Optional Client identifier for the connection. The purpose is to associate a connection with a state maintained on behalf of the client by a provider. The only such state identified by the JMS API is that required to support durable subscriptions.
durableSubscriptionName Specifies the name used to register a durable subscription.
jndiConnectionFactoryNameConnectionFactorySpecifies the JNDI name bound to the JMS connection factory to use when connecting to the JMS destination.
jndiInitialContextFactory Specifies the fully qualified Java class name of the "InitialContextFactory" implementation class to use.
jndiURL Specifies the JNDI provider URL
jndi-* Additional parameters for a JNDI provider
messageTypebyteJMS message type used by CXF (byte, text or binary)
password Password for creating the connection. Using this in the URI is discouraged
priority4Priority for the messages. See your JMS provider documentation for details. Values range from 0 to 9 where 0 is lowest priority
replyToName Specifies the JNDI name bound to the JMS destinations where replies are sent
receiveTimeout60000Timeout in milliseconds the client waits for a reply in case of request / repy exchanges
reconnectOnExceptiontrueShould the transport reconnect in case of exceptions. From version 3.0.0 on the transport will always reconnect in case of exceptions
targetService Used by the service implementation to dispatch the service request.
timeToLive0Time (in ms) after which the message will be discarded by the jms provider
topicReplyToName Reply to messages on a topic with this name. Depending on the variant this is either a jndi or jms name.
useConduitIdSelectortrue

Each conduit is assigned with a UUID. If set to true this conduit id will be the prefix for all correlation ids. This allows several endpoints to share a JMS queue or topic

username Username for creating the connection

Some of these attributes are specified in the JMS URI specification.

Further parameters are supported by the underlying CXF 3.x, namely jndiTransactionManager, which allows the configuration of JTA transactions around JMS message processing. However, this is an advanced feature for which it is recommended to read the CXF documentation and the documentation of the MOM in use.

Depending of the MOM used, the connection URI can look differently. For more information on how the address URI for connection to Active MQ looks like, see Connecting to ActiveMQ, and for more information on how the address URI for connection to Websphere MQ looks like, see Connecting to Websphere MQ.

Connecting to ActiveMQ

For connection to ActiveMQ:

  • JMS_broker_URL for ActiveMQ has the following structure:

    tcp://<host>:<port>
  • connection_factory_class_name should be org.apache.activemq.jndi.ActiveMQInitialContextFactory.

  • connection_factory_name is usually ConnectionFactory.

  • variant should take the jndi or jndi-topic value to connect to a queue or a topic respectively. However, queue or topic work also for ActiveMQ.

In case of connection to a dynamic queue/topic, the destination name needs to be prefixed with dynamicQueues/ or dynamicTopics/ respectively.

Below is an example of connection to a ActiveMQ dynamic queue called "test.queue" with a broker running on the localhost port 61616:

ActiveMQ connection to queue URI

jms:jndi:dynamicQueues/test.queue?jndiInitialContextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory&jnd
iConnectionFactoryName=ConnectionFactory&jndiURL=tcp://localhost:61616

Below is an example of connection to the dynamic topic "test.topic" with the broker running on localhost port 61616:

ActiveMQ connection to a topic URI

jms:jndi-topic:dynamicTopics/test.topic?jndiInitialContextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory&jnd
iConnectionFactoryName=ConnectionFactory&jndiURL=tcp://localhost:61616

Connecting to Websphere MQ

For connection to Websphere MQ:

  • JMS_broker_URL is either not set at all, or needs to have the same value as the clientConnection parameter:

    <hostname>:<port>
  • context_factory_class_name should be org.talend.esb.jms.wmq.Nojndi.

    This is a wrapper around the pseudo InitialContextFactory Nojndi from IBM which is included in the Websphere MQ JMS support libraries. The Talend ESB Nojndi wrapper is included in the Talend ESB Runtime Enterprise Edition in the file tesb-jms-transport-enterprise.jar. It adds topic destination support to the wrapped IBM Nojndi and a workaround which avoids some spurious error messages the IBM Nojndi tends to write to stderr.

  • connection_factory_name is a Websphere MQ-specific connection parameter string which is equal to the Websphere MQ connection access strings used by non-JMS clients.

    The Websphere MQ connection parameter string looks like the following:

    connectQueueManager(<queue_manager>)binding(client)clientChannel(<channel_name>)cl
    ientConnection(<mq_host_name>:<mq_port>)

    Where:

    • For connectQueueManager, (<queue_manager>) is the name of the Websphere MQ queue manager which manages the requested destination, for example: QMGR, QM01 or something similar.

    • For binding, (client) should be set to the literal value client for JMS.

    • For clientChannel, (<channel_name>) is the name or the Websphere MQ channel through which the requested destination is to be accessed, for example: EXAMPLE.CHANNEL.SVRCONN

    • For clientConnection, (<mq_host_name>:<mq_port>) corresponds to the network address (<mq_host_name>) with port (<mq_port>) of the Websphere MQ server to connect to, for example: examplehost:1414 or 10.1.2.3:1414.

  • variant should take the queue or topic value to connect to a queue or a topic respectively.

  • jndiURL needs to be set to a non-empty value. The recommendation is wmq://queue for queue connections and wmq://topic for topic connections.

Below is an example of connection to a Webpshere MQ queue called test.queue with broker running on localhost port 1414. The channel EXAMPLE.CHANNEL.SVRCONN and the queue manager QMGR will be used to connect to the queue.

Websphere MQ connection to queue URI

jms:queue:test.queue?jndiInitialContextFactory=org.talend.esb.jms.wmq.Nojndi&jndiConnectionFactoryName=co
nnectQueueManager(QMGR)binding(client)clientChannel(EXAMPE.CHANNEL.SVRCONN)clientCon
nection(localhost:1414)&jndiURL=wmq://queue

When connecting to a topic, an additional JMS URI parameter is required: jndi-destination-type=topic. Starting with the version 6.1.1 of Talend ESB, this parameter is optional if jndiURL=wmq://topic.

Below is an example showing connection to the topic test.topic to the same broker using the same channel and queue manager QMGR:

Websphere MQ topic connection URI

jms:topic:test.topic?jndiInitialContextFactory=org.talend.esb.jms.wmq.Nojndi&jndiConnectionFactoryName=co
nnectQueueManager(QMGR)binding(client)clientChannel(EXAMPE.CHANNEL.SVRCONN)clientCon
nection(localhost:1414)&jndiURL=wmq://topic&jndi-destination-type=topic

Wrapping IBM MQ client library JARs into an OSGI bundle

This section describes how to wrap IBM WMQ client library jars into an OSGi bundle that can be used to create client connections to WMQ in an OSGi environment.

Prerequisites:

The following WMQ JARs (version 7.5) should be installed into the local maven repository:

  • CL3Export.jar

  • CL3Nonexport.jar

  • com.ibm.mq.commonservices.jar

  • com.ibm.mq.headers.jar

  • com.ibm.mq.jmqi.jar

  • com.ibm.mq.jms.Nojndi.jar

  • com.ibm.mq.pcf.jar

  • com.ibm.mqjms.jar

  • dhbcore.jar rmm.jar

To install JAR files into local repository, run the following commands from the directory that contains the JARs:

mvn install:install-file -Dfile=dhbcore.jar -DgroupId=com.ibm -DartifactId=com.ibm.disthub2.dhbcore -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=com.ibm.mq.jms.Nojndi.jar -DgroupId=com.ibm -DartifactId=com.ibm.mq.jms.Nojndi -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=com.ibm.mq.jmqi.jar -DgroupId=com.ibm -DartifactId=com.ibm.mq.jmqi -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=com.ibm.mqjms.jar -DgroupId=com.ibm -DartifactId=com.ibm.mqjms -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=CL3Export.jar -DgroupId=com.ibm -DartifactId=cl3export -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=CL3Nonexport.jar -DgroupId=com.ibm -DartifactId=cl3nonexport -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=com.ibm.mq.commonservices.jar -DgroupId=com.ibm -DartifactId=com.ibm.mq.commonservices -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=rmm.jar -DgroupId=com.ibm -DartifactId=rmm -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=com.ibm.mq.headers.jar -DgroupId=com.ibm -DartifactId=com.ibm.mq.headers -Dversion=7.5 -Dpackaging=jar
mvn install:install-file -Dfile=com.ibm.mq.pcf.jar -DgroupId=com.ibm -DartifactId=com.ibm.mq.pcf -Dversion=7.5 -Dpackaging=jar
  1. Add the file pom.xml containing the following content into an empty directory:

    <project xmlns="http://maven.apache.org/POM/4.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
     http://maven.apache.org/xsd/maven-4.0.0.xsd">
    
     <modelVersion>4.0.0</modelVersion>
    
     <groupId>osgi.com.ibm</groupId>
     <artifactId>wsmq</artifactId>
     <version>7.5</version>
     <packaging>bundle</packaging>
     <name>Websphere MQ client libraries OSGi Bundle</name>
     <description>This OSGi bundle simply wraps several WMQ artifacts into one.</description>
    
     <properties>
       <wmq.version>${project.version}</wmq.version>
     </properties>
    
     <dependencies>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>com.ibm.mq.jms.Nojndi</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>com.ibm.mq.jmqi</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>com.ibm.mqjms</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>com.ibm.disthub2.dhbcore</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>cl3export</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>cl3nonexport</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>com.ibm.mq.commonservices</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>rmm</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>com.ibm.mq.headers</artifactId>
         <version>${wmq.version}</version>
       </dependency>
       <dependency>
         <groupId>com.ibm</groupId>
         <artifactId>com.ibm.mq.pcf</artifactId>
         <version>${wmq.version}</version>
       </dependency>
     </dependencies>
    
     <build>
       <defaultGoal>install</defaultGoal>
    
       <plugins>
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-shade-plugin</artifactId>
           <version>1.1</version>
           <executions>
             <execution>
               <phase>package</phase>
               <goals>
                 <goal>shade</goal>
               </goals>
               <configuration>
                 <artifactSet>
                   <includes>
                     <include>com.ibm:*</include>
                   </includes>
                 </artifactSet>
                 <promoteTransitiveDependencies>true</promoteTransitiveDependencies>
                 <createDependencyReducedPom>true</createDependencyReducedPom>
               </configuration>
             </execution>
           </executions>
         </plugin>
         <plugin>
           <groupId>org.apache.felix</groupId>
           <artifactId>maven-bundle-plugin</artifactId>
           <version>2.1.0</version>
           <extensions>true</extensions>
             <configuration>
               <instructions>
                 <Bundle-SymbolicName>wmq-osgi-bundle</Bundle-SymbolicName>
                 <Export-Package>*</Export-Package>
                 <Import-Package>
    com.ibm.disthub2.impl.multi.*;resolution:=optional,
    com.ibm.disthub2.impl.multicast.server;resolution:=optional,
    com.ibm.disthub2.impl.server;resolution:=optional,
    com.ibm.disthub2.impl.server.*;resolution:=optional,
    com.ibm.disthub2.impl.util.*;resolution:=optional, com.ibm.ejs.*;resolution:=optional,
    com.ibm.rmm.ptl.tchan.*;resolution:=optional,
    com.ibm.disthub2.broker.reference.security;resolution:=optional,
    com.ibm.misc;resolution:=optional, com.ibm.mq.internal;resolution:=optional,
    com.ibm.crypto.pkcs11impl.provider;resolution:=optional,
    com.ibm.crypto.provider;resolution:=optional, com.ibm.security.*;resolution:=optional,
    sun.net.www;resolution:=optional, sun.security.*;resolution:=optional, *
                 </Import-Package>
                 <_versionpolicy>[$(version;==;$(@)),$(version;+;$(@)))</_versionpolicy>
                 <_removeheaders>Ignore-Package,Include-Resource,Private-Package,Embed-Dependency</_removeheaders>
               </instructions>
               <unpackBundle>true</unpackBundle>
             </configuration>
         </plugin>
       </plugins>
     </build>
    </project>
  2. Go to the directory that contains the pom.xml and create a subdirectory src/main/resources/META-INF.

  3. Place the file compinfo.properties containing the following content to the directory src/main/resources/META-INF:

    CompList: comp1,comp2,comp3,comp4
    
    comp1_CompClass:com.ibm.msg.client.wmq.factories.WMQComponent
    comp2_CompClass:com.ibm.msg.client.commonservices.j2se.J2SEComponent
    comp3_CompClass: com.ibm.msg.client.jms.internal.JMSComponent
    comp4_CompClass: com.ibm.mq.jms.MQJMSComponent
  4. Go to the directory that contains the pom.xml file and use the following command:

    mvn clean install

    During Maven build on Linux, a RuntimeException may occur with the message: " data starting at XX is in unknown format". This Exception is harmless and does not affect the build result.

  5. The bundle file wsmq-7.5.jar will appear in the subdirectory target/. This bundle can be used for deployment into OSGi.

  6. To deploy the bundle, copy the wsmq-7.5.jar file to the directory <TESB-HOME>/container/deploy.