Author: asankha
Date: Tue Dec 19 01:02:38 2006
New Revision: 488592
URL: http://svn.apache.org/viewvc?view=rev&rev=488592
Log:
update for set-property change to allow scope
Modified:
incubator/synapse/trunk/java/src/site/resources/Synapse_Configuration_Language.html
Modified:
incubator/synapse/trunk/java/src/site/resources/Synapse_Configuration_Language.html
URL:
http://svn.apache.org/viewvc/incubator/synapse/trunk/java/src/site/resources/Synapse_Configuration_Language.html?view=diff&rev=488592&r1=488591&r2=488592
==============================================================================
---
incubator/synapse/trunk/java/src/site/resources/Synapse_Configuration_Language.html
(original)
+++
incubator/synapse/trunk/java/src/site/resources/Synapse_Configuration_Language.html
Tue Dec 19 01:02:38 2006
@@ -200,12 +200,12 @@
<p>The send token represents a <send> element. The <send> element
is used to send messages out of Synapse to some endpoint, and stop further
-mediation of the message. The send mediator also copies any message context
-properties named "correlate/*" from the current message context to the reply
+mediation of the message. The send mediator also copies any correlation
+message context properties from the current message context to the reply
message received on the execution of the send operation. This allows the
reply messages to be correlated to the original messages in a flexible
manner. Messages may be correlated by WS-A MessageID, or even simple custom
-text labels. See example 1 for more details.</p>
+text labels. Also see the set-property mediator.</p>
<p>In the simplest case, the place to send the message to is implicit in the
message (via a property of the message itself)- that is indicated by the
@@ -364,13 +364,15 @@
core will remain simple and lightweight.</p>
<h4>Properties</h4>
-<pre> <set-property name="string" (value="literal" |
expression="xpath")/></pre>
+<pre> <set-property name="string" (value="literal" | expression="xpath")
[scope=correlate|axis2]/></pre>
<p>The setproperty token refers to a <set-property> element which is a
mediator that has no direct impact on the message but rather on the message
context flowing through Synapse. The properties thus set on the message
context applies only to the current message and can be later retrieved
-through the synapse:get-property(prop-name) extension function.</p>
+through the synapse:get-property(prop-name) extension function. If a scope is
+specified for a property, the property could be set as a correlation property
+or an (underlying) Axis2 message context property.</p>
<h4>Try</h4>
<pre> <try>
@@ -438,433 +440,67 @@
<h4>Script Language Mediators</h4>
-<p>
-Synapse supports Mediators implemented in a variety of scripting languages
such as JavaScript, Python or Ruby.
+<p>Synapse supports Mediators implemented in a variety of scripting languages
+such as JavaScript, Python or Ruby.</p>
-<p>There are two ways of defining script mediators, either with the script
program statements stored in a separate file which is referenced via a Synapse
property, or with the script program statements embedded in-line within the
Synapse configuration.</p>
-<p>
-A script mediator using a registry property is defined as follows:
-<p>
-<pre>
- <script key="property-key"
[function="script-function-name"]/>
-</pre>
-<p>
-The property-key is a Synapse registry property containing a URL to the script
source. The function is an
-optional attribute defining the name of the script function to call, if not
specified it
-defaults to a function named 'mediate'. The function is passed a single
parameter which is the
-Synapse MessageContext. The function may return a boolean, if it does not then
true is assumed.
-The language the script is written in is determined from the file name suffix
of the property key value.
-<p>
-An inline script mediator has the script source embedded in the config XML:
-<pre>
- <script.LL>...script source code...<script.LL/>
-</pre>
-<p>
-where LL is the script language name extension. For example, script.js
indicates a JavaScript program, script.rb a Ruby program, or script.py a Python
program.
-The environment of the script has the Synapse MessageContext predefined in a
script variable named 'mc'.
-<p>
-An example of an inline mediator using JavaScript/E4X which returns false if
the SOAP message
-body contains an element named 'symbol' which has a value of 'IBM' would be:
-<p>
-<pre>
- <script.js>mc.getPayloadXML()..symbol != "IBM";<script.js/>
-</pre>
-<p>
-The boolean response from the inlined mediator is either the response from the
evaluation of the
-script statements or if that result is not a boolean then a response of true
is assumed.
-<p>
-Synapse uses the Apache <a href="http://jakarta.apache.org/bsf/";>Bean
Scripting Framework</a> for the script language
-support, any script language supported by BSF may be used to implement a
Synapse Mediator.
-<p>
-Implementing a Mediator with a script language can have advantages over using
the built in Synapse Mediator types or implementing a custom Java class
Mediator.
-Script Mediators have all the flexibility of a class Mediator with access to
the Synapse MessageContext and SynapseEnvironment APIs, and
-the ease of use and dynamic nature of scripting languages allows rapid
development and prototyping of custom mediators. An additional
-benefit of some scripting languages is that they have very simple and elegant
XML manipulation capabilities, for example JavaScript E4X or Ruby REXML,
-so this makes them well suited for use in the Synapse mediation environment.
-<p>
-For both types of script mediator definition the MessageContext passed in to
the script
-has additional methods over the standard Synapse MessageContext to enable
working with the XML
-in a way natural to the scripting language. For example when using JavaScript
get/setPayloadXML
-use E4X XML objects, when using Ruby they use REXML documents.
+<p>There are two ways of defining script mediators, either with the script
+program statements stored in a separate file which is referenced via a
+Synapse property, or with the script program statements embedded in-line
+within the Synapse configuration.</p>
+
+<p>A script mediator using a registry property is defined as follows:</p>
<p></p>
+<pre> <script key="property-key"
[function="script-function-name"]/></pre>
+
+<p>The property-key is a Synapse registry property containing a URL to the
+script source. The function is an optional attribute defining the name of the
+script function to call, if not specified it defaults to a function named
+'mediate'. The function is passed a single parameter which is the Synapse
+MessageContext. The function may return a boolean, if it does not then true
+is assumed. The language the script is written in is determined from the file
+name suffix of the property key value.</p>
+
+<p>An inline script mediator has the script source embedded in the config
+XML:</p>
+<pre> <script.LL>...script source code...<script.LL/></pre>
+
+<p>where LL is the script language name extension. For example, script.js
+indicates a JavaScript program, script.rb a Ruby program, or script.py a
+Python program. The environment of the script has the Synapse MessageContext
+predefined in a script variable named 'mc'.</p>
+
+<p>An example of an inline mediator using JavaScript/E4X which returns false
+if the SOAP message body contains an element named 'symbol' which has a value
+of 'IBM' would be:</p>
-<h2>Examples</h2>
+<p></p>
+<pre> <script.js>mc.getPayloadXML()..symbol !=
"IBM";<script.js/></pre>
-<p>The following illustrates the hypothetical example used to illustrate the
-new Synapse configuration language syntax. However, features such as load
-balancing and failover etc are still not available with Synapse.</p>
-
-<p>The sample configuration presented below applies in the following
-hypothetical scenario. Assume that two web service endpoints exists, where
-registration requests could be processed. Requests may fall into Gold and
-Silver categories, and a specialized endpoint exists to process the Gold
-requests. If the Gold endpoint cannot be reached for whatever reason,
-requests should be processed via the Silver endpoint (i.e. failover).</p>
-
-<p>Once message arrive at Synapse, the 'to' address is looked up and
-different mediation rules applied depending on it. For registration messages,
-first we need to validate the incoming message against a schema, and if the
-validation fails, a log entry should be made and a fault reply should be sent
-back. For valid messages, we determine its category and attempt to use the
-Gold endpoint, failing which the Silver endpoint is tried. For requests that
-does not fall into the Gold category the default silver endpoint is used
-always.</p>
-<pre> <synapse>
- <definitions>
- <sequence name="registration_flow">
- <validate schema="http://registry/xsd/registration.xsd";
source="//regRequest">
- <on-fail>
- <set-property name="error-code" value="100"/>
- <set-property name="error-reason" value="validation failed"/>
- <sequence ref="fault_flow"/>
- </on-fail>
- </validate>
- <filter xpath="/[EMAIL PROTECTED]'GOLD']">
- <send>
- <failover>
- <endpoint ref="gold_registration"/>
- <endpoint ref="silver_registration"/>
- </failover>
- </send>
- <filter>
- <send>
- <endpoint ref="silver_registration"/>
- </send>
- <sequence>
-
- <sequence name="fault_flow">
- <log level="simple">
- <property name="application"
value="synapse:get-property('reg-app')"/>
- </log>
- <makefault version="soap11">
- <code value="synapse:get-property('error-code')"/>
- <reason expression="synapse:get-property('error-reason')">
- <makefault>
- <send/>
- <sequence>
-
- <endpoint name="gold_registration"
address="http://gold/registration"/>
- <endpoint name="silver_registration"
address="http://silver/registration"/>
-
- <set-property name="reg_app" value="Registration Application"/>
- </definitions>
-
- <rules>
- <switch source="synapse:get-property('to')">
- <case regex="/registration">
- <sequence ref="registration_flow"/>
- </case>
- <case regex="someother">
- ...
- </case>
- <default>
- <drop/>
- </default>
- <switch>
- </rules>
-
-</synapse> </pre>
-
-<h3>Example 0.</h3>
-<pre><synapse xmlns="http://ws.apache.org/ns/synapse">
-
- <definitions>
-
- <sequence name="stockquote">
- <!-- set the To address to the real endpoint -->
- <header name="To"
value="http://ws.invesbot.com/stockquotes.asmx"/>
-
- <!-- check if the symbol is MSFT -->
- <filter xpath="//*[wsx:symbol='MSFT']"
xmlns:wsx="http://ws.invesbot.com/">
- <!-- if it is throw a fault -->
- <makefault>
- <code value="tns:Receiver"
- xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
- <reason value="Isn't there a Windows API for
that?"/>
- </makefault>
- </filter>
- </sequence>
-
- </definitions>
-
- <rules>
- <!-- now log the message using log4j -->
- <log level="full"/>
-
- <!-- Check if the URL matches the stockquote gateway/dumb case
-->
- <filter source="get-property('To')" regex=".*/StockQuote.*">
- <sequence ref="stockquote"/>
- </filter>
-
- <!-- check if the URL matches the virtual url - either the proxy
or ws-add case -->
- <filter source="get-property('To')"
regex="http://.*stockquotes.*">
- <sequence ref="stockquote"/>
- </filter>
-
- <!-- send the message on -->
- <send/>
- </rules>
-
-</synapse> </pre>
-
-<p>The above configuration is available with the Synapse distribution and
-illustrates the usual Stock quote examples. The client code for these are
-available with the Synapse samples, and the README.txt of the samples defines
-these in detail.</p>
-
-<h3>Example 1.</h3>
-<pre><synapse xmlns="http://ws.apache.org/ns/synapse">
-
- <definitions>
-
- <sequence name="customrequest">
- <!-- set the To address to the real endpoint -->
- <header name="To"
value="http://ws.invesbot.com/stockquotes.asmx"/>
-
- <!-- set correlation field to custom label -->
- <set-property name="correlate/label" value="customquote"/>
-
- <!-- transform the custom quote into a standard quote requst
-->
- <transform
xslt="file:synapse_repository/conf/sample/transform.xslt"/>
-
- <!-- send message to real endpoint and stop -->
- <send/>
- </sequence>
-
- <sequence name="customresponse">
- <!-- transform the custom quote into a standard quote requst
-->
- <transform
xslt="file:synapse_repository/conf/sample/transform_back.xslt"/>
-
- <!-- now send the custom response back to the client and stop
-->
- <send/>
- </sequence>
-
- <sequence name="stockquote">
- <!-- set the To address to the real endpoint -->
- <header name="To"
value="http://ws.invesbot.com/stockquotes.asmx"/>
-
- <!-- check if the symbol is MSFT -->
- <filter xpath="//*[wsx:symbol='MSFT']"
xmlns:wsx="http://www.webserviceX.NET/">
- <!-- if it is throw a fault -->
- <makefault>
- <code value="tns:Receiver"
xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
- <reason value="Isn't there a Windows API for
that?"/>
- </makefault>
- </filter>
-
- <send/>
- </sequence>
-
- <sequence name="standardrequest">
- <!-- now log the message using log4j -->
- <log level="full"/>
-
- <!-- Check if the URL matches the stockquote gateway/dumb
case -->
- <filter source="get-property('To')"
regex=".*/StockQuote.*">
- <sequence ref="stockquote"/>
- </filter>
-
- <!-- check if the URL matches the virtual url -
- either the proxy or ws-add case -->
- <filter source="get-property('To')"
regex="http://stockquote.*">
- <sequence ref="stockquote"/>
- </filter>
-
- <!-- send the message on -->
- <send/>
- </sequence>
-
- </definitions>
-
- <rules>
- <in>
- <!-- is this a custom stock quote message? -->
- <filter xpath="//m0:CheckPriceRequest"
- xmlns:m0="http://www.apache-synapse.org/test">
- <sequence ref="customrequest"/>
- </filter>
-
- <!-- else, proceed as usual with the standard processing
rules -->
- <sequence ref="standardrequest"/>
- </in>
-
- <out>
- <!-- is this a custom stock quote reply? -->
- <filter source="get-property('correlate/label')"
regex="customquote">
- <sequence ref="customresponse"/>
- </filter>
-
- <!-- just let the message flow through -->
- <send/>
- </out>
- </rules>
-
-</synapse> </pre>
-
-<p>This example illustrates the correlation of incoming and outgoing messages
-and the use of the <in> and <out> mediators that simplify the
-mediation configuration. This example also shows how an XSLT transformation
-of a message may be performed on receipt or reply, and also how a SOAP fault
-message may be created when required.</p>
-
-<h3>Example 2.</h3>
-<pre><synapse xmlns="http://ws.apache.org/ns/synapse">
-
- <definitions>
-
- <!-- define global properties -->
- <set-property name="version" value="0.1"/>
-
- <!-- define a reuseable endpoint definition and use it within
config -->
- <endpoint name="invesbot"
address="http://ws.invesbot.com/stockquotes.asmx"/>
-
- <sequence name="customrequest">
- <!-- is this a valid custom request ? -->
- <validate
schema="file:synapse_repository/conf/sample/validate.xsd">
- <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>
-
- <!-- send the fault and stop processing -->
- <send/>
- </on-fail>
- </validate>
-
- <switch source="//m0:CheckPriceRequest/m0:Code"
- xmlns:m0="http://www.apache-synapse.org/test">
- <case regex="IBM">
- <set-property name="symbol" value="Great stock
- IBM"/>
- </case>
- <case regex="MSFT">
- <set-property name="symbol" value="Are you sure? -
MSFT"/>
- </case>
- <default>
- <set-property name="symbol"
- expression="fn:concat('Normal Stock - ',
//m0:CheckPriceRequest/m0:Code)"
- xmlns:m0="http://www.apache-synapse.org/test"/>
- </default>
- </switch>
-
- <!-- set a dynamic (local) message property -->
-
-
- <!-- set correlation field to custom label -->
- <set-property name="correlate/label" value="customquote"/>
-
- <!-- transform the custom quote into a standard quote requst
-->
- <transform
xslt="file:synapse_repository/conf/sample/transform.xslt"/>
-
- <log level="custom">
- <property name="Text" value="Sending quote request"/>
- <property name="version"
expression="get-property('version')"/>
- <property name="symbol"
expression="get-property('symbol')"/>
- </log>
-
- <!-- send message to real endpoint referenced by name
"invesbot" and stop -->
- <send>
- <endpoint ref="invesbot"/>
- </send>
- </sequence>
-
- <sequence name="customresponse">
- <!-- transform the custom quote into a standard quote requst
-->
- <transform
xslt="file:synapse_repository/conf/sample/transform_back.xslt"/>
-
- <!-- now send the custom response back to the client and stop
-->
- <send/>
- </sequence>
-
- <sequence name="stockquote">
- <!-- set the To address to the real endpoint -->
- <header name="To"
value="http://ws.invesbot.com/stockquotes.asmx"/>
-
- <!-- check if the symbol is MSFT -->
- <filter xpath="//*[wsx:symbol='MSFT']"
xmlns:wsx="http://www.webserviceX.NET/">
- <!-- if it is throw a fault -->
- <makefault>
- <code value="tns:Receiver"
- xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
- <reason value="Isn't there a Windows API for
that?"/>
- </makefault>
- </filter>
-
- <send/>
- </sequence>
-
- <sequence name="standardrequest">
- <!-- now log the message using log4j -->
- <log level="full"/>
-
- <!-- Check if the URL matches the stockquote gateway/dumb
case -->
- <filter source="get-property('To')"
regex=".*/StockQuote.*">
- <sequence ref="stockquote"/>
- </filter>
-
- <!-- check if the URL matches the virtual url - either
the proxy or ws-add case -->
- <filter source="get-property('To')"
regex="http://stockquote.*">
- <sequence ref="stockquote"/>
- </filter>
-
- <!-- send the message on -->
- <send/>
- </sequence>
-
- </definitions>
-
- <rules>
- <in>
- <!-- is this a custom stock quote message? -->
- <filter xpath="//m0:CheckPriceRequest"
xmlns:m0="http://www.apache-synapse.org/test">
- <sequence ref="customrequest"/>
- </filter>
-
- <!-- else, proceed as usual with the standard processing
rules -->
- <sequence ref="standardrequest"/>
- </in>
-
- <out>
- <!-- is this a custom stock quote reply? -->
- <filter source="get-property('correlate/label')"
regex="customquote">
- <sequence ref="customresponse"/>
- </filter>
-
- <!-- just let the message flow through -->
- <send/>
- </out>
- </rules>
-
-</synapse> </pre>
-
-<p>This example adds onto the example 2 shown above and shows how the
-validate mediator could be used to perform message validation. This also
-illustrates the use of custom properties with the log mediator, global
-properties and message context properties and how they may be queried via the
-synapse:get-property(name) XPath extension function. See the Synapse samples
-for more information on this example and to try it out for real with the
-given test client. You will need to place the Xerces 2.8.0 jars into your
-<JAVA_HOME>/lib/endorsed directory, and the synapse-extensions.jar into
-the <SYNAPSE>/lib folder for this excersice as the validation mediator
-extension is dependent on the Xerces parser.</p>
-
-<h3>Example 3.</h3>
-<pre><synapse xmlns="http://ws.apache.org/ns/synapse";
xmlns:spring="http://ws.apache.org/ns/synapse/spring">
- <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
- <property name="root" value="file:./../../repository/"/>
- <property name="cachableDuration" value="15000"/>
- </registry>
- <definitions>
- <set-property name="springconfig1"
key="conf/sample/springsample.xml"/>
- <set-property name="springconfig2"
src="conf/sample/springsample.xml"/>
- </definitions>
- <rules>
- <spring:spring bean="springtest" key="springconfig1"/>
- <spring:spring bean="springtest" key="springconfig2"/>
- </rules>
-</synapse> </pre>
+<p>The boolean response from the inlined mediator is either the response from
+the evaluation of the script statements or if that result is not a boolean
+then a response of true is assumed.</p>
+
+<p>Synapse uses the Apache <a href="http://jakarta.apache.org/bsf/";>Bean
+Scripting Framework</a> for the script language support, any script language
+supported by BSF may be used to implement a Synapse Mediator.</p>
+
+<p>Implementing a Mediator with a script language can have advantages over
+using the built in Synapse Mediator types or implementing a custom Java class
+Mediator. Script Mediators have all the flexibility of a class Mediator with
+access to the Synapse MessageContext and SynapseEnvironment APIs, and the
+ease of use and dynamic nature of scripting languages allows rapid
+development and prototyping of custom mediators. An additional benefit of
+some scripting languages is that they have very simple and elegant XML
+manipulation capabilities, for example JavaScript E4X or Ruby REXML, so this
+makes them well suited for use in the Synapse mediation environment.</p>
+
+<p>For both types of script mediator definition the MessageContext passed in
+to the script has additional methods over the standard Synapse MessageContext
+to enable working with the XML in a way natural to the scripting language.
+For example when using JavaScript get/setPayloadXML use E4X XML objects, when
+using Ruby they use REXML documents.</p>
+
+<p></p>
</body>
</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
