Working with Proxy Services

A Proxy service is a way of triggering a mediation flow defined in the ESB of WSO2 Enterprise Integrator (WSO2 EI). Alternatively, you can use REST APIs, Inbound Endpoints, Scheduled Tasks or Topics and Events.

Overview of proxy services

A proxy service is a virtual service that receives messages and optionally processes them before forwarding them to a service at a given endpoint. This approach allows you to perform necessary transformations and introduce additional functionality without changing your existing service. For example, if you want to use WS-Security with an existing, unsecured service, you can create a secure proxy service with WS-Security enabled with a specified security policy. Additionally, if you want a service to handle messages that are in different formats, you can create a Transformer proxy service to transform requests and responses based on specified XSLT configurations. A proxy service can also switch transports, process the messages with mediation sequences and tasks and terminate the flow or send a message back to the client even without sending it to the actual service.

Each service could define the target for received messages as a named sequence or a direct endpoint (Target inSequence or endpoint ), and a target outSequence defines how responses should be handled.

To create a dynamic proxy, specify the properties of the proxy as dynamic entries by referring to them with the key attribute. For example, you could specify the inSequence or endpoint with a remote key instead of defining it in the local configuration. As the remote registry entry changes, the properties of the proxy are updated accordingly.

Elements of a proxy service

Shown below is a Synapse proxy service's XML configuration. For additional samples of manual proxy service configurations, see Proxy Service Samples.

<proxy name="string" [transports="(http |https |jms |.. )+|all"] [pinnedServers="(serverName )+"] [serviceGroup="string"]>
   <description>...</description>?
   <target [inSequence="name"] [outSequence="name"] [faultSequence="name"] [endpoint="name"]>
      <inSequence>...</inSequence>?
      <outSequence>...</outSequence>?
      <faultSequence>...</faultSequence>?
      <endpoint>...</endpoint>?
   </target>?
   <publishWSDL key="string" uri="string">
      ( <wsdl:definition>...</wsdl:definition> | <wsdl20:description>...</wsdl20:description> )?
      <resource location="..." key="..."/>*
   </publishWSDL>?
   <enableAddressing/>?
   <enableSec/>?
   <enableRM/>?
   <policy key="string" [type="(in | out)"]/>?       // optional service or message level policies such as (e.g. WS-Security and/or WS-RM policies)
   <parameter name="string">                 // optional service parameters such as (e.g. transport.jms.ConnectionFactory)
      string | xml
   </parameter>
 </proxy>

The elements used in the above configuration are explained below.

Target in-sequence/endpoint

The target of a proxy service can be defined by adding an endpoint artifact to the proxy service, or by defining the required mediation logic inside the in-sequence of the proxy service. Consider an example, where the proxy service should route messages to a back-end service named StockQuoteService. The URI to access this back-end service is http://localhost:9000/services/SimpleStockQuoteService.

• Shown below is an example of how an endpoint artifact is used to define this target.

  <?xml version="1.0" encoding="UTF-8"?>
  <proxy name="pass_through_proxy" startOnLoad="true" transports="https http" xmlns="http://ws.apache.org/ns/synapse">
      <target>
          <endpoint name="endpoint_urn_uuid_f112183f-1de3-4753-a066-3231474502f5">
              <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
          </endpoint>
          <inSequence/>
          <outSequence/>      
          <faultSequence/>
      </target>
  </proxy>

• Shown below is an example of how a mediation logic is defined in the in-sequence to define this endpoint. In this example, the Call mediator is used.

  <?xml version="1.0" encoding="UTF-8"?>
  <proxy name="custom" startOnLoad="true" transports="http https" xmlns="http://ws.apache.org/ns/synapse">
      <target>
          <inSequence>
              <call>
                  <endpoint>
                      <http method="get"/>
                  </endpoint>
              </call>
          </inSequence>
          <outSequence/>
          <faultSequence/>
      </target>
  </proxy>