This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Proxy Service

Owned by Former user (Deleted)
Last updated: May 13, 2014 by Rukshani Weerasinha (Unlicensed)
12 min read

The following examples are available:

1. #Introduction to Proxy Services.
2. #Custom Sequences and Endpoints with Proxy Services.
3. #Switching Transports and Message Format from SOAP to REST/POX.
4. #Routing the Messages Arrived to a Proxy Service without Processing the Security Headers.
5. #Load Balancing with Proxy Services.
6. #Dual Channel Invocation on Both Client Side and Server Side of Synapse with Proxy Services.

Example 1. Introduction to proxy services

Objective: Introduction to ESB Proxy Services.

<definitions xmlns="http://ws.apache.org/ns/synapse">
    <proxy name="StockQuoteProxy">
        <target>
            <endpoint>
                <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
            </endpoint>
            <outSequence>
                <send/>
            </outSequence>
        </target>
        <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
    </proxy>
</definitions>

Prerequisites:

  • Start the Synapse configuration numbered 150 (i.e. wso2esb-samples -sn 150).
  • Start the Axis2 server and deploy the SimpleStockQuoteService if not already done.

Once ESB starts, you could go to http://localhost:8280/services/StockQuoteProxy?wsdl and view the WSDL generated for the Proxy Service defined in the configuration. This WSDL is based on the source WSDL supplied in the Proxy Service definition and is updated to reflect the Proxy Service EPR.

Execute the stock quote client by requesting for a stock quote on the Proxy Service as follows:

1. Stock Quote Client

This is a simple SOAP client that could send stock quote requests, and receive and display the last sale price for a stock symbol.

ant stockquote -Dsymbol=IBM
-Dmode=quote
-Daddurl=http://localhost:9000/soap/SimpleStockQuoteService|||||||||||||||||\
-Dtrpurl=http://localhost:8080|||||||||||||||||\ -Dprxurl=http://localhost:8080|||||||||||||||||\
-Dpolicy=../../repository/conf/sample/resources/policy/policy_1.xml|||||||||||||||||\

The client is able to operate in the following modes, and send the payloads listed below as SOAP messages:

quote - sends a quote request for a single stock as follows. The response contains the last sales price for the stock which would be displayed.

<m:getQuote xmlns:m="http://services.samples/xsd">
<m:request>
<m:symbol>IBM</m:symbol>
</m:request>
</m:getQuote>

customquote - sends a quote request in a custom format. The ESB would transform this custom request into the standard stock quote request format and send it to the service. Upon receipt of the response it would be transformed again to a custom response format and returned to the client, which will then display the last sales price.

<m0:checkPriceRequest xmlns:m0="http://services.samples/xsd">
<m0:Code>symbol</m0:Code>
</m0:checkPriceRequest>

fullquote - gets quote reports for the stock over a number of days (i.e. last 100 days of the year).

<m:getFullQuote xmlns:m="http://services.samples/xsd">
<m:request>
<m:symbol>IBM</m:symbol>
</m:request>
</m:getFullQuote>

placeorder - places an order for stocks using a one way request

<m:placeOrder xmlns:m="http://services.samples/xsd">
<m:order>
<m:price>3.141593E0</m:price>
<m:quantity>4</m:quantity>
<m:symbol>IBM</m:symbol>
</m:order>
</m:placeOrder>

marketactivity - gets a market activity report for the day (i.e. quotes for multiple symbols)

<m:getMarketActivity xmlns:m="http://services.samples/xsd">
<m:request>
<m:symbol>IBM</m:symbol>
...
<m:symbol>MSFT</m:symbol>
</m:request>
</m:getMarketActivity>

Note

See samples/axis2Client/src/samples/common/StockQuoteHandler.java for sample responses expected by the clients.

ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy

An "inSequence" or "endpoint" or both of these would decide how the message would be handled after the Proxy Service receives the message. In the above example the request received is forwarded to the sample service hosted on Axis2. The "outSequence" defines how the response is handled before it is sent back to the client. By default, a Proxy Service is exposed over all transports configured for ESB, unless these are specifically mentioned through the transports attribute.

Example 2. Custom Sequences and Endpoints with Proxy Services

Objective: Using custom sequences and endpoints for message mediation with Proxy Services.

<definitions xmlns="http://ws.apache.org/ns/synapse">

    <sequence name="proxy_1">
        <send>
            <endpoint><address uri="http://localhost:9000/services/SimpleStockQuoteService"/></endpoint>
        </send>
    </sequence>
    <sequence name="out">
        <send/>
    </sequence>
    <endpoint name="proxy_2_endpoint">
        <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
    </endpoint>
    <localEntry key="proxy_wsdl" src="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>

    <proxy name="StockQuoteProxy1">
        <publishWSDL key="proxy_wsdl"/>
        <target inSequence="proxy_1" outSequence="out"/>
    </proxy>

    <proxy name="StockQuoteProxy2">
        <publishWSDL key="proxy_wsdl"/>
        <target endpoint="proxy_2_endpoint" outSequence="out"/>
    </proxy>
</definitions>

Prerequisites:

  • Start the Synapse configuration numbered 151 (i.e. wso2esb-samples -sn 151).
  • Start the Axis2 server and deploy the SimpleStockQuoteService if not already done.

This configuration creates two Proxy Services. The first Proxy Service "StockQuoteProxy1" uses the sequence named "proxy_1" to process incoming messages and the sequence named "out" to process outgoing responses. The second Proxy Service "StockQuoteProxy2" is set to directly forward messages that are received to the endpoint named "proxy_2_endpoint" without any mediation.

You could send a stock quote request to each of these Proxy Services and receive the reply generated by the actual service hosted on the Axis2 instance.

ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy1
ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy2

Example 3. Switching Transports and Message Format from SOAP to REST/POX

Objective: Switching transports and message format from SOAP to REST/POX.

<definitions xmlns="http://ws.apache.org/ns/synapse">
    <proxy name="StockQuoteProxy" transports="https">
        <target>
            <endpoint>
                <address uri="http://localhost:9000/services/SimpleStockQuoteService" format="pox"/>
            </endpoint>
            <outSequence>
                <send/>
            </outSequence>
        </target>
        <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
    </proxy>
</definitions>

Prerequisites:

  • Start the Synapse configuration numbered 152 (i.e. wso2esb-samples -sn 152).
  • Start the Axis2 server and deploy the SimpleStockQuoteService if not already done.

This configuration demonstrates how a Proxy Service could be exposed on a subset of available transports and how it could switch from one transport to another. This example exposes the created Proxy Service only on HTTPS, and thus if the user tries to access it over HTTP, would result in a fault.

ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy
...
     [java] org.apache.axis2.AxisFault: The service cannot be found for the endpoint reference (EPR) /services/StockQuoteProxy

Accessing this over HTTPS(ant stockquote -Dtrpurl=https://localhost:8243/services/StockQuoteProxy) causes the Proxy Service to access the SimpleStockQuoteService on the sample Axis2 server using REST/POX. This could be seen if the message exchange was captured using TCPMon as follows. The REST/POX response is now transformed back into a SOAP message and returned to the client.

POST http://localhost:9000/services/SimpleStockQuoteService HTTP/1.1
Host: 127.0.0.1
SOAPAction: urn:getQuote
Content-Type: application/xml; charset=UTF-8;action="urn:getQuote";
Transfer-Encoding: chunked
Connection: Keep-Alive
User-Agent: Synapse-HttpComponents-NIO

75
<m0:getQuote xmlns:m0="http://services.samples/xsd">
   <m0:request>
      <m0:symbol>IBM</m0:symbol>
   </m0:request>
</m0:getQuote>

HTTP/1.1 200 OK
Content-Type: application/xml; charset=UTF-8;action="http://services.samples/SimpleStockQuoteServicePortType/getQuoteResponse";
Date: Tue, 24 Apr 2007 14:42:11 GMT
Server: Synapse-HttpComponents-NIO
Transfer-Encoding: chunked
Connection: Keep-Alive

2b3
<ns:getQuoteResponse xmlns:ns="http://services.samples/xsd">
   <ns:return>
      <ns:change>3.7730036841862384</ns:change>
      <ns:earnings>-9.950236235550818</ns:earnings>
      <ns:high>-80.23868444613285</ns:high>
      <ns:last>80.50750970812187</ns:last>
      <ns:lastTradeTimestamp>Tue Apr 24 20:42:11 LKT 2007</ns:lastTradeTimestamp>
      <ns:low>-79.67368355714606</ns:low>
      <ns:marketCap>4.502043663670823E7</ns:marketCap>
      <ns:name>IBM Company</ns:name>
      <ns:open>-80.02229531286982</ns:open>
      <ns:peRatio>25.089295161182022</ns:peRatio>
      <ns:percentageChange>4.28842665653824</ns:percentageChange>
      <ns:prevClose>87.98107059692451</ns:prevClose>
      <ns:symbol>IBM</ns:symbol>
      <ns:volume>19941</ns:volume>
   </ns:return></ns:getQuoteResponse>

Example 4. Routing the Messages Arrived to a Proxy Service without Processing the Security Headers

Objective: Routing the messages arrived to a Proxy Service without processing the MustUnderstand headers (Security header).

<definitions xmlns="http://ws.apache.org/ns/synapse">
    <proxy name="StockQuoteProxy">
        <target>
            <inSequence>
                <send>
                    <endpoint>
                        <address uri="http://localhost:9000/services/SecureStockQuoteService"/>
                    </endpoint>
                </send>
            </inSequence>
            <outSequence>
                <send/>
            </outSequence>
        </target>
        <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
    </proxy>
</definitions>

Prerequisites:

  • You may also need to download and install the unlimited strength policy files for your JDK before using Apache Rampart (e.g. see http://java.sun.com/javase/downloads/index_jdk5.jsp)
  • Start the Synapse configuration numbered 153 (i.e. wso2esb-samples -sn 153).
  • Start the Axis2 server and deploy the SecureStockQuoteService if not already done.

The Proxy Service will receive secure messages with security headers which are MustUnderstand. But hence element "engageSec'" is not present in the proxy configuration ESB will not engage that Apache Rampart on this Proxy Service. It is expected that an MustUnderstand failure exception on the AxisEngine would occur before the message arrives ESB. But ESB handles this message and gets it in by setting all the headers which are MustUnderstand and not processed to processed state. This will enable ESB to route the messages without reading the Security headers (just routing the messages from client to service, both of which are secure). To execute the client, send a stock quote request to the Proxy Service, sign and encrypt the request by specifying the client side security policy as follows:

ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dpolicy=./../../repository/samples/resources/policy/client_policy_3.xml

By following through the debug logs or TCPMon output you could see that the request received by the Proxy Service was signed and encrypted. Also looking up the WSDL of the Proxy Service by requesting the URL http://localhost:8280/services/StockQuoteProxy?wsdl reveals the security policy attachments are not there and security is not engaged. When sending the message to the backend service, you could verify that the security headers were there as in the original message to ESB from client and that the response received does use WS-Security, and forwarded back to the client without any modification. You should note that this won't be a security hole because the message inside ESB is signed and encrypted and can only be forwarded to a secure service to be useful.

Example 5. Load Balancing with Proxy Services

Objective: Load Balancing with Proxy Service.

<!-- A proxy service with a loadbalace endpoint -->
<definitions xmlns="http://ws.apache.org/ns/synapse">
    <proxy name="LBProxy" transports="https http" startOnLoad="true">
        <target faultSequence="errorHandler">
            <inSequence>
                <send>
                    <endpoint>
                        <session type="simpleClientSession"/>
                        <loadbalance algorithm="org.apache.synapse.endpoints.algorithms.RoundRobin">
                            <endpoint>
                                <address uri="http://localhost:9001/services/LBService1">
                                    <enableAddressing/>
                                    <suspendDurationOnFailure>20</suspendDurationOnFailure>
                                </address>
                            </endpoint>
                            <endpoint>
                                <address uri="http://localhost:9002/services/LBService1">
                                    <enableAddressing/>
                                    <suspendDurationOnFailure>20</suspendDurationOnFailure>
                                </address>
                            </endpoint>
                            <endpoint>
                                <address uri="http://localhost:9003/services/LBService1">
                                    <enableAddressing/>
                                    <suspendDurationOnFailure>20</suspendDurationOnFailure>
                                </address>
                            </endpoint>
                        </loadbalance>
                    </endpoint>
                </send>
                <drop/>
            </inSequence>
            <outSequence>
                <send/>
            </outSequence>
        </target>
        <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_2.wsdl"/>
    </proxy>
    <sequence name="errorHandler">

        <makefault>
            <code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
            <reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
        </makefault>

        <header name="To" action="remove"/>
        <property name="RESPONSE" value="true"/>

        <send/>
    </sequence>
</definitions>

Prerequisites:

  • Start the Synapse configuration numbered 154 (i.e. wso2esb-samples -sn 154).
  • Start the Axis2 server and deploy the SecureStockQuoteService if not already done.

Runs the client with

ant loadbalancefailover -Dmode=session -Dtrpurl=http://localhost:8280/services/LBProxy

Example 6. Dual Channel Invocation on Both Client Side and Server Side of Synapse with Proxy Services

Objective: Demonstrate the dual channel invocation with Synapse proxy services.

<definitions xmlns="http://ws.apache.org/ns/synapse">
    <proxy name="StockQuoteProxy">
        <target>
            <endpoint>
                <address uri="http://localhost:9000/services/SimpleStockQuoteService">
                    <enableAddressing separateListener="true"/>
                </address>
            </endpoint>
            <outSequence>
                <send/>
            </outSequence>
        </target>
        <publishWSDL uri="file:repository/samples/resources/proxy/sample_proxy_1.wsdl"/>
    </proxy>
</definitions>

Prerequisites:

  • Start the Synapse configuration numbered 155 (i.e. wso2esb-samples -sn 155).
  • Start the Axis2 server and deploy the SimpleStockQuoteService if not already done.

This sample shows the action of the dual channel invocation within client and Synapse as well as within synapse and the actual server.

Note

If you want to enable dual channel invocation, you need to set the separateListener attribute to true of the enableAddressing element of the endpoint.

Execute the stock quote client by requesting for a stock quote on a dual channel from the Proxy Service as follows:

ant stockquote -Daddurl=http://localhost:8280/services/StockQuoteProxy -Dmode=dualquote

In the above example, the request received is forwarded to the sample service hosted on Axis2 and the endpoint specifies to enable addressing and do the invocation over a dual channel. If you observe this message flow by using a TCPmon, you could see that on the channel you send the request to synapse the response has been written as an HTTP 202 Accepted, where as the real response from synapse will come over a different channel which cannot be observed unless you use tcpdump to dump all the TCP level messages.

At the same time you can observe the behavior of the invocation between synapse and the actual Axis2 service, where you can see a 202 Accepted message being delivered to synapse as the response to the request. The actual response will be delivered to synapse over a different channel.