Integrating WSO2 DSS

This page describes how to integrate WSO2 Message Broker with WSO2 Data Services Server to facilitate subscribing data services to JMS queues or topics and receiving messages from the broker. It contains the following sections:

Setting up WSO2 Message Broker

Download and install WSO2 MB according to the instructions in Getting Started.
It is not possible to start multiple WSO2 products with their default configurations simultaneously in the same environment. Since all WSO2 products use the same port in their default configuration, there will be port conflicts. Therefore, to avoid port conflicts, apply a port offset in <MB_HOME>/repository/conf/carbon.xml file changing the offset value to 1. For example:
```
<Ports>
   
   <Offset>1</Offset>
```
Start the Message Broker by running <MB_HOME>/bin/wso2server.sh (on Linux) or <MB_HOME>/bin/wso2server.bat (on Windows). Note that Message Broker must be up and running before starting the Data Services Server.

Setting up WSO2 DSS

Download and install the WSO2 DSS binary distribution (see the installation instructions in the DSS documentation).
The unzipped DSS distribution folder is referred to as <DSS_HOME>.

WSO2 DSS does not have a default enabled JMS transport configuration for communicating with the Message Broker. Therefore, we need to add a <transport receiver> block for MB 2.x.x by editing <DSS_HOME>/repository/conf/axis2/axis2.xml as follows:

<!--Configure for JMS transport support with WSO2 MB 2.x.x -->
    <transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener">
        <parameter name="myTopicConnectionFactory" locked="false">
           <parameter name="java.naming.factory.initial" locked="false">org.wso2.andes.jndi.PropertiesFileInitialContextFactory</parameter>
            <parameter name="java.naming.provider.url" locked="false">repository/conf/jndi.properties</parameter>
            <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">TopicConnectionFactory</parameter>
            <parameter name="transport.jms.ConnectionFactoryType" locked="false">topic</parameter>
        </parameter>
        <parameter name="myQueueConnectionFactory" locked="false">
            <parameter name="java.naming.factory.initial" locked="false">org.wso2.andes.jndi.PropertiesFileInitialContextFactory</parameter>
            <parameter name="java.naming.provider.url" locked="false">repository/conf/jndi.properties</parameter>
            <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>
           <parameter name="transport.jms.ConnectionFactoryType" locked="false">queue</parameter>
        </parameter>
        <parameter name="default" locked="false">
            <parameter name="java.naming.factory.initial" locked="false">org.wso2.andes.jndi.PropertiesFileInitialContextFactory</parameter>
            <parameter name="java.naming.provider.url" locked="false">repository/conf/jndi.properties</parameter>
            <parameter name="transport.jms.ConnectionFactoryJNDIName" locked="false">QueueConnectionFactory</parameter>
            <parameter name="transport.jms.ConnectionFactoryType" locked="false">queue</parameter>
        </parameter>
    </transportReceiver>

Also, uncomment the <transport sender> block for JMS in the same file as follows:

<!-- uncomment this and configure to use connection pools for sending messages>
<transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/-->

Create and add the following jndi.properties file into the <DSS_HOME>/repository/conf/directory to point to the running Message Broker:

#  Copyright (c) 2011, WSO2 Inc. (http://wso2.com) All Rights Reserved.
#
#  Licensed under the Apache License, Version 2.0 (the "License");
#  you may not use this file except in compliance with the License.
#  You may obtain a copy of the License at
#
#        http://www.apache.org/licenses/LICENSE-2.0
#
#  Unless required by applicable law or agreed to in writing, software
#  distributed under the License is distributed on an "AS IS" BASIS,
#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#  See the License for the specific language governing permissions and
#  limitations under the License.
#
 
# register some connection factories
# connectionfactory.[jndiname] = [ConnectionURL]
connectionfactory.QueueConnectionFactory = amqp://admin:admin@clientID/carbon?brokerlist='tcp://localhost:5673'
connectionfactory.TopicConnectionFactory = amqp://admin:admin@clientID/carbon?brokerlist='tcp://localhost:5673'
# register some queues in JNDI using the form
# queue.[jndiName] = [physicalName]

 
# register some topics in JNDI using the form
# topic.[jndiName] = [physicalName]

Copy the following client library JAR files from the <MB_HOME>/client-lib folder to <DSS_HOME>/repository/components/lib.

- andes-client-0.13.wso2v8
- geronimo-jms_1.1_spec-1.1.0.wso2v1

Important: If you are integrating with DSS version 3.0.1, replace <DSS_HOME>/repository/components/plugins/axis2-transport-jms_1.1.0.wso2v7.jar with the one attached here. This JAR file contains JMS transport changes that affect the integration of DSS 3.0.1 with MB. Future versions of Data Services Server will have this fix built in, so replacing this JAR will be not necessary.
Once the JMS transport is enabled for DSS, it will reflect in all the services deployed in Data Services Server, which can cause an unexpected error during server start up. To prevent this error, edit and add the following parameters into the <service> entry of <DSS_HOME>/repository/deployment/server/dataservices/samples/RDBMSSample_services.xml.
```
<parameter name="transport.jms.ContentType">
       <rules>
           <jmsProperty>contentType</jmsProperty>
           <default>application/xml</default>
       </rules>
</parameter>
```
Copy the two files RDBMSSample_services.xml and RDBMSSample.dbs in this 'samples/' directory into the <DSS_HOME>/repository/deployment/server/dataservices/ directory.
Save all the files and start the DSS by running <DSS_HOME>/bin/wso2server.sh (on Linux) or <DSS_HOME>/bin/wso2server.bat (on Windows).

Testing the integration

Deploy a sample data_service in DSS. A JMS queue for the name of this service will be generated in the Message Broker. Publish a message to this queue and it will be received by the corresponding data_service in DSS. There can be any message processing operations performed using these messages, inside the data_service now.