Working with Proxy Services

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

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>

Transports

A proxy service is created and exposed on the specified transports through the underlying Axis2 engine. The proxy service can be a SOAP or REST/POX service over HTTP/S or SOAP, POX, Plain Text, or Binary/Legacy service for other transports such as JMS and VFS file systems. It exposes service EPRs as per the standard Axis2 conventions based on the service name.

Pinned servers

You can use the pinnedServers attribute to specify the list of Synapse servers where this proxy service should be deployed. If there is no pinned server list, the proxy service is started in all server instances. The pinnedServers attribute takes the Synapse server names separated by commas or spaces. The Synapse server name is specified in the system property SynapseServerName or through the axis2.xml parameter SynapseConfig.ServerName. If neither of these are set, the server hostname is used, or it defaults to localhost. You can give a name to a Synapse server instance by specifying the property -DSynapseServerName=<ServerName> when you execute the startup script integrator.bat or integrator.sh, or by editing wrapper.conf to do this where Synapse is started as a service.

Security

Any supplied WS-Policies apply as service-level policies, and any service parameters can be passed into the proxy services' AxisService instance using the parameter elements (for example, the JMS destination). If the proxy service should enable Security, the appropriate modules could be engaged, and specified service level policies will apply.

WSDL for proxy services

You can publish a WSDL for the proxy service using the <publishWSDL> element. The WSDL document can be loaded from the registry by specifying the key attribute or from any other location by specifying the uri attribute. Alternatively, you can provide the WSDL inline as a child element of <publishWSDL>. Artifacts (schemas or other WSDL documents) imported by the WSDL can be resolved from the registry by specifying appropriate <resource> elements:

<publishWSDL key="my.wsdl">
   <resource location="http://www.standards.org/standard.wsdl" key="standard.wsdl"/>
 </publishWSDL>

In this example, the WSDL is retrieved from the registry using the key my.wsdl. It imports another WSDL from http://www.standards.org/standard.wsdl , but instead of loading it from this location, Synapse retrieves the imported WSDL from the registry entry standard.wsdl.

Following are additional service parameters you can use:

The following service parameters are for specific transports: