| <?xml version="1.0" encoding="ISO-8859-1"?> |
| |
| <!DOCTYPE html |
| PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" > |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/> |
| <title> |
| Apache Synapse - Quick Start Guide |
| </title> |
| <meta name="generator" content="Amaya 9.54, see http://www.w3.org/Amaya/"/> |
| <style type="text/css" xml:space="preserve"> |
| .command { |
| border: 1px dashed #3c78b5; |
| text-align: left; |
| background-color: #f0f0f0; |
| padding: 3px; |
| font-size: 11px; |
| font-family: Courier; |
| margin: 10px; |
| line-height: 13px; |
| } |
| .consoleOutput { |
| border: 1px dashed #3c78b5; |
| font-size: 11px; |
| font-family: Courier; |
| margin: 10px; |
| line-height: 13px; |
| background-color: #f0f0f0; |
| border-bottom: 1px dashed #3c78b5; |
| padding: 3px; |
| border-style: solid; |
| } |
| .info { |
| border-style: solid; |
| border-width: 1px; |
| border-color: #090; |
| background-color: #dfd; |
| text-align:left; |
| margin-top: 5px; |
| margin-bottom: 5px; |
| } |
| li { |
| font-family: Verdana, arial, sans-serif; |
| font-size: 11px; |
| line-height: 16px; |
| color: #000000; |
| font-weight: normal; |
| } |
| p { |
| font-family: Verdana, arial, sans-serif; |
| font-size: 11px; |
| line-height: 16px; |
| color: #000000; |
| font-weight: normal; |
| } |
| pre { |
| padding: 0px; |
| margin-top: 5px; |
| margin-left: 15px; |
| margin-bottom: 5px; |
| margin-right: 5px; |
| text-align: left; |
| background-color: #f0f0f0; |
| padding: 3px; |
| border: 1px dashed #3c78b5; |
| font-size: 11px; |
| font-family: Courier; |
| margin: 10px; |
| line-height: 13px; |
| } |
| h1 { |
| font-size: 24px; |
| line-height: normal; |
| font-weight: bold; |
| background-color: #f0f0f0; |
| color: #003366; |
| border-bottom: 1px solid #3c78b5; |
| padding: 2px; |
| margin: 36px 0px 4px 0px; |
| } |
| h2 { |
| font-size: 18px; |
| line-height: normal; |
| font-weight: bold; |
| background-color: #f0f0f0; |
| border-bottom: 1px solid #3c78b5; |
| padding: 2px; |
| margin: 27px 0px 4px 0px; |
| } |
| h3 { |
| font-size: 14px; |
| line-height: normal; |
| font-weight: bold; |
| background-color: #f0f0f0; |
| padding: 2px; |
| margin: 21px 0px 4px 0px; |
| } |
| h4 { |
| font-size: 12px; |
| line-height: normal; |
| font-weight: bold; |
| background-color: #f0f0f0; |
| padding: 2px; |
| margin: 18px 0px 4px 0px; |
| }</style> |
| </head> |
| <body> |
| <h1> |
| Quick start guide |
| </h1> |
| <p> |
| 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. |
| </p> |
| <h3> |
| Pre-requisites |
| </h3> |
| <p> |
| You should have following pre-requisites installed on your system to |
| follow through this guide |
| </p> |
| <ul> |
| <li> |
| A Java 2 SE - JDK or JRE of version 1.4.2 or higher |
| </li> |
| <li> |
| Apache Ant http://ant.apache.org |
| </li> |
| </ul> |
| <p> |
| Note: To use the bundled https transport, you will need a Java 2 SE |
| runtime of version 1.5 or later. If you are using a J2SE below 1.5 and |
| does not require the https transport, you may comment out the following |
| section from your repository/conf/axis2.xml and |
| samples/axis2Server/repository/conf/axis2.xml configuration files. |
| </p> |
| <pre xml:space="preserve">... |
| <transportReceiver name="https"...<br/> ...<br/> </transportReceiver> |
| ... |
| <transportSender name="https"...<br/> ...<br/> </transportSender> |
| ....</pre> |
| <p/> |
| <h2> |
| Message Mediation |
| </h2> |
| <p> |
| 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. |
| </p> |
| <h3> |
| Download |
| </h3> |
| <p> |
| Our first task is to download Synapse. Open a web browser and access the |
| following URL: http://ws.apache.org/synapse/download.cgi. You will then |
| see the list of available releases. Click on the 1.0 version, and you will |
| be directed to the Synapse 1.0 release download page. Now download the |
| 'Standard binary distribution' ZIP or tar.gz archive compatible with your |
| operating system. |
| </p> |
| <h3> |
| Installation |
| </h3> |
| <p> |
| Synapse can be installed just by extracting the downloaded binary |
| archive.. A directory named synapse-1.0 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. |
| </p> |
| <h3> |
| Running the sample |
| </h3> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h4> |
| Starting the sample Axis2 server |
| </h4> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <pre xml:space="preserve">user@host:/opt/synapse/samples/axis2Server$ cd src/SimpleStockQuoteService/ |
| user@host:/opt/synapse/samples/axis2Server/src/SimpleStockQuoteService$ ant |
| Buildfile: build.xml |
| |
| clean: |
| [delete] Deleting directory /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp |
| |
| init: |
| [mkdir] Created dir: /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp |
| [mkdir] Created dir: /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/classes |
| |
| compile-all: |
| [javac] Compiling 9 source files to /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/classes |
| |
| build-service: |
| [mkdir] Created dir: /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote |
| [mkdir] Created dir: /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF |
| [copy] Copying 1 file to /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF |
| [copy] Copying 1 file to /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote/META-INF |
| [copy] Copying 9 files to /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/src/SimpleStockQuoteService/temp/SimpleStockQuote |
| [jar] Building jar: /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository/services/SimpleStockQuoteService.aar |
| |
| BUILD SUCCESSFUL |
| Total time: 1 second</pre> |
| <p> |
| 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). |
| </p> |
| <div class="command"> |
| <p> |
| Linux / Unix: . axis2server.sh |
| </p> |
| <p> |
| Windows: axis2server.bat |
| </p> |
| </div> |
| <p> |
| You will see the following messages on the console. |
| </p> |
| <pre xml:space="preserve">user@host:/opt/synapse/samples/axis2Server$ ./axis2server.sh |
| Using JAVA_HOME: /opt/jdk1.5_06 |
| Using AXIS2 Repository : /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository |
| Using AXIS2 Configuration : /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository/conf/axis2.xml |
| [SimpleAxisServer] Using the Axis2 Repository : /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository |
| [SimpleAxisServer] Using the Axis2 Configuration File : /home/asankha/java/synapse-1.0-RC1-SNAPSHOT/samples/axis2Server/repository/conf/axis2.xml |
| [main] INFO HttpCoreNIOSender - HTTPS Sender starting |
| [main] INFO HttpCoreNIOSender - HTTP Sender starting |
| [main] INFO HttpCoreNIOListener - HTTPS Listener starting on port : 9002 |
| [main] INFO HttpCoreNIOListener - HTTP Listener starting on port : 9000 </pre> |
| <p/> |
| <h4> |
| Starting Synapse |
| </h4> |
| <p> |
| 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. |
| </p> |
| <pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse"><br/> <log level="full"/> <br/> <send/> |
| </definitions> </pre> |
| <p/> |
| <p> |
| Go to <synapse-home>/bin directory and type the command given below. |
| Synapse will be started on port 8080 (http) and 8443 (https - under JDK |
| 1.5) |
| </p> |
| <div class="command"> |
| <p> |
| Linux / Unix: . synapse.sh -sample 0 |
| </p> |
| <p> |
| Windows: synapse.bat -sample 0 |
| </p> |
| </div> |
| <p/> |
| <p> |
| Following messages will be displayed on the console to indicate the |
| successfull startup of Synapse. |
| </p> |
| <pre xml:space="preserve">user@host:/opt/synapse/bin$ ./synapse.sh -sample 0 |
| Starting Synapse/Java ... |
| Using SYNAPSE_HOME: /opt/synapse |
| Using JAVA_HOME: /opt/jdk1.5_06 |
| Using SYNAPSE_XML: -Dsynapse.xml=/opt/synapse/repository/conf/sample/synapse_sample_0.xml |
| [SynapseServer] Using the Axis2 Repository /opt/synapse/repository |
| [main] INFO SynapseModule - Initializing the Synapse configuration ... |
| ... |
| [main] INFO SynapseConfigurationBuilder - Loaded Synapse configuration from : /opt/synapse/repository/conf/sample/synapse_sample_0.xml |
| [main] INFO SynapseModule - Deploying the Synapse service.. |
| [main] INFO SynapseModule - Deploying Proxy services... |
| [main] INFO SynapseModule - Synapse initialized successfully...! |
| [main] ERROR SandeshaModule - Could not load module policies. Using default values. |
| [main] INFO HttpCoreNIOSender - HTTPS Sender starting |
| [main] INFO HttpCoreNIOSender - HTTP Sender starting |
| [main] INFO HttpCoreNIOListener - HTTPS Listener starting on port : 8443 |
| [SynapseServer] Starting transport https on port 8443 |
| [main] INFO HttpCoreNIOListener - HTTP Listener starting on port : 8080 |
| [SynapseServer] Starting transport http on port 8080 |
| [SynapseServer] Ready</pre> |
| <p/> |
| <h4> |
| Run the client |
| </h4> |
| <p> |
| Now the final step, running the client. Go to <synapse-home>/samples/axis2Client |
| directory and type the following command |
| </p> |
| <pre xml:space="preserve">user@host:/opt/synapse/samples/axis2Client$ ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080 -Dmode=quote -Dsymbol=IBM |
| Buildfile: build.xml |
| |
| init: |
| |
| compile: |
| |
| stockquote: |
| [java] Standard :: Stock price = $175.56196739870038 |
| |
| BUILD SUCCESSFUL</pre> |
| <p/> |
| <p> |
| This sends a request for a stock quote for the symbol IBM and sets the |
| transport URL to Synapse (http://localhost:8080) and the WS-Addressing EPR |
| set that of the actual server |
| (http://localhost:9000/soap/SimpleStockQuoteService). The actual wire |
| level http message sent by the client is as follows, and is sent over port |
| 8080 to the Synapse instance on localhost. |
| </p> |
| <pre xml:space="preserve">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/soap/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/xsd"> |
| <m0:request> |
| <m0:symbol>IBM</m0:symbol> |
| </m0:request> |
| </m0:getQuote> |
| </soapenv:Body> |
| </soapenv:Envelope>0</pre> |
| <p/> |
| <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 - as Synapse is running on debug mode by default. |
| </p> |
| <pre xml:space="preserve">[I/O reactor worker thread 5] INFO PipeImpl - Using native OS Pipes for event-driven to stream IO bridging |
| [HttpServerWorker-1] DEBUG SynapseMessageReceiver - Synapse received a new message for message mediation... |
| [HttpServerWorker-1] DEBUG SynapseMessageReceiver - Received To: http://localhost:9000/soap/SimpleStockQuoteService |
| [HttpServerWorker-1] DEBUG SynapseMessageReceiver - SOAPAction: urn:getQuote |
| [HttpServerWorker-1] DEBUG SynapseMessageReceiver - WSA-Action: urn:getQuote |
| [HttpServerWorker-1] DEBUG SynapseMessageReceiver - Body : |
| <?xml version='1.0' encoding='utf-8'?><br/><soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><br/><soapenv:Header><br/><wsa:To>http://localhost:9000/soap/SimpleStockQuoteService</wsa:To><br/><wsa:MessageID>urn:uuid:32748ED82860C9DBDE1177504004875</wsa:MessageID><br/><wsa:Action>urn:getQuote</wsa:Action></soapenv:Header><br/><soapenv:Body><m0:getQuote xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol></m0:request><br/></m0:getQuote></soapenv:Body></soapenv:Envelope> |
| [HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <main> :: mediate() |
| [HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate() |
| [HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate() |
| [HttpServerWorker-1] INFO LogMediator - To : http://localhost:9000/soap/SimpleStockQuoteService, <br/>MessageID : urn:uuid:32748ED82860C9DBDE1177504004875, Action : urn:getQuote, Envelope: <br/><?xml version='1.0' encoding='utf-8'?><br/><soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><br/><soapenv:Header><br/><wsa:To>http://localhost:9000/soap/SimpleStockQuoteService</wsa:To><br/><wsa:MessageID>urn:uuid:32748ED82860C9DBDE1177504004875</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action><br/></soapenv:Header><soapenv:Body><m0:getQuote xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol><br/></m0:request></m0:getQuote></soapenv:Body></soapenv:Envelope> |
| [HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate() |
| [HttpServerWorker-1] DEBUG SendMediator - Sending message using implicit message properties.. |
| [HttpServerWorker-1] DEBUG SendMediator - Sending To: http://localhost:9000/soap/SimpleStockQuoteService |
| [HttpServerWorker-1] DEBUG SendMediator - SOAPAction: urn:getQuote |
| [HttpServerWorker-1] DEBUG SendMediator - Body : |
| <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing" <br/>xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Header><br/><wsa:To>http://localhost:9000/soap/SimpleStockQuoteService</wsa:To><br/><wsa:MessageID>urn:uuid:32748ED82860C9DBDE1177504004875</wsa:MessageID><wsa:Action>urn:getQuote</wsa:Action></soapenv:Header><br/><soapenv:Body><m0:getQuote xmlns:m0="http://services.samples/xsd"><m0:request><m0:symbol>IBM</m0:symbol></m0:request><br/></m0:getQuote></soapenv:Body></soapenv:Envelope> |
| [HttpServerWorker-1] DEBUG Axis2FlexibleMEPClient - sending [add = false] [sec = false] [rm = false] <br/>[ to Address: http://localhost:9000/soap/SimpleStockQuoteService] |
| [HttpClientWorker-1] DEBUG SynapseCallbackReceiver - Synapse received an asynchronous response message |
| [HttpClientWorker-1] DEBUG SynapseCallbackReceiver - Received To: null |
| [HttpClientWorker-1] DEBUG SynapseCallbackReceiver - SOAPAction: null |
| [HttpClientWorker-1] DEBUG SynapseCallbackReceiver - WSA-Action: null |
| [HttpClientWorker-1] DEBUG SynapseCallbackReceiver - Body : |
| <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><br/><soapenv:Body><soapenv:Envelope><soapenv:Body><ns:getQuoteResponse xmlns:ns="http://services.samples/xsd"><br/><ns:return><ns:change>3.9759712191629117</ns:change><ns:earnings>-9.463240695957264</ns:earnings><br/><ns:high>97.0893936590198</ns:high><ns:last>93.87052890651084</ns:last><br/><ns:lastTradeTimestamp>Wed Apr 25 18:26:46 LKT 2007</ns:lastTradeTimestamp><ns:low>96.4856592398509</ns:low><br/><ns:marketCap>5.572519121414568E7</ns:marketCap><ns:name>IBM Company</ns:name><ns:open>-92.43795414108462</ns:open><br/><ns:peRatio>-18.381880013551893</ns:peRatio><br/><ns:percentageChange>-4.5174961332793435</ns:percentageChange><ns:prevClose>-88.01271991962221</ns:prevClose><br/><ns:symbol>IBM</ns:symbol><ns:volume>15381</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body><br/></soapenv:Envelope></soapenv:Body></soapenv:Envelope> |
| [HttpClientWorker-1] DEBUG SequenceMediator - Sequence mediator <main> :: mediate() |
| [HttpClientWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate() |
| [HttpClientWorker-1] DEBUG LogMediator - Log mediator :: mediate() |
| [HttpClientWorker-1] INFO LogMediator - Envelope: <?xml version='1.0' encoding='utf-8'?><br/><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><soapenv:Envelope><soapenv:Body><br/><ns:getQuoteResponse xmlns:ns="http://services.samples/xsd"><ns:return><ns:change>3.9759712191629117</ns:change><br/><ns:earnings>-9.463240695957264</ns:earnings><ns:high>97.0893936590198</ns:high><ns:last>93.87052890651084</ns:last><br/><ns:lastTradeTimestamp>Wed Apr 25 18:26:46 LKT 2007</ns:lastTradeTimestamp><ns:low>96.4856592398509</ns:low><br/><ns:marketCap>5.572519121414568E7</ns:marketCap><ns:name>IBM Company</ns:name><ns:open>-92.43795414108462</ns:open><br/><ns:peRatio>-18.381880013551893</ns:peRatio><br/><ns:percentageChange>-4.5174961332793435</ns:percentageChange><ns:prevClose>-88.01271991962221</ns:prevClose><br/><ns:symbol>IBM</ns:symbol><ns:volume>15381</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body></soapenv:Envelope><br/></soapenv:Body></soapenv:Envelope> |
| [HttpClientWorker-1] DEBUG SendMediator - Send mediator :: mediate() |
| [HttpClientWorker-1] DEBUG SendMediator - Sending message using implicit message properties.. |
| [HttpClientWorker-1] DEBUG SendMediator - Sending To: null |
| [HttpClientWorker-1] DEBUG SendMediator - SOAPAction: null |
| [HttpClientWorker-1] DEBUG SendMediator - Body : |
| <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><br/><soapenv:Body><soapenv:Envelope><soapenv:Body><ns:getQuoteResponse xmlns:ns="http://services.samples/xsd"><br/><ns:return><ns:change>3.9759712191629117</ns:change><ns:earnings>-9.463240695957264</ns:earnings><br/><ns:high>97.0893936590198</ns:high><ns:last>93.87052890651084</ns:last><br/><ns:lastTradeTimestamp>Wed Apr 25 18:26:46 LKT 2007</ns:lastTradeTimestamp><ns:low>96.4856592398509</ns:low><br/><ns:marketCap>5.572519121414568E7</ns:marketCap><ns:name>IBM Company</ns:name><ns:open>-92.43795414108462</ns:open><br/><ns:peRatio>-18.381880013551893</ns:peRatio><br/><ns:percentageChange>-4.5174961332793435</ns:percentageChange><ns:prevClose>-88.01271991962221</ns:prevClose><br/><ns:symbol>IBM</ns:symbol><ns:volume>15381</ns:volume></ns:return></ns:getQuoteResponse></soapenv:Body><br/></soapenv:Envelope></soapenv:Body></soapenv:Envelope></pre> |
| <p/> |
| <p> |
| You have successfully completed the first part of this guide. Now let's |
| look at the next scenario, proxy services. |
| </p> |
| <p/> |
| <h2> |
| Proxy Services |
| </h2> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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 neccessary 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 messge 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. |
| </p> |
| <p/> |
| <h3> |
| Running the sample |
| </h3> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h4> |
| Starting the sample Axis2 server |
| </h4> |
| <p> |
| 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. |
| </p> |
| <div class="command"> |
| <p> |
| Linux / Unix: . axis2server.sh |
| </p> |
| <p> |
| Windows: axis2server.bat |
| </p> |
| </div> |
| <p> |
| You can see the console messages as in the previous section. |
| </p> |
| <h4> |
| Starting Synapse |
| </h4> |
| <p> |
| We have to start Synapse with a configuration containing a proxy service |
| definition. In this case we are using the synapse_sample_100.xml, so that |
| you don't have to write the configuration your self. |
| </p> |
| <pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse"> |
| <proxy name="StockQuoteProxy"> |
| <target> |
| <endpoint> |
| <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/> |
| </endpoint> |
| <outSequence> |
| <send/> |
| </outSequence> |
| </target> |
| <publishWSDL uri="file:repository/conf/sample/resources/proxy/sample_proxy_1.wsdl"/> |
| </proxy> |
| </definitions></pre> |
| <p/> |
| <p> |
| The above configuration will expose a proxy service named StockQuoteProxy |
| and specifies an endpoint |
| (http://localhost:9000/soap/SimpleStockQuoteService) as the target for the |
| proxy service. Therefore, messages coming to the proxy service will be |
| directed to the address http://localhost:9000/soap/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. |
| </p> |
| <p/> |
| <div class="command"> |
| <p> |
| Linux / Unix: . synapse.sh -sample 100 |
| </p> |
| <p> |
| Windows: synapse.bat -sample 100 |
| </p> |
| </div> |
| <p/> |
| <p> |
| 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 diplaying |
| the published WSDL. Just open a web browser and point it to the address |
| http://localhost:8080/soap/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. |
| </p> |
| <p/> |
| <h4> |
| Run the client |
| </h4> |
| <p> |
| Now it is time to see it in action. Go to the <synapse-home>/samples/axis2Clients |
| directory and type the following command: |
| </p> |
| <div class="command"> |
| ant stockquote -Dtrpurl=http://localhost:8080/soap/StockQuoteProxy |
| -Dmode=quote -Dsymbol=IBM |
| </div> |
| <p> |
| The above command sends a stockquote request directly to the provided |
| transport endpoint at: http://localhost:8080/soap/StockQuoteProxy. You |
| will see the response from the server displayed on the console as follows: |
| </p> |
| <div class="consoleOutput"> |
| Standard :: Stock price = $165.32687331383468 |
| </div> |
| <p/> |
| <p> |
| This quick guide illustrates the simple use case of proxy services. Please |
| refer to samples #100 and above in the Samples guide, for indepth coverage |
| of more advanced use cases. |
| </p> |
| <p/> |
| <p> |
| 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://ws.apache.org/synapse/mail-lists.html). |
| </p> |
| <p/> |
| <p/> |
| <p/> |
| </body> |
| </html> |
