Added docs for using IBM MQ. #476

The examples cannot be done in snippets since the ibm mq client jar is not publicly available trough maven / ivy repo.
akka · Sep 19, 2017 · b4c6e58 · b4c6e58
1 parent 98ba107
commit b4c6e58
Showing 1 changed file with 95 additions and 0 deletions.
diff --git a/docs/src/main/paradox/jms.md b/docs/src/main/paradox/jms.md
@@ -178,3 +178,98 @@ Java
     sbt
     > jms/testOnly *.JmsConnectorsTest
     ```
+
+### Using IBM MQ
+
+You can use IBM MQ like any other JMS Provider by creating a `QueueConnectionFactory` or a `TopicConnectionFactory`
+and creating a `JmsSourceSettings` or `JmsSinkSettings` from it.
+The below snippets have been tested with a default IBM MQ docker image which contains queues and topics for testing.
+The following command starts MQ 9 using docker:
+
+    docker run --env LICENSE=accept --env MQ_QMGR_NAME=QM1 --publish 1414:1414 --publish 9443:9443 ibmcom/mq:9
+
+MQ settings for this image are shown here: https://github.com/ibm-messaging/mq-docker#mq-developer-defaults
+
+#### Create a JmsSource to an IBM MQ Queue
+
+The `MQQueueConnectionFactory` needs a queue manager name and a channel name, the docker command used in the previous section sets up a `QM1` queue manager and a `DEV.APP.SVRCONN` channel. The IBM MQ client makes it possible to 
+connect to the MQ server over TCP/IP or natively through JNI (when the client and server run on the same machine). In the examples below we have chosen to use TCP/IP, which is done by setting the transport type to `CommonConstants.WMQ_CM_CLIENT`.
+
+Scala
+:   ```
+    import com.ibm.mq.jms.MQQueueConnectionFactory
+    import com.ibm.msg.client.wmq.common.CommonConstants
+    val QueueManagerName = "QM1"
+    val TestChannelName = "DEV.APP.SVRCONN"
+    // Create the IBM MQ QueueConnectionFactory
+    val queueConnectionFactory = new MQQueueConnectionFactory()
+    queueConnectionFactory.setQueueManager(QueueManagerName)
+    queueConnectionFactory.setChannel(TestChannelName)
+    // Connect to IBM MQ over TCP/IP
+    queueConnectionFactory.setTransportType(CommonConstants.WMQ_CM_CLIENT)
+    val TestQueueName = "DEV.QUEUE.1"
+    val jmsSource: Source[String, NotUsed] = JmsSource.textSource(
+      JmsSourceSettings(queueConnectionFactory).withQueue(TestQueueName)
+    )
+    ```
+
+Java
+:   ```
+    import com.ibm.mq.jms.MQQueueConnectionFactory;
+    import com.ibm.msg.client.wmq.common.CommonConstants;
+    String queueManagerName = "QM1";
+    String testChannelName = "DEV.APP.SVRCONN";
+    // Create the IBM MQ QueueConnectionFactory
+    MQQueueConnectionFactory queueConnectionFactory = new MQQueueConnectionFactory();
+    queueConnectionFactory.setQueueManager(queueManagerName);
+    queueConnectionFactory.setChannel(testChannelName);
+    // Connect to IBM MQ over TCP/IP
+    queueConnectionFactory.setTransportType(CommonConstants.WMQ_CM_CLIENT);
+    String testQueueName = "DEV.QUEUE.1";
+    Source<String, NotUsed> jmsSource = JmsSource.textSource(
+      JmsSourceSettings
+        .create(queueConnectionFactory)
+        .withQueue(testQueueName)
+    );
+    ```
+
+#### Create a JmsSink to an IBM MQ Topic
+The IBM MQ docker container sets up a `dev/` topic, which is used in the example below.
+
+Scala
+:   ```
+    import com.ibm.mq.jms.MQTopicConnectionFactory
+    import com.ibm.msg.client.wmq.common.CommonConstants
+    val QueueManagerName = "QM1"
+    val TestChannelName = "DEV.APP.SVRCONN"
+    // Create the IBM MQ TopicConnectionFactory
+    val topicConnectionFactory = new MQTopicConnectionFactory()
+    topicConnectionFactory.setQueueManager(QueueManagerName)
+    topicConnectionFactory.setChannel(TestChannelName)
+    // Connect to IBM MQ over TCP/IP
+    topicConnectionFactory.setTransportType(CommonConstants.WMQ_CM_CLIENT)
+    val TestTopicName = "dev/"
+    val jmsTopicSink: Sink[String, NotUsed] = JmsSink(
+      JmsSinkSettings(topicConnectionFactory).withTopic(TestTopicName)
+    )
+    ```
+
+Java
+:   ```
+    import com.ibm.mq.jms.MQTopicConnectionFactory;
+    import com.ibm.msg.client.wmq.common.CommonConstants;
+    String queueManagerName = "QM1";
+    String testChannelName = "DEV.APP.SVRCONN";
+    // Create the IBM MQ TopicConnectionFactory
+    val topicConnectionFactory = new MQTopicConnectionFactory();
+    topicConnectionFactory.setQueueManager(queueManagerName);
+    topicConnectionFactory.setChannel(testChannelName);
+    // Connect to IBM MQ over TCP/IP
+    topicConnectionFactory.setTransportType(CommonConstants.WMQ_CM_CLIENT);
+    String testTopicName = "dev/";
+    Sink<String, NotUsed> jmsTopicSink = JmsSink.textSink(
+      JmsSinkSettings
+        .create(topicConnectionFactory)
+        .withTopic(testTopicName)
+    );
+    ```