IBM WebSphere MQ JMS Event Receiver

IBM WebSphere MQ JMS event receiver is an internal event receiver that comes with WSO2 products by default. You can configure it with XML, map, JSON, and text input mapping types.

Prerequisites

Follow the instructions below to complete the prerequisites before starting the event receiver configurations.

Configuring WebSphere MQ

Follow the steps below to configure WebSphere MQ.

Configuring JMSAdmin.conf file

Download and install WebSphere MQ pack with the latest fixes. For more information on installing, go to the IBM documentation).
Start the IBM WebSphere MQ JMS server.
Open the <WebSphere_MQ_HOME>/java/bin/JMSAdmin.config file in a text editor.
Comment the existing INITIAL_CONTEXT_FACTORY, and add an INITIAL_CONTEXT_FACTORY named com.sun.jndi.fscontext.RefFSContextFactory as follows.
```
INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory 
```

Comment the default PROVIDER_URL, and use a directory path instead. Ensure the directory is created in the file system (e.g., C:/JNDI-Directory).

If there are .bindings files of earlier versions already existing in this directory, delete them. It should typically be an empty folder.

Your JMSAdmin.config file should now look similar to this:

# appropriate one should be uncommented.
#
#INITIAL_CONTEXT_FACTORY=com.sun.jndi.ldap.LdapCtxFactory
INITIAL_CONTEXT_FACTORY=com.sun.jndi.fscontext.RefFSContextFactory
#INITIAL_CONTEXT_FACTORY=com.ibm.ejs.ns.jndi.CNInitialContextFactory
#INITIAL_CONTEXT_FACTORY=com.ibm.websphere.naming.WsnInitialContextFactory
#INITIAL_CONTEXT_FACTORY=com.ibm.websphere.naming.WMQInitialContextFactory
#
#  The following line specifies the URL of the service provider's initial
#  context. It currently refers to an LDAP root context. Examples of a
#  file system URL and WebSphere's JNDI namespace are also shown, commented
#  out.
#
#PROVIDER_URL=ldap://polaris/o=ibm,c=us
PROVIDER_URL=file:/C:/JNDI-Directory
#PROVIDER_URL=iiop://localhost/
#PROVIDER_URL=localhost:1414/SYSTEM.DEF.SVRCONN
......

Restart the WebSphere MQ service.

Creating the Queue in WebSphere MQ

Start IBM WebSphere MQ Explorer, and create a new queue manager. Make sure you select make this the default queue manager check box and leave the default values on the other fields as shown below.
Select the options to Start Queue Manager, Autostart Queue Manager, and Create server connection channel, and then click Next .
Select the option to create a listener configuration for TCP/IP, and provide a port number (e.g., 1415).
Select the created queue manager and expand its navigation tree. Click Queues in the tree and create a new local queue (e.g., localq) as shown below.
Keep the default configurations, and click Finish.
Click Topics in the tree view, and create a new local topic (e.g., localt).
Right-click Channels under Advanced, and click New Server-connection Channel. Provide a name for the channel (e.g., myChannel), and click Next.
Set the transmission protocol as TCP, and click Finish.
A listener is created and is running on the given port (e.g., 1415). You should be able to view it by clicking the listeners icon.

Generating the .bindings file

Navigate to the <WebSphere_MQ_HOME> /java/bin/ directory, and invoke the IVT app by running the following command:
```
IVTRun.bat -nojndi -client -m mymgr -host localhost -channel mychannel
```
Create the default set of JNDI bindings by running the following command on the command prompt:
```
IVTSetup.bat
```

Execute the IVTRun tool as follows.

IVTRun.bat -url "file:/C:/JNDI-Directory" -icf com.sun.jndi.fscontext.RefFSContextFactory

You have now enabled and verified JNDI support.

Navigate to C:/JNDI-Directory to view the .bindings file there.
Start the JMSAdmin tool by running the jmsadmin.bat file.

Modify the JNDI bindings by executing the following commands:
For queues:

ALTER QCF(ivtQCF) TRANSPORT(CLIENT)
ALTER QCF(ivtQCF) QMGR(mymgr)

For topics:

ALTER TCF(ivtTCF) TRANSPORT(CLIENT)
ALTER TCF(ivtTCF) QMGR(mymgr)

In IBM WebSphere MQ Explorer, select JMS Administered Objects from the tree view on the left, and then select Add initial context.
Select File system, and enter the JNDI directory path. This brings up all created queues and topics.
You have now set up and configured IBM WebSphere MQ in your environment.

Configuring WSO2 CEP

Follow the instructions below to configure WSO2 CEP.

If you set up WSO2 CEP on a different machine from WebSphere MQ, copy C:/JNDI-Directory/ to that machine. The bindings file allows you to access WebSphere queues from any machine in the network.
Copy the following JAR files from the <WebSphere_MQ_HOME>/java/lib/ directory to the <CEP_HOME>/repository/components/lib/ directory .
- com.ibm.mqjms.jar
- fscontext.jar
- providerutil.jar
- com.ibm.mq.jmqi.jar
- dhbcore.jar
If you are using WebSphere MQ version 6.0 instead of version 7.0, add the following two JAR files. You might not find com.ibm.mq.jmqi.jar in version 6.0.
- com.ibm.mq.jar
- connector.jar
Optionally, you might have to add the following JAR files as well.
- jms.jar
- jndi.jar
- jta.jar
- ldap.jar
If you are using WebSphere MQ version 7.1 or later, add the following JAR files to the <CEP_HOME>/repository/components/dropins/ directory.
- com.ibm.mq_2.0.0.jar
- fscontext_1.0.0.jar
Add the following files to the < CEP_HOME>/repository/components/lib directory.
- jms.jar
- jta.jar
Log in to the JMSAdmin tool, and create a queue named bogusq by running the following commands in JMSAdmin shell.
```
DEFINE Q(bogusq) QMGR(mymgr)
ALTER Q(bogusq) QUEUE(localq)
```
localq is the queue you created earlier. You use two queues for the queue scenario. The queue named bogusq is the default destination since you need the default queue (ivtQ) for your proxy service only. If you use ivtQ here, all the services deployed in WSO2 CEP (XKMS, echo, wso2carbon-sts etc.) will start listening on the same queue.
Repeat these steps for the topic scenarios. For example:
```
DEFINE T(bogust)
ALTER T(bogust) TOPIC(localt)
```
localt is the topic you created earlier.

Configure the <CEP_HOME>\repository\conf\axis2\axis2.xml file as follows:

<transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener">
        <parameter name="myTopicConnectionFactory" locked="false"> 
            <parameter name="java.naming.factory.initial"
locked="false">com.sun.jndi.fscontext.RefFSContextFactory</parameter>
            <parameter name="java.naming.provider.url" locked="false">file:/C:/JNDI-Directory</parameter>
            <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">ivtQCF</parameter>
            <parameter name="transport.jms.ConnectionFactoryType" locked="false">topic</parameter>
        </parameter>  
 
        <!--parameter name="SQProxyCF" locked="false">
            <parameter name="java.naming.factory.initial">com.sun.jndi.fscontext.RefFSContextFactory</parameter>
            <parameter name="java.naming.provider.url">file:/C:/JNDI-Directory</parameter>
            <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">ivtQCF</parameter>
            <parameter name="transport.jms.ConnectionFactoryType" locked="false">queue</parameter>
        </parameter-->
 
        <parameter name="default" locked="false">
            <parameter name="java.naming.factory.initial"
locked="false">com.sun.jndi.fscontext.RefFSContextFactory</parameter>
            <parameter name="java.naming.provider.url" locked="false">file:/C:/JNDI-Directory</parameter>
            <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">ivtQCF</parameter>
            <parameter name="transport.jms.ConnectionFactoryType" locked="false">queue</parameter>
        </parameter>
</transportReceiver>

Comment and uncomment the non-default connection factories depending on which scenario you are running, as described in the next section.

For details on the JMS configuration parameters used in the code segments, see JMS Connection Factory Parameters.

Creating an IBM WebSphere MQ JMS event receiver

For instructions on creating an IBM WebSphere JMS event receiver, see Configuring Event Receivers.

Configuring adapter properties

Specify the Adapter Properties, when creating an IBM WebSphere JMS event receiver using the management console as shown below.

IBM WebSphere input event adapter properties

After entering the above adapter properties, select the Event Stream to which you want to map the incoming events, and the Message Format which you want to apply on the receiving events. Also, click Advanced to define custom input mappings based on the Message Format you selected. For more information on custom input mapping types, see Input Mapping Types.

You can also define the respective adapter properties of the event receiver based on the transport type within the <from> element of the event receiver configuration in the <PRODUCT_HOME>/repository/deployment/server/eventreceivers/ directory as follows.

<eventReceiver name="iBMWebSphereJMSInputEventAdapter"
    statistics="disable" trace="disable" xmlns="http://wso2.org/carbon/eventreceiver">
    <from eventAdapterType="jms">
        <property name="java.naming.factory.initial">com.sun.jndi.fscontext.RefFSContextFactory</property>
        <property name="java.naming.provider.url">file:/C:/JNDI-Directory</property>
        <property name="transport.jms.DestinationType">topic</property>
        <property name="transport.jms.SubscriptionDurable">false</property>
        <property name="transport.jms.Destination">test_topic</property>
        <property name="transport.jms.ConnectionFactoryJNDIName">ivtQCF</property>
        <property encrypted="true" name="transport.jms.Password">P2ve4G8+qF7JXkiGnP9/Ew5GXALEWTu7znEwxZGYa/MQMaQBRfsXiP094fn9U+0rntdBMitXU9o7h5uV3m5h97Po8WTJRpnFBV5YCGZEO+ELSg6twY3386MipwFhFMrbUMKamI2sXksDRcogojWKtoHNmODnt8Ud1dh0LK5zqec=        </property>
        <property name="transport.jms.UserName">jms-user</property>
        <property name="transport.jms.DurableSubscriberName">subscriber</property>
        <property name="jms.properties">SessionTransacted:false</property>
    </from>
    ...................
</eventReceiver>

The above adapter properties are described below.

Adapter Property	Description	Configuration file property	Example
Topic/Queue Name	A valid name for the JMS topic/queue. WSO2 CEP/DAS sends and receives messages by subscribing to a topic or using named queues.	transport.jms.Destination	test_topic
JNDI Initial Context Factory Class	JNDI initial context factory class. The class must implement the `java.naming.spi.InitialContextFactory` interface.	java.naming.factory.initial	com.sun.jndi.fscontext.RefFSContextFactory
JNDI Provider URL	URL of the JNDI provider.	java.naming.provider.url	file:/C:/JNDI-Directory
The JMS connection password	A valid password for the JMS connection	transport.jms.Password	jms-password
The JMS connection username	A valid username for the JMS connection	transport.jms.UserName	jms-user
Connection Factory JNDI Name	The JNDI name of the connection factory.	transport.jms.ConnectionFactoryJNDIName	ivtQCF
Destination Type	The sort order for messages that arrive on a specific destination.	transport.jms.DestinationType	topic/queue
Enable Durable Subscription	Whether the subscription is durable or not.	transport.jms.SubscriptionDurable	true/false
Durable Subscriber Name	A valid name of the durable subscriber (If any value added, Durable subscription will be enabled).	transport.jms.DurableSubscriberName	subscriber
JMS Properties	Valid "property:value" pairs of Axis2 JMS properties (e.g. "property1: value1, property2: value2") For more information on Axis2 JMS properties, go to Apache AXIS2 Transports Documentation.	jms.properties	SessionTransacted:false