You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2011/12/28 10:23:11 UTC
svn commit: r1225148 [14/15] - in /synapse/branches/2.1/src/site: ./
xdoc/1_0/ xdoc/1_1/ xdoc/1_1_1/ xdoc/1_2/
Added: synapse/branches/2.1/src/site/xdoc/1_2/Synapse_Samples.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/1_2/Synapse_Samples.xml?rev=1225148&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/1_2/Synapse_Samples.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/1_2/Synapse_Samples.xml Wed Dec 28 09:23:09 2011
@@ -0,0 +1,5385 @@
+<?xml version="1.0"?>
+
+<document>
+ <properties>
+ <title>Apache Synapse - Samples Guide</title>
+ </properties>
+ <head>
+ <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>
+ <div style="margin-top:-40px; float:right; _margin-top:0px;">
+ <img alt="Synapse logo"
+ src="images/synapse-logo-web2.png" width="197"
+ height="82"/>
+ </div>
+ <div>
+ <h1>
+ Apache Synapse ESB - Running the Samples
+ </h1>
+ </div>
+ <p>
+ This guide will walk you through the built-in samples shipped with the product,
+ which will cover most of the basic functional sceanrios and capabilities of Apache Synapse
+ as an ESB. If you are unable to solve your problem by reading through and
+ running these samples, feel free to raise your problem on the
+ <a href="http://synapse.apache.org/mail-lists.html">mailing lists</a>.</p>
+ <h2>
+ <a name="TOC" id="TOC">Contents</a>
+ </h2>
+ <div class="section-content">
+ <ul>
+ <li>
+ <a href="Synapse_Samples_Setup.html#Overview">Overview</a>
+ </li>
+ <li>
+ <a href="#MediationSamples">Message mediation samples</a>
+ <ul>
+ <li>
+ <a href="#Sample0">Sample 0: Introduction to Synapse</a>
+ </li>
+ <li>
+ <a href="#Sample1">Sample 1: Simple content based routing (CBR)
+ of messages</a>
+ </li>
+ <li>
+ <a href="#Sample2">Sample 2: CBR with the Switch-case mediator,
+ using message properties</a>
+ </li>
+ <li>
+ <a href="#Sample3">Sample 3: Local Registry entry definitions,
+ reusable endpoints and sequences</a>
+ </li>
+ <li>
+ <a href="#Sample4">Sample 4: Introduction to error handling</a>
+ </li>
+ <li>
+ <a href="#Sample5">Sample 5: Creating SOAP fault messages and
+ changing the direction of a message</a>
+ </li>
+ <li>
+ <a href="#Sample6">Sample 6: Manipulating SOAP headers, and
+ filtering incoming and outgoing messages</a>
+ </li>
+ <li>
+ <a href="#Sample7">Sample 7: Introduction to local Registry
+ entries and using Schema validation</a>
+ </li>
+ <li>
+ <a href="#Sample8">Sample 8: Introduction to static and dynamic
+ registry resources, and using XSLT transformations</a>
+ </li>
+ <li>
+ <a href="#Sample9">Sample 9: Introduction to dynamic sequences
+ with the Registry</a>
+ </li>
+ <li>
+ <a href="#Sample10">Sample 10: Introduction to dynamic
+ endpoints with the Registry</a>
+ </li>
+ <li>
+ <a href="#Sample11">Sample 11: A full registry based
+ configuration, and sharing a configuration between multiple
+ instances</a>
+ </li>
+ <li>
+ <a href="#Sample12">Sample 12: One way messaging /
+ fireAndForget through Synapse</a>
+ </li>
+ <li>
+ <a href="#Sample13">Sample 13: Dual channel invocation through Synapse</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Endpoints">Advanced mediations with endpoints</a>
+ <ul>
+ <li>
+ <a href="#Sample50">Sample 50: POX to SOAP conversion</a>
+ </li>
+ <li>
+ <a href="#Sample51">Sample 51: MTOM and SwA optimizations and
+ request/response correlation</a>
+ </li>
+ <li>
+ <a href="#Sample52">Sample 52: Session less load balancing
+ between 3 endpoints</a>
+ </li>
+ <li>
+ <a href="#Sample53">Sample 53: Failover sending among 3
+ endpoints</a>
+ </li>
+ <li>
+ <a href="#Sample54">Sample 54: Session affinity load balancing
+ between 3 endpoints</a>
+ </li>
+ <li>
+ <a href="#Sample55">Sample 55: Session affinity load balancing
+ between fail over endpoints</a>
+ </li>
+ <li>
+ <a href="#Sample56">Sample 56: WSDL endpoint</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#MessageMediationQoS">Quality of Service addition or
+ deduction samples in message mediation</a>
+ <ul>
+ <li>
+ <a href="#Sample100">Sample 100: Using WS-Security for outgoing
+ messages</a>
+ </li>
+ <li>
+ <a href="#Sample101">Sample 101: Reliable message exchange
+ between Synapse and the back-end server using WS-ReliableMessaging</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#ProxyServices">Synapse Proxy service samples</a>
+ <ul>
+ <li>
+ <a href="#Sample150">Sample 150: Introduction to proxy services</a>
+ </li>
+ <li>
+ <a href="#Sample151">Sample 151: Custom sequences and endpoints
+ with proxy services</a>
+ </li>
+ <li>
+ <a href="#Sample152">Sample 152: Switching transports and
+ message format from SOAP to REST/POX</a>
+ </li>
+ <li>
+ <a href="#Sample153">Sample 153: Routing the messages arrived
+ to a proxy service without processing the security headers</a>
+ </li>
+ <li>
+ <a href="#Sample154">Sample 154: Load Balancing with Proxy
+ Service </a>
+ </li>
+ <li>
+ <a href="#Sample155">Sample 155: Dual channel invocation
+ on both client side and server side of Synapse with Proxy Services</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#ProxyServiceQoS">QoS addition and deduction for service
+ mediation (proxy) samples</a>
+ <ul>
+ <li>
+ <a href="#Sample200">Sample 200: Using WS-Security with policy
+ attachments for proxy services</a>
+ </li>
+ <li>
+ <a href="#Sample201">Sample 201: Reliable message exchange
+ between the client and proxy services using WS-ReliableMessaging</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Transport">Transport samples and switching transports</a>
+ <ul>
+ <li>
+ <a href="#Sample250">Sample 250: Introduction to switching
+ transports - JMS to http/s</a>
+ </li>
+ <li>
+ <a href="#Sample251">Sample 251: Switching from http/s to JMS</a>
+ </li>
+ <li>
+ <a href="#Sample252">Sample 252: Pure text/binary and POX
+ message support with JMS</a>
+ </li>
+ <li>
+ <a href="#Sample253">Sample 253: One way bridging from JMS to
+ http and replying with a 202 Accepted response</a>
+ </li>
+ <li>
+ <a href="#Sample254">Sample 254: Using the file system as
+ transport medium using VFS transport listener and sender</a>
+ </li>
+ <li>
+ <a href="#Sample255">Sample 255: Switching from ftp transport
+ listener to mail transport sender</a>
+ </li>
+ <li>
+ <a href="#Sample256">Sample 256: Proxy services with the mail
+ transport</a>
+ </li>
+ <li>
+ <a href="#Sample257">Sample 257: Proxy services with the FIX
+ transport</a>
+ </li>
+ <li>
+ <a href="#Sample258">Sample 258: Switching from HTTP to FIX
+ </a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Task">Introduction to Synapse tasks</a>
+ <ul>
+ <li>
+ <a href="#Sample300">Sample 300: Introduction to tasks with
+ simple trigger</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#AdvancedMediation">Advanced mediations with advanced
+ mediators</a>
+ <ul>
+ <li>
+ <a href="#ScriptMediator">Using scripts in mediation (Script
+ Mediator)</a>
+ <ul>
+ <li>
+ <a href="#Sample350">Sample 350: Introduction to the script
+ mediator using js scripts</a>
+ </li>
+ <li>
+ <a href="#Sample351">Sample 351: In-line script mediation
+ with JavaScript</a>
+ </li>
+ <li>
+ <a href="#Sample352">Sample 352: Accessing Synapse message
+ context API methods using scripting language</a>
+ </li>
+ <li>
+ <a href="#Sample353">Sample 353: Using Ruby scripts for
+ mediation</a>
+ </li>
+ <li>
+ <a href="#Sample354">Sample 354: Using In-lined Ruby
+ scripts for mediation</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#DBMediators">Database interactions in mediation
+ (DBLookup / DBReport)</a>
+ <ul>
+ <li>
+ <a href="#Sample360">Sample 360: Introduction to dblookp
+ mediator</a>
+ </li>
+ <li>
+ <a href="#Sample361">Sample 361: Introduction to dbreport
+ mediator</a>
+ </li>
+ <li>
+ <a href="#Sample362">Sample 362: Action of dbreport and
+ dblookup mediators together</a>
+ </li>
+ <li><a href="#Sample363">Sample 363: Reusable database connection pools</a></li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Throttle">Throtteling messages (Throttle Mediator)</a>
+ <ul>
+ <li>
+ <a href="#Sample370">Sample 370: Introduction to throttle
+ mediator and concurrency throttling</a>
+ </li>
+ <li>
+ <a href="#Sample371">Sample 371: Restricting requests based
+ on policies</a>
+ </li>
+ <li>
+ <a href="#Sample372">Sample 372: Use of both concurrency
+ throttling and request rate based throttling </a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Class">Extending the mediation in java (Class
+ Mediator)</a>
+ <ul>
+ <li>
+ <a href="#Sample380">Sample 380: Writing your own custom
+ mediation in Java</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#XQuery">Evaluating XQuery for mediation (XQuery
+ Mediator)</a>
+ <ul>
+ <li>
+ <a href="#Sample390">Sample 390: Introduction to the XQuery
+ mediator</a>
+ </li>
+ <li>
+ <a href="#Sample391">Sample 391: How to use the data from
+ an external XML document with in XQuery </a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Splitter">Splitting messages in to parts and process
+ in parallel (Iterate / Clone)</a>
+ <ul>
+ <li>
+ <a href="#Sample400">Sample 400: Message splitting and
+ aggregating the responses</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Cache">Caching the responses over the requests</a>
+ <ul>
+ <li>
+ <a href="#Sample420">Sample 420: Simple cache implemented
+ on Synapse for the actual service</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Callout">Synchronize web service invocation with
+ Callout mediator </a>
+ <ul>
+ <li>
+ <a href="#Sample430">Sample 430: Simple Callout Mediator
+ for synchronize web service invocation</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </div>
+ <h1>
+ <a name="MediationSamples" id="MediationSamples">Message Mediation
+ Samples</a>
+ </h1>
+ <h2>
+ <a name="Sample0" id="Sample0">Sample 0: Introduction to Synapse</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <!-- log all attributes of messages passing through -->
+ <log level="full"/>
+
+ <!-- Send the messageto implicit destination -->
+ <send/>
+</definitions></pre>
+ <p>
+ <strong>Objective: Introduction to Synapse. Shows how a message could
+ be made to pass through Synapse </strong><strong>and logged
+ before it is delivered to its ultimate receiver.</strong>
+ </p>
+ <p>
+ The Stock quote client can operate in the following modes for this
+ example.
+ </p>
+ <ol>
+ <li>
+ Smart Client mode
+ </li>
+ <pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ </pre>
+ <li>
+ Using Synapse as a HTTP Proxy
+ </li>
+ <pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dprxurl=http://localhost:8280/</pre>
+ <li>
+ Gateway Mode / Dumb Client
+ </li>
+ <p>
+ See sample # 1
+ </p>
+ </ol>
+ <p>
+ <strong>Prerequisites:<br/> </strong>Start the Synapse
+ configuration numbered 0: e.g. synapse -sample 0<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already deployed
+ </p>
+ <p>
+ <strong>Execute the Smart Client </strong>
+ </p>
+ <p>
+ By tracing the execution of Synapse with the log output level set to
+ DEBUG, you will see the client request arriving at Synapse with a
+ WS-Addressing 'To' set to EPR
+ http://localhost:9000/soap/SimpleStockQuoteService. The Synapse engine
+ logs the message at the "full" log level (i.e. all the message headers and
+ the body) then sends the message to its implicit 'To' address which is
+ http://localhost:9000/soap/SimpleStockQuoteService. You will see a message
+ in the Axis2 server console confirming that the message got routed to the
+ sample server and the sample service hosted at the sample server
+ generating a stock quote for the requested symbol.
+ </p>
+<pre xml:space="preserve">Sat Nov 18 21:01:23 IST 2006 SimpleStockQuoteService :: Generating quote for : IBM</pre>
+ <p>
+ The response message generated by the service is again received by
+ Synapse, and flows through the same mediation rules, which logs the
+ response message and then sends it back. This time to the client. On the
+ client console you should see an output similar to the following based on
+ the message received by the client.
+ </p>
+<pre xml:space="preserve">Standard :: Stock price = $95.26454380258552</pre>
+ <p>
+ <strong>Execute the Proxy Client </strong>
+ </p>
+ <p>
+ You will see the exact same behaviour as per the previous example when you
+ run this scenario. However this time the difference is at the client, as
+ it sends the message to the WS-Addressing 'To' address
+ http://localhost:9000/soap/SimpleStockQuoteService, but the transport
+ specifies Synapse as the HTTP proxy.
+ </p>
+ <h2>
+ <a name="Sample1" id="Sample1">Sample 1: Simple content based routing
+ (CBR) of messages</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <!-- filtering of messages with XPath and regex matches -->
+ <filter source="get-property('To')" regex=".*/StockQuote.*">
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/>
+ </endpoint>
+ </send>
+ <drop/>
+ </filter>
+ <send/>
+</definitions> </pre>
+ <p>
+ <strong>Objective: Introduction to simple content based routing. Shows
+ how a message could be made to pass through Synapse using the Dumb Client
+ mode, where Synapse acts as a gateway to accept all messages and then
+ perform mediation and routing based on message properties or content.</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 1: i.e. synapse -sample 1<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already deployed<br/>
+ </p>
+ <p>
+ Execute the Dumb Client as:
+ </p>
+<pre xml:space="preserve">ant stockquote -Dtrpurl=http://localhost:8280/soap/StockQuote<br/></pre>
+ <p>
+ This time you will see Synapse receiving a message for which Synapse was
+ set as the ultimate receiver of the message. Based on the 'To' EPR of
+ http://localhost:8280/soap/StockQuote, Synapse performs a match to the
+ path '/StockQuote' and as the request matches the XPath expression of the
+ filter mediator, the filter mediator's child mediators execute. This sends
+ the message to a different endpoint as specified by the endpoint
+ definition. The 'drop' mediator terminates further processing of the
+ current message in a configuration. During response processing, the filter
+ condition fails, and thus the implicit 'send' mediator forwards the
+ response back to the client.
+ </p>
+ <h2>
+ <a name="Sample2" id="Sample2">Sample 2: CBR with the Switch-case
+ mediator, using message properties</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <switch source="//m0:getQuote/m0:request/m0:symbol" xmlns:m0="http://services.samples/xsd">
+ <case regex="IBM">
+ <!-- the property mediator sets a local property on the *current* message -->
+ <property name="symbol" value="Great stock - IBM"/>
+ </case>
+ <case regex="MSFT">
+ <property name="symbol" value="Are you sure? - MSFT"/>
+ </case>
+ <default>
+ <!-- it is possible to assign the result of an XPath expression as well -->
+ <property name="symbol"
+ expression="fn:concat('Normal Stock - ', //m0:getQuote/m0:request/m0:symbol)"
+ xmlns:m0="http://services.samples/xsd"/>
+ </default>
+ </switch>
+
+ <log level="custom">
+ <!-- the get-property() XPath extension function allows the lookup of local message properties
+ as well as properties from the Axis2 or Transport contexts (i.e. transport headers) -->
+ <property name="symbol" expression="get-property('symbol')"/>
+ <!-- the get-property() function supports the implicit message headers To/From/Action/FaultTo/ReplyTo -->
+ <property name="epr" expression="get-property('To')"/>
+ </log>
+
+ <!-- Send the messages where they are destined to (i.e. the 'To' EPR of the message) -->
+ <send/>
+</definitions></pre>
+ <p>
+ <strong>Objective: Introduce switch-case mediator and writing and
+ reading of local properties set on a message instance</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 2: i.e. synapse -sample 2<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done.
+ </p>
+ <p>
+ Execute the 'ant stockquote ..' request again in the smart client mode,
+ specifying 'IBM', 'MSFT' and 'SUN' as the stock symbols. When the symbol
+ IBM is requested, viewing the mediation logs you will see that the case
+ statements' first case for 'IBM' is executed and a local property named
+ 'symbol' was set to 'Great stock - IBM'. Subsequently this local property
+ value is looked up by the log mediator and logged using the
+ 'get-property()' XPath extension function.
+ </p>
+ <pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=IBM</pre>
+ <pre xml:space="preserve"> INFO LogMediator - symbol = Great stock - IBM, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService </pre>
+ <pre>ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT</pre>
+ <pre xml:space="preserve"> INFO LogMediator - symbol = Are you sure? - MSFT, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService</pre>
+ <h2>
+ <a name="Sample3" id="Sample3">Sample 3: Local Registry entry
+ definitions, reusable endpoints and sequences</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <!-- define a string resource entry to the local registry -->
+ <localEntry key="version">0.1</localEntry>
+ <!-- define a reuseable endpoint definition -->
+ <endpoint name="simple">
+ <address uri="http://localhost:9000/soap/SimpleStockQuoteService"/>
+ </endpoint>
+
+ <!-- define a reusable sequence -->
+ <sequence name="stockquote">
+ <!-- log the message using the custom log level. illustrates custom properties for log -->
+ <log level="custom">
+ <property name="Text" value="Sending quote request"/>
+ <property name="version" expression="get-property('version')"/>
+ <property name="direction" expression="get-property('direction')"/>
+ </log>
+ <!-- send message to real endpoint referenced by key "simple" endpoint definition -->
+ <send>
+ <endpoint key="simple"/>
+ </send>
+ </sequence>
+
+ <sequence name="main">
+ <in>
+ <property name="direction" value="incoming"/>
+ <sequence key="stockquote"/>
+ </in>
+ <out>
+ <send/>
+ </out>
+ </sequence>
+</definitions></pre>
+ <p>
+ <strong>Objective: Illustrates local registry entry definitions,
+ reusable endpoints and sequences</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 3: i.e. synapse -sample 3<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done
+ </p>
+ <p>
+ This example uses a sequence named as "main" that specifies the main
+ mediation rules to be executed. This is equivalent to directly specifying
+ the mediators of the main sequence within the <definitions> tags.
+ This is the recommended and also a better approach for non-trivial
+ configurations. Execute the 'ant stockquote ..' request again, and
+ following through the mediation logs you will now notice that the sequence
+ named "main" is executed. Then for the incoming message flow the <in>
+ mediator executes, and it calls the sequence named "stockquote".
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/</pre>
+<pre xml:space="preserve">DEBUG SequenceMediator - Sequence mediator <main> :: mediate()<br/>DEBUG InMediator - In mediator mediate()<br/>DEBUG SequenceMediator - Sequence mediator <stockquote> :: mediate()</pre>
+ <p>
+ As the "stockquote" sequence executes, the log mediator dumps a simple
+ text/string property, result of an XPath evaluation, that picks up the key
+ named "version", and a second result of an XPath evaluation that picks up
+ a local message property set previously by the <property> mediator.
+ The get-property() XPath extension function is able to read message
+ properties local to the current message, local or remote registry entries,
+ Axis2 message context properties as well as transport headers. The local
+ entry definition for "version" defines a simple text/string registry entry
+ for that which is visible to all messages that pass through Synapse.
+ </p>
+<pre xml:space="preserve">[HttpServerWorker-1] INFO LogMediator - Text = Sending quote request, version = 0.1, direction = incoming
+[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
+[HttpServerWorker-1] DEBUG AddressEndpoint - Sending To: http://localhost:9000/soap/SimpleStockQuoteService </pre>
+ <h2>
+ <a name="Sample4" id="Sample4">Sample 4: Introduction to error handling</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the default fault handling sequence used by Synapse - named 'fault' -->
+ <sequence name="fault">
+ <log level="custom">
+ <property name="text" value="An unexpected error occured"/>
+ <property name="message" expression="get-property('ERROR_MESSAGE')"/>
+ </log>
+ <drop/>
+ </sequence>
+
+ <sequence name="sunErrorHandler">
+ <log level="custom">
+ <property name="text" value="An unexpected error occured for stock SUN"/>
+ <property name="message" expression="get-property('ERROR_MESSAGE')"/>
+ </log>
+ <drop/>
+ </sequence>
+
+ <!-- default message handling sequence used by Synapse - named 'main' -->
+ <sequence name="main">
+ <in>
+ <switch source="//m0:getQuote/m0:request/m0:symbol" xmlns:m0="http://services.samples/xsd">
+ <case regex="IBM">
+ <send>
+ <endpoint><address uri="http://localhost:9000/soap/SimpleStockQuoteService"/></endpoint>
+ </send>
+ </case>
+ <case regex="MSFT">
+ <send>
+ <endpoint key="bogus"/>
+ </send>
+ </case>
+ <case regex="SUN">
+ <sequence key="sunSequence"/>
+ </case>
+ </switch>
+ <drop/>
+ </in>
+
+ <out>
+ <send/>
+ </out>
+ </sequence>
+
+<sequence name="sunSequence" onError="sunErrorHandler">
+ <send>
+ <endpoint key="sunPort"/>
+ </send>
+</sequence>
+
+</definitions> </pre>
+ <p>
+ <strong>Objective: Introduction to error handling with the 'fault'
+ sequence</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 4: i.e. synapse -sample 4<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done
+ </p>
+ <p>
+ When the IBM stock quote is requested, the configuration routes it to the
+ defined in-line endpoint, which routes the message to the
+ SimpleStockQuoteService on the local Axis2 instance. Hence a valid
+ response message is shown at the client.
+ </p>
+ <p>
+ If you lookup a stock quote for 'MSFT', Synapse is instructed to route the
+ message to the endpoint defined as the 'bogus' endpoint, which does not
+ exist. Synapse executes the specified error handler sequence closest to
+ the point where the error was encountered. In this case, the currently
+ executing sequence is 'main' and it does not specify an 'onError'
+ attribute. Whenever Synapse cannot find an error handler, it looks for a
+ sequence named 'fault'. Thus the 'fault' sequence can be seen executing,
+ and writing the generic error message to the logs.
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT</pre>
+<pre xml:space="preserve">[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
+[HttpServerWorker-1] ERROR IndirectEndpoint - Reference to non-existent endpoint for key : bogus
+[HttpServerWorker-1] DEBUG MediatorFaultHandler - MediatorFaultHandler :: handleFault
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <fault> :: mediate()
+[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
+[HttpServerWorker-1] INFO LogMediator - text = An unexpected error occured, message = Reference to non-existent endpoint for key : bogus</pre>
+ <p>
+ When the 'SUN' quote is requested, a custom sequence 'sunSequence' is
+ invoked, and it specifies 'sunErrorHandler' as its error handler. Hence
+ when the send fails, you could see the proper error handler invocation and
+ the custom error message printed as follows.
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN</pre>
+<pre xml:space="preserve">[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <sunSequence> :: mediate()
+[HttpServerWorker-1] DEBUG SequenceMediator - Setting the onError handler for the sequence
+[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
+[HttpServerWorker-1] DEBUG SendMediator - Send mediator :: mediate()
+[HttpServerWorker-1] ERROR IndirectEndpoint - Reference to non-existent endpoint for key : sunPort
+[HttpServerWorker-1] DEBUG MediatorFaultHandler - MediatorFaultHandler :: handleFault
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <sunErrorHandler> :: mediate()
+[HttpServerWorker-1] DEBUG AbstractListMediator - Implicit Sequence <SequenceMediator> :: mediate()
+[HttpServerWorker-1] DEBUG LogMediator - Log mediator :: mediate()
+[HttpServerWorker-1] INFO LogMediator - text = An unexpected error occured for stock SUN, message = Reference to non-existent endpoint for key : sunPort</pre>
+ <h2>
+ <a name="Sample5" id="Sample5">Sample 5: Creating SOAP fault messages
+ and changing the direction of a message</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <sequence name="myFaultHandler">
+ <makefault>
+ <code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
+ <reason expression="get-property('ERROR_MESSAGE')"/>
+ </makefault>
+
+ <property name="RESPONSE" value="true"/>
+ <header name="To" expression="get-property('ReplyTo')"/>
+ <send/>
+ </sequence>
+
+ <sequence name="main" onError="myFaultHandler">
+ <in>
+ <switch source="//m0:getQuote/m0:request/m0:symbol"
+ xmlns:m0="http://services.samples/xsd">
+ <case regex="MSFT">
+ <send>
+ <endpoint><address uri="http://bogus:9000/soap/NonExistentStockQuoteService"/></endpoint>
+ </send>
+ </case>
+ <case regex="SUN">
+ <send>
+ <endpoint><address uri="http://localhost:9009/soap/NonExistentStockQuoteService"/></endpoint>
+ </send>
+ </case>
+ </switch>
+ <drop/>
+ </in>
+
+ <out>
+ <send/>
+ </out>
+ </sequence>
+
+</definitions></pre>
+ <p>
+ <strong>Objective: Makefault mediator and sending back error responses
+ </strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 5: i.e. synapse -sample 5<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done
+ </p>
+ <p>
+ When the MSFT stock quote is requested, an unknown host exception would be
+ generated. A connection refused exception would be generated for the SUN
+ stock request. This error message is captured and returned to the original
+ client as a SOAP fault in this example.
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=MSFT</pre>
+ <p>
+ returns,
+ </p>
+<pre xml:space="preserve"><soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><faultcode>soapenv:Client</faultcode>
+ <faultstring>java.net.UnknownHostException: bogus</faultstring><detail /></soapenv:Fault></pre>
+ <p>
+ And
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dsymbol=SUN</pre>
+ <p>
+ returns,
+ </p>
+<pre xml:space="preserve"><soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><faultcode>soapenv:Client</faultcode>
+ <faultstring>java.net.ConnectException: Connection refused</faultstring><detail /></soapenv:Fault></pre>
+ <h2>
+ <a name="Sample6" id="Sample6">Sample 6: Manipulating SOAP headers, and
+ filtering incoming and outgoing messages</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <in>
+ <header name="To" value="http://localhost:9000/soap/SimpleStockQuoteService"/>
+ </in>
+ <send/>
+</definitions></pre>
+ <p>
+ <strong>Objective: Introduction to header, in (out) mediators</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 6: i.e. synapse -sample 6<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done
+ </p>
+ <p>
+ In this example we use the stockquote client in the dumb client mode,
+ setting the 'To' EPR of the message to Synapse. Then the 'in' mediator
+ processes the incoming messages, and manipulates the 'To' header to refer
+ to the stock quote service on the sample Axis2 server. Thus it is now
+ possible to request for a stock quote as follows.
+ </p>
+<pre xml:space="preserve">ant stockquote -Dtrpurl=http://localhost:8280/</pre>
+ <h2>
+ <a name="Sample7" id="Sample7">Sample 7: Introduction to local Registry
+ entries and using Schema validation</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <localEntry key="validate_schema">
+ <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ xmlns="http://www.apache-synapse.org/test" elementFormDefault="qualified"
+ attributeFormDefault="unqualified"
+ targetNamespace="http://services.samples/xsd">
+ <xs:element name="getQuote">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="request">
+ <xs:complexType>
+ <xs:sequence>
+ <xs:element name="stocksymbol" type="xs:string"/>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:sequence>
+ </xs:complexType>
+ </xs:element>
+ </xs:schema>
+ </localEntry>
+
+ <in>
+ <validate>
+ <schema key="validate_schema"/>
+ <on-fail>
+ <!-- if the request does not validate againt schema throw a fault -->
+ <makefault>
+ <code value="tns:Receiver"
+ xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
+ <reason value="Invalid custom quote request"/>
+ </makefault>
+ <property name="RESPONSE" value="true"/>
+ <header name="To" expression="get-property('ReplyTo')"/>
+ </on-fail>
+ </validate>
+ </in>
+ <send/>
+</definitions> </pre>
+ <p>
+ <strong>Objective: Introduction to local (static) registry entries and
+ the validate mediator</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 7: i.e. synapse -sample 7<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done
+ </p>
+ <p>
+ This example shows how a static XML fragment could be made available to
+ the Synapse local registry. Resources defined in the local registry are
+ static (i.e. never changes over the lifetime of the configuration) and may
+ be specified as a source URL, in-line text or in-line xml. In this example
+ the schema is made available under the key 'validate_schema'.
+ </p>
+ <p>
+ The validate mediator by default operates on the first child element of
+ the SOAP body. You may specify an XPath expression using the 'source'
+ attribute to override this behaviour. The validate mediator now uses the
+ 'validate_schema' resource to validate the incoming message, and if the
+ message validation fails it invokes the 'on-fail' sequence of mediators.
+ </p>
+ <p>
+ If you send a stockquote request using 'ant stockquote ...' you will get a
+ fault back with the message 'Invalid custom quote request' as the schema
+ validation failed. This is because the schema used in the example expects
+ a slightly different message than what is created by the stock quote
+ client. (i.e. expects a 'stocksymbol' element instead of 'symbol' to
+ specify the stock symbol)
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/</pre>
+ <h2>
+ <a name="Sample8" id="Sample8">Sample 8: Introduction to static and
+ dynamic registry resources, and using XSLT transformations</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <!-- the SimpleURLRegistry allows access to a URL based registry (e.g. file:/// or http://) -->
+ <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <!-- the root property of the simple URL registry helps resolve a resource URL as root + key -->
+ <parameter name="root">file:./repository/conf/sample/resources/</parameter>
+ <!-- all resources loaded from the URL registry would be cached for this number of milli seconds -->
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <!-- define the request processing XSLT resource as a static URL source -->
+ <localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/>
+
+ <in>
+ <!-- transform the custom quote request into a standard quote requst expected by the service -->
+ <xslt key="xslt-key-req"/>
+ </in>
+ <out>
+ <!-- transform the standard response back into the custom format the client expects -->
+ <!-- the key is looked up in the remote registry and loaded as a 'dynamic' registry resource -->
+ <xslt key="transform/transform_back.xslt"/>
+ </out>
+ <send/>
+</definitions></pre>
+ <p>
+ <strong>Objective: Introduction to static and dynamic registry
+ resources and the XSLT mediator</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 8: i.e. synapse -sample 8<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done
+ </p>
+ <p>
+ This example uses the XSLT mediator to perform transformations, and the
+ xslt transformations are specified as registry resources. The first
+ resource 'xslt-key-req' is specified as a 'local' registry entry. Local
+ entries do not place the resource on the registry, but simply make it
+ available to the local configuration. If a local entry is defined with a
+ key that already exists in the remote registry, the local entry will get
+ higher preference and override the remote resource.
+ </p>
+ <p>
+ In this example you will notice the new 'registry' definition. Synapse
+ comes with a simple URL based registry implementation SimpleURLRegistry.
+ During initialization of the registry, the SimpleURLRegistry expects to
+ find a property named 'root', which specifies a prefix for the registry
+ keys used later. When the SimpleURLRegistry is used, this root is prefixed
+ to the entry keys to form the complete URL for the resource being looked
+ up. The registry caches a resource once requested, and caches it
+ internally for a specified duration. Once this period expires, it will
+ reload the meta information about the resource and reload its cached copy
+ if necessary, the next time the resource is requested.
+ </p>
+ <p>
+ Hence the second XSLT resource key 'transform/transform_back.xslt'
+ concatenated with the 'root' of the SimpleURLRegistry
+ 'file:repository/conf/sample/resources/' forms the complete URL of the
+ resource as
+ 'file:repository/conf/sample/resources/transform/transform_back.xslt' and
+ caches its value for a period of 15000 ms.
+ </p>
+ <p>
+ Execute the custom quote client as 'ant stockquote -Dmode=customquote ...'
+ and analyze the the Synapse debug log output
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=customquote</pre>
+ <p>
+ The incoming message is now transformed into a standard stock quote
+ request as expected by the SimpleStockQuoteService deployed on the local
+ Axis2 instance, by the XSLT mediator. The XSLT mediator uses Xalan-J to
+ perform the transformations. It is possible to configure the underlying
+ transformation engine using properties where necessary. The response from
+ the SimpleStockQuoteService is converted back into the custom format as
+ expected by the client during the out message processing.
+ </p>
+ <p>
+ During the response processing you could see the SimpleURLRegistry
+ fetching the resource as shown by the log message below
+ </p>
+<pre xml:space="preserve">[HttpClientWorker-1] DEBUG SimpleURLRegistry ==> Repository fetch of resource with key : transform/transform_back.xslt</pre>
+ <p>
+ If you run the client again immediately (i.e within 15 seconds of the
+ first request) you will not see the resource being reloaded by the
+ registry as the cached value would be still valid.
+ </p>
+ <p>
+ However if you leave the system idle for 15 seconds or more and then retry
+ the same request, you will now notice that the registry noticed the cached
+ resource has expired and will check the meta information about the
+ resource to check if the resource itself has changed and will require a
+ fresh fetch from the source URL. If the meta data / version number
+ indicates that a reload of the cached resource is not necessary (i.e.
+ unless the resource itself actually changed) the updated meta information
+ is used and the cache lease extended as appropriate.
+ </p>
+<pre xml:space="preserve">[HttpClientWorker-1] DEBUG AbstractRegistry - Cached object has expired for key : transform/transform_back.xslt
+[HttpClientWorker-1] DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : transform/transform_back.xslt
+[HttpClientWorker-1] DEBUG AbstractRegistry - Expired version number is same as current version in registry
+[HttpClientWorker-1] DEBUG AbstractRegistry - Renew cache lease for another 15s </pre>
+ <p>
+ Now edit the
+ repository/conf/sample/resources/transform/transform_back.xslt file and
+ add a blank line at the end. Now when you run the client again, and if the
+ cache is expired, the resource would be re-fetched from its URL by the
+ registry and this can be seen by the following debug log messages
+ </p>
+<pre xml:space="preserve">[HttpClientWorker-1] DEBUG AbstractRegistry - Cached object has expired for key : transform/transform_back.xslt
+[HttpClientWorker-1] DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : transform/transform_back.xslt
+[HttpClientWorker-1] INFO SimpleURLRegistry - ==> Repository fetch of resource with key : transform/transform_back.xslt </pre>
+ <p>
+ Thus the SimpleURLRegistry allows resource to be cached, and updates
+ detected so that the changes could be reloaded without restarting the
+ Synapse instance.
+ </p>
+ <h2>
+ <a name="Sample9" id="Sample9">Sample 9: Introduction to dynamic
+ sequences with the Registry</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <parameter name="root">file:./repository/conf/sample/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <sequence key="sequence/dynamic_seq_1.xml"/>
+</definitions> </pre>
+ <p>
+ <strong>Objective: Introduction to dynamic sequences with a registry</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 9: i.e. synapse -sample 9<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done
+ </p>
+ <p>
+ This example introduces the dynamic behaviour of Synapse through the use
+ of a registry. Synapse supports dynamic definitions for sequences and
+ endpoints, and as seen before, for resources. In this example we define a
+ Synapse configuration which references a sequence definition specified as
+ a registry key. The registry key resolves to the actual content of the
+ sequence which would be loaded dynamically by Synapse at runtime, and
+ cached appropriately as per its definition in the registry. Once the cache
+ expires, Synapse would re-check the meta information for the definition and
+ re-load the sequence definition if necessary and re-cache it again.
+ </p>
+ <p>
+ Once Synapse is started, execute the stock quote client as 'ant
+ stockquote..'. You will notice that that Synapse fetches the definition of
+ the sequence from the registry and executes its rules as follows:
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/</pre>
+<pre xml:space="preserve">[HttpServerWorker-1] DEBUG SimpleURLRegistry - ==> Repository fetch of resource with key : sequence/dynamic_seq_1.xml
+...
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <dynamic_sequence> :: mediate()
+...
+[HttpServerWorker-1] INFO LogMediator - message = *** Test Message 1 ***</pre>
+ <p>
+ Now if you execute the client immediately (i.e. within 15 seconds of the
+ last execution) you will notice that the sequence was not reloaded. If you
+ edit the sequence definition in
+ repository/conf/sample/resources/sequence/dynamic_seq_1.xml (i.e. edit the
+ log message to read as "*** Test Message 2 ***") and execute the client
+ again, you will notice that the new message is not yet visible (i.e. if
+ you execute this within 15 seconds of loading the resource for the first
+ time) However, after 15 seconds elapsed since the original caching of the
+ sequence, you will notice that the new sequence is loaded and executed by
+ Synapse from the following log messages.
+ </p>
+<pre xml:space="preserve">[HttpServerWorker-1] DEBUG SimpleURLRegistry - ==> Repository fetch of resource with key : sequence/dynamic_seq_1.xml
+...
+[HttpServerWorker-1] DEBUG SequenceMediator - Sequence mediator <dynamic_sequence> :: mediate()
+...
+[HttpServerWorker-1] INFO LogMediator - message = *** Test Message 2 ***</pre>
+ <p>
+ The cache timeout could be tuned appropriately by configuring the URL
+ registry to suit the environment and the needs.
+ </p>
+ <h2>
+ <a name="Sample10" id="Sample10">Sample 10: Introduction to dynamic
+ endpoints with the Registry</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <parameter name="root">file:repository/conf/sample/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+
+ <in>
+ <send>
+ <endpoint key="endpoint/dynamic_endpt_1.xml"/>
+ </send>
+ </in>
+ <out>
+ <send/>
+ </out>
+</definitions> </pre>
+ <p>
+ <strong>Objective: Introduction to dynamic endpoints with the Registry</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 10: i.e. synapse -sample 10<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done<br/>
+ Start a second Axis2 server on HTTP port 9001 and HTTPS port 9003 as
+ follows:
+ </p>
+<pre xml:space="preserve">./axis2server.sh -http 9001 -https 9003</pre>
+ <p>
+ This example introduces dynamic endpoints, where the definition of an
+ endpoint is stored in the registry. To follow this example execute the
+ stock quote client as 'ant stockquote..' and see that the message is
+ routed to the SimpleStockQuoteService on the default Axis2 instance on
+ HTTP port 9000. Repeat the above example immediately again, and notice
+ that the endpoint is cached and reused by Synapse - similarly to example #
+ 8.
+ </p>
+<pre xml:space="preserve">ant stockquote -Dtrpurl=http://localhost:8280/</pre>
+ <p>
+ Now edit the repository/conf/sample/resources/endpoint/dynamic_endpt_1.xml
+ definition and update the address to
+ "http://localhost:9001/soap/SimpleStockQuoteService". After the cached value
+ expires, the Registry loads the new definition of the endpoint, and then
+ the messages can be seen being routed to the second sample Axis2 server on
+ HTTP port 9001.
+ </p>
+ <h2>
+ <a name="Sample11" id="Sample11">Sample 11: A full registry based
+ configuration, and sharing a configuration between multiple instances</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <parameter name="root">file:./repository/conf/sample/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+ </registry>
+</definitions> </pre>
+ <p>
+ <strong>Objective: A full registry based configuration</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 11: i.e. synapse -sample 11<br/> Start the Axis2
+ server and deploy the SimpleStockQuoteService if not already done
+ </p>
+ <p>
+ This example shows a full registry based Synapse configuration. Thus it is
+ possible to start a remote configuration from multiple instances of
+ Synapse in a clustered environment easily. The Synapse configuration held
+ on a node hosting Synapse simply points to the registry and looks up the
+ actual configuration by requesting the key 'synapse.xml'.
+ </p>
+ <p>
+ (Note: Full registry based configuration is not dynamic atleast for the
+ moment. i.e. it is not reloading itself)
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/</pre>
+<pre xml:space="preserve">[HttpServerWorker-1] INFO LogMediator - message = This is a dynamic Synapse configuration</pre>
+ <p>
+ The actual synapse.xml loaded is:
+ </p>
+<pre xml:space="preserve"><!-- a registry based Synapse configuration -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <log level="custom">
+ <property name="message" value="This is a dynamic Synapse configuration $$$"/>
+ </log>
+ <send/>
+</definitions></pre>
+ <h2>
+ <a name="Sample12" id="Sample12">Sample 12: One way messaging /
+ fireAndForget through Synapse</a>
+ </h2>
+ <p>
+ <strong>Objective: Demonstrate one-way messaging / fireAndForget
+ through Synapse</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Axis2 server
+ and deploy the SimpleStockQuoteService (Refer steps above)<br/> Start
+ the Synapse configuration numbered 1: i.e. synapse -sample 1
+ </p>
+ <p>
+ This example invokes the one-way 'placeOrder' operation on the
+ SimpleStockQuoteService using the custom client which uses the Axis2
+ ServiceClient.fireAndForget() API. To test this, use 'ant
+ -Dmode=placeorder...' and you will notice the one-way message flowing
+ through Synapse into the sample Axis2 server instance, which reports the
+ acceptance of the order as follows:
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=placeorder</pre>
+<pre xml:space="preserve">SimpleStockQuoteService :: Accepted order for : 7482 stocks of IBM at $ 169.27205579038733</pre>
+ <p>
+ If you send your client request through TCPmon, you will notice that the
+ SimpleStockQuoteService replies to Synapse with a HTTP 202 reply, and that
+ Synapse in turns replies to the client with a HTTP 202 acknowledgment
+ </p>
+ <h2>
+ <a name="Sample13" id="Sample13">Sample 13: Dual channel invocation through Synapse</a>
+ </h2>
+ <p>
+ <strong>Objective: Demonstrate dual channel messaging
+ through Synapse</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Axis2 server
+ and deploy the SimpleStockQuoteService (Refer steps above)<br/> Start
+ the Synapse configuration numbered 0: i.e. synapse -sample 0
+ </p>
+ <p>
+ This example invokes the same 'getQuote' operation on the
+ SimpleStockQuoteService using the custom client which uses the Axis2
+ ServiceClient API with useSeparateListener set to true so that the response is
+ coming through a different channel than the one which is used to send the request
+ to a callback defined in the client.
+ To test this, use 'ant
+ -Dmode=dualquote...' and you will notice the dual channel invocation
+ through Synapse into the sample Axis2 server instance, which reports the response
+ back to the client over a different channel:
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8280/ -Dmode=dualquote</pre>
+<pre xml:space="preserve">Response received to the callback
+Standard dual channel :: Stock price = $57.16686934968289</pre>
+ <p>
+ If you send your client request through TCPmon, you will notice that
+ Synapse replies to the client with a HTTP 202 acknowledgment when you send the request and
+ the communication between Synapse and the server happens on a single channel and then you
+ get the response back from Synapse to the clients callback in a different channel (which
+ cannot be observed through TCPmon)
+ </p>
+ <p>
+ Also you could see the wsa:Reply-To header being something like
+ http://localhost:8200/axis2/soap/anonService2 which implies that the reply
+ is being on a different channel listening on the port 8200. Please note that it is
+ required to engage addressing when using the dual channel invocation because it
+ requires the wsa:Reply-To header.
+ </p>
+ <h1>
+ <a name="Endpoints" id="Endpoints">Advanced mediations with endpoints</a>
+ </h1>
+ <h2>
+ <a name="Sample50" id="Sample50">Sample 50: POX to SOAP conversion</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <!-- filtering of messages with XPath and regex matches -->
+ <filter source="get-property('To')" regex=".*/StockQuote.*">
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/soap/SimpleStockQuoteService" format="soap11"/>
+ </endpoint>
+ </send>
+ <drop/>
+ </filter>
+ <send/>
+</definitions> </pre>
+ <p>
+ <strong>Objective: POX to SOAP conversion</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 50: i.e. synapse -sample 50
+ </p>
+ <p>
+ Start the Axis2 server and deploy the SimpleStockQuoteService if not
+ already done
+ </p>
+ <p>
+ Execute the 'ant stockquote' specifying that the request should be a REST
+ request as follows:
+ </p>
+<pre xml:space="preserve">ant stockquote -Dtrpurl=http://localhost:8280/soap/StockQuote -Drest=true</pre>
+ <p>
+ This example shows a HTTP REST request (as shown below) being transformed
+ into a SOAP request and forwarded to the stock quote service.
+ </p>
+<pre xml:space="preserve">POST /soap/StockQuote HTTP/1.1
+Content-Type: application/xml; charset=UTF-8;action="urn:getQuote";
+SOAPAction: urn:getQuote
+User-Agent: Axis2
+Host: 127.0.0.1
+Transfer-Encoding: chunked
+
+75
+<m0:getQuote xmlns:m0="http://services.samples/xsd">
+ <m0:request>
+ <m0:symbol>IBM</m0:symbol>
+ </m0:request>
+</m0:getQuote>0</pre>
+ <h2>
+ <a name="Sample51" id="Sample51">Sample 51: MTOM and SwA optimizations
+ and request/response correlation</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+ <in>
+ <filter source="get-property('Action')" regex="urn:uploadFileUsingMTOM">
+ <property name="example" value="mtom"/>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/soap/MTOMSwASampleService" optimize="mtom"/>
+ </endpoint>
+ </send>
+ </filter>
+ <filter source="get-property('Action')" regex="urn:uploadFileUsingSwA">
+ <property name="example" value="swa"/>
+ <send>
+ <endpoint>
+ <address uri="http://localhost:9000/soap/MTOMSwASampleService" optimize="swa"/>
+ </endpoint>
+ </send>
+ </filter>
+ </in>
+ <out>
+ <filter source="get-property('example')" regex="mtom">
+ <property name="enableMTOM" value="true" scope="axis2"/>
+ </filter>
+ <filter source="get-property('example')" regex="swa">
+ <property name="enableSwA" value="true" scope="axis2"/>
+ </filter>
+ <send/>
+ </out>
+</definitions></pre>
+ <p>
+ <strong>Objective: MTOM and SwA optimizations and request/response
+ correlation</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong><br/> Start the Synapse
+ configuration numbered 51: i.e. synapse -sample 51<br/> Start the Axis2
+ server and deploy the MTOMSwASampleService if not already done
+ </p>
+ <p>
+ Execute the 'ant optimizeclient' specifying MTOM optimization as follows:
+ </p>
+<pre xml:space="preserve">ant optimizeclient -Dopt_mode=mtom</pre>
+ <p>
+ The configuration now sets a local message context property, and forwards
+ the message to 'http://localhost:9000/soap/MTOMSwASampleService'
+ optimizing binary content as MTOM. By sending this message through TCPMon
+ you would be able to see the actual message sent over the HTTP transport
+ if required. Thus during response processing, by checking the local
+ message property Synapse could identify the past information about the
+ current message context, and uses this knowledge to transform the response
+ back to the client in the same format as the original request.
+ </p>
+ <p>
+ When the client executes successfully, it will upload a file containing
+ the ASF logo and receive its response back again and saves it into a
+ temporary file.
+ </p>
+<pre xml:space="preserve">[java] Sending file : ./../../repository/conf/sample/resources/mtom/asf-logo.gif as MTOM
+[java] Saved response to file : ./../../work/temp/sampleClient/mtom-4417.gif</pre>
+ <p>
+ Next try SwA as:
+ </p>
+<pre xml:space="preserve">ant optimizeclient -Dopt_mode=swa</pre>
+<pre xml:space="preserve">[java] Sending file : ./../../repository/conf/sample/resources/mtom/asf-logo.gif as SwA
+[java] Saved response to file : ./../../work/temp/sampleClient/swa-30391.gif</pre>
+ <p>
+ By using TCPMon and sending the message through it, one can inspect that
+ the requests and responses sent are indeed MTOM optimized or sent as HTTP
+ attachments as follows:
+ </p>
+<pre xml:space="preserve">POST http://localhost:9000/soap/MTOMSwASampleService HTTP/1.1
+Host: 127.0.0.1
+SOAPAction: urn:uploadFileUsingMTOM
+Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_B94996494E1DD5F9B51177413845353; type="application/xop+xml";
+start="<0.urn:uuid:B94996494E1DD5F9B51177413845354@apache.org>"; start-info="text/xml"; charset=UTF-8
+Transfer-Encoding: chunked
+Connection: Keep-Alive
+User-Agent: Synapse-HttpComponents-NIO
+
+--MIMEBoundaryurn_uuid_B94996494E1DD5F9B51177413845353241
+Content-Type: application/xop+xml; charset=UTF-8; type="text/xml"
+Content-Transfer-Encoding: binary
+Content-ID:
+ <0.urn:uuid:B94996494E1DD5F9B51177413845354@apache.org>221b1
+ <?xml version='1.0' encoding='UTF-8'?>
+ <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+ <soapenv:Body>
+ <m0:uploadFileUsingMTOM xmlns:m0="http://www.apache-synapse.org/test">
+ <m0:request>
+ <m0:image>
+ <xop:Include href="cid:1.urn:uuid:78F94BC50B68D76FB41177413845003@apache.org" xmlns:xop="http://www.w3.org/2004/08/xop/include" />
+ </m0:image>
+ </m0:request>
+ </m0:uploadFileUsingMTOM>
+ </soapenv:Body>
+ </soapenv:Envelope>
+--MIMEBoundaryurn_uuid_B94996494E1DD5F9B51177413845353217
+Content-Type: image/gif
+Content-Transfer-Encoding: binary
+Content-ID:
+ <1.urn:uuid:78F94BC50B68D76FB41177413845003@apache.org>22800GIF89a... << binary content >></pre>
+<pre xml:space="preserve">POST http://localhost:9000/soap/MTOMSwASampleService HTTP/1.1
+Host: 127.0.0.1
+SOAPAction: urn:uploadFileUsingSwA
+Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_B94996494E1DD5F9B51177414170491; type="text/xml";
+start="<0.urn:uuid:B94996494E1DD5F9B51177414170492@apache.org>"; charset=UTF-8
+Transfer-Encoding: chunked
+Connection: Keep-Alive
+User-Agent: Synapse-HttpComponents-NIO
+
+--MIMEBoundaryurn_uuid_B94996494E1DD5F9B51177414170491225
+Content-Type: text/xml; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+Content-ID:
+ <0.urn:uuid:B94996494E1DD5F9B51177414170492@apache.org>22159
+ <?xml version='1.0' encoding='UTF-8'?>
+ <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+ <soapenv:Body>
+ <m0:uploadFileUsingSwA xmlns:m0="http://www.apache-synapse.org/test">
+ <m0:request>
+ <m0:imageId>urn:uuid:15FD2DA2584A32BF7C1177414169826</m0:imageId>
+ </m0:request>
+ </m0:uploadFileUsingSwA>
+ </soapenv:Body>
+ </soapenv:Envelope>22--34MIMEBoundaryurn_uuid_B94996494E1DD5F9B511774141704912
+17
+Content-Type: image/gif
+Content-Transfer-Encoding: binary
+Content-ID:
+ <urn:uuid:15FD2DA2584A32BF7C1177414169826>22800GIF89a... << binary content >></pre>
+ <h2>
+ <a name="Sample52" id="Sample52">Sample 52: Session less load balancing
+ between 3 endpoints</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <sequence name="main" onError="errorHandler">
+ <in>
+ <send>
+ <endpoint>
+ <loadbalance>
+ <endpoint>
+ <address uri="http://localhost:9001/soap/LBService1">
+ <enableAddressing/>
+ <suspendDurationOnFailure>60</suspendDurationOnFailure>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9002/soap/LBService1">
+ <enableAddressing/>
+ <suspendDurationOnFailure>60</suspendDurationOnFailure>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9003/soap/LBService1">
+ <enableAddressing/>
+ <suspendDurationOnFailure>60</suspendDurationOnFailure>
+ </address>
+ </endpoint>
+ </loadbalance>
+ </endpoint>
+ </send>
+<drop/>
+ </in>
+
+ <out>
+ <!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
+ <send/>
+ </out>
+ </sequence>
+
+ <sequence name="errorHandler">
+
+ <makefault>
+ <code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
+ <reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
+ </makefault>
+
+ <header name="To" action="remove"/>
+ <property name="RESPONSE" value="true"/>
+
+ <send/>
+ </sequence>
+
+</definitions></pre>
+ <p>
+ <strong>Objective: Demonstrate the simple load balancing among a set of
+ endpoints</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong>
+ </p>
+ <p>
+ Start Synapse with sample configuration 52. (i.e. synapse -sample 52)
+ </p>
+ <p>
+ Deploy the LoadbalanceFailoverService by switching to <Synapse
+ installation directory>/samples/axis2Server/src/LoadbalanceFailoverService
+ directory and running ant.
+ </p>
+ <p>
+ Start three instances of sample Axis2 server on HTTP ports 9001, 9002 and
+ 9003 and give some unique names to each server.
+ </p>
+ <p>
+ Example commands to run sample Axis2 servers from the <Synapse
+ installation directory>/samples/axis2Server directory in Linux are
+ listed below:
+ </p>
+<pre xml:space="preserve">./axis2server.sh -http 9001 -https 9005 -name MyServer1
+./axis2server.sh -http 9002 -https 9006 -name MyServer2
+./axis2server.sh -http 9003 -https 9007 -name MyServer3</pre>
+ <p>
+ Now we are done with setting up the environment for load balance sample.
+ Start the load balance and failover client using the following command:
+ </p>
+<pre xml:space="preserve">ant loadbalancefailover -Di=100</pre>
+ <p>
+ This client sends 100 requests to the LoadbalanceFailoverService through
+ Synapse. Synapse will distribute the load among the three endpoints
+ mentioned in the configuration in round-robin manner.
+ LoadbalanceFailoverService appends the name of the server to the response,
+ so that client can determine which server has processed the message. If
+ you examine the console output of the client, you can see that requests
+ are processed by three servers as follows:
+ </p>
+<pre xml:space="preserve">[java] Request: 1 ==> Response from server: MyServer1
+[java] Request: 2 ==> Response from server: MyServer2
+[java] Request: 3 ==> Response from server: MyServer3
+[java] Request: 4 ==> Response from server: MyServer1
+[java] Request: 5 ==> Response from server: MyServer2
+[java] Request: 6 ==> Response from server: MyServer3
+[java] Request: 7 ==> Response from server: MyServer1
+...</pre>
+ <p>
+ Now run the client without the -Di=100 parameter to send infinite
+ requests. While running the client shutdown the server named MyServer1.
+ You can observe that requests are only distributed among MyServer2 and
+ MyServer3 after shutting down MyServer1. Console output before and after
+ shutting down MyServer1 is listed below (MyServer1 was shutdown after
+ request 63):
+ </p>
+<pre xml:space="preserve">...
+[java] Request: 61 ==> Response from server: MyServer1
+[java] Request: 62 ==> Response from server: MyServer2
+[java] Request: 63 ==> Response from server: MyServer3
+[java] Request: 64 ==> Response from server: MyServer2
+[java] Request: 65 ==> Response from server: MyServer3
+[java] Request: 66 ==> Response from server: MyServer2
+[java] Request: 67 ==> Response from server: MyServer3
+...</pre>
+ <p>
+ Now restart MyServer1. You can observe that requests will be again sent to
+ all three servers roughly after 60 seconds. This is because we have
+ specified <suspendDurationOnFailure> as 60 seconds in the
+ configuration. Therefore, load balance endpoint will suspend any failed
+ child endpoint only for 60 seconds after detecting the failure.
+ </p>
+ <h2>
+ <a name="Sample53" id="Sample53">Sample 53: Failover sending among 3
+ endpoints</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <sequence name="main" onError="errorHandler">
+ <in>
+ <send>
+ <endpoint>
+ <failover>
+ <endpoint>
+ <address uri="http://localhost:9001/soap/LBService1">
+ <enableAddressing/>
+ <suspendDurationOnFailure>60</suspendDurationOnFailure>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9002/soap/LBService1">
+ <enableAddressing/>
+ <suspendDurationOnFailure>60</suspendDurationOnFailure>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9003/soap/LBService1">
+ <enableAddressing/>
+ <suspendDurationOnFailure>60</suspendDurationOnFailure>
+ </address>
+ </endpoint>
+ </failover>
+ </endpoint>
+ </send>
+<drop/>
+ </in>
+
+ <out>
+ <!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
+ <send/>
+ </out>
+ </sequence>
+
+ <sequence name="errorHandler">
+
+ <makefault>
+ <code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
+ <reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
+ </makefault>
+
+ <header name="To" action="remove"/>
+ <property name="RESPONSE" value="true"/>
+
+ <send/>
+ </sequence>
+
+</definitions></pre>
+ <p>
+ <strong>Objective: Demonstrate the failover sending</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong>
+ </p>
+ <p>
+ Start Synapse with sample configuration 53 (i.e. synapse -sample 53)
+ </p>
+ <p>
+ Deploy the LoadbalanceFailoverService and start three instances of sample
+ Axis2 server as mentioned in sample 52.
+ </p>
+ <p/>
+ <p>
+ Above configuration sends messages with the failover behavior. Initially
+ the server at port 9001 is treated as primary and other two are treated as
+ backups. Messages are always directed only to the primary server. If the
+ primary server has failed, next listed server is selected as the primary.
+ Thus, messages are sent successfully as long as there is at least one
+ active server. To test this, run the loadbalancefailover client to send
+ infinite requests as follows:
+ </p>
+<pre xml:space="preserve">ant loadbalancefailover</pre>
+ <p>
+ You can see that all requests are processed by MyServer1. Now shutdown
+ MyServer1 and inspect the console output of the client. You will observe
+ that all subsequent requests are processed by MyServer2.
+ </p>
+ <p>
+ The console output with MyServer1 shutdown after request 127 is listed
+ below:
+ </p>
+<pre xml:space="preserve">...
+[java] Request: 125 ==> Response from server: MyServer1
+[java] Request: 126 ==> Response from server: MyServer1
+[java] Request: 127 ==> Response from server: MyServer1
+[java] Request: 128 ==> Response from server: MyServer2
+[java] Request: 129 ==> Response from server: MyServer2
+[java] Request: 130 ==> Response from server: MyServer2
+...</pre>
+ <p>
+ You can keep on shutting down servers like this. Client will get a
+ response till you shutdown all listed servers. Once all servers are
+ shutdown, the error sequence is activated and a fault message is sent to
+ the client as follows.
+ </p>
+<pre xml:space="preserve">[java] COULDN'T SEND THE MESSAGE TO THE SERVER.</pre>
+ <p>
+ Once a server is detected as failed, it will be added to the active
+ servers list again after 60 seconds (specified in <suspendDurationOnFailure>
+ in the configuration). Therefore, if you have restarted any of the stopped
+ servers and have shutdown all other servers, messages will be directed to
+ the newly started server.
+ </p>
+ <h2>
+ <a name="Sample54" id="Sample54">Sample 54: Session affinity load
+ balancing between 3 endpoints</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <sequence name="main" onError="errorHandler">
+ <in>
+ <send>
+ <endpoint>
+ <!-- specify the session as the simple client session provided by Synapse for
+ testing purpose -->
+ <strong><session type="simpleClientSession"/></strong>
+
+ <loadbalance>
+ <endpoint>
+ <address uri="http://localhost:9001/soap/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9002/soap/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9003/soap/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ </loadbalance>
+ </endpoint>
+ </send>
+<drop/>
+ </in>
+
+ <out>
+ <!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
+ <send/>
+ </out>
+ </sequence>
+
+ <sequence name="errorHandler">
+
+ <makefault>
+ <code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
+ <reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
+ </makefault>
+
+ <header name="To" action="remove"/>
+ <property name="RESPONSE" value="true"/>
+
+ <send/>
+ </sequence>
+
+</definitions></pre>
+ <p>
+ <strong>Objective: Demonstrate the loadbalancing with session affinity
+ using client initiated sessions</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong>
+ </p>
+ <p>
+ Start Synapse with sample configuration 54 (i.e. synapse -sample 54).
+ </p>
+ <p>
+ Deploy the LoadbalanceFailoverService and start three instances of the
+ sample Axis2 server as in sample 52.
+ </p>
+ <p/>
+ <p>
+ Above configuration is same as the load balancing configuration in sample
+ 52, except that the session type is specified as "simpleClientSession".
+ This is a client initiated session, which means that the client generates
+ the session identifier and sends it with each request. In this sample
+ session type, client adds a SOAP header named ClientID containing the
+ identifier of the client. Synapse binds this ID with a server on the first
+ request and sends all successive requests containing that ID to the same
+ server. Now switch to samples/axis2Client directory and run the client
+ using the following command to check this in action.
+ </p>
+<pre xml:space="preserve">ant loadbalancefailover -Dmode=session</pre>
+ <p>
+ In the session mode, client continuously sends requests with three different
+ client (session) IDs. One ID is selected among these three IDs for each
+ request randomly. Then client prints the session ID with the responded
+ server for each request. Client output for the first 10 requests are shown
+ below.
+ </p>
+<pre xml:space="preserve">[java] Request: 1 Session number: 1 Response from server: MyServer3
+[java] Request: 2 Session number: 2 Response from server: MyServer2
+[java] Request: 3 Session number: 0 Response from server: MyServer1
+[java] Request: 4 Session number: 2 Response from server: MyServer2
+[java] Request: 5 Session number: 1 Response from server: MyServer3
+[java] Request: 6 Session number: 2 Response from server: MyServer2
+[java] Request: 7 Session number: 2 Response from server: MyServer2
+[java] Request: 8 Session number: 1 Response from server: MyServer3
+[java] Request: 9 Session number: 0 Response from server: MyServer1
+[java] Request: 10 Session number: 0 Response from server: MyServer1
+... </pre>
+ <p>
+ You can see that session number 0 is always directed to the server named
+ MyServer1. That means session number 0 is bound to MyServer1. Similarly
+ session 1 and 2 are bound to MyServer3 and MyServer2 respectively.
+ </p>
+ <h2>
+ <a name="Sample55" id="Sample55">Sample 55: Session affinity load
+ balancing between fail over endpoints</a>
+ </h2>
+<pre xml:space="preserve"><definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <sequence name="main" onError="errorHandler">
+ <in>
+ <send>
+ <endpoint>
+ <!-- specify the session as the simple client session provided by Synapse for
+ testing purpose -->
+ <strong><session type="simpleClientSession"/></strong>
+
+ <loadbalance>
+ <endpoint>
+ <failover>
+ <endpoint>
+ <address uri="http://localhost:9001/soap/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9002/soap/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ </failover>
+ </endpoint>
+ <endpoint>
+ <failover>
+ <endpoint>
+ <address uri="http://localhost:9003/soap/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ <endpoint>
+ <address uri="http://localhost:9004/soap/LBService1">
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ </failover>
+ </endpoint>
+ </loadbalance>
+ </endpoint>
+ </send>
+<drop/>
+ </in>
+
+ <out>
+ <!-- Send the messages where they have been sent (i.e. implicit To EPR) -->
+ <send/>
+ </out>
+ </sequence>
+
+ <sequence name="errorHandler">
+
+ <makefault>
+ <code value="tns:Receiver" xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
+ <reason value="COULDN'T SEND THE MESSAGE TO THE SERVER."/>
+ </makefault>
+
+ <header name="To" action="remove"/>
+ <property name="RESPONSE" value="true"/>
+
+ <send/>
+ </sequence>
+
+</definitions></pre>
+ <p>
+ <strong>Objective: Demonstrate the session affinity based load
+ balancing with failover capability</strong>
+ </p>
+ <p>
+ <strong>Prerequisites:</strong>
+ </p>
+ <p>
+ Start Synapse with sample configuration 55 (i.e. synapse -sample 55).
+ </p>
+ <p>
+ Deploy the LoadbalanceFailoverService and start four sample Axis2 servers
+ on HTTP ports 9001, 9002, 9003 and 9004 respectively (make sure to specify
+ non-conflicting HTTPS ports).
+ </p>
+ <p/>
+ <p>
+ This configuration also uses "simpleClientSession" to bind sessions as in
+ the previous sample. But failover endpoints are specified as the child
+ endpoints of the load balance endpoint. Therefore sessions are bound to
+ the failover endpoints. Session information has to be replicated among the
+ servers listed under each failover endpoint using some clustering
+ mechanism. Therefore, if one endpoint bound to a session failed,
+ successive requets for that session will be directed to the next endpoint
+ in that failover group. Run the client using the following command to
+ observe this behaviour.
+ </p>
+<pre xml:space="preserve">ant loadbalancefailover -Dmode=session</pre>
+ <p>
+ You can see a client output as shown below.
+ </p>
[... 3448 lines stripped ...]