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.
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 ESB 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.
- 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.
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 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.
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:
<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:
Parameter | Value | Default | Description |
---|---|---|---|
useOriginalwsdl | true / false | false | If this parameter is set to |
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 This is only applicable when you publish the WSDL (i.e., via the |
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. |
The following service parameters are for specific transports:
Transport | Require | Parameter | Description |
---|---|---|---|
Optional | transport.jms. | The JMS connection factory definition (from axis2.xml) to be used to | |
Optional | transport.jms. | The JMS destination name (Defaults to the service name). | |
Optional | transport.jms. | The JMS destination type. Accept values "queue" or "topic." | |
Optional | transport.jms. | The destination where a reply will be posted. | |
Optional | transport.jms. | The wrapper element for the JMS message. | |
Required | transport.vfs. | The primary File (or Directory) URI in the vfs* transport format, for this service. | |
Required | transport.vfs. | The expected content type for files retrieved for this service. The VFS
| |
Optional | transport.vfs. | A file name regex pattern to match files against a directory specified | |
Optional | transport. | The poll interval (in seconds). | |
Optional | transport.vfs. | DELETE or MOVE. | |
Optional | transport.vfs. | The directory to move files after processing (i.e. all files process | |
Optional | transport.vfs. | DELETE or MOVE. | |
Optional | transport.vfs. | The directory to move files after errors (i.e. some of the files | |
Optional | transport.vfs. | DELETE or MOVE. | |
Optional | transport.vfs. | The directory to move after failure (i.e. all files fail). | |
Optional | transport.vfs. | Reply file URI. | |
Optional | transport.vfs. | Reply file name (defaults to response XML). | |
Optional | transport.vfs. | Timestamp prefix format for processed file name. |