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.

Proxy Service vs. Proxy Server

Do not confuse a proxy service, which processes messages on their way to a service, with a proxy server, which acts as an intermediary for handling traffic to a server. For information on how to configure WSO2 Enterprise Integrator to route messages through a proxy server, see Working with Proxy Servers.

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.

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.

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.

Note

Axis2 does not allow custom URIs to be set for services on some transports such as HTTP/S. The proxy service could be exposed over all enabled Axis2 transports such as HTTP, HTTPS, JMS, Mail and File etc. or on a subset of these as specified with the optional transports attribute.

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.

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.

Note

The proxy service definition itself cannot be specified dynamically. That is, you cannot specify <proxy key="string"/>.

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:

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:

Parameter

Value

Default

Description

useOriginalwsdl

true / false

false

If this parameter is set to true, the original WSDL published via the publishWSDL parameter is used. This WSDL would not be replaced by a WSDL generated by the proxy service.

modifyUserWSDLPortAddress

true / false

true

(Effective only with useOriginalwsdl=true) If true (default) modify the port addresses to current host.

ApplicationXMLBuilder.allowDTD

true / false

true

If this parameter is set to true, it enables data type definition processing for the proxy service. Data type definition processing is disabled in the Axis2 engine due to security vulnerability. This parameter enables it for individual proxy services.

enablePublishWSDLSafeMode

true / false

true

If this parameter is set to true when deploying a proxy service, even though the WSDL is not available, you can prevent the proxy service being faulty. However, the deployed proxy service will be unaccessible since the WSDL is not available.

This is only applicable when you publish the WSDL (i.e., via the publishWSDL property) either as a URI or as an endpoint.

showAbsoluteSchemaURL

true/false

true

If this parameter is set to true, the absolute path of the referred schemas of the WSDL is shown instead of the relative paths.

showProxySchemaURL

true/false

If this parameter is set to true, the full proxy URL will be set as the prefix to the schema location of the imports in proxy WSDL.