This documentation is for WSO2 Enterprise Service Bus version 4.9.0 . View documentation for the latest release.
Due to a known issue do not use JDK1.8.0_151 with WSO2 products. Use JDK 1.8.0_144 until JDK 1.8.0_162-ea is released.
Skip to end of metadata
Go to start of metadata

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 example, a server might require HTTP basic authentication over a proxy server before it will handle communication from the ESB.

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 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.allowDTDtrue / falsetrueIf 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

When creating a proxy, if this parameter is set to true, it prevents the proxy service deployment from failing when the wsdl is not available at server startup.

showAbsoluteSchemaURLtrue/falsetrueIf this parameter is set to true, the absolute path of the referred schemas of the WSDL is shown instead of the relative paths.
showProxySchemaURLtrue/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

JMS

Optional

transport.jms.
ConnectionFactory

The JMS connection factory definition (from axis2.xml) to be used to
listen for messages for this service.

 

Optional

transport.jms.
Destination

The JMS destination name (Defaults to the service name).

 

Optional

transport.jms.
DestinationType

The JMS destination type. Accept values "queue" or "topic."

 

Optional

transport.jms.
ReplyDestination

The destination where a reply will be posted.

 

Optional

transport.jms.
Wrapper

The wrapper element for the JMS message.

VFS

Required

transport.vfs.
FileURI

The primary File (or Directory) URI in the vfs* transport format, for this service.

 

Required

transport.vfs.
ContentType

The expected content type for files retrieved for this service. The VFS
transport uses this information to select the appropriate message builder.
Examples:

  • text/xml for plain XML or SOAP
  • text/plain; charset=ISO-8859-1 for text files
  • application/octet-stream for binary data

 

Optional

transport.vfs.
FileNamePattern

A file name regex pattern to match files against a directory specified
by the FileURI.

 

Optional

transport.
PollInterval

The poll interval (in seconds).

 

Optional

transport.vfs.
ActionAfterProcess

DELETE or MOVE.

 

Optional

transport.vfs.
MoveAfterProcess

The directory to move files after processing (i.e. all files process
successfully).

 

Optional

transport.vfs.
ActionAfterErrors

DELETE or MOVE.

 

Optional

transport.vfs.
MoveAfterErrors

The directory to move files after errors (i.e. some of the files
succeed but some fail).

 

Optional

transport.vfs.
ActionAfterFailure

DELETE or MOVE.

 

Optional

transport.vfs.
MoveAfterFailure

The directory to move after failure (i.e. all files fail).

 

Optional

transport.vfs.
ReplyFileURI

Reply file URI.

 

Optional

transport.vfs.
ReplyFileName

Reply file name (defaults to response XML).

 

Optional

transport.vfs.
MoveTimestampFormat

Timestamp prefix format for processed file name.
java.text.SimpleDateFormat compatible string. e.g. yyMMddHHmmss'-'.

  • No labels