Message Router

This section explains, through an example scenario, how the Message Router EIP can be implemented using the WSO2 ESB. The following topics are covered:

Introduction to Message Router

The Message Router reads the content of a message and routes it to a specific recipient based on its content. When the implementation of a specific logical function is distributed across multiple physical systems, an incoming request needs to be passed on to the correct service, based on the request's content. A Message Router is useful in handling such scenarios.

The following diagram depicts the Message Router's behavior, where the router performs a logical function (such as an inventory check). It receives a request message (new order), reads it, and routes the request to one of the two recipients according to the message's content. The router is also defined as a special type of filter.

For more information, go to Message Router.

Figure 1: Message Router EIP

Example scenario

The following diagram depicts an example scenario, where the Message Router EIP is implemented using the ESB. In this example, a stock inventory is exposed through two instances of the Stock Quote Service (we will refer to these as the foo inventory service and the bar inventory service). When a stock quote request is sent to the ESB by a client application, the request is routed to the relevant back-end service (depending on the message content). That is, when the router receives the stock request, it first reads the content and if the request is made to the foo service, the request is routed to fooOutQueue. Alternatively, if the request is for the bar service, it is routed to barOutQueue.

Figure 2: Example scenario of the Message Router EIP

Before digging into implementation details, let's take a look at the relationship between the example scenario and the Message Router EIP by comparing their core components.

Message Router EIP (Figure 1)

Message Router Example Scenario (Figure 2)

Incoming message

Stock Quote Request

Message router

The Switch and Send mediators of the ESB simulates the Message Router EIP. The Switch Mediator depicts the Router and observes the content of the message, while the Send Mediator sends the message to a selected recipient.

The message should be routed to the appropriate service, based on the case defined.

Outgoing queues

fooOutQueue and barOutQueue act as two separate services in the example scenario.

The ESB configuration

Given below is the ESB configuration of this sample.

<definitions xmlns="http://ws.apache.org/ns/synapse">
   <!-- Receiving sequence which will be the message router -->
   <sequence name="message-router-sequence">
       <!-- Would analyze the data for filtering -->
       <switch xmlns:m0="http://services.samples" source="//m0:getQuote/m0:request/m0:symbol">
           <!-- If the content is "foo" -->
           <case regex="foo">
               <!-- Sends the information to the fooOutQueue -->
               <send>
                   <endpoint>
                       <address uri="http://localhost:9000/services/SimpleStockQuoteService?wsdl"/>
                   </endpoint>
               </send>
           </case>
           <!-- If the content is "bar" -->
           <case regex="bar">
               <!-- Sends the information to the barOutQueue -->
               <send>
                   <endpoint>
                       <address uri="http://localhost:9001/services/SimpleStockQuoteService?wsdl"/>
                   </endpoint>
               </send>
           </case>
           <default>
               <property name="symbol" expression="fn:concat('Normal Stock - ', //m0:getQuote/m0:request/m0:symbol)"/>
           </default>
       </switch>
   </sequence>
   <proxy name="message-router-proxy" startOnLoad="true" transports="http https">
       <target>
           <inSequence>
               <!-- Will call the message router -->
               <sequence key="message-router-sequence"/>
           </inSequence>
           <outSequence>
               <respond/>
           </outSequence>
           <description>Message Router</description>
       </target>
   </proxy>
</definitions>

The configuration elements

The elements used in the above ESB configuration are explained below.

<proxy> - This is the proxy service that should be invoked to execute the configuration.
<inSequence> - A message is first received by the proxy service, and then directed to this sequence.
<outSequence> - This sequence is triggered after the execution of the <inSequence>.
<sequence> - This is an external sequence, which is invoked by the proxy.
<send> - This is the Send mediator that routes the message to the endpoint indicated by the address URI.
<case> - The filtered content will be matched with the specified regular expression.
<default> - If a matching condition is not found, the message will be diverted to this default case.

Simulating the sample scenario

Now, let's try out the sample scenario explained above.

Setting up the environment

You need to set up the ESB, and the back-end services:

Download the Message-Router.zip file, which includes the ESB configuration described above.
See Setting up the Environment for instructions on setting up the ESB and the back-end service.

When you set up the environment, note that you need to start two instances of the back-end service (Stock Quote Service) to simulate this example.

Executing the sample

Let's send a request to the ESB using the Stock Quote Client application. Find out more about the Stock Quote Client from the ESB documentation.

Open a new terminal, and navigate to the <ESB_HOME>/samples/axis2Client/ directory. The Stock Quote client application is stored in this directory.

Execute the following command to send the request to the ESB.

ant stockquote -Dtrpurl=http://localhost:8280/services/message-router-proxy -Dsymbol=foo

The structure of the request is as follows:

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

Analyzing the result

When you send the request, the ESB first receives the message and then routes it to the relevant back-end service (foo inventory service). The following output will be printed on the Axis2 server's console, confirming that the request is successfully received by the back-end service.

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

The stock quote generated by the 'foo' service will then be sent to the client application (Stock Quote Client). The following output will be printed on the client application's console:

Standard :: Stock price = $77.86763451813164

Now, change the -Dsymbol parameter to bar, and send another request as shown below.

ant stockquote -Dtrpurl=http://localhost:8280/services/message-router-proxy -Dsymbol=bar

See that the request goes to the bar inventory service. The following output will be printed on the Axis2 server's console (bar inventory service), confirming that the request is successfully received by the relevant back-end service.

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

The stock quote generated by the 'bar' service will then be sent to the client application (Stock Quote Client). The following output will be printed on the client application's console:

Standard :: Stock price = $64.81823486260222