Stepping into Apache Synapse - PART II (Proxy Services)

This article by Ruwan Linton is the second of a series of articles on Apache Synapse. In this series, you will learn what Synapse is, how it works, and how you can use it to solve common enterprise problems. You will understand some of the advanced features of Synapse, how you can extend it, and also some of its limitations.

Introduction

In Part-I [1] of this series, you learned the basics of Apache Synapse. In this article, you will learn in detail about one basic operation model of Synapse named Proxy Services. At the end of this article, a real life integration scenario will be explained with a sample using the Proxy Services operation model. At the same time, this article will walk you through the pros and cons of the proxy services inside Synapse.

Applies To

Apache Synapse

Version 1.1.1

Proxy Service [1]
Model of a Synapse Proxy Service [1]
Proxy Service Configuration [1]
Composite Services using Proxy Services [1]
Conclusion [1]
References/Resources [1]

Synapse Configuration Language [2], and can be described using the BNF (Backus-Naur Form) of the language as follows;

<proxy name="string" [transports="(http | https | jms | mail | vfs )+ | all"] [trace="(enable | disable)"] 
	[statistics="(enable | disable)"]>
    <description>..</description>?
    <target [inSequence="name"] [outSequence="name"] [faultSequence="name"] [endpoint="name"]>
        <endpoint>...</endpoint>
        <inSequence>...</inSequence>
        <outSequence>...</outSequence>
        <faultSequence>...</faultSequence>
    </target>
    <publishWSDL uri=".." key="string">
        <wsdl:definitions>...</wsdl:definitions>?
        <wsdl20:description>...</wsdl20:description>?
        <resource location="..." key="..."/>*
    </publishWSDL>?
    <enableSec/>?
    <enableRM/>?
    <policy key="string" [type="(in | out)"] [operationName="string"] [operationNamespace="string"]/>*
    <parameter name="string">
        text | xml
    </parameter>*
</proxy>

The following section describes the above configuration, and the possible values for each element and attribute.

The name attribute value of the proxy element represents the name of the proxy service to be deployed. It has to be a string without special characters.
The transports attribute value of the proxy element represents the set of transports on which this particular service is deployed. It can be any combination of the existing transports including http, https, jms, mail, vfs or the keyword all. If the attribute is not specified, it represents that this proxy service is deployed on all the existing transports.
The attributes trace and statistics represent the tracing state and the statistics reporting state respectively. The attribute value can be either enable or disable.
The description element specifies a description of the proxy, which has no impact over the functionality of the proxy service. This is an optional element.
Each proxy must contain only one target element that describes the target information of the proxy service.
- The sequence of mediation for the incoming messages can be defined two ways. It can either be a reference using the inSequence attribute of the target element or defined inline enclosed with the inSequence element
- In the same manner, the sequence for the outgoing message mediation can also be defined two ways, either as a referencec using the outSequence attribute of the target element or defined inline enclosed with the outSequence element.
- The same holds true for the fault message processing sequence with the attribute and tag names as faultSequence
- endpoint as an attribute or element inside the target element represents the message delivery endpoint after the mediation. This is optional. However, when it is present in the target, the inSequence becomes optional, allowing the messages to be directly forwarded to the specified endpoint without any mediation.
If a particular service has to represent a WSDL, then that can be specified by using the publishWSDL element as an external URL. This can be done by using the uri attribute, as an registry entry using the key attribute, or it can be specified inline. This particular WSDL can be a WSDL11 document or a WSDL20 document.
Further, if there are any resources like XSD files refered to in the WSDL, those resources can be specified with the location and the key attributes of the resource element within the publishWSDL element
enableSec and the enableRM elements represent whether this service has to be secured and made reliable respectively, if present.
policy elements can be used to specify any service level policies with the key attribute to configure the above specified QoS features on a per service basis. If the type of the policy is specified, then the policy will only be effective for the specified type which can be either in or out. Also, it is possible to configure the operation level policies by providing the operationName and the operationNamespace attributes of the policy, which is only effective if there is a WSDL specified.
Some of the transports will require service parameters to be present for them to configure their behavior. For example, vfs transport requires a file location to be listened, a mail transport requires an email address to be listened, and so on. These parameters can be specified in the configuration using the parameter element with a name and a value inside the parameter

With this information on the proxy services configuration, we will be moving into a real life usage of the proxy services. If you have not already had a look at the samples on proxy services, which are shipped with Synapse distribution, it is recommended to have a look at a set of samples namely;

Sample 150: Introduction to proxy services [3]
Sample 151: Custom sequences and endpoints with proxy services [4]
Sample 152: Switching transports and message format from SOAP to REST/POX [5]
Sample 153: Routing the messages arrived to a proxy service without processing the security headers [6]
Sample 154: Load Balancing with proxy services [7]
Sample 200: Using WS-Security with policy attachments for proxy services [8]
Sample 201: Reliable message exchange between the client and the proxy services using WS-ReliableMessageing [9]
Sample 250 - 256: Transport samples with proxy services [10]

synapse [11] and need to deploy the SimpleStockQuoteService shipped with the Synapse samples in the Synapse distribution. You will need to have apache-ant-1.7 [12] or above and Java installed. Follow the steps described below to set it up.

Go to the SYNAPSE_HOME folder (where you have extracted the Synapse distribution) using a console in Unix or using the command prompt on MS Windows
Go to the samples/axis2Server/src/SimpleStockQuoteService folder and type the command ant
Go back to the axis2Server folder and start the axis2 server using the relevant command for the operating system (For Unix: axis2server.sh and for MS Windows: axis2server.bat)

 cd $SYNAPSE_HOME
 cd samples/axis2Server/src/SimpleStockQuoteService
 ant
 cd ../..
 sh axis2server.sh

Setting up Synapse

Go to the SYNAPSE_HOME and replace the synapse.xml file found at repository/conf/synapse.xml, with the configuration file downloaded from here [12]. Then use the synapse.sh or synapse.bat file found in the bin folder to start the Syanspe server. (Note: You will need to download a patch to the 1.1.1 release aggregate mediator for this to work properly from here [13] and put it in to the $SYNAPSE_HOME/lib/patches folder before starting synapse)

 cd $SYNAPSE_HOME
 cp $DOWNLOADED_FILE repository/conf/synapse.xml
 sh bin/synapse.sh

Executing the client and observing it

Now we are ready to try this composite service and use the following command to send a stockquote request to the composite service.

 cd $SYNAPSE_HOME
 cd samples/axis2Client
 ant stockquote -Dsymbol=HIGHEST -Dtrpurl=http://localhost:8080/soap/HighestQuoteService

On receiving the request from the client, Synapse will invoke the SimpleStockQuoteService. You can have a look at the service console to see the three requests with the different symbols, which are served from the Axis2 server. If we look at the message flows (you can do so by monitoring the messages through a tcpmon) these messages will look something like the following.

Request message from client to synapse

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wsa="http://www.w3.org/2005/08/addressing">
   <soapenv:Body>
      <m0:getQuote xmlns:m0="http://services.samples/xsd">
         <m0:request>
            <m0:symbol>HIGHEST</m0:symbol>
         </m0:request>
      </m0:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

Request from Syanpse to three services

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <m0:getQuote xmlns:m0="http://services.samples/xsd" xmlns:ns="http://services.samples/xsd">
         <m0:request>
            <m0:symbol>MSFT</m0:symbol>
         </m0:request>
      </m0:getQuote>
   </soapenv:Body>
</soapenv:Envelope>

Response from three services to Synapse

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:getQuoteResponse xmlns:ns="http://services.samples/xsd">
         <ns:return type="samples.services.GetQuoteResponse">
            <ns:change>-2.757242439429394</ns:change>
            <ns:earnings>13.926070553389701</ns:earnings>
            <ns:high>-79.99660594704424</ns:high>
            <ns:last>81.90254083344033</ns:last>
            <ns:lastTradeTimestamp>Thu Mar 27 14:36:49 LKT 2008</ns:lastTradeTimestamp>
            <ns:low>-80.02562455961932</ns:low>
            <ns:marketCap>309592.02627594396</ns:marketCap>
            <ns:name>MSFT Company</ns:name>
            <ns:open>85.83639924522409</ns:open>
            <ns:peRatio>23.24419444176838</ns:peRatio>
            <ns:percentageChange>-3.09564134617401</ns:percentageChange>
            <ns:prevClose>89.06853640642665</ns:prevClose>
            <ns:symbol>MSFT</ns:symbol>
            <ns:volume>5238</ns:volume>
         </ns:return>
      </ns:getQuoteResponse>
   </soapenv:Body>
</soapenv:Envelope>

Aggregated response message

This message cannot be seen out of the synapse, and it represents the message inside synapse just after aggregation whihc will be transformed to remove two response segments and only one (highest quote) can be seen in the response whihc goes out from synapse. You may put a log mediator just after the aggregation and before the transformation to observe this message within the synapse console or change the log level of synapse to DEBUG to observe the traces of the message.

<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <ns:getQuoteResponse xmlns:ns="http://services.samples/xsd">
            <ns:return type="samples.services.GetQuoteResponse">
                <ns:change>4.462968020386499</ns:change>
                <ns:earnings>13.471360130234485</ns:earnings>
                <ns:high>-154.61523860622725</ns:high>
                <ns:last>154.8932926618978</ns:last>
                <ns:lastTradeTimestamp>Thu Mar 27 14:36:49 LKT 2008</ns:lastTradeTimestamp>
                <ns:low>160.49531857882639</ns:low>
                <ns:marketCap>-4772597.076954884</ns:marketCap>
                <ns:name>IBM Company</ns:name>
                <ns:open>-154.5429010268229</ns:open>
                <ns:peRatio>24.43118178596917</ns:peRatio>
                <ns:percentageChange>2.513772963420755</ns:percentageChange>
                <ns:prevClose>177.54061664794378</ns:prevClose>
                <ns:symbol>IBM</ns:symbol>
                <ns:volume>9913</ns:volume>
            </ns:return>
            <ns:return type="samples.services.GetQuoteResponse">
                <ns:change>-2.9921002202631746</ns:change>
                <ns:earnings>12.152974355548952</ns:earnings>
                <ns:high>96.57893911367476</ns:high>
                <ns:last>94.02448935872526</ns:last>
                <ns:lastTradeTimestamp>Thu Mar 27 14:36:49 LKT 2008</ns:lastTradeTimestamp>
                <ns:low>98.65295506037018</ns:low>
                <ns:marketCap>-1466954.6426709667</ns:marketCap>
                <ns:name>SUN Company</ns:name>
                <ns:open>-92.16779342982966</ns:open>
                <ns:peRatio>25.29595199699729</ns:peRatio>
                <ns:percentageChange>3.233176500747909</ns:percentageChange>
                <ns:prevClose>-92.54367089365618</ns:prevClose>
                <ns:symbol>SUN</ns:symbol>
                <ns:volume>15470</ns:volume>
            </ns:return>
            <ns:return type="samples.services.GetQuoteResponse">
                <ns:change>-2.757242439429394</ns:change>
                <ns:earnings>13.926070553389701</ns:earnings>
                <ns:high>-79.99660594704424</ns:high>
                <ns:last>81.90254083344033</ns:last>
                <ns:lastTradeTimestamp>Thu Mar 27 14:36:49 LKT 2008</ns:lastTradeTimestamp>
                <ns:low>-80.02562455961932</ns:low>
                <ns:marketCap>309592.02627594396</ns:marketCap>
                <ns:name>MSFT Company</ns:name>
                <ns:open>85.83639924522409</ns:open>
                <ns:peRatio>23.24419444176838</ns:peRatio>
                <ns:percentageChange>-3.09564134617401</ns:percentageChange>
                <ns:prevClose>89.06853640642665</ns:prevClose>
                <ns:symbol>MSFT</ns:symbol>
                <ns:volume>5238</ns:volume>
            </ns:return>
        </ns:getQuoteResponse>
    </soapenv:Body>
</soapenv:Envelope>

Transformed highest quote response to the client

<?xml version='1.0' encoding='UTF-8'?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns:getQuoteResponse xmlns:ns="http://services.samples/xsd" xmlns:m0="http://services.samples/xsd">
         <ns:return>
            <ns:change>4.462968020386499</ns:change>
            <ns:earnings>13.471360130234485</ns:earnings>
            <ns:high>-154.61523860622725</ns:high>
            <ns:last>154.8932926618978</ns:last>
            <ns:lastTradeTimestamp>Thu Mar 27 14:36:49 LKT 2008</ns:lastTradeTimestamp>
            <ns:low>160.49531857882639</ns:low>
            <ns:marketCap>-4772597.076954884</ns:marketCap>
            <ns:name>IBM Company</ns:name>
            <ns:open>-154.5429010268229</ns:open>
            <ns:peRatio>24.43118178596917</ns:peRatio>
            <ns:percentageChange>2.513772963420755</ns:percentageChange>
            <ns:prevClose>177.54061664794378</ns:prevClose>
            <ns:symbol>IBM</ns:symbol>
            <ns:volume>9913</ns:volume>
         </ns:return>
      </ns:getQuoteResponse>
   </soapenv:Body>
</soapenv:Envelope>

Synapse Home Page [14]
Synapse Samples Guide [15]

Synapse Configuration Language [16]

Stepping into Apache Synapse - PART I [17]

Author

Ruwan Linton - Software Engineer - WSO2 Inc. (ruwan AT wso2 DOT com)