Message Translator

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

Introduction to Message Translator

Different applications typically use different data types. Therefore, for two applications to successfully communicate, we should intermediately translate the messages that pass from one application to the data type compatible with the receiving application. A translator changes the context of a message from one interface to another, allowing messages to adhere to message context rules of the back-end service.

The Message Translator EIP is responsible for message translating to ensure compatibility between applications supporting different data types. For more information, refer to http://www.eaipatterns.com/MessageTranslator.html.

Figure 1: Message Translator EIP

Example scenario

The example scenario is an inventory for stocks. It illustrates how the sender sends a request in one format, which is then transformed into another format compatible with the receiver. The format 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: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>

All requests in the first format should be translated to the second by WSO2 ESB. The diagram below depicts how to simulate this scenario using WSO2 ESB.

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.

Message Translator EIP (Figure 1)	Message Translator Example Scenario (Figure 2)
Incoming Message	Stock Quote Request
Translator	The translation is done through the Payload Factory Mediator

Environment setup

Download and install WSO2 ESB from http://wso2.com/products/enterprise-service-bus. For a list of prerequisites and step-by-step installation instructions, refer to Installation Guide in the WSO2 ESB documentation.
Start an instance of Axis2 server. For instructions, refer to Setting Up the ESB Samples - Starting the Axis2 server in the WSO2 ESB documentation.

ESB configuration

Start the ESB server and log into its management console UI (https://localhost:9443/carbon). In the management console, navigate to the Main menu and click Source View in the Service Bus section. Next, copy and paste the following configuration, which helps you explore the example scenario, to the source view.

<definitions xmlns="http://ws.apache.org/ns/synapse">
   <sequence name="fault">
      <log level="full">
         <property name="MESSAGE" value="Executing default &#34;fault&#34; sequence"/>
         <property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/>
         <property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/>
      </log>
      <drop/>
   </sequence>
   <!-- Will trigger when a request is sent to the ESB --> 
   <sequence name="main">
      <in>
		 <!-- 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>
      </in>
      <out>      
      	<send/>
	  </out>
   </sequence>
</definitions>

Simulating the sample scenario

Send a request using a SOAP request client (such as SoapUI) to WSO2 ESB in the following manner.

<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>

After sending the request to the ESB through the client, notice that the request is successfully generated in the stock quote server.

How the implementation works

Let's investigate the elements of the ESB configuration in detail. The line numbers below refer to the ESB configuration shown above.

main sequence [line 12 in ESB config] - The default sequence that gets triggered when the user invokes the ESB server.
in [line 13 in ESB config] - The message is directed to the in mediator when it is received by the main sequence.
out [line 33 in ESB config] - Triggered when a response is received for the message that was sent by the in mediator.
payload factory [line 15 in ESB config] - Will transform the message to the format denoted within the mediator.