Working with 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.

You can create the following types of proxy services:

• Pass Through Proxy - Forwards messages to the endpoint without performing any processing on them. This proxy service is useful as a catch-all, so that messages that do not meet the criteria to be handled by other proxy services are simply forwarded to the endpoint.
• Secure Proxy - Uses WS-Security to process incoming requests and forward them to an unsecured backend service.
• WSDL Based Proxy - A proxy service that is created from the remotely hosted WSDL of an existing web service. The endpoint information is extracted from the WSDL.
• Logging Proxy - Logs all the incoming requests and forwards them to a given endpoint. It can also log responses from the backend service before routing them to the client.
• Transformer Proxy - Transforms all the incoming requests using XSLT and then forwards them to a given endpoint. It can also transform responses from the backend service.
• Custom Proxy - A custom proxy service in which you customize the sequences, endpoints, transports, and other QoS settings.

The simplest way to create a proxy service is through the management console, as described in Adding a Proxy Service. You can then use the console to manage the proxy service (edit it, redeploy it, or disable its statistics or tracing) as described in Managing Proxy Services.

You can also configure proxy services manually in XML. Following is an example of manually configuring a Synapse proxy service. For additional samples of manual proxy service configurations, see Proxy Service Samples.

The <proxy> element defines the proxy service, as shown below.

<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>

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.

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 wso2server.bat or wso2server.sh, or by editing wrapper.conf to do this where Synapse is started as a service.

Each service could define the target for received messages as a named sequence or a direct endpoint. Target inSequence or endpoint is required for the proxy configuration, and a target outSequence defines how responses should be handled. 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.

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.

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: