com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

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
  1. Download and install WebSphere MQ pack with the latest fixes. For more information on installing, go to the IBM documentation
  2. Start the IBM WebSphere MQ JMS server.

  3. Open the <WebSphere_MQ_HOME>/java/bin/JMSAdmin.config  file in a text editor.

  4. 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 
  5. 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
    ......      
  6. Restart the WebSphere MQ service.
Creating the Queue in WebSphere MQ
  1. 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.
    create query manager
  2. Select the options to  Start Queue Manager Autostart Queue Manager , and  Create server connection channel , and then click  Next .
  3. Select the option to create a listener configuration for TCP/IP, and provide a port number ( e.g., 1415 ).
  4. 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. 
    new local queue
  5. Keep the default configurations, and click Finish.
  6. Click Topics in the tree view, and create a new local topic (e.g., localt). 
  7. Right-click Channels under Advanced, and click New Server-connection Channel. Provide a name for the channel (e.g., myChannel), and click Next.
    new server connection channel
  8.   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 
  1. 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
  2. Create the default set of JNDI bindings by running the following command on the command prompt:  

    IVTSetup.bat
  3. 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. 

  4. Navigate to  C:/JNDI-Directory to  view the .bindings file there.
  5. Start the JMSAdmin tool by running the jmsadmin.bat  file.   
  6. 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)
  7. In  IBM WebSphere MQ Explorer,  select JMS Administered Objects from the tree view on the left, and then select Add initial context
  8. 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.

  1.  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.
  2. 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   
  3. 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
  4. 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 
  5. Add the following files to the  <   CEP_HOME>/repository/components/lib  directory.

    • jms.jar
    • jta.jar 
  6. 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. 

  7. Repeat these steps for the topic scenarios. For example:

    DEFINE T(bogust)
    ALTER T(bogust) TOPIC(localt)

    localt is the topic you created earlier.

  8. 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 d efine 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.DurableSubscriberClientID">subscriber</property>
        <property name="jms.properties">SessionTransacted:false</property>
    </from>
    ...................
</eventReceiver>

The above adapter properties are described below.

Adapter Property
Description
Configuration file propertyExample

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 Client ID

A string of characters to denote a valid id for client connecting as the durable subscriber. (It will enable durable subscription if you add any value here).

transport.jms.DurableSubscriberClientID
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
com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.