Sample 17: Transforming / Replacing Message Content with PayloadFactory Mediator

Introduction

This Sample demonstrates how the PayloadFactory Mediator can be used to perform transformations as an alternative to the XSLT mediator, which is demonstrated in Sample 8: Introduction to Static and Dynamic Registry Resources and Using XSLT Transformations . In this sample, the ESB implements the message translator enterprise integration pattern, and acts as a translator between the client and the back-end server when mediating a message to the sample back-end server from a sample client.

In this scenario, there is a web service endpoint that has the getQuote operation that expects a symbol parameter. However, the client that invokes the service sends the getQuote operation with the Code parameter. Therefore, the request message will be sent in the following format:

<p:getquote xmlns:p="http://services.samples">
      <p:request>
       <p:code>IBM</p:code>
      </p:request>
</p:getquote>

The service expects the message in the following format:

<p:getquote xmlns:p="http://services.samples">
     <p:request>
       <p:symbol>IBM</p:symbol>
      </p:request>
</p:getquote>

Similarly, the service will send the response in the following format:

<m:checkpriceresponse xmlns:m="http://services.samples/xsd">
   <m:symbol>IBM</m:symbol>
   <m:last>84.76940826343248</m:last>
</m:checkpriceresponse>  

The client expects the response in the following format:

<m:checkpriceresponse xmlns:m="http://services.samples/xsd">
   <m:code>IBM</m:code>
   <m:price>84.76940826343248</m:price>
</m:checkpriceresponse>

To resolve this discrepancy, the PayloadFactory mediator is used to transform the message into the request format required by the service and the response format required by the client.

Prerequisites

For a list of prerequisites, see Prerequisites to Start the ESB Samples.

Building the sample

The XML configuration for this sample is as follows: 

<definitions xmlns="http://ws.apache.org/ns/synapse">
    <sequence name="main">
        <in>
            <!-- using payloadFactory mediator to transform the request message -->
            <payloadFactory media-type="xml">
                <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>
        </in>
        <out>
            <!-- using payloadFactory mediator to transform the response message -->
            <payloadFactory media-type="xml">
                <format>
                    <m:CheckPriceResponse xmlns:m="http://services.samples/xsd">
                        <m:Code>$1</m:Code>
                        <m:Price>$2</m:Price>
                    </m:CheckPriceResponse>
                </format>
                <args>
                    <arg xmlns:m0="http://services.samples/xsd" expression="//m0:symbol"/>
                    <arg xmlns:m0="http://services.samples/xsd" expression="//m0:last"/>
                </args>
            </payloadFactory>
        </out>
        <send/>
    </sequence>
</definitions>

This configuration file  synapse_sample_17.xml is available in the <ESB_HOME>/repository/samples directory.

To build the sample

1. Start the ESB with the sample 17 configuration. For instructions on starting a sample ESB configuration, see Starting the ESB with a sample configuration.
   
   The operation log keeps running until the server starts, which usually takes several seconds. Wait until the server has fully booted up and displays a message similar to "WSO2 Carbon started in n seconds."

2. Start the Axis2 server. For instructions on starting the Axis2 server, see Starting the Axis2 server.

3. Deploy the back-end service SimpleStockQuoteService. For instructions on deploying sample back-end services, see Deploying sample back-end services.

   Now you have a running ESB instance and a back-end service deployed. In the next section, we will send a message to the back-end service through the ESB using a sample client.

Executing the sample

The sample client used here is the Stock Quote Client, which can operate in several modes. For further details on this sample client and its operation modes, see Stock Quote Client.

To execute the sample client

• Run the following command from the <ESB_HOME>/samples/axis2Client directory.

  ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote

Analyzing the output

When you analyze the debug log output on the ESB console, you will see that the incoming message is transformed by the PayloadFactory Mediator into a standard stock quote request as expected by the SimpleStockQuoteService deployed on the Axis2 server.

printf() style formatting is used to configure the transformation performed by the mediator. Each argument in the mediator configuration can be a static value or an XPath expression.

When an expression is used, the argument value is fetched at runtime by evaluating the provided XPath expression against the existing SOAP message.

The response from the SimpleStockQuoteService is converted back into the custom format as expected by the client during the out message processing, once again using the PayloadFactory Mediator.