Apache Synapse ESB - Quick Start Guide

This guide will demonstrate two sample applications covering the basic and the most common usage scenarios of Synapse; which is Message mediation and Service mediation (i.e. using Proxy services). You will be guided through a step by step approach to get a feeling about Synapse from the absolute beginning.

Pre-requisites

You should have following pre-requisites installed on your system to follow through this guide

• A Java 2 SE - JDK or JRE of version 1.5.x or higher (JDK 1.6.0_21 recommended)
• Apache Ant http://ant.apache.org

Message Mediation

In this example Synapse will be used to simply log all the messages passing through it. Although this simple scenario only performs logging, it demonstrates the basics of message mediation, where the logging functionality could be replaced with any combination of advanced mediations such as transformations, content based routing as well as bridging between different communication protocols etc. So, let's start with the basics.

Download

Our first task is to download Synapse. Open a web browser and access the following URL: http://synapse.apache.org/download.html . You will then see the list of available releases. Click on the latest version, and you will be directed to the Synapse release download page. Now download the 'Standard binary distribution' ZIP or tar.gz archive compatible with your operating system.

Installation

Synapse can be installed just by extracting the downloaded binary archive.. A directory named synapse with the release number will be created in the selected parent directory, containing all the files required for Synapse. We will refer to this directory as <synapse-home> from now on.

Running the Sample

Synapse ships with a set of sample clients and services to demonstrate some of its core capabilities. Hence, you will need to run three programs to get an idea of message mediation. The destination server that hosts the ultimate service to be invoked to service the client, the client itself, and Synapse, which acts as the intermediary to bridge between the client and the server.

Starting the Sample Axis2 Server

In this case we are using a standalone Axis2 web services engine as the server. You don't have to get it now, it is already bundled with your Synapse distribution. But we have to deploy a sample service for which client can send requests. Go to <synapse-home>/samples/axis2Server/src/SimpleStockQuoteService directory. Run "ant" to build and deploy this service to the sample Axis2 server.

Now go to <synapse-home>/samples/axis2Server directory and start the server using the following command. This will start Axis2 server on port 9000 (http).

You will see the following messages on the console.

Starting Synapse

Now it's time to start Synapse. In this scenario we are starting Synapse using the sample configuration found in synapse_sample_0.xml (i.e. in repository/conf/sample) and listed below. It is configured to log and pass through, all the messages.

<definitions xmlns="http://ws.apache.org/ns/synapse">
    <sequence name="main">
        <log level="full"/>
        <send/>
    </sequence>
</definitions>

Go to <synapse-home>/bin directory and type the command given below. Synapse will be started on port 8280 (http) and 8243 (https - under JDK 1.5)

Following messages will be displayed on the console to indicate the successfull startup of Synapse.

Run the Client

Now the final step, running the client. Go to <synapse-home>/samples/axis2Client directory and type the following command

You will see the following output on the console

This sends a request for a stock quote for the symbol IBM and sets the transport URL to Synapse (http://localhost:8280) and the WS-Addressing EPR set that to the actual server (http://localhost:9000/services/SimpleStockQuoteService). The actual wire level http message sent by the client is as follows, and is sent to port 8280 to the Synapse instance on localhost.

Now take a look at the console running Synapse. You will see that all the details of the mediation are logged along with all the SOAP messages passed through Synapse. If you execute Synapse in debug mode by editing the lib/log4j.properties "log4j.category.org.apache.synapse" as "DEBUG" instead of INFO, you will see more information as follows after a restart and replay of the above scenario again.

And with that you have successfully completed the first part of this guide. Now let's look at the next scenario, proxy services.

Proxy Services

As the name implies, a proxy service acts as a service hosted in Synapse, and typically fronts an existing service endpoint. A proxy service can be created and exposed on a different transport, schema, WSDL, or QoS (such as WS-Security, WS-Reliable Messaging) aspect than the real service and could mediate the messages before being delivered to the actual endpoint, and the responses before they reach the client.

Clients can send requests for proxy services directly to Synapse, as the client sees as if they are hosted on it, and for example can perform ?wsdl and view the WSDL of the virtual proxy service. But in the Synapse configuration, such requests can be handled in anyway you like. Most obvious thing would be to do some processing to the message and send it to the actual service, probably running on a different computer. But it is not necessary to always send the message to the actual service. You may list any combination of tasks to be performed on the messages received for the proxy service and terminate the flow or send some java back to the client even without sending it to an actual service. Let's explore a simple proxy services scenario step by step to get a better feeling. As you have downloaded and installed Synapse in the previous section, now you can start directly on the sample.

Running the Sample

As in the previous section, there should be three entities running to demonstrate proxy services, the server, client and Synapse. Let's start with the server.

Starting the Sample Axis2 Server

As you have built and deployed the SimpleStockQuote service in the previous section, you can simply start the server by switching to the <synapse-home>/samples/axis2Server directory and running the following command.

You can see the console messages as in the previous section.

Starting Synapse

We have to start Synapse with a configuration containing a proxy service definition. In this case we are using the synapse_sample_150.xml, so that you don't have to write the configuration your self.

<definitions xmlns="http://synapse.apache.org/ns/2010/04/configuraiton">
    <proxy name="StockQuoteProxy">
        <target>
            <endpoint>
                <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
            </endpoint>
            <outSequence>
                <send/>
            </outSequence>
        </target>
        <publishWSDL uri="file:repository/conf/sample/resources/proxy/sample_proxy_1.wsdl"/>
    </proxy>
</definitions>

The above configuration will expose a proxy service named StockQuoteProxy and specifies an endpoint (http://localhost:9000/services/SimpleStockQuoteService) as the target for the proxy service. Therefore, messages coming to the proxy service will be directed to the address http://localhost:9000/services/SimpleStockQuoteService specified in the endpoint. There is also an out sequence for the proxy service, which is applicable for response messages. In the out sequence, we just send the messages back to the client. The publishWSDL tag specifies an WSDL to be published for this proxy service. Let's start Synapse with this sample configuration by running the below command from the <synapse-home>/bin directory. It is possible to specify a sequence of mediation for incoming messages instead of a target endpoint, and many other possibilities and options are available to configure proxy services. These are explained in the samples and configuration guides.

Synapse will display a set of messages as in the previous section describing the steps of starting procedure. Before running the client, it is time to observe another feature of proxy services. That is displaying the published WSDL. Just open a web browser and point it to the address http://localhost:8280/services/StockQuoteProxy?wsdl. You will see the sample_proxy_1.wsdl specified in the configuration but containing the correct EPR for the service over HTTP/S.

Run the Client

Now it is time to see it in action. Go to the <synapse-home>/samples/axis2Clients directory and type the following command:

The above command sends a stockquote request directly to the provided transport endpoint at: http://localhost:8280/services/StockQuoteProxy. You will see the response from the server displayed on the console as follows:

This quick guide illustrates the simple use case of proxy services. Please refer to samples #150 and above in the Samples guide, for in depth coverage of more advanced use cases.

Yes, you are done with a quick look at Synapse. Now it is time to go deeper and reveal the advanced features of Synapse. You can browse through the samples for your interested areas. If you have any issue regarding Synapse as a user, feel free ask it in the Synapse user mailing list (http://synapse.apache.org/mail-lists.html ).