| <?xml version="1.0" encoding="ISO-8859-1" ?> |
| <!-- |
| ~ Licensed to the Apache Software Foundation (ASF) under one |
| ~ or more contributor license agreements. See the NOTICE file |
| ~ distributed with this work for additional information |
| ~ regarding copyright ownership. The ASF licenses this file |
| ~ to you under the Apache License, Version 2.0 (the |
| ~ "License"); you may not use this file except in compliance |
| ~ with the License. You may obtain a copy of the License at |
| ~ |
| ~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~ |
| ~ Unless required by applicable law or agreed to in writing, |
| ~ software distributed under the License is distributed on an |
| ~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~ KIND, either express or implied. See the License for the |
| ~ specific language governing permissions and limitations |
| ~ under the License. |
| --> |
| |
| <document> |
| <properties> |
| <title>Apache Synapse - Quick Start Guide</title> |
| </properties> |
| <body> |
| <section name="Quick Start Guide"> |
| <p> |
| 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. |
| </p> |
| </section> |
| |
| <section name="Pre-requisites"> |
| <p> |
| You should have following pre-requisites installed on your system to |
| follow this tutorial. |
| </p> |
| <ul> |
| <li> |
| A Java runtime - JDK or JRE of version 1.6.x or higher |
| (1.6.x or 1.7.x is recommended. 1.8.x is not tested enough) |
| </li> |
| <li> |
| Apache Ant <a href="http://ant.apache.org">http://ant.apache.org</a> |
| </li> |
| </ul> |
| </section> |
| |
| <section name="Installing Synapse"> |
| <p> |
| Let's start by downloading Apache Synapse. Launch a web browser and navigate to |
| the <a href="../download.html">Synapse Downloads</a> page. Download the binary distribution |
| of the latest release. Binary distributions are available in standard zip |
| format and Unix tar ball format. |
| </p> |
| <p> |
| 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. |
| </p> |
| </section> |
| |
| <section name="Running the Axis2 Server"> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <div class="consoleOutput">user@domain:/opt/synapse-3.0.0/samples/axis2Server/src/SimpleStockQuoteService$ ant |
| Buildfile: build.xml |
| |
| clean: |
| |
| init: |
| [mkdir] Created dir: /opt/synapse-3.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp |
| [mkdir] Created dir: /opt/synapse-3.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/classes |
| [mkdir] Created dir: /opt/synapse-3.0.0/samples/axis2Server/repository/services |
| |
| compile-all: |
| [javac] Compiling 9 source files to /opt/synapse-3.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/classes |
| |
| build-service: |
| [mkdir] Created dir: /opt/synapse-3.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote |
| [mkdir] Created dir: /opt/synapse-3.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF |
| [copy] Copying 1 file to /opt/synapse-3.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF |
| [copy] Copying 9 files to /opt/synapse-3.0.0/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote |
| [jar] Building jar: /opt/synapse-3.0.0/samples/axis2Server/repository/services/SimpleStockQuoteService.aar |
| |
| BUILD SUCCESSFUL |
| Total time: 1 second</div> |
| <p> |
| Now go to {SYNAPSE_HOME}/samples/axis2Server directory and start the sample server |
| by executing the following command. |
| </p> |
| <div class="command"> |
| Linux / Unix: . axis2server.sh<br/> |
| Windows: axis2server.bat |
| </div> |
| <p> |
| 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. |
| </p> |
| </section> |
| |
| <section name="Message Mediation"> |
| <p> |
| 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: |
| </p> |
| <div class="xmlConf"><definitions xmlns="http://ws.apache.org/ns/synapse"> |
| <sequence name="main"> |
| <log level="full"/> |
| <send/> |
| </sequence> |
| </definitions></div> |
| <p> |
| To start the ESB with the above configuration go the {SYNAPSE_HOME}/bin directory |
| and execute the following command. |
| </p> |
| <div class="command"> |
| Linux / Unix: . synapse.sh -sample 0<br/> |
| Windows: synapse.bat -sample 0 |
| </div> |
| <p> |
| Following messages will be displayed on the console as Synapse boots up with the |
| above configuration. |
| </p> |
| <div class="consoleOutput">Starting Synapse/Java ... |
| Using SYNAPSE_HOME: /opt/synapse-3.0.0 |
| Using JAVA_HOME: /opt/jdk1.7.0_79 |
| Using SYNAPSE_XML: /opt/synapse-3.0.0/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.0 |
| 2016-12-28 10:38:00,476 [-] [main] INFO SynapseControllerFactory Using Axis2 repository : /opt/synapse-3.0.0/repository |
| 2016-12-28 10:38:00,476 [-] [main] INFO SynapseControllerFactory Using axis2.xml location : /opt/synapse-3.0.0/repository/conf/axis2.xml |
| 2016-12-28 10:38:00,476 [-] [main] INFO SynapseControllerFactory Using synapse.xml location : /opt/synapse-3.0.0/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.0/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</div> |
| <p> |
| Note that by default Synapse listens for HTTP requests on port 8280. |
| </p> |
| <subsection name="Executing the Sample Client"> |
| <p> |
| 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. |
| </p> |
| <div class="command">ant stockquote -Daddurl=http://localhost:9000/services/SimpleStockQuoteService -Dtrpurl=http://localhost:8280 -Dmode=quote -Dsymbol=IBM</div> |
| <p> |
| You should get the following output on the conosle. |
| </p> |
| <div class="consoleOutput">Buildfile: build.xml |
| |
| init: |
| [mkdir] Created dir: /opt/synapse-3.0.0/samples/axis2Client/target/classes |
| |
| compile: |
| [javac] Compiling 22 source files to /opt/synapse-3.0.0/samples/axis2Client/target/classes |
| [javac] Note: /opt/synapse-3.0.0/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.0/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</div> |
| <p> |
| 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. |
| </p> |
| <div class="consoleOutput">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</div> |
| <p> |
| 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. |
| </p> |
| <div class="consoleOutput"><![CDATA[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>]]></div> |
| <p> |
| 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. |
| </p> |
| </subsection> |
| </section> |
| <section name="Service Mediation (Proxy Services)"> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <div class="xmlConf"><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></div> |
| <p> |
| 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. |
| </p> |
| <div class="command"> |
| Linux / Unix: . synapse.sh -sample 150<br/> |
| Windows: synapse.bat -sample 150 |
| </div> |
| <p> |
| 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. |
| </p> |
| <subsection name="Executing the Sample Client"> |
| <p> |
| 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. |
| </p> |
| <div class="command">ant stockquote -Dtrpurl=http://localhost:8280/services/StockQuoteProxy -Dmode=quote -Dsymbol=IBM</div> |
| <p> |
| 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: |
| </p> |
| <div class="consoleOutput">Standard :: Stock price = $165.32687331383468</div> |
| </subsection> |
| <subsection name="More on Proxy Services"> |
| <p> |
| 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. |
| </p> |
| </subsection> |
| </section> |
| <section name="Conclusion"> |
| <p> |
| 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 |
| (<a href="http://synapse.apache.org/mail-lists.html">http://synapse.apache.org/mail-lists.html</a>). |
| </p> |
| </section> |
| </body> |
| </document> |
