Modified: webservices/synapse/site/Synapse_Samples.html URL: http://svn.apache.org/viewvc/webservices/synapse/site/Synapse_Samples.html?view=diff&rev=545490&r1=545489&r2=545490 ============================================================================== --- webservices/synapse/site/Synapse_Samples.html (original) +++ webservices/synapse/site/Synapse_Samples.html Fri Jun 8 05:23:07 2007 @@ -1,25 +1,120 @@ - + Synapse Samples + @@ -29,315 +124,389 @@
-

Overview

- -

To run the samples bundled with the Synapse distribution you will need Ant -1.5 or later. Ant can be downloaded from http://ant.apache.org. The samples -now come with a built in Axis2 server to host the service endpoints used in -the samples, along with simple ant scripts to build and deploy the services -into this Axis2 instance.

- -

Starting the Axis2 Server

- -

To start the bundled Axis2 server, go to the samples/axis2Server directory -and execute the axis2server.sh or axis2server.bat script. This starts the -Axis2 server with the HTTP transport listener on port 9000.

- -

Please note that the script picks up the correct config from the AXIS2_HOME directory, so please -ensure this isn't set, or points to the samples/axis2Server directory.

- -

The sample services are available in the samples/axis2Server/src -directory. To deploy these services go the the selected directory and run -'ant'. This will build the service archive file (aar) and deploy it into the -Axis2 server. (i.e. copy it to the -samples/axis2Server/repository\services)

- -

For example, to deploy the SimpleStockQuoteService service go to the -samples/axis2Server/src/SimpleStockQuoteService and execute 'ant' without any -arguments as follows:

-
C:\Java\synapse\samples\axis2Server\src\SimpleStockQuoteService>ant
Buildfile: build.xml -... -[jar] Building jar: C:\Java\synapse\samples\axis2Server\repository\services\SimpleStockQuoteService.aar -BUILD SUCCESSFUL
- -

Descriptions of sample Services

-
    -
  1. SimpleStockQuoteService - This service has two operations, getQuote - (in/out) and placeOrder (in-only). It will generate a sample stock quote - for a given symbol.
  2. -
  3. SimpleStockQuoteService1 - This has the same functionality as the - SimpleStockQuoteService service, but exists to make available a different - service instance/EPR to demonstrating routing
  4. -
  5. SecureStockQuoteService1 - Simple stock quote service using WS-Security - with timestamps and username token authentication
  6. -
  7. SecureStockQuoteService3 - Stock quote service using WS-Security - signatures and encryption
  8. -
- -

Starting Synapse

- -

To start Synapse with the default configuration execute the synapse.bat or -synapse.sh script in the bin directory. This starts up an instance of Synapse -using the Synapse and Axis2 configuration files located at repository/conf

- -

To start specific sample configurations of Synapse, use the -sample -<number> switch as follows:
-

-
bin\synapse.bat -sample <number>
- -

The above on a Windows system will use the sample synapse.xml -configuration file located at -repository\conf\sample\synapse_sample_<number>.xml

- -

Invoking the sample clients

- -

The clients are located in the samples/axis2Client directory, and should -be executed with the ant script supplied. (e.g. ant stockquote) The ant -script expects an argument to select the client scenario to be executed. The -samples/axis2Client/client_repo directory contains an Axis2 client repository -along with the necessary modules and dependencies to make available -WS-Addressing, WS-Security (Rampart) and WS-Reliable Messaging (Sandesha2) on -the client side.

-

Message Mediation Samples

Sample 0:

+
<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>
+ 

Objective: Introduction to Synapse. Shows how a message could be made to pass through Synapse and logged before it is delivered to its ultimate receiver.

-

A client could interact with Synapse in one of three modes as follows:

+

The Stock quote client can operate in the following modes for this +example.

  1. Smart Client mode
  2. +
    ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ 
    +
  3. Using Synapse as a HTTP Proxy
  4. +
    ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dprxurl=http://localhost:8080/
    +
  5. Gateway mode / Dumb Client
  6. -

    In this mode, the client addresses its messages to the ultimate receiver - of the message using WS-Addressing, but specifies the transport URL to - Synapse. This results in the messages reaching Synapse with the - WS-Addressing information which could be used to route the message as - appropriate.

    -
  7. Synapse as a Proxy
  8. - -

    In this mode, the client sets Synapse as an HTTP Proxy but sets the - destination EPR to indicate the ultimate receiver of the message. This - forces all outgoing HTTP messages to flow into Synapse, which will then - send the messages as appropriate.

    -
  9. Dumb Client
  10. - -

    In this mode, the client expects Synapse to decide on the destination of - the message through appropriate routing rules using the content of the - message.

    +

    See sample # 1

Pre-Requisites:
-
Start the Synapse configuration numbered 0: i.e. synapse -sample +Start the Synapse configuration numbered 0: e.g. synapse -sample 0
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +deployed

-

Execute the Smart Client as 'ant stockquote'
-
Client: samples.userguide.StockQuoteClient

+

Execute the Smart Client

-

If you follow through the execution of Synapse mediation rules while -looking at the configuration used synapse_sample_0.xml you will notice that -the client request arrived at Synapse with a WS-Addressing 'To' EPR of -http://localhost:9000/axis2/services/SimpleStockQuoteService

- -

The Synapse configuration logs the message at the highest log level as the -configuration specifies the log level as 'full'. Then Synapse sends the -message using the implicit 'To' address of the message - which is -http://localhost:9000/axis2/services/SimpleStockQuoteService

- -

Then you will see on the Axis2 server console, a message similar to the -following
-

+

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.

Sat Nov 18 21:01:23 IST 2006 SimpleStockQuoteService :: Generating quote for : IBM
-

This shows that Synapse forwarded the message to the intended recepient -after logging the message and then the actual service received and processed -it. The response message generated is again received at Synapse, and flows -through the same mediation rules, which logs the message and then sends it - -this time back to the client.

- -

On the client console you should see an output similar to the following -based on the message received by the client.

+

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.

Standard :: Stock price = $95.26454380258552
-

Execute the Proxy client as 'ant proxystockquote'
-Client: samples.userguide.ProxyStockQuoteClient

+

Execute the Proxy client

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 and -would be noticable only if one looks at the source code of the example class -samples.userguide.ProxyStockQuoteClient

- -

Execute the Proxy client as 'ant proxystockquote'
-Client: samples.userguide.ProxyStockQuoteClient

- -

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 and -would be noticable only if one looks at the source code of the example class -samples.userguide.ProxyStockQuoteClient

- -

Sample 1:

+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.

+ +

Sample 1:

+
<!-- 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> 

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.

+mediation and routing based on message properties or content.

Pre-Requisites:
Start the Synapse configuration numbered 1: i.e. synapse -sample 1
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)
+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +deployed

-

Execute the Dumb Client as 'ant dumbstockquote'
-Client: samples.userguide.DumbStockQuoteClient
-

+

Execute the Dumb Client as:

+
ant stockquote -Dtrpurl=http://localhost:8080/soap/StockQuote

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, Synapse performed a match to the given path '/StockQuote' and as the -request matched the XPath expression of the filter mediator, the filter -mediators' child mediators executes, and thereby semding the message to a -different endpoint as specified by the [reusable] endpoint definition.

+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.

Sample 2:

+
<!-- 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>

Objective: Introduce switch-case mediator and writing and reading -of local properties on a message

+of local properties set on a message instance

Pre-Requisites:
Start the Synapse configuration numbered 2: i.e. synapse -sample 2
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done.

-

Execute the 'ant stockquote' request again, and by following through the -mediation rules executed 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. The message flowes through to Axis2 and then the reply -back to the client.

+

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.

+ +

ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService +-Dtrpurl=http://localhost:8080/ -Dsymbol=IBM

+
INFO LogMediator - symbol = Great stock - IBM, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService 
+ +

ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService +-Dtrpurl=http://localhost:8080/ -Dsymbol=MSFT

+
INFO LogMediator - symbol = Are you sure? - MSFT, epr = http://localhost:9000/axis2/services/SimpleStockQuoteService
+ +

Sample 3:

+
<!-- 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>
-

Sample 3:

- -

Objective: Illustrates simple properties, and reusable endpoints -and sequences

+

Objective: Illustrates local registry entry definitions, reusable +endpoints and sequences

Pre-Requisites:
Start the Synapse configuration numbered 3: i.e. synapse -sample 3
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done

-

Execute the 'ant stockquote' request again. Following through the -mediation logs you will see that once the filter and switch statments are -through, the sequence named 'stockquote' is referenced and invoked. Also the -log mediator dumps a string property, and two XPath evaluation results. The -first expression fetches a local static string lieral property named -'version'. This is a global property applicable to all messages passing -through Synapse, and available for reading from any reusable sequence or the -main rules. The second expression fetches the local message property named -'symbol' which was set within the switch mediator, using the set-property -mediator. However, for both expressions the 'get-property()' XPath extension -function has been used. This function will first look for a given property -within the local message, and if a property with the name cannot be found, it -performs a lookup over all global properties. In addition, the get-property() -function supports the special cases 'To', 'From', 'Action', 'FaultTo' and -'ReplyTo', which fetches the appropriate values from the current message -context.

+

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"

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/
+
DEBUG SequenceMediator - Sequence mediator <main> :: mediate()
DEBUG InMediator - In mediator mediate()
DEBUG SequenceMediator - Sequence mediator <stockquote> :: mediate()
+ +

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.

+
[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 

Sample 4:

+
<!-- introduction to error handling -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
 
-

Objective: Introduction to error handling with the try and -makefault mediators

+ <!-- 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>
+ +

Objective: Introduction to error handling with the 'fault' +sequence

Pre-Requisites:
Start the Synapse configuration numbered 4: i.e. synapse -sample 4
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

- -

When you execute 'ant stockquote', the default stock symbol queried is -'IBM'. However you could use the 'symbol' system property and pass it into -the above (e.g. ant stockquote -Dsymbol=MSFT) to query another symbol.

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done

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 @@ -345,162 +514,274 @@ message is shown at the client.

If you lookup a stock quote for 'MSFT', Synapse is instructed to route the -message to the endpoint defined as the 'bogus' endpoint, which tries to -deliver the message to a non existing service. Hence the method encounters a -connection exception, which gets handled by the enclosing try mediator. When -an error is encountered within the scope of a try mediator, it executes the -mediation logic specified in its 'onError' segment. In this example, the -sequence named 'errorHandler' is invoked, and it logs the error message as -well as the error detail, and then creates a custom fault message reading the -property named 'ERROR_MESSAGE' which is set on the current message by the try -mediator on encountering an exception. At the client end, you would see the -custom SOAP fault message instead of a stock quote.

+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.

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ -Dsymbol=MSFT
+
[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
+ +

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:

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ -Dsymbol=SUN
+
[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

Sample 5:

+
<definitions xmlns="http://ws.apache.org/ns/synapse">
 
-

Objective: Introduction to error handling within a sequence using -the 'onError' sequence

+ <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>
+ +

Objective: Makefault mediator and sending back error responses +

Pre-Requisites:
Start the Synapse configuration numbered 5: i.e. synapse -sample 5
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done

-

This sample demonstrates the ability to assign an existing sequence as the -error handling sequence of another. The 'onError' attribute of a sequence -calls on the named sequence specified when an exception is encountered during -the processing. You could request for IBM and MSFT quotes using the same -client and experience the same behaviour from Synapse.

+

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.

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ -Dsymbol=MSFT
+ +

Returns:

+
<soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><faultcode>soapenv:Client</faultcode>
+    <faultstring>java.net.UnknownHostException: bogus</faultstring><detail /></soapenv:Fault>
+ +

And

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ -Dsymbol=SUN
+ +

Returns:

+
<soapenv:Fault xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><faultcode>soapenv:Client</faultcode>
+    <faultstring>java.net.ConnectException: Connection refused</faultstring><detail /></soapenv:Fault>

Sample 6:

+
<definitions xmlns="http://ws.apache.org/ns/synapse">
+    <in>
+        <header name="To" value="http://localhost:9000/soap/SimpleStockQuoteService"/>
+    </in>
+    <send/>
+</definitions>
-

Objective: Introduction to header, in and out -mediators

+

Objective: Introduction to header, in (out) mediators

Pre-Requisites:
Start the Synapse configuration numbered 6: i.e. synapse -sample 6
-Start the Axis2 server and deploy the SimpleStockQuoteService1 (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done

-

In this example we use the same stockquote client which sets the 'To' EPR -of the message to the SimpleStockQuoteService service. However, if this -request is for the IBM stock, the configuration invokes the header mediator -and sets the 'To' value to the SimpleStockQuoteService1. Hence if you request -for the IBM stock, you should see the header mediator changing the -WS-Addressing header in the log message, and on the Axis2 server console you -would notice that the SimpleStockQuoteService1 service indeed received and -processed the response. You will also see that the mediation rules now use -the in and out mediators - which executes the mediators within them depending -on whether the message is an incoming request from a client, or a response -message being sent to a client from Synapse. The log message 'sending back -the response' prints only during the processing of the response message.

- -

If a request is made for any other stock, Synapse is instructed to drop -the message and hence the client will not receive any response. The drop -mediator aborts further processing of a message and may be used to discard -and reject unwanted messages.

+

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:

+
ant stockquote -Dtrpurl=http://localhost:8080/soap/SimpleStockQuoteService

Sample 7:

+
<!-- introduction of static inline XML properties and the validation mediator -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
 
-

Objective: Introduction to the extension mediators, static XML -properties and the validate mediator

+ <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>
+ +

Objective: Introduction to local (static) registry entries and the +validate mediator

Pre-Requisites:
-Download Xerces2-j 2.8.0 or later, and copy the xml-apis.jar and -xercesImpl.jar into the lib/endorsed folder
Start the Synapse configuration numbered 7: i.e. synapse -sample 7
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done

-

The validate mediator is bundled as an extension mediator as it depends on -the Xerces2-j parser for schema validation, to keep the core Synapse -distribution compact. Hence to try this example you will first need to -download the Xerces parser and place its jar files into the lib folder to -make it available to the validate mediator.

- -

This example shows how an XML fragment could be made available to Synapse -as a property. Such a property is called an inline XML property and is static -since its content never changes after initiation. Hence a Schema is made -available to the configuration as a property named 'validate_schema'.

- -

Synapse supports string, inline text, inline xml and URL source properties -which are static properties. In addition it supports dynamic registry based -properties as introduced later.

- -

In this example the request messages are filtered using a boolean XPath -expression which checks if the request is a getQuote request. If so the -'customsequence' sequence is invoked, which in-turn calls on the validate -mediator passing it the property key 'validate_schema'. The validate mediator -by default operates on the first child element of the SOAP body. You may -specify an XPath expression using an attribute 'source' to override this -behaviour. The validate mediator now uses the 'validate_schema' property to -validate the incoming message, and if the message is in error invokes on the -'on-fail' sequence of mediators.

- -

If you send a standard 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)

+

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'.

+ +

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.

+ +

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)

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/

Sample 8:

+
<!-- introduction to static and dynamic registry resources and the XSLT mediator -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
 
-

Objective: Introduction to URL source properties, registry based -properties and the XSLT mediator

+ <!-- 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>
+ +

Objective: Introduction to static and dynamic registry resources +and the XSLT mediator

Pre-Requisites:
-Download Xalan-J version 2.7.0 or later, and copy xalan.jar and -serializer.jar into the Synapse lib folder. Copy xercesImpl.jar and -xml-apis.jar (of Xerces-J) into the lib/endorsed folder.
Start the Synapse configuration numbered 8: i.e. synapse -sample 8
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done

This example uses the XSLT mediator to perform transformations, and the -xslt tranformation is specified as a property, similar to the way the a -schema was specified to the validate mediator. The first resource -'xslt-key-req' is specified by specifying its URL. The URL could be any valid -URL, for e.g. http://someserver/path/resource.xslt or a file:// URL etc. The -second resource 'xslt-key-resp' is specified using a 'key' attribute.

+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.

In this example you will notice the new 'registry' definition. Synapse -comes with a simple URL based registry called 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 -property key 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 required, the -next time the resource is requested.

+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.

Hence the second XSLT resource key 'transform/transform_back.xslt' -concatenated with the 'root' of the SimpleUTLRegistry +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 seconds.

+caches its value for a period of 15000 ms.

-

Execute the custom quote client as 'ant customquote' and check analyze the -the Synapse debug log output as shown below

-
DEBUG XSLTMediator - Transformation source :<m0:CheckPriceRequest xmlns:m0=http://www.apache-synapse.org/test>
-<m0:Code>IBM</m0:Code></m0:CheckPriceRequest>
-DEBUG XSLTMediator - Transformation result :
-<m:getQuote xmlns:m=http://services.samples/xsd>
-<m:request><m:symbol>IBM</m:symbol></m:request></m:getQuote>
+

Execute the custom quote client as 'ant stockquote -Dmode=customquote ..' +and analyze the the Synapse debug log output as shown below

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/ -Dmode=customquote
+
[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">

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, and hence the necessary Xalan-J and Xerces-J -libraries needs to be made available to Synapse. The response from the -SimpleStockQuoteService is converted into the custom format as expected by -the client during the out message processing.

+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.

During the response processing you could notice the SimpleURLRegistry -fetching the resource as shown by the debug logs below

-
INFO SimpleURLRegistry - ==> Repository fetch of resource with key : transform/transform_back.xslt
+fetching the resource as shown by the log message below

+
[HttpClientWorker-1] INFO  SimpleURLRegistry - ==> Repository fetch of resource with key : transform/transform_back.xslt

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 @@ -509,427 +790,1429 @@

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.

-

-
DEBUG AbstractRegistry - Cached object has expired for key : transform/transransform_back.xslt
-DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : transform/transform_back.xslt
-DEBUG AbstractRegistry - Expired version number is same as current version in registry
-DEBUG AbstractRegistry - Renew cache lease for another 15s
+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.

+
[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 

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

-

-
DEBUG AbstractRegistry - Cached object has expired for key : transform/transform_back.xslt
-DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : transform/transform_back.xslt
-INFO SimpleURLRegistry - ==> Repository fetch of resource with key : transform/transform_back.xslt
+
[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 

Thus the SimpleURLRegistry allows resource to be cached, and updates detected so that changes could be reloaded without restarting the Synapse instance.

-

-

Sample 9:

+
<!-- 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> 

Objective: Introduction to dynamic sequences with a Registry

Pre-Requisites:
Start the Synapse configuration numbered 9: i.e. synapse -sample 9
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done

This example introduces the dynamic behaviour of Synapse through the use -of a Registry. Synapse supports dynamic definitions for sequences, the main -rules, endpoints and as seen before resources and properties. 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 accordingly as per its registry definition. Once the cache expires, +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.

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:

-
DEBUG SequenceMediator - Sequence mediator <anonymous> :: mediate()
INFO SimpleURLRegistry - ==> Repository fetch of resource with key : sequence/dynamic_seq_1.xml
.....
INFO LogMediator - message = *** Test Message 1 ***
...
+stockquote..'. You will notice that that Synapse fetches the definition of +the sequence from the registry and executes its rules as follows:

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/
+
[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 ***

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 -now edit the 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:

-
DEBUG SequenceMediator - Sequence mediator <anonymous> :: mediate()
DEBUG AbstractRegistry - Cached object has expired for key : sequence/dynamic_seq_1.xml
DEBUG SimpleURLRegistry - Perform RegistryEntry lookup for key : sequence/dynamic_seq_1.xml
INFO SimpleURLRegistry - ==> Repository fetch of resource with key : sequence/dynamic_seq_1.xml
...
INFO LogMediator - message = *** Test Message 2 ***
...
+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:

+
[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 ***

The cache timeout could be tuned appropriately by configuring the URL registry to suite the environment and the needs.

Sample 10:

+
<!-- introduction dynamic endpoints -->
+<definitions xmlns="http://ws.apache.org/ns/synapse">
 
-

Objective: Introduction to dynamic endpoints with a + <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>

+ +

Objective: Introduction to dynamic endpoints with the Registry

Pre-Requisites:
Start the Synapse configuration numbered 10: i.e. synapse -sample 10
-Start the Axis2 server and deploy the SimpleStockQuoteService and the -SimpleStockQuoteervice1 (Refer steps above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done
+Start a second Axis2 server on http port 9001 and https port 9003 as +follows:

+
./axis2server.sh -http 9001 -https 9003

This example introduces dynamic endpoints, where the definition of an -endpoint is stored in a 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 Axis2 instance. Repeat the above example and -notice that the endpoint is cached and reused by Synapse - similarly to -example # 8.

-
SimpleStockQuoteService :: Generating quote for : IBM
+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.

+
ant stockquote -Dtrpurl=http://localhost:8080/

Now edit the repository/conf/sample/resources/endpoint/dynamic_endpt_1.xml definition and update the address to -"http://localhost:9000/axis2/services/SimpleStockQuoteService1". 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 -SimpleStockQuoteService1.

-
SimpleStockQuoteService 1 :: Generating quote for : IBM
- -

+"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.

Sample 11:

+
<!-- 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> 

Objective: A full registry based configuration

Pre-Requisites:
Start the Synapse configuration numbered 11: i.e. synapse -sample 11
-Start the Axis2 server and deploy the SimpleStockQuoteService (Refer steps -above)

+Start the Axis2 server and deploy the SimpleStockQuoteService if not already +done

-

This example shows a full registry based Synapse configuration. 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'. This could be used to host a configuration on a file system -or http server based registry, and allow a cluster of Synapse instances to -load the configuration from this registry.

- -

Using 'ant stockquote' you would notice that the 'synapse.xml' -configuration has been loaded from the root of the Simple URL based -registry.

+

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'.

+
ant stockquote -Daddurl=http://localhost:9000/soap/SimpleStockQuoteService -Dtrpurl=http://localhost:8080/
+
[HttpServerWorker-1] INFO LogMediator - message = This is a dynamic Synapse configuration
+ +

The actual synapse.xml loaded is:

+
<!-- 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>

-

WS-Security

+

Endpoints

Sample 50:

+
<!-- 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>

Objective: Connecting to endpoints with WS-Security for outgoing messages

Pre-Requisites:
-Download and copy the BouncyCastle JAR file into your Synapse lib directory. -(Note: the exact JAR you need to install depends on your JDK - for JDK 1.4 I -have used bcprov-jdk13-132.jar)
-Start the Synapse configuration numbered 50: i.e. synapse -sample 50
-Copy the Apache Rampart module (e.g. rampart-1.1-SNAPSHOT.mar) into the -modules directory of the sample Axis2 server -samples/axis2Server/repository/modules. The Rampart module could be found at -repository\modules and is not duplicated within the distributions due to its -large file size.
-Start the Axis2 server and deploy the SecureStockQuoteService3 (Refer steps -above)

+

+ +

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)

+ +

Start the Synapse configuration numbered 50: i.e. synapse -sample 50
+Start the Axis2 server and deploy the SecureStockQuoteService if not already +done

Use the stock quote client to send a request without WS-Security. Synapse -is configured to enable WS-Security policy 'policy_3.xml' to the outgoing -message when sent to the SecureStockQuoteService3 service 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 it expects.

+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:

+
ant stockquote -Dtrpurl=http://localhost:8080/
+ +

The message sent by Synapse to the secure service can be seen as follows, +when TCPMon is used.

+
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
+ +

Sample 51:

+
<!-- 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>
+ +

Objective: MTOM and SwA optimizations and request/response +correlation

+ +

Pre-Requisites:
+Start the Synapse configuration numbered 51: i.e. synapse -sample 51
+Start the Axis2 server and deploy the MTOMSwASampleService if not already +done

+ +

Execute the 'ant optimizeclient' specifying MTOM optimization as +follows:

+
ant optimizeclient -Dopt_mode=mtom
+ +

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.

+ +

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.

+
[java] Sending file : ./../../repository/conf/sample/resources/mtom/asf-logo.gif as MTOM
+
[java] Saved response to file : /tmp/mtom-36877.gif
+ +

Next try SwA as:

+
ant optimizeclient -Dopt_mode=swa
+
[java] Sending file : ./../../repository/conf/sample/resources/mtom/asf-logo.gif as SwA
+[java] Saved response to file : /tmp/swa-47549.gif
+ +

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:

+
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 >>
+
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 >>
+ +

Sample 52:

+
<!-- 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> 
+ +

Objective: POX to SOAP conversion

+ +

Pre-Requisites:
+Start the Synapse configuration numbered 52: i.e. synapse -sample 52\

+ +

Start the Axis2 server and deploy the SimpleStockQuoteService if not +already done

+ +

Execute the 'ant stockquote' specifying that the request should be a REST +request as follows:

+
ant stockquote -Dtrpurl=http://localhost:8081/soap/StockQuote -Drest=true
+ +

This example shows a http REST request (as shown below) being transformed +into a SOAP request and forwarded to the stock quote service.

+
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
+ +

Sample 53:

+
<!-- 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>
+Objective: Demonstrate the message exchange between Synapse and the +server using WS-ReliableMessaging (WS-RM) + +

Pre-Requisites:

+ +

Deploy the ReliableStockQuoteService in the sample Axis2 server by +switching to the samples/axis2Server/src/ReliableStockQuoteService directory +and running ant.

+ +

Start the sample Axis2 server on port 9000.

+ +

Start Synapse with the sample configuration 53 (i.e. synapse -sample +53).

+

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.

+
ant stockquote -Dsymbol=IBM -Dmode=quote -Daddurl=http://localhost:8080
+ +

You can observer the client output displaying the quote price for IBM as +follows:

+
[java] Standard :: Stock price = $189.2521262517493
+ +

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.

+
...
+<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>
+...
+ +

Sample Axis2 server responds to CreateSequence request with the following +message:

+
...
+<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>
+...
+ +

Once the sequence is established, Synapse sends the request to the server +with the pre-negotiated sequence ID.

+
<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>

[... 2187 lines stripped ...]


---------------------------------------------------------------------
To unsubscribe, e-mail: synapse-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: synapse-dev-help@ws.apache.org