Quick Start Guide

Welcome to Apache Synapse quick start guide. This tutorial demonstrates two sample applications covering the fundamental usage scenarios of Synapse, namely message mediation and service mediation. It starts from the absolute beginning and walks you through a series of steps while giving a firm grasp on the Synapse messaging model.

Pre-requisites

You should have following pre-requisites installed on your system to follow this tutorial.

Installing Synapse

Let's start by downloading Apache Synapse. Launch a web browser and navigate to the Synapse Downloads page. Download the binary distribution of the latest release. Binary distributions are available in standard zip format and Unix tar ball format.

Once downloaded you can install Synapse by simply extracting the archive to a suitable location on your local disk. When extracted, a directory named synapse with the corresponding version number will be created. This directory houses all the libraries, configuration files, scripts and other artifacts used by the Synapse runtime. From now on we will refer to this directory as {SYNAPSE_HOME}. So for an example {SYNAPSE_HOME}/bin refers to the subdirectory named 'bin' which is generally available in the Synapse installation.

Running the Axis2 Server

Samples described in this tutorial involve routing messages to a Web Service through the Synapse ESB. In real world applications, these Web Services could be hosted in a web server in your organization, or practically anywhere in the Internet. In this tutorial we will be using a sample Web Service that ships with Synapse and we will deploy it in the sample Axis2 server that comes bundled with Synapse.

To deploy the sample service in the Axis2 server, go to {SYNAPSE_HOME}/samples/axis2Server/src/SimpleStockQuoteService directory and run 'ant'. You will see an output similar to the following as the service is built and deployed to the sample Axis2 server.

user@domain:/opt/synapse-3.0.1/samples/axis2Server/src/SimpleStockQuoteService$ ant Buildfile: build.xml clean: init: [mkdir] Created dir: /opt/synapse-3.0.1/samples/axis2Server/src/SimpleStockQuoteService/temp [mkdir] Created dir: /opt/synapse-3.0.1/samples/axis2Server/src/SimpleStockQuoteService/temp/classes [mkdir] Created dir: /opt/synapse-3.0.1/samples/axis2Server/repository/services compile-all: [javac] Compiling 9 source files to /opt/synapse-3.0.1/samples/axis2Server/src/SimpleStockQuoteService/temp/classes build-service: [mkdir] Created dir: /opt/synapse-3.0.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote [mkdir] Created dir: /opt/synapse-3.0.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF [copy] Copying 1 file to /opt/synapse-3.0.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF [copy] Copying 9 files to /opt/synapse-3.0.1/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote [jar] Building jar: /opt/synapse-3.0.1/samples/axis2Server/repository/services/SimpleStockQuoteService.aar BUILD SUCCESSFUL Total time: 1 second

Now go to {SYNAPSE_HOME}/samples/axis2Server directory and start the sample server by executing the following command.

Linux / Unix: . axis2server.sh
Windows: axis2server.bat

This will start the Axis2 server on HTTP port 9000. You can see the WSDL of the sample service by launching your web browser and navigating to the URL http://localhost:9000/services/SimpleStockQuoteService?wsdl.

Message Mediation

Now we are all set to try our first scenario with Synapse. We will be starting Synapse using the sample configuration found in synapse_sample_0.xml file which resides in {SYNAPSE_HOME}/repository/conf/sample directory. This configuration enables Synapse to log all the messages passing through the service bus:

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

To start the ESB with the above configuration go the {SYNAPSE_HOME}/bin directory and execute the following command.

Linux / Unix: . synapse.sh -sample 0
Windows: synapse.bat -sample 0

Following messages will be displayed on the console as Synapse boots up with the above configuration.

Starting Synapse/Java ... Using SYNAPSE_HOME: /opt/synapse-3.0.1 Using JAVA_HOME: /opt/jdk1.7.0_79 Using SYNAPSE_XML: /opt/synapse-3.0.1/repository/conf/sample/synapse_sample_0.xml 2016-12-28 10:38:00,456 [-] [main] INFO SynapseServer Starting Apache Synapse... 2016-12-28 10:38:00,476 [-] [main] INFO SynapseControllerFactory Using Synapse home : /opt/synapse-3.0.1 2016-12-28 10:38:00,476 [-] [main] INFO SynapseControllerFactory Using Axis2 repository : /opt/synapse-3.0.1/repository 2016-12-28 10:38:00,476 [-] [main] INFO SynapseControllerFactory Using axis2.xml location : /opt/synapse-3.0.1/repository/conf/axis2.xml 2016-12-28 10:38:00,476 [-] [main] INFO SynapseControllerFactory Using synapse.xml location : /opt/synapse-3.0.1/repository/conf/sample/synapse_sample_0.xml 2016-12-28 10:38:00,476 [-] [main] INFO SynapseControllerFactory Using server name : localhost 2016-12-28 10:38:00,493 [-] [main] INFO SynapseControllerFactory The timeout handler will run every : 15s 2016-12-28 10:38:00,566 [-] [main] INFO Axis2SynapseController Initializing Synapse at : Wed Dec 28 10:38:00 IST 2016 2016-12-28 10:38:01,140 [-] [main] INFO PassThroughHttpSSLSender Loading Identity Keystore from : lib/identity.jks 2016-12-28 10:38:01,174 [-] [main] INFO PassThroughHttpSSLSender Loading Trust Keystore from : lib/trust.jks 2016-12-28 10:38:01,242 [-] [main] INFO PassThroughHttpSSLSender Pass-through HTTPS sender started... 2016-12-28 10:38:01,243 [-] [main] INFO PassThroughHttpSender Pass-through HTTP sender started... 2016-12-28 10:38:01,249 [-] [main] INFO JMSSender JMS Sender started 2016-12-28 10:38:01,250 [-] [main] INFO JMSSender JMS Transport Sender initialized... 2016-12-28 10:38:01,251 [-] [main] INFO VFSTransportSender VFS Sender started 2016-12-28 10:38:01,428 [-] [main] INFO PassThroughHttpSSLListener Loading Identity Keystore from : lib/identity.jks 2016-12-28 10:38:01,429 [-] [main] INFO PassThroughHttpSSLListener Loading Trust Keystore from : lib/trust.jks 2016-12-28 10:38:01,443 [-] [main] INFO Axis2SynapseController Loading mediator extensions... 2016-12-28 10:38:01,451 [-] [main] INFO XMLConfigurationBuilder Generating the Synapse configuration model by parsing the XML configuration 2016-12-28 10:38:01,506 [-] [main] INFO SynapseConfigurationBuilder Loaded Synapse configuration from : /opt/synapse-3.0.1/repository/conf/sample/synapse_sample_0.xml 2016-12-28 10:38:01,542 [-] [main] INFO Axis2SynapseController Deploying the Synapse service... 2016-12-28 10:38:01,563 [-] [main] INFO Axis2SynapseController Deploying Proxy services... 2016-12-28 10:38:01,563 [-] [main] INFO Axis2SynapseController Deploying EventSources... 2016-12-28 10:38:01,584 [-] [main] INFO PassThroughHttpSSLListener Starting pass-through HTTPS listener... 2016-12-28 10:38:01,601 [-] [main] INFO PassThroughHttpSSLListener Pass-through HTTPS listener started on port: 8243 2016-12-28 10:38:01,601 [-] [main] INFO PassThroughHttpListener Starting pass-through HTTP listener... 2016-12-28 10:38:01,603 [-] [main] INFO PassThroughHttpListener Pass-through HTTP listener started on port: 8280 2016-12-28 10:38:01,603 [-] [main] INFO Axis2SynapseController Management using JMX available via: service:jmx:rmi:///jndi/rmi://localhost:1099/synapse 2016-12-28 10:38:01,606 [-] [main] INFO TimeoutHandler This engine will expire all callbacks after : 180 seconds, irrespective of the timeout action, after the specified or optional timeout 2016-12-28 10:38:01,607 [-] [main] INFO ServerManager Server ready for processing... 2016-12-28 10:38:01,608 [-] [main] INFO SynapseServer Apache Synapse started successfully

Note that by default Synapse listens for HTTP requests on port 8280.

Executing the Sample Client

Now we have a Web Service hosted in Axis2 and a Synapse ESB instance which is configured to log and route messages. All that is left is to send some requests to Synapse and see the magic happen. Synapse comes bundled with a sample Web Service client that can be used to send different kinds of requests. Go to {SYNAPSE_HOME}/samples/axis2Client directory and execute the following command to send a request to Synapse.

ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dmode=quote -Dsymbol=IBM

You should get the following output on the conosle.

Buildfile: build.xml init: [mkdir] Created dir: /opt/synapse-3.0.1/samples/axis2Client/target/classes compile: [javac] Compiling 22 source files to /opt/synapse-3.0.1/samples/axis2Client/target/classes [javac] Note: /opt/synapse-3.0.1/samples/axis2Client/src/samples/userguide/PWCallback.java uses or overrides a deprecated API. [javac] Note: Recompile with -Xlint:deprecation for details. [javac] Note: /opt/synapse-3.0.1/samples/axis2Client/src/samples/userguide/LoadbalanceFailoverClient.java uses unchecked or unsafe operations. [javac] Note: Recompile with -Xlint:unchecked for details. stockquote: [java] 2010-11-26 01:35:16,485 [-] [main] INFO MailTransportSender MAILTO Sender started [java] 2010-11-26 01:35:16,496 [-] [main] INFO JMSSender JMS Sender started [java] 2010-11-26 01:35:16,497 [-] [main] INFO JMSSender JMS Transport Sender initialized... [java] Standard :: Stock price = $99.14593325984416 BUILD SUCCESSFUL Total time: 5 seconds

This sends a stock quote request for the symbol 'IBM' with the transport URL set to http://localhost:8280 (Synapse) and the WS-Addressing EPR set to http://localhost:9000/services/SimpleStockQuoteService (Axis2). Synapse first logs the message and then forwards it to the URL given in the WS-Addressing headers. The actual message sent by the client is as follows.

POST / HTTP/1.1 Content-Type: text/xml; charset=UTF-8 SOAPAction: "urn:getQuote" User-Agent: Axis2 Host: 127.0.0.1 Transfer-Encoding: chunked 218 <?xml version='1.0' encoding='UTF-8'?> <soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header> <wsa:To>http://localhost:9000/services/SimpleStockQuoteService</wsa:To> <wsa:MessageID>urn:uuid:D538B21E30B32BB8291177589283717</wsa:MessageID> <wsa:Action>urn:getQuote</wsa:Action> </soapenv:Header> <soapenv:Body> <m0:getQuote xmlns:m0="http://services.samples"> <m0:request> <m0:symbol>IBM</m0:symbol> </m0:request> </m0:getQuote> </soapenv:Body> </soapenv:Envelope>0

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 file and setting "log4j.category.org.apache.synapse" as "DEBUG" instead of INFO, you will see even more information as follows after a restart and on replay of the above scenario.

2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG SynapseMessageReceiver Synapse received a new message for message mediation... 2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG SynapseMessageReceiver Received To: http://localhost:9000/services/SimpleStockQuoteService 2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG SynapseMessageReceiver SOAPAction: urn:getQuote 2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG SynapseMessageReceiver WSA-Action: urn:getQuote 2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG Axis2SynapseEnvironment Injecting MessageContext 2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG Axis2SynapseEnvironment Using Main Sequence for injected message 2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG SequenceMediator Start : Sequence <main> 2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG SequenceMediator Sequence <SequenceMediator> :: mediate() 2012-09-18 09:46:57,909 [-] [HttpServerWorker-2] DEBUG LogMediator Start : Log mediator 2012-09-18 09:46:57,910 [-] [HttpServerWorker-2] INFO LogMediator To: http://localhost:9000/services/SimpleStockQuoteService, WSAction: urn:getQuote, SOAPAction: urn:getQuote, ReplyTo: http://www.w3.org/2005/08/addressing/anonymous, MessageID: urn:uuid:754cc296-ff58-4875-a999-3a33ec94c8a1, Direction: request, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Header xmlns:wsa="http://www.w3.org/2005/08/addressing"><wsa:To>http://localhost:9000/services/SimpleStockQuoteService</wsa:To><wsa:MessageID>urn:uuid:754cc296-ff58-4875-a999-3a33ec94c8a1</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action></soapenv:Header><soapenv:Body><m0:getQuote xmlns:m0="http://services.samples"><m0:request><m0:symbol>IBM</m0:symbol></m0:request></m0:getQuote></soapenv:Body></soapenv:Envelope> 2012-09-18 09:46:57,910 [-] [HttpServerWorker-2] DEBUG LogMediator End : Log mediator 2012-09-18 09:46:57,910 [-] [HttpServerWorker-2] DEBUG SendMediator Start : Send mediator 2012-09-18 09:46:57,910 [-] [HttpServerWorker-2] DEBUG SendMediator Sending request message using implicit message properties.. Sending To: http://localhost:9000/services/SimpleStockQuoteService SOAPAction: urn:getQuote 2012-09-18 09:46:57,910 [-] [HttpServerWorker-2] DEBUG Axis2FlexibleMEPClient Sending [add = false] [sec = false] [rm = false] [to=Address: http://localhost:9000/services/SimpleStockQuoteService] 2012-09-18 09:46:57,910 [-] [HttpServerWorker-2] DEBUG Axis2FlexibleMEPClient Message [Original Request Message ID : urn:uuid:754cc296-ff58-4875-a999-3a33ec94c8a1] [New Cloned Request Message ID : urn:uuid:835c68a7-0645-496d-9acc-1d84a03ccb09] 2012-09-18 09:46:57,911 [-] [HttpServerWorker-2] DEBUG SynapseCallbackReceiver Callback added. Total callbacks waiting for : 1 2012-09-18 09:46:57,912 [-] [HttpServerWorker-2] DEBUG SendMediator End : Send mediator 2012-09-18 09:46:57,912 [-] [HttpServerWorker-2] DEBUG SequenceMediator End : Sequence <main> 2012-09-18 09:46:58,035 [-] [HttpClientWorker-2] DEBUG SynapseCallbackReceiver Callback removed for request message id : urn:uuid:835c68a7-0645-496d-9acc-1d84a03ccb09. Pending callbacks count : 0 2012-09-18 09:46:58,035 [-] [HttpClientWorker-2] DEBUG SynapseCallbackReceiver Synapse received an asynchronous response message 2012-09-18 09:46:58,035 [-] [HttpClientWorker-2] DEBUG SynapseCallbackReceiver Received To: null 2012-09-18 09:46:58,035 [-] [HttpClientWorker-2] DEBUG SynapseCallbackReceiver SOAPAction: 2012-09-18 09:46:58,035 [-] [HttpClientWorker-2] DEBUG SynapseCallbackReceiver WSA-Action: 2012-09-18 09:46:58,036 [-] [HttpClientWorker-2] DEBUG SynapseCallbackReceiver Body : <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><ns:getQuoteResponse xmlns:ns="http://services.samples"><ns:return xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns:GetQuoteResponse"><ns:change>4.158253518011668</ns:change><ns:earnings>13.000214652478554</ns:earnings><ns:high>176.07121446241788</ns:high><ns:last>171.44223855674258</ns:last><ns:lastTradeTimestamp>Tue Sep 18 09:46:57 CEST 2012</ns:lastTradeTimestamp><ns:low>-169.3791832231285</ns:low><ns:marketCap>3.844340450887613E7</ns:marketCap><ns:name>IBM Company</ns:name><ns:open>-167.9098655007073</ns:open><ns:peRatio>-17.815829214870217</ns:peRatio><ns:percentageChange>-2.4400099237243</ns:percentageChange><ns:prevClose>-170.41953303471544</ns:prevClose><ns:symbol>IBM</ns:symbol><ns:volume>16090</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body></soapenv:Envelope> 2012-09-18 09:46:58,036 [-] [HttpClientWorker-2] DEBUG Axis2SynapseEnvironment Injecting MessageContext 2012-09-18 09:46:58,036 [-] [HttpClientWorker-2] DEBUG Axis2SynapseEnvironment Using Main Sequence for injected message 2012-09-18 09:46:58,036 [-] [HttpClientWorker-2] DEBUG SequenceMediator Start : Sequence <main> 2012-09-18 09:46:58,036 [-] [HttpClientWorker-2] DEBUG SequenceMediator Sequence <SequenceMediator> :: mediate() 2012-09-18 09:46:58,036 [-] [HttpClientWorker-2] DEBUG LogMediator Start : Log mediator 2012-09-18 09:46:58,037 [-] [HttpClientWorker-2] INFO LogMediator To: http://www.w3.org/2005/08/addressing/anonymous, WSAction: , SOAPAction: , ReplyTo: http://www.w3.org/2005/08/addressing/anonymous, MessageID: urn:uuid:835c68a7-0645-496d-9acc-1d84a03ccb09, Direction: response, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><ns:getQuoteResponse xmlns:ns="http://services.samples"><ns:return xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns:GetQuoteResponse"><ns:change>4.158253518011668</ns:change><ns:earnings>13.000214652478554</ns:earnings><ns:high>176.07121446241788</ns:high><ns:last>171.44223855674258</ns:last><ns:lastTradeTimestamp>Tue Sep 18 09:46:57 CEST 2012</ns:lastTradeTimestamp><ns:low>-169.3791832231285</ns:low><ns:marketCap>3.844340450887613E7</ns:marketCap><ns:name>IBM Company</ns:name><ns:open>-167.9098655007073</ns:open><ns:peRatio>-17.815829214870217</ns:peRatio><ns:percentageChange>-2.4400099237243</ns:percentageChange><ns:prevClose>-170.41953303471544</ns:prevClose><ns:symbol>IBM</ns:symbol><ns:volume>16090</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body></soapenv:Envelope> 2012-09-18 09:46:58,037 [-] [HttpClientWorker-2] DEBUG LogMediator End : Log mediator 2012-09-18 09:46:58,037 [-] [HttpClientWorker-2] DEBUG SendMediator Start : Send mediator 2012-09-18 09:46:58,037 [-] [HttpClientWorker-2] DEBUG SendMediator Sending response message using implicit message properties.. Sending To: http://www.w3.org/2005/08/addressing/anonymous SOAPAction: 2012-09-18 09:46:58,038 [-] [HttpClientWorker-2] DEBUG SendMediator End : Send mediator 2012-09-18 09:46:58,038 [-] [HttpClientWorker-2] DEBUG SequenceMediator End : Sequence <main>

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

Service Mediation (Proxy Services)

As the name implies, a proxy service acts as an intermediary 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 setup (such as WS-Security, WS-Reliable Messaging) than the real service. Proxy services are capable of mediating requests before they are delivered to the actual endpoint. Similarly responses from the actual service can be mediated before they are sent back to the client.

Clients can send proxy service requests directly to Synapse. From the client's perspective, proxy services are simply Web Services hosted on Synapse. They can append the '?wsdl' suffix to the proxy service endpoints to get the WSDLs of these virtual services. But in the Synapse configuration, service requests can be handled in anyway you like. Most obvious thing would be to do some processing on the message and send it to the actual service, which could be running on a different host. But it is not necessary to always send the messages to an actual service. You may list any combination of tasks to be performed on the messages received by the proxy service and terminate the flow or send some response back to the client even without sending it to any 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 just run the scenario straightaway. This scenario also requires the same stock quote service we used in the previous example. So have it deployed in Axis2 and make sure Axis2 server is up and running.

We are going to start Synapse with a configuration which contains a proxy service. The configuration in synapse_sample_150.xml file in repository/conf/sample directory matches well with the scope of this tutorial.

<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 exposes 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 will be executed 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.

Linux / Unix: . synapse.sh -sample 150
Windows: synapse.bat -sample 150

Synapse will display a set of messages as it boots up just like in the previous section describing the start-up 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 URL http://localhost:8280/services/StockQuoteProxy?wsdl. You will see the sample_proxy_1.wsdl specified in the configuration but containing the correct EPRs for the service over HTTP/S.

Executing the Sample Client

Now we can invoke the proxy service by sending a request from our sample Axis2 client. Go to the {SYNAPSE_HOME}/samples/axis2Client directory and run the following command.

ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dmode=quote -Dsymbol=IBM

The above command sends a stock quote request directly to the provided transport endpoint at http://localhost:8280/services/StockQuoteProxy. The proxy service will forward the message to the Axis2 server and route the response from Axis2 back to the client. You will see the response from the server displayed on the console as follows:

Standard :: Stock price = $165.32687331383468

More on Proxy Services

Proxy services are among the most powerful functional components of Apache Synapse. They can be used to perform transport switching, message format switching and lot more. This quick start tutorial only covers the simple usecases of proxy services. Please refer samples #150 and above in the Synapse samples catalog, for in depth coverage on more advanced use cases.

Conclusion

This brings the Synapse quick start guide to an end. Now it is time to go deeper and discover the advanced features of Synapse. You can browse through the array of samples for your interested areas. If you have any issue regarding Synapse as a user, feel free write to the Synapse user mailing list (http://synapse.apache.org/mail-lists.html).