Message Translator

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

Introduction to Message Translator

The Message Translator EIP is responsible for translating messages between applications. This ensures compatibility between applications that support different data types.

Different applications typically use different data types. Therefore, for two applications to successfully communicate, we should translate the messages (that pass from one application) to the data type compatible with the receiving application. In this case, a translator changes the context of a message from one interface to another. This ensures that the message adheres to the context rules of the back-end service.

For more information, go to Message Translator. 

Figure 1: Message Translator EIP

Example scenario

In this example, we will use a stock inventory exposed through a service (Stock Quote Service). A client application sends a stock quote request to the ESB, and the ESB routes the request to the back-end service (Stock Quote Service). The message format of the client's request and the message format compatible with the receiving service is different.

• The format of the client's 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:Code>foo</ser:Code>
     </soapenv:Body>
  </soapenv:Envelope>

• The message format compatible with the receiver 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:Body>
        <ser:getQuote>
           <!--Optional:-->
           <ser:request>
              <!--Optional:-->
              <ser:symbol>foo</ser:symbol>
           </ser:request>
        </ser:getQuote>
     </soapenv:Body>
  </soapenv:Envelope>

Therefore, the ESB transforms the client's message (to the format that is compatible with the receiver), before passing the request to the back-end as depicted in the following diagram.

Figure 2: Example scenario of the Message Translator EIP

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

The ESB configuration

Given below is the ESB configuration for simulating the example scenario explained above. 

<definitions xmlns="http://ws.apache.org/ns/synapse">
   <!-- Will trigger when a request is sent to the ESB profile of WSO2 EI -->
   <proxy name="message-translator-proxy" startOnLoad="true" transports="http https">
       <target>
           <inSequence>
               <!-- Will transform the incoming message to the format specified below -->
               <payloadFactory>
                   <format>
                       <m:getQuote xmlns:m="http://services.samples">
                           <m:request>
                               <m:symbol>$1</m:symbol>
                           </m:request>
                       </m:getQuote>
                   </format>
                   <args>
                       <arg xmlns:m0="http://services.samples" expression="//m0:Code"/>
                   </args>
               </payloadFactory>
               <send>
                   <endpoint>
                       <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
                   </endpoint>
               </send>
           </inSequence>
           <outSequence>
               <respond/>
           </outSequence>
       </target>
   </proxy>
</definitions>

The configuration elements

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

• <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>.
• <send> - This is the Send mediator that routes the message to the endpoint indicated by the address URI.
• <main sequence> - The default sequence that is triggered when you invoke the ESB.
• <payload factory> - Transforms the message to the format denoted by the mediator.

Simulating the example scenario

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

Setting up the environment

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

1. Download the Messsage-Translator.zip file, which includes the ESB configuration described above. 

2. 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 only need to start one instance of the back-end service (Stock Quote Service) to simulate this example.

Executing the sample

Send the following request to the ESB, by using a SOAP client. When you send the request, you will need the wsdl URL of the proxy service defined in the ESB configuration. The default wsdl URL for this proxy service is http://localhost:8280/services/message-translator-proxy?wsdl.

<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:Code>foo</ser:Code>
   </soapenv:Body>
</soapenv:Envelope>

Analyzing the output

When you send the request, the ESB first receives the message and then routes it to the back-end service (StockQuoteService). 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 generated stock quote will then be sent to the client application (SOAP UI). You can view the response in the SOAP UI as follows: