Integrating WSO2 ESB

This section describes how to integrate WSO2 Message Broker with WSO2 Enterprise Service Bus to facilitate message brokering needs of the ESB and to implement store and forward messaging pattern.

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

Setting up WSO2 Message Broker

This step is not required if you have installed WSO2 MB as a feature as WSO2 ESB. See Working with Features for instructions to install a feature. The name of the feature to be installed is Stratos Message Broker - Dashboard UI Features.

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 the <MB_HOME>/repository/conf/carbon.xml file by 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).

Setting up WSO2 ESB

Download and install WSO2 ESB according to the instructions in Getting Started. The unzipped ESB distribution folder is referred to as ESB_HOME.

Enable the JMS transport of WSO2 ESB to communicate with the Message Broker by editing the <ESB_HOME>/repository/conf/axis2/axis2.xml file. Find a commented <transport receiver> block for MB and uncomment it as shown below.

<!--Uncomment this and configure as appropriate for JMS transport support with WSO2 MB 2.x.x -->
<transportReceiver name="jms" class="org.apache.axis2.transport.jms.JMSListener">
…..
  </parameter>
      </transportReceiver>

Also, uncomment the <transport sender> block for JMS in the same file as shown below.

<transportSender name="jms" class="org.apache.axis2.transport.jms.JMSSender"/>

Copy the following jar files from the <MB_HOME>/clent-lib folder to the <ESB_HOME>/repository/components/lib folder.
- andes-client-3.1.1.jar
- geronimo-jms_1.1_spec-1.1.0.wso2v1.jar
- org.wso2.securevault-1.0.0-wso2v2.jar
Open the <ESB_HOME>/repository/conf/JNDI.proerties file and make a reference to the running Message Broker as shown below.
Use carbon as the virtualhost. Define a queue called JMSMS. Comment out the topic since it is not needed for this scenario. However, in order to avoid getting the javax.naming.NameNotFoundException: TopicConnectionFactory exception during server startup, make a reference to the Message Broker from the TopicConnectionFactory as well.
```
# 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.JMSMS=JMSMS
queue.StockQuotesQueue = StockQuotesQueue
```
The connection factory specifies the URL to be used by a client using WSO2 MB in order to connect to it. 5673 in this example is the port listening for messages on TCP when the AMQP transport is used. This port changes depending on the port offsets done in different scenarios. See Configuring a Client to Access Broker When Port Offset is Change for more information.
If you want to create a queue that is specific to a particular tenant (e.g., a tenant with test.com domain), the following is required.
- The connection factory entries should have the tenant's credentials instead of the super tenant's credentials.
- The queue name should have the tenant's domain as a prefix as shown below.
  test.com/StockQuotesQueue
See Managing Tenant-specific Subscriptions for detailed information.
Start WSO2 ESB by running <ESB_HOME>/bin/wso2server.sh (on Linux) or <ESB_HOME>/bin/wso2server.bat (on Windows).
Now you will have both the Enterprise Service Bus and the Message Broker running.
We need some background services to be available for testing purposes. Therefore, run an ANT task to deploy the SimpleStockQuoteService in the simple axis2server as follows.

- Navigate to <ESB_HOME>/samples/axis2Server/src/SimpleStockQuoteService and run the ant command to build the sample and deploy background services.
- Next, run <ESB_HOME>/samples/axis2server/axis2Server.sh (on Linux) to start the Axis2 server.
- Enter http://127.0.0.1:9000/services/SimpleStockQuoteService?wsdl in the address bar of your browser and press the Enter key to verify that the service is running.

You now have two instances of WSO2 Message Broker and WSO2 ESB configured, up and running. Next, proceed to integrate the Message Broker with ESB, for which there are two implementation options as follows.

Using JMS Endpoints and JMS Proxy Services
Using Message Stores and Processors

Integration Using JMS Endpoints and JMS Proxy Services

This section describes how to integrate WSO2 Message Broker with WSO2 ESB as JMS endpoints. A user case is used for this purpose.

Usecase

Store a message received to a http proxy of the ESB in a JMS queue. Then consume that queue, get the message and send it to the actual endpoint.

Execution Steps

Create a JMS proxy named StockQuotesQueue. It is the same name defined in the jndi.properties file above. By creating this proxy, you will be creating a consumer to make a subscription to be used in this user case. The Synapse configuration of the proxy looks as follows. See Adding a Proxy Service for detailed instructions to create a proxy service.
```
<proxy xmlns="http://ws.apache.org/ns/synapse" name="StockQuotesQueue" transports="jms" statistics="disable" trace="disable" startOnLoad="true">
  <target>
     <inSequence>
        <log level="full"/>
        <property name="OUT_ONLY" value="true"/>
        <send>
           <endpoint>
              <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
           </endpoint>
        </send>
     </inSequence>
  </target>
  <description></description>
</proxy>
```
Once this proxy service is configured, the StockQuotesQueue JMS queue will be created in the MB management console (see Browsing Queues for more information).

Create the HTTP proxy to send messages to the JMS Queue. Synapse configuration of this HTTP proxy is as follows. Since this is a one-way message, the OUT_ONLY property is set to true, and the FORCE_SC_ACCEPTED property is defined to send a 202 response to the client that invokes this proxy.

<proxy xmlns="http://ws.apache.org/ns/synapse" name="StockQuoteProxy" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
  <target>
     <inSequence>
        <property name="OUT_ONLY" value="true"/>
        <property name="FORCE_SC_ACCEPTED" value="true" scope="axis2"/>
        <send>
           <endpoint>
              <address uri="jms:/StockQuotesQueue?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&amp;java.naming.factory.initial=org.wso2.andes.jndi.PropertiesFileInitialContextFactory&amp;java.naming.provider.url=repository/conf/jndi.properties&amp;transport.jms.DestinationType=queue"/>
           </endpoint>
        </send>
     </inSequence>
  </target>
  <description></description>
</proxy>

The message flow paths are completed. When the StockQuoteProxy proxy service is invoked, it will send the message to the queue. This message will be consumed by the StockQuotesQueue JMS proxy and sent to the actual endpoint.

Testing the Integration

Send the following SOAP message to StockQuoteProxy proxy service using the SOAP UI.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://services.samples" xmlns:xsd="http://services.samples/xsd">
  <soap:Header/>
  <soap:Body>
     <ser:placeOrder>
        <!--Optional:-->
        <ser:order>
           <!--Optional:-->
           <xsd:price>10</xsd:price>
           <!--Optional:-->
           <xsd:quantity>100</xsd:quantity>
           <!--Optional:-->
           <xsd:symbol>IBM</xsd:symbol>
        </ser:order>
     </ser:placeOrder>
  </soap:Body>
</soap:Envelope>

The above message will be logged in the ESB console as output.

The log of the SimpleAxis2Server will be as follows.

Tue Jan 15 15:31:28 IST 2013 samples.services.SimpleStockQuoteService  :: Accepted order #2 for : 100 stocks of IBM at $ 10.0

Integrate Using Message Stores and Processors

This section describes how to integrate WSO2 Message Broker with WSO2 ESB using message stores and processors.

Execution Steps

Perform the following steps in WSO2 ESB.

Create a message store with the following configuration. See Adding a Message Store for further information.

<messageStore name="JMSMS" class="org.wso2.carbon.message.store.persistence.jms.JMSMessageStore" xmlns="http://ws.apache.org/ns/synapse">   
   <parameter name="java.naming.factory.initial">org.wso2.andes.jndi.PropertiesFileInitialContextFactory</parameter>   
   <parameter name="java.naming.provider.url">repository/conf/jndi.properties</parameter>
   <parameter name="store.jms.destination">JMSMS</parameter>
   <parameter name="store.jms.JMSSpecVersion">1.1</parameter>   
   <parameter name="store.jms.cache.connection">false</parameter>
</messageStore>

Define an endpoint to send the message. In this example, the backend just set-up in the previous step is used.

<endpoint name="SimpleStockQuoteService">
   <address uri="http://127.0.0.1:9000/services/SimpleStockQuoteService"/>
</endpoint>

Define a message forwarding processor with the following configuration. See Adding a Message Processor for further information.

<messageProcessor class="org.apache.synapse.message.processors.forward.ScheduledMessageForwardingProcessor" name="Processor1" messageStore="JMSMS">
    <parameter name="max.delivery.attempts">4</parameter>
    <parameter name="interval">4000</parameter>
</messageProcessor>

Define a proxy service with the following configuration.

<proxy name="InOnlyProxy" transports="https http" startOnLoad="true" trace="disable">   
   <target>
      <inSequence>
         <property name="FORCE_SC_ACCEPTED" value="true" scope="axis2"/>
         <property name="OUT_ONLY" value="true"/>
         <property name="target.endpoint" value="SimpleStockQuoteService"/>
         <log level="full"/>
         <store messageStore="JMSMS"/>
      </inSequence>
   </target>
</proxy>

Messages sent to this proxy service are stored in the JMSMS queue in the Message Broker which serves as a message store.I If messages are sent while the message processor is disabled, you will notice an increase in the message count of the JMSMS queue in the MB Management Console. See Browsing Queues for more information.

Note

The following section describes the In Only service invocation with the Message Forwarding Processor. Follow this article to implement the others.

Testing the Integration

Using the SOAP UI, send the following SOAP message to the InOnlyProxy proxy service you created.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.samples" xmlns:xsd="http://services.samples/xsd">
   <soapenv:Header/>
      <soapenv:Body>
         <ser:getQuote>
            <!--Optional:-->
            <ser:request>
               <!--Optional:-->
               <xsd:symbol>IBM</xsd:symbol>
            </ser:request>
         </ser:getQuote>
      </soapenv:Body>
</soapenv:Envelope>

The above message will be logged in ESB console. SOAP UI will get the 202 Accepted message.

The following message will be logged in the axis2server console.

samples.services.SimpleStockQuoteService :: Generating quote for : IBM

To adapt to your specific environment, simply replace the following with a suitable name.

<endpoint name="SimpleStockQuoteService">
   <address uri="http://test"/>
</endpoint>