Creating a Proxy Service

You can create a new proxy service or import an existing proxy service from an XML file, such as a Synapse configuration file using WSO2 EI tooling.

Prerequisites

You need to have WSO2 EI tooling installed to create a new proxy service or to import an existing proxy service via tooling. For instructions on installing WSO2 EI tooling, see Installing Enterprise Integrator Tooling.

Step 1:Creating an ESB project

First, create an ESB Solution Project in ESB tooling. We will use this project to store the proxy service file.

1. Open the Developer Studio Dashboard (click Developer Studio > Open Dashboard) and click ESB Solution Project.

2. Enter a name for the project and click Next.
3. Enter the Maven information about the project and click Finish.
4. The new project will be listed in the project explorer.

Step 2: Creating a new proxy service

Following sections describe how you can create a new proxy service.

1. In Eclipse, click the Developer Studio menu and then click Open Dashboard. This opens the Developer Studio Dashboard.

2. Click Proxy Service on the Developer Studio Dashboard. 
   

   Importing a proxy service?

   If you already have a proxy service created, you have the option of importing the XML configuration. Select Import Proxy Service and follow the instructions on the UI. To create a new proxy service from scratch, continue with the following steps.

3. Select Create a New Proxy Service and click Next.

4. Type a unique name for the proxy service, and select a proxy service template from the list shown below. These templates will automatically create the mediation logic relevant to each use case.

   
   The templates are explained below.

   Template Type	Description
   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. When you select this proxy service type, you just specify the target endpoint as described in the previous step. You need to specify the following parameters: Target Endpoint Endpoint URL
   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. Specify the target endpoint as described in the previous step, and then specify the location of the XSLT you want to use to transform requests, either by typing the path or by clicking Browse and navigating to the XSLT, which can be a file in the workspace or registry or can be a local entry. If you also want to transform the responses from the backend service, click Transform Responses. You need to specify the following parameters: Target Endpoint Endpoint URL Request XSLT Response XSLT
   Log Forward 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. Specify the log level for requests and responses, where Simple logs To, From, WSAction, SOAPAction, ReplyTo, MessageID, and any properties, and Full logs all attributes of the message plus the SOAP envelope information. You need to specify the following parameters: Target Endpoint Endpoint URL Request Log Level Response Log Level
   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. In the URI field, enter the URL and URN of the WSDL. The URL defines the host address of the network resource (can be omitted if resources are not network homed), and the URN defines the resource name in local namespaces. For example, if the URL is  ftp://ftp.dlink.ru  and the URN is /pub/ADSL/, you would enter  ftp://ftp.dlink.ru/pub/ADSL/  for the URI. To ensure that the URI is valid, click Test URI. You then enter the service name and port of the WSDL. Lastly, if you want to publish this WSDL, click Publish Same Service Contract. You need to specify the following parameters: WSDL URI WSDL Service WSDL Port Publish Same Service Contract
   Secure proxy	Uses WS-Security to process incoming requests and forward them to an unsecured backend service. Specify the target endpoint as described in the previous step, and then specify the key of the security policy or click Browse and select it from the registry. You need to specify the following parameters: Target Endpoint Endpoint URL Security Policy
   Custom proxy	A custom proxy service in which you customize all the sequences, endpoints, transports, and other QoS settings by adding them to the mediation workflow after the proxy service is created. 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.

5. Click Finish. The proxy service is created in the src/main/synapse-config/proxy-service folder under the ESB Config Project you specified, and the proxy service appears in the editor. Click its icon in the editor to view its properties.

Configuring transports

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.

Configuring pinned servers

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.

Configuring service parameters

The following service parameters are for specific transports:

Configuring security

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.

Step 3: Deploying the proxy service in the ESB server

Once you have added the security policy to your proxy service as explained in the previous topics, you need to create a Composite Application project with a CAR file. You can then deploy the CAR file in the ESB server:

1. Right-click the Project Explorer and click New > Project.
2. From the window that opens, click Composite Application Project.

3. Give a name to the Composite Application project and select the projects that you need to group into your C-App from the list of available projects. You need to select the ESB project, which contains the proxy service and security policy file respectively.

4. Next, deploy the CAR file in the ESB server.

Step 4: Enabling logs for services (Optional)

The advantage of having per-service log files is that it is very easy to analyze/monitor the basic logs relevant to a proxy service defined in the ESB. This file will contain the complete log with every log statement, including the service logs that you have configured to be logged into a different log file. In other words, the service log is an additional log file, which will contain a copy of the logs to that particular service.

Follow the instructions below to configure the logs of a particular service to be logged into a given log file.  The following steps explain how to enable logs for a sample proxy service deployed in the ESB profile of WSO2 EI.

1. See Sample 150 in Proxy Service Samples. It has a proxy service named StockQuoteProxy.
2. Configure log4j to log the service specific logs to a file called stock-quote-proxy-service.log in the logs directory of the EI installation directory.

   1. Open up the log4j.properties file found in the conf directory of the WSO2 EI installation directory using your favorite text editor and add the following section to the end of the file starting in a new line.

      log4j.category.SERVICE_LOGGER.StockQuoteProxy=DEBUG, SQ_PROXY_APPENDER
      log4j.additivity.SERVICE_LOGGER.StockQuoteProxy=false
      log4j.appender.SQ_PROXY_APPENDER=org.apache.log4j.DailyRollingFileAppender
      log4j.appender.SQ_PROXY_APPENDER.File=logs/stock-quote-proxy-service.log
      log4j.appender.SQ_PROXY_APPENDER.datePattern='.'yyyy-MM-dd-HH-mm
      log4j.appender.SQ_PROXY_APPENDER.layout=org.apache.log4j.PatternLayout
      log4j.appender.SQ_PROXY_APPENDER.layout.ConversionPattern=%d{ISO8601} \[%X{ip}-%X{host}\] \[%t\] %5p %c{1} %m%n

   2. Save the file.

3. Execute the sample client after starting the server with sample 150: and the sample axis2 server with the SimpleStockQuote service deployed on it as per stated in the sample documentation.

   $<EI_HOME>/bin/wso2ei-samples.sh \-sn 150

4. Inspect the logs directory of the ESB profile's installation directory to see the stock-quote-proxy-service.log file.

Further, to demonstrate the log file rotation; this particular logger was configured to rotate the file in each minute whenever there is a log going into the service log. Therefore, if you execute the sample client once again after 1 minute, you will be able to see the service log file rotation as well.