Sample 17: Transforming / Replacing Message Content with PayloadFactory Mediator

Introduction

This Sample demonstrates the PayloadFactory mediator to perform transformations as an alternative to 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 a 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 this format:

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

But the service expects the message in this 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 this format:

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

But the client expects the response in this 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, we will use the PayloadFactory mediator 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 the Prerequisites section in ESB Samples Setup.

Building the Sample

1. Start the ESB with sample 17 configuration using the instructions given in Starting Sample ESB Configurations.

2. A message should appear in the command or text Linux console stating the server started successfully.

3. The synapse configuration in the ESB used for message mediation in this sample is provided in <ESB_HOME>/repository/samples/synapse_sample_17.xml as shown below:

<definitions xmlns="http://ws.apache.org/ns/synapse">
    <sequence name="main">
        <in>
            <!-- using payloadFactory mediator to transform the request message -->
            <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>
        </in>
        <out>
            <!-- using payloadFactory mediator to transform the response message -->
            <payloadFactory>
                <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>

4. Deploy the back-end service 'SimpleStockQuoteService' and start the Axis2 server using the instructions given in section Starting Sample Back-End Services.

5. 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 'Stock Quote Client' which can operate in multiple modes. For instructions on this sample client and its operation modes, refer to Stock Quote Client

1. Run the custom quote client as 'ant stockquote -Dmode=customquote ...' from <ESB_HOME>/samples/axis2Client directory.

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

2. Analyze the ESB's debug log output. The incoming message is transformed by the Payload-factory 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 Payload-factory mediator.