This documentation is for WSO2 ESB version 4.5.1. View documentation for the latest release.

Proxy Services

A proxy service can define the transports over which the service is exposed, and point to the mediation sequences that should be used to process request and response messages through the Proxy Service. A Proxy Service maybe 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. 

The <proxy> element is used to define a Synapse Proxy Service.

<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, exposing service EPR's as per the standard Axis2 conventions - based on the service name.

Note

Currently Axis2 does not allow custom URI's 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 give a list of Synapse server names, where this Proxy Service should be deployed using pinnedServers attribute. It takes the server names separated by comma or space character. If there is no pinned server list, then Proxy Service will be started in all server instances. If a pinned server names list is given, it will only start in the given named Synapse server instances. The Synapse server name is picked up either from the system property SynapseServerName or through the axis2.xml parameter SynapseConfig.ServerName, failing which the hostname of the machine would be used or default to localhost. You can give a name to a Synapse server instance by specifying -DSynapseServerName=<ServerName> property when you execute the startup script, wso2server.bat or wso2server.sh. You can also edit the 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 would apply as service level policies, and any service parameters could be passed into the Proxy Services' AxisService instance using the parameter elements (for example, the JMS destination etc). If the Proxy Service should enable WS-Reliable Messaging or Security, the appropriate modules could be engaged, and specified service level policies will apply.

A Dynamic Proxy may be defined by specifying the properties of the proxy as dynamic entries by referring them with the key.

For example, one could specify the inSequence or endpoint with a remote key, without defining it in the local configuration.

Tip

As the remote registry entry changes, the properties of the proxy will dynamically be updated accordingly.

Note

Proxy Service definition itself can not be specified to be dynamic, <proxy key="string"/> is wrong.

A WSDL for the Proxy Service can be published 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, the WSDL can be provided 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 location http://www.standards.org/standard.wsdl. Instead of loading it from this location, Synapse will retrieve the imported WSDL from the registry entry standard.wsdl.

You can give the following as service parameters:

Parameter

Value

Default

Description

useOriginalwsdl

true / false

false

Use the given WSDL instead of generating the WSDL.

modifyUserWSDLPortAddress

true / false

true

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

Transport specific parameters that may be set as service parameters:

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

See also Adding a Proxy Service, Managing Services, Managing Service Groups, HTTP Basic Authentication over a Proxy Server, Proxy Service Specific Configuration.