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 [3/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_0/samples.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/1_0/samples.xml?rev=1225148&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/1_0/samples.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/1_0/samples.xml Wed Dec 28 09:23:09 2011
@@ -0,0 +1,3485 @@
+<?xml version="1.0"?>
+
+<!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=""/>
+ <title>
+ Synapse Samples
+ </title>
+ <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>
+ Running the Synapse Samples
+ </h1>
+ <h2>
+ <a name="TOC" id="TOC">Contents</a>
+ </h2>
+ <div class="section-content">
+ <ul>
+ <li>
+ <a href="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: Content based routing (CBR)</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>
+ </ul>
+ </li>
+ <li>
+ <a href="#Endpoints">Endpoints</a>
+ <ul>
+ <li>
+ <a href="#Sample50">Sample 50: Using WS-Security for outgoing
+ messages</a>
+ </li>
+ <li>
+ <a href="#Sample51">Sample 51: MTOM and SwA optimizations and
+ request/response correlation</a>
+ </li>
+ <li>
+ <a href="#Sample52">Sample 52: POX to SOAP conversion</a>
+ </li>
+ <li>
+ <a href="#Sample53">Sample 53: Reliable message exchange
+ between Synapse and the back-end server using WS-ReliableMessaging</a>
+ </li>
+ <li>
+ <a href="#Sample54">Sample 54: Load balancing</a>
+ </li>
+ <li>
+ <a href="#Sample55">Sample 55: Failover</a>
+ </li>
+ <li>
+ <a href="#Sample56">Sample 56: Load balancing with session
+ affinity</a>
+ </li>
+ <li>
+ <a href="#Sample57">Sample 57: Load balancing with session
+ affinity among failover groups</a>
+ </li>
+ <li>
+ <a href="#Sample60">Sample 60: WSDL endpoint</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#ProxyServices">Synapse Proxy service samples</a>
+ <ul>
+ <li>
+ <a href="#Sample100">Sample 100: Introduction to proxy services</a>
+ </li>
+ <li>
+ <a href="#Sample101">Sample 101: Custom sequences and endpoints
+ with proxy services</a>
+ </li>
+ <li>
+ <a href="#Sample102">Sample 102: Switching transports and
+ message format from SOAP to REST/POX</a>
+ </li>
+ <li>
+ <a href="#Sample103">Sample 103: Using WS-Security with policy
+ attachments for proxy services</a>
+ </li>
+ <li>
+ <a href="#Sample104">Sample 104: Reliable message exchange
+ between the client and proxy services using WS-ReliableMessaging</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#Transport">Transport samples</a>
+ <ul>
+ <li>
+ <a href="#Sample110">Sample 110: Introduction to switching
+ transports - JMS to http/s</a>
+ </li>
+ <li>
+ <a href="#Sample111">Sample 111: Demonstrate switching from
+ http/s to JMS</a>
+ </li>
+ <li>
+ <a href="#Sample112">Sample 112: Demonstrate one way messaging
+ / fireAndForget()</a>
+ </li>
+ <li>
+ <a href="#Sample113">Sample 113: Pure text/binary and POX
+ message support with JMS</a>
+ </li>
+ <li>
+ <a href="#Sample114">Sample 114: One way bridging from JMS to
+ http and replying with a 202 Accepted response</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#ExtensionMediators">Extension Mediators</a>
+ <ul>
+ <li>
+ <a href="Synapse_Samples_Setup.html#ScriptSetup">Setting up
+ Script Mediators</a>
+ </li>
+ <li>
+ <a href="#Sample500">Sample 500: Introduction to script
+ mediators</a>
+ </li>
+ <li>
+ <a href="#Sample501">Sample 501: In-line script mediation</a>
+ </li>
+ <li>
+ <a href="#Sample502">Sample 502: Accessing Synapse message
+ context API methods</a>
+ </li>
+ <li>
+ <a href="#Sample503">Sample 503: Using Ruby scripts for
+ mediation</a>
+ </li>
+ <li>
+ <a href="#Sample510">Sample 510: Class mediator - Writting your
+ own mediation in Java</a>
+ </li>
+ </ul>
+ </li>
+ <li>
+ <a href="#AdvancedMediations">Advanced Mediations</a>
+ <ul>
+ <li>
+ <a href="#Sample600">Sample 600: Throttle mediator -
+ Restricting requests based on policies</a>
+ </li>
+ </ul>
+ </li>
+ </ul>
+ </div>
+ <h1>
+ <a name="MediationSamples" id="MediationSamples">Message Mediation
+ Samples</a>
+ </h1>
+ <h2>
+ <a name="Sample0" id="Sample0">Sample 0:</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>
+ <li>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ </pre>
+ </li>
+ <li>
+ Using Synapse as a HTTP Proxy
+ </li>
+ <li>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dprxurl=http://localhost:8080/</pre>
+ </li>
+ <li>
+ Gateway mode / Dumb Client
+ </li>
+ <li>
+ <p>
+ See sample # 1
+ </p>
+ </li>
+ </ol>
+ <p>
+ <strong>Pre-Requisites:<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 following through the execution of Synapse through the DEBUG level log
+ output to the system output stream (i.e. console), you will notice that
+ the client request arrived at Synapse with a WS-Addressing 'To' EPR of
+ http://localhost:9000/soap/SimpleStockQuoteService. The Synapse engine now
+ logs the message at the "full" log level (i.e. all message headers and the
+ body) and sends the message to its implicit 'To' address - which is
+ http://localhost:9000/soap/SimpleStockQuoteService. Then you will see on
+ the Axis2 server console, a message confirming that the message got routed
+ to the sample server and the sample service that was invoked generated 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:</a>
+ </h2>
+<pre xml:space="preserve"><!-- simple content based routing of messages -->
+<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>Pre-Requisites:</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:8080/soap/StockQuote<br/></pre>
+ <p>
+ This time you will notice that Synapse received a message for which
+ Synapse was set as the ultimate receiver of the message. Based on the 'To'
+ EPR of http://localhost:8080/soap/StockQuote, Synapse performes a match to
+ the path '/StockQuote' and as the request matched the XPath expression of
+ the filter mediator, the filter mediators' child mediators executes, and
+ thereby sending 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
+ reply back to the client.
+ </p>
+ <h2>
+ <a name="Sample2" id="Sample2">Sample 2:</a>
+ </h2>
+<pre xml:space="preserve"><!-- switch-case mediator and setting and reading of local properties on a message -->
+<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>Pre-Requisites:</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 request, following through the mediation logs you will see that the
+ case statements' first case for 'IBM' 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>
+ <p>
+ ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService
+ -Dtrpurl=http://localhost:8080/ -Dsymbol=IBM
+ </p>
+<pre xml:space="preserve">INFO LogMediator - symbol = Great stock - IBM, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService </pre>
+ <p>
+ ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService
+ -Dtrpurl=http://localhost:8080/ -Dsymbol=MSFT
+ </p>
+<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:</a>
+ </h2>
+<pre xml:space="preserve"><!-- illustration of local registry entry definitions, and reusable endpoints and sequences -->
+<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>Pre-Requisites:</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 neater 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" executed. Then for the incoming message flow the <in>
+ mediator executes, and it calls into the sequence named "stockquote"
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/</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, an XPath evaluation result - that picks up the key
+ named "version", and a second XPath evaluation result 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 is visible to all messages that passes 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:</a>
+ </h2>
+<pre xml:space="preserve"><!-- introduction to error handling -->
+<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>Pre-Requisites:</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
+ endpoint defined as the 'simple' 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 up for
+ a sequence named 'fault'. Thus the 'fault' sequence can be seen executing,
+ and writing the generic error message into the logs.
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ -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, now you could see the proper error handler invocation
+ and the custom error message as follows:
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ -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:</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>Pre-Requisites:</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
+ caused, and a connection refused exception would be caused for the SUN
+ stock. This information is captured and returned back 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:8080/ -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:8080/ -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:</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>Pre-Requisites:</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:8080/soap/SimpleStockQuoteService</pre>
+ <h2>
+ <a name="Sample7" id="Sample7">Sample 7:</a>
+ </h2>
+<pre xml:space="preserve"><!-- introduction of static inline XML properties and the validation mediator -->
+<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>Pre-Requisites:</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 to the local registry are
+ static (i.e. never changes over the lifetime of the configuration) and may
+ be specified as a source URL, inline-text or inline-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 is in error invokes on the 'on-fail' sequence of mediators.
+ </p>
+ <p>
+ If you send a stockquote request using 'ant stockquote ..' you will now
+ get a fault back with a 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 thestock symbol)
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/</pre>
+ <h2>
+ <a name="Sample8" id="Sample8">Sample 8:</a>
+ </h2>
+<pre xml:space="preserve"><!-- introduction to static and dynamic registry resources and the XSLT mediator -->
+<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>Pre-Requisites:</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 tranformations 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 makes 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 have
+ preference and hide the existence of 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 as shown below
+ </p>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ -Dmode=customquote</pre>
+<pre xml:space="preserve">[HttpServerWorker-1] DEBUG XSLTMediator - Performing XSLT transformation against property with key : xslt-key-req
+[HttpServerWorker-1] DEBUG XSLTMediator - Transformation source :
+ <m0:CheckPriceRequest xmlns:m0="http://www.apache-synapse.org/test"><m0:Code>IBM</m0:Code></m0:CheckPriceRequest>
+[HttpServerWorker-1] DEBUG XSLTMediator - Transformation result : <m:getQuote xmlns:m="http://services.samples/xsd"></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 notice the SimpleURLRegistry
+ fetching the resource as shown by the log message below
+ </p>
+<pre xml:space="preserve">[HttpClientWorker-1] INFO SimpleURLRegistry - ==> Repository fetch of resource with key : transform/transform_back.xslt</pre>
+ <p>
+ If you re-run the client again immidiately (i.e within 15 seconds of the
+ first request) you will not see the resource being re-loaded 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 cache
+ expiry and checked the meta information about the resource to check if the
+ resource itself has changes and requires 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 changes could be reloaded without restarting the Synapse
+ instance.
+ </p>
+ <h2>
+ <a name="Sample9" id="Sample9">Sample 9:</a>
+ </h2>
+<pre xml:space="preserve"><!-- introduction dynamic sequences -->
+<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>Pre-Requisites:</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 &
+ 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 recheck 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:8080/</pre>
+<pre xml:space="preserve">[HttpServerWorker-1] INFO 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 immidiately (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 and 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 have 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] INFO 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 suite the environment and the needs.
+ </p>
+ <h2>
+ <a name="Sample10" id="Sample10">Sample 10:</a>
+ </h2>
+<pre xml:space="preserve"><!-- introduction dynamic endpoints -->
+<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>Pre-Requisites:</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 immidiately 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:8080/</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
+ 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>
+ </h2>
+<pre xml:space="preserve"><!-- a full registry based configuration -->
+<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>Pre-Requisites:</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, and allow the configuration to
+ be reloaded as well. 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>
+<pre xml:space="preserve">ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/</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>
+ <p/>
+ <h1>
+ <a name="Endpoints" id="Endpoints">Endpoints</a>
+ </h1>
+ <h2>
+ <a name="Sample50" id="Sample50">Sample 50:</a>
+ </h2>
+<pre xml:space="preserve"><!-- Connecting to endpoints with WS-Security for outgoing messages -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+ <localEntry key="sec_policy" src="file:repository/conf/sample/resources/policy/policy_3.xml"/>
+
+ <in>
+ <send>
+ <endpoint name="secure">
+ <address uri="http://localhost:9000/soap/SecureStockQuoteService">
+ <enableSec policy="sec_policy"/>
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ </send>
+ </in>
+ <out>
+ <header name="wsse:Security" action="remove"
+ xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"/>
+ <send/>
+ </out>
+</definitions></pre>
+ <p>
+ <strong>Objective: Connecting to endpoints with WS-Security for
+ outgoing messages</strong>
+ </p>
+ <p>
+ <strong>Pre-Requisites:</strong><br/>
+ </p>
+ <p>
+ You may also need to download and install the unlimited strength policy
+ files for your JDK before using Apache Rampart (e.g. see
+ http://java.sun.com/javase/downloads/index_jdk5.jsp)
+ </p>
+ <p>
+ Start the Synapse configuration numbered 50: i.e. synapse -sample 50<br/>
+ Start the Axis2 server and deploy the SecureStockQuoteService if not
+ already done
+ </p>
+ <p/>
+ <p>
+ Use the stock quote client to send a request without WS-Security. Synapse
+ is configured to enable WS-Security as per the policy specified by
+ 'policy_3.xml' for the outgoing messages to the SecureStockQuoteService
+ endpoint hosted on the Axis2 instance. The debug log messages on Synapse
+ shows the encrypted message flowing to the service and the encrypted
+ response being received by Synapse. The wsse:Security header is then
+ removed from the decrypted message and the response is delivered back to
+ the client, as expected. You may execute the client as follows:
+ </p>
+<pre xml:space="preserve">ant stockquote -Dtrpurl=http://localhost:8080/</pre>
+ <p>
+ The message sent by Synapse to the secure service can be seen as follows,
+ when TCPMon is used.
+ </p>
+<pre xml:space="preserve">POST http://localhost:9001/soap/SecureStockQuoteService HTTP/1.1
+Host: 127.0.0.1
+SOAPAction: urn:getQuote
+Content-Type: text/xml; charset=UTF-8
+Transfer-Encoding: chunked
+Connection: Keep-Alive
+User-Agent: Synapse-HttpComponents-NIO
+
+800
+<?xml version='1.0' encoding='UTF-8'?>
+ <soapenv:Envelope xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" xmlns:wsa="http://www.w3.org/2005/08/addressing" ..>
+ <soapenv:Header>
+ <wsse:Security ..>
+ <wsu:Timestamp ..>
+ ...
+ </wsu:Timestamp>
+ <xenc:EncryptedKey..>
+ ...
+ </xenc:EncryptedKey>
+ <wsse:BinarySecurityToken ...>
+ <ds:SignedInfo>
+ ...
+ </ds:SignedInfo>
+ <ds:SignatureValue>
+ ...
+ </ds:SignatureValue>
+ <ds:KeyInfo Id="KeyId-29551621">
+ ...
+ </ds:KeyInfo>
+ </ds:Signature>
+ </wsse:Security>
+ <wsa:To>http://localhost:9001/soap/SecureStockQuoteService</wsa:To>
+ <wsa:MessageID>urn:uuid:1C4CE88B8A1A9C09D91177500753443</wsa:MessageID>
+ <wsa:Action>urn:getQuote</wsa:Action>
+ </soapenv:Header>
+ <soapenv:Body xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" wsu:Id="Id-3789605">
+ <xenc:EncryptedData Id="EncDataId-3789605" Type="http://www.w3.org/2001/04/xmlenc#Content">
+ <xenc:EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc" />
+ <xenc:CipherData>
+ <xenc:CipherValue>Layg0xQcnH....6UKm5nKU6Qqr</xenc:CipherValue>
+ </xenc:CipherData>
+ </xenc:EncryptedData>
+ </soapenv:Body>
+ </soapenv:Envelope>0</pre>
+ <h2>
+ <a name="Sample51" id="Sample51">Sample 51:</a>
+ </h2>
+<pre xml:space="preserve"><!-- MTOM and SwA and message properties to correlate requests and responses -->
+<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>Pre-Requisites:</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 bindary 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 save it into a
+ temporary file.
+ </p>
+<pre xml:space="preserve">[java] Sending file : ./../../repository/conf/sample/resources/mtom/asf-logo.gif as MTOM</pre>
+<pre xml:space="preserve">[java] Saved response to file : /tmp/mtom-36877.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 : /tmp/swa-47549.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:</a>
+ </h2>
+<pre xml:space="preserve"><!-- POX to SOAP conversion -->
+<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="soap"/>
+ </endpoint>
+ </send>
+ <drop/>
+ </filter>
+ <send/>
+</definitions> </pre>
+ <p>
+ <strong>Objective: POX to SOAP conversion</strong>
+ </p>
+ <p>
+ <strong>Pre-Requisites:</strong><br/> Start the Synapse
+ configuration numbered 52: i.e. synapse -sample 52\
+ </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:8081/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="Sample53" id="Sample53">Sample 53:</a>
+ </h2>
+<pre xml:space="preserve"><!-- RMSequence example -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
+
+ <in>
+ <RMSequence single="true" version="1.0"/>
+ <send>
+ <endpoint name="reliable">
+ <address uri="http://localhost:9000/soap/ReliableStockQuoteService">
+ <enableRM/>
+ <enableAddressing/>
+ </address>
+ </endpoint>
+ </send>
+ </in>
+ <out>
+ <header name="wsrm:SequenceAcknowledgement" action="remove"
+ xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"/>
+ <header name="wsrm:Sequence" action="remove"
+ xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"/>
+ <send/>
+ </out>
+
+</definitions></pre>
+ <strong>Objective: Demonstrate the message exchange between Synapse and
+ the server using WS-ReliableMessaging (WS-RM)</strong>
+ <p>
+ <strong>Pre-Requisites:</strong>
+ </p>
+ <p>
+ Deploy the ReliableStockQuoteService in the sample Axis2 server by
+ switching to the samples/axis2Server/src/ReliableStockQuoteService
+ directory and running ant.
+ </p>
+ <p>
+ Start the sample Axis2 server on port 9000.
+ </p>
+ <p>
+ Start Synapse with the sample configuration 53 (i.e. synapse -sample 53).
+ </p>
+ <p/>
+ <p>
+ In the above configuration, WS-RM is engaged to the endpoint using the
+ <enableRM/> tag. It is possible to engage WS-RM to both Address and
+ WSDL endpoints using this tag. In addition to the RM enabled endpoint,
+ RMSequence mediator is specified before the send mediator. This mediator
+ is used to specify the set of messages to be sent using a single RM
+ sequence. In this sample it is specified as single message per sequence.
+ It also specifies the version of the WS-RM to be used. Refer to the
+ Synapse configuration language documentation for more information about
+ the RMSequence mediator. RM related SOAP headers are removed form the
+ message in the out mediator as WS-RM message exchange happens only between
+ the Synapse and the server. Now run the sample client using the following
+ command.
+ </p>
+<pre xml:space="preserve">ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8080</pre>
+ <p>
+ You can observer the client output displaying the quote price for IBM as
+ follows:
+ </p>
+<pre xml:space="preserve">[java] Standard :: Stock price = $189.2521262517493</pre>
+ <p>
+ There is no difference to be observed between the normal message exchange
+ and WS-RM enabled message exchange as far as client and server outputs are
+ considered. But if you look at the wire level messages, you would observe
+ additional WS-RM messages and WS-RM elements. Synapse, the initiator of
+ the RM sequence, first try to create a sequence by sending a message with
+ CreateSequence element.
+ </p>
+<pre xml:space="preserve">...
+<soapenv:Body>
+ <wsrm:CreateSequence xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm">
+ <wsrm:AcksTo>
+ <wsa:Address>http://www.w3.org/2005/08/addressing/anonymous</wsa:Address>
+ </wsrm:AcksTo>
+ <wsrm:Offer>
+ <wsrm:Identifier>urn:uuid:546F6F33FB7D8BBE351179807372769</wsrm:Identifier>
+ </wsrm:Offer>
+ </wsrm:CreateSequence>
+</soapenv:Body>
+...</pre>
+ <p>
+ Sample Axis2 server responds to CreateSequence request with the following
+ message:
+ </p>
+<pre xml:space="preserve">...
+<soapenv:Body>
+ <wsrm:CreateSequenceResponse xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm">
+ <wsrm:Identifier>urn:uuid:879853A6871A66641C1179807373270</wsrm:Identifier>
+ <wsrm:Accept>
+ <wsrm:AcksTo>
+ <wsa:Address>http://localhost:9000/soap/ReliableStockQuoteService</wsa:Address>
+ </wsrm:AcksTo>
+ </wsrm:Accept>
+ </wsrm:CreateSequenceResponse>
+</soapenv:Body>
+...</pre>
+ <p>
+ Once the sequence is established, Synapse sends the request to the server
+ with the pre-negotiated sequence ID.
+ </p>
+<pre xml:space="preserve"><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/ReliableStockQuoteService</wsa:To>
+ <wsa:MessageID>urn:uuid:DB9A5257B637DDA38B1179807372560712002-1515891720</wsa:MessageID>
+ <wsa:Action>urn:getQuote</wsa:Action>
+ <wsrm:Sequence xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
+ soapenv:mustUnderstand="1">
+ <wsrm:Identifier>urn:uuid:879853A6871A66641C1179807373270</wsrm:Identifier>
+ <wsrm:MessageNumber>1</wsrm:MessageNumber>
+ <wsrm:LastMessage/>
+ </wsrm:Sequence>
+ </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></pre>
+ <p>
+ Synapse keeps on sending above message till the server responds with a
+ valid response message with 200 OK HTTP header. If the server is not ready
+ with a response, it will respond with 202 Accepted HTTP header for all
+ requests. Once the server is ready with a response it will send the
+ response message with sequence ID as follows.
+ </p>
+<pre xml:space="preserve"><soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing"
+ xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+ <soapenv:Header>
+ <wsa:MessageID>urn:uuid:879853A6871A66641C1179807373804</wsa:MessageID>
+ <wsa:Action>http://services.samples/ReliableStockQuoteServicePortType/getQuoteResponse
+ </wsa:Action>
+ <wsa:RelatesTo>urn:uuid:DB9A5257B637DDA38B1179807372560712002-1515891720</wsa:RelatesTo>
+ <wsrm:Sequence xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
+ soapenv:mustUnderstand="1">
+ <wsrm:Identifier>urn:uuid:546F6F33FB7D8BBE351179807372769</wsrm:Identifier>
+ <wsrm:MessageNumber>1</wsrm:MessageNumber>
+ <wsrm:LastMessage/>
+ </wsrm:Sequence>
+ <wsrm:SequenceAcknowledgement xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
+ soapenv:mustUnderstand="1">
+ <wsrm:Identifier>urn:uuid:879853A6871A66641C1179807373270</wsrm:Identifier>
+ <wsrm:AcknowledgementRange Lower="1" Upper="1"/>
+ </wsrm:SequenceAcknowledgement>
+ </soapenv:Header>
+ <soapenv:Body>
+ <ns:getQuoteResponse xmlns:ns="http://services.samples/xsd">
+...</pre>
+ <p>
+ Now both Synapse and the server are done with the actual message exchange.
+ Then Synapse sends a request to terminate the sequence as follows:
+ </p>
+<pre xml:space="preserve"><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/ReliableStockQuoteService</wsa:To>
+ <wsa:MessageID>urn:uuid:546F6F33FB7D8BBE351179807379591</wsa:MessageID>
+ <wsa:Action>http://schemas.xmlsoap.org/ws/2005/02/rm/TerminateSequence</wsa:Action>
+ <wsrm:SequenceAcknowledgement xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm"
+ soapenv:mustUnderstand="1">
+ <wsrm:Identifier>urn:uuid:546F6F33FB7D8BBE351179807372769</wsrm:Identifier>
+ <wsrm:AcknowledgementRange Lower="1" Upper="1"/>
+ </wsrm:SequenceAcknowledgement>
+ </soapenv:Header>
+ <soapenv:Body>
+ <wsrm:TerminateSequence xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm">
+ <wsrm:Identifier>urn:uuid:879853A6871A66641C1179807373270</wsrm:Identifier>
+ </wsrm:TerminateSequence>
+ </soapenv:Body>
+</soapenv:Envelope></pre>
+ <p>
+ Server responds to the sequence termination message, accepting to
+ terminate the sequence as follows.
+ </p>
+<pre xml:space="preserve"><soapenv:Envelope xmlns:wsa="http://www.w3.org/2005/08/addressing"
+ xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
+ <soapenv:Header>
+ <wsa:ReplyTo>
+ <wsa:Address>http://localhost:9000/soap/ReliableStockQuoteService</wsa:Address>
+ </wsa:ReplyTo>
+ <wsa:MessageID>urn:uuid:879853A6871A66641C1179807380190</wsa:MessageID>
+ <wsa:Action>http://schemas.xmlsoap.org/ws/2005/02/rm/TerminateSequence</wsa:Action>
+ </soapenv:Header>
+ <soapenv:Body>
+ <wsrm:TerminateSequence xmlns:wsrm="http://schemas.xmlsoap.org/ws/2005/02/rm">
+ <wsrm:Identifier>urn:uuid:546F6F33FB7D8BBE351179807372769</wsrm:Identifier>
+ </wsrm:TerminateSequence>
+ </soapenv:Body>
+</soapenv:Envelope></pre>
+ <p>
+ Note that although each of above messages are separate SOAP messages, in
+ most cases they will be exchanged in a single socket connection as HTTP
+ Keep-Alive header is used.
+ </p>
+ <h2>
+ <a name="Sample54" id="Sample54">Sample 54:</a>
+ </h2>
+<pre xml:space="preserve"><!-- demonstrates simple session less load balancing between 3 endpoints -->
+<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>
+ </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 set of
+ endpoints</strong>
+ </p>
+ <p>
+ <strong>Pre-Requisites:</strong>
+ </p>
+ <p>
+ Start Synapse with sample configuration 54. (i.e. synapse -sample 54)
+ </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 in Linux is 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 requets 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="Sample55" id="Sample55">Sample 55:</a>
+ </h2>
+<pre xml:space="preserve"><!-- Demontrates failover sending among 3 endpoints. -->
+<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>
+ </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>Pre-Requisites:</strong>
+ </p>
+ <p>
+ Start Synapse with sample configuration 55 (i.e. synapse -sample 55)
+ </p>
+ <p>
+ Deploy the LoadbalanceFailoverService and start three instances of sample
+ Axis2 server as mentioned in sample 54.
+ </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
+ back ups. 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 shutdown all other servers, messages will be directed to the
+ newly started server.
+ </p>
+ <h2>
+ <a name="Sample56" id="Sample56">Sample 56:</a>
+ </h2>
+<pre xml:space="preserve"><!-- Demontrates session affinity load balancing between 3 endpoints. We are using client
+ initiated session for this sample. -->
+<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>
+ </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 load balancing with session affinity
+ using client initiated sessions</strong>
+ </p>
+ <p>
+ <strong>Pre-Requisites:</strong>
+ </p>
+ <p>
+ Start Synapse with sample configuration 56 (i.e. synapse -sample 56).
+ </p>
+ <p>
+ Deploy the LoadbalanceFailoverService and start three instances of the
+ sample Axis2 server as in sample 54.
+ </p>
+ <p/>
+ <p>
+ Above configuration is same as the load balancing configuration in sample
+ 54, 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 send it to 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 seccessive 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 continuesly sends requests with three diferent
+ 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>
[... 1573 lines stripped ...]