Integrating WSO2 AS

This section describes how to integrate WSO2 Message Broker with WSO2 App Server to facilitate subscribing web services to JMS queues or topics and receiving messages from the broker.

The first step is to set up WSO2 MB and WSO2 AS.

Setting up WSO2 Message Broker

1. Download and install WSO2 MB according to the instructions in the 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 by changing the offset value to 1. For example,

<Ports>
   <!-- Ports offset. This entry will set the value of the ports defined below to
 the define value + Offset.
 e.g. Offset=2 and HTTPS port=9443 will set the effective HTTPS port to 9445
 -->
   <Offset>1</Offset>

2. 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 App Server.

Setting up WSO2 AS

1. Download and install WSO2 AS binary distribution. Instructions can be found in the 'Installation Guide' of the respective AS documentation version. For example, Installation Guide. The unzipped AS distribution folder is referred to as AS_HOME.

2. WSO2 AS doesn't come with a default enabled JMS transport configuration to communicate with the Message Broker. Therefore we need to add a <transport receiver> block for MB 2.x.x by editing $AS_HOME/repository/conf/axis2/axis2.xml file 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>

3. Also, uncomment <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"/-->

4. Then add the following 'jndi.properties' into $AS_HOME/repository/conf/ directory in order 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]
queue.SimpleEventSinkService = SimpleEventSinkService

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

In this file add the names of the queues or topics that needs to be created in the Message Broker, for the corresponding service in the App Server. For example, if the deployed service which needs to subscribe to a queue in MB is named SimpleEventSinkService, add a queue named 'SimpleEventSinkService' into the jndi.properties file as shown above. When there are messages published to 'SimpleEventSinkService' queue in MB, the SimpleEventSinkService in App Server will receive them and process accordingly.

5. Copy the following jar files from <MB_HOME>/client-lib folder to <AS_HOME>/repository/components/lib folder. They are client libraries required from Message Broker to AS.

• andes-client-0.13.wso2v8

• geronimo-jms_1.1_spec-1.1.0.wso2v1

Important

In addition to that for the App Server version 5.1.0, it is needed to replace $<AS_HOME>/repository/components/plugins/axis2-transport-jms_1.1.0.wso2v7.jar file with the one attached here. The reason for this is some recent JMS transport level changes which affects into the integration of AS with MB. However this issue will be fixed from the App Server version 5.1.1 onwards and this replacement would be not necessary.

6. Once the JMS transport enabled for App Server it will reflect in all the services deployed in App Server and this can cause unexpected error while server start up. Message Broker handles this for axis2 services by using dynamic queue/topic support however the REST, JS services deployed in App Server still needs to be explicitly configured. Therefore edit and add the following parameters into $<AS_HOME>/repository/deployment/server/servicemetafiles/admin/RESTSample.xml file. Make sure exposedAllTransports parameter is set to 'false'.

<service name="admin/RESTSample" serviceDocumentation="&lt;div&gt;The RESTSample service demonstrate the use of httpmethod and httpLocation annotations to develop RESTy mashups.&lt;/div&gt;" exposedAllTransports="false" serviceDeployedTime="1371635743646" successfullyAdded="true">
 	<transports> 
        <transport>https</transport> 
        <transport>http</transport> 
   </transports>

Now save all the files and start the App Server by running <AS_HOME>/bin/wso2server.sh (on Linux) or <AS_HOME>/bin/wso2server.bat (on Windows).

Integration of sample web service deployed in App Server a a subscriber to Message Broker

This section describes, through a usecase, how to integrate WSO2 Message Broker for using a WSO2 AS web service as JMS subscriber.

Usecase

Deploy a sample web service in App Server which listens on SOAP messages and print message string into console. Then 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 and printed into the App Server console by the sample web service.

1. Log into App Server and upload SimpleEventSinkService.aar archive which can be downloaded from here, by selecting 'Home --> Manager --> Services --> Add --> AAR Service'.
2. Log into Message Broker and publish a text message into the created SimpleEventSinkService queue using the message sender UI.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.samples">
   <soapenv:Header/>
   <soapenv:Body>
      <ser:receive>
         <!--Optional:-->
         <ser:message>Test Message</ser:message>
      </ser:receive>
   </soapenv:Body>
</soapenv:Envelope>

3. Go to the App Server terminal back and the published message will be displayed in the console as, 'Got the message ==> Test Message'.