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/22 13:56:32 UTC
svn commit: r1222210 -
/synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/mediators.xml
Author: hiranya
Date: Thu Dec 22 12:56:32 2011
New Revision: 1222210
URL: http://svn.apache.org/viewvc?rev=1222210&view=rev
Log:
Extension mediators
Modified:
synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/mediators.xml
Modified: synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/mediators.xml
URL: http://svn.apache.org/viewvc/synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/mediators.xml?rev=1222210&r1=1222209&r2=1222210&view=diff
==============================================================================
--- synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/mediators.xml (original)
+++ synapse/trunk/scratch/hiranya/website/src/site/xdoc/userguide/mediators.xml Thu Dec 22 12:56:32 2011
@@ -25,14 +25,23 @@
</ul>
</li>
<li>
- <a href="#FilterMediators">Transformation Mediators</a>
+ <a href="#TransformationMediators">Transformation Mediators</a>
<ul>
- <li><a href="#XSLT">XSLT Mediator</a></li>
- <li><a href="#XQuery">XQuery Mediator</a></li>
- <li><a href="#MakeFault">MakeFault Mediator</a></li>
<li><a href="#Header">Header Mediator</a></li>
- <li><a href="#URLRewrite">URL Rewrite Mediator</a></li>
+ <li><a href="#MakeFault">MakeFault Mediator</a></li>
<li><a href="#PayloadFactory">Payload Factory Mediator</a></li>
+ <li><a href="#URLRewrite">URL Rewrite Mediator</a></li>
+ <li><a href="#XSLT">XSLT Mediator</a></li>
+ <li><a href="#XQuery">XQuery Mediator</a></li>
+ </ul>
+ </li>
+ <li>
+ <a href="#ExtensionMediators">Extension Mediators</a>
+ <ul>
+ <li><a href="#Clazz">Class Mediator</a></li>
+ <li><a href="#POJOCommand">POJO Command Mediator</a></li>
+ <li><a href="#Script">Script Mediator</a></li>
+ <li><a href="#Spring">Spring Mediator</a></li>
</ul>
</li>
</ul>
@@ -352,58 +361,108 @@
</subsection>
</section>
<section name="Transformation Mediators" id="TransformationMediators">
- <subsection name="XSLT Mediator" id="XSLT">
- <p>
- XSLT mediator applies the specified XSLT transformation to the selected
- element of the current message payload. 'source' attribute selects the source
- element to apply the transformation on. Where not specified, it defaults to the
- first child of the SOAP body. Output of the transformation replaces the source
- element when 'target' attribute is not specified. Otherwise, the output is
- stored in the property specified by the 'target' attribute.
- </p>
- <div class="xmlConf"><xslt key="string" [source="xpath"] [target="string"]>
- <property name="string" (value="literal" | expression="xpath")/>*
- <feature name="string" value="true | false" />*
- <attribute name="string" value="string" />*
- <resource location="..." key="..."/>*
-</xslt></div>
+ <subsection name="Header Mediator" id="Header">
<p>
- If the output method specified by the stylesheet is text (i.e. the stylesheet
- has the <tt><xsl:output method="text"/></tt> directive),
- then the output of the transformation is wrapped in an element with name
- <tt>{http://ws.apache.org/commons/ns/payload}text</tt>. Note that when an
- element with this name is present as the first child of the SOAP body of an
- outgoing message, JMS and VFS transports automatically unwrap the
- content and send it out as plain text. XSLT mediator can therefore be used for
- integration with systems relying on plain text messages.
+ Header mediator sets or removes a specified header from the current SOAP
+ infoset. The optional 'action' attribute specifies whether the mediator should
+ set or remove the header. If omitted, it defaults to 'set' action.
</p>
+ <div class="xmlConf"><header name="qname" (value="literal" | expression="xpath") [action="set"]/>
+<header name="qname" action="remove"/></div>
<p>
- Usage of sub-elements of XSLT mediator configuration is as follows:
+ The value of the 'name' attribute must be one of the following aliases or
+ a valid QName with a namespace prefix. In the latter case the namespace prefix
+ must be mapped to a valid namespace URI using the standard 'xmlns' attribute.
</p>
<ul>
- <li>
- property - Stylesheet parameters can be passed into the transformations
- using 'property' elements.
- </li>
- <li>
- feature - Defines any features which should be explicitly set to the
- TransformerFactory. For example,
- <tt>'http://ws.apache.org/ns/synapse/transform/feature/dom'</tt> feature
- enables DOM based transformations instead of serializing elements into byte
- streams and/or temporary files. Although enabling this feature could improve
- performance of the transformation, it might not work for all transformations.
- </li>
- <li>
- attribute - Defines attributes which should be explicitly set on the
- TransformerFactory.
- </li>
- <li>
- resource - Can be used to resolve XSLT imports and includes from the
- repository. It works in exactly the same way as the corresponding element in
- a <proxy> definition.
- </li>
+ <li>To</li>
+ <li>From</li>
+ <li>Action</li>
+ <li>FaultTo</li>
+ <li>ReplyTo</li>
+ <li>RelatesTo</li>
</ul>
</subsection>
+ <subsection name="MakeFault Mediator" id="MakeFault">
+ <p>
+ MakeFault mediator transforms the current message into a fault message.
+ It should be noted that makeFault mediator does NOT send the message after
+ transforming it. A send mediator needs to be invoked separately to send
+ a fault message created by this mediator.
+ </p>
+ <div class="xmlConf"><makefault [version="soap11|soap12|pox"] [response="true|false"]>
+ <code (value="literal" | expression="xpath")/>
+ <reason (value="literal" | expression="xpath")/>
+ <node>...</node>?
+ <role>...</role>?
+ (<detail expression="xpath"/> | <detail>...</detail>)?
+</makefault></div>
+ <p>
+ The To header of the fault message is set to the 'Fault-To' of the original message
+ if such a header exists on the original message. Depending on the 'version'
+ attribute, the fault message is created as a SOAP 1.1, SOAP 1.2
+ or POX fault. If the optional response attribute value is set as 'true',
+ makefault mediator marks the message as a response. Optional 'node',
+ 'role' and 'detail' sub-elements in the mediator configuration can
+ be used to set the corresponding elements in the resulting SOAP fault.
+ </p>
+ </subsection>
+ <subsection name="Payload Factory Mediator" id="PayloadFactory">
+ <p>
+ Payload-factory mediator creates a new SOAP payload for the message, replacing
+ the existing one. <tt>printf()</tt> style formatting is used to configure the
+ transformation performed by this mediator.
+ </p>
+ <div class="xmlConf"><payloadFactory>
+ <format>"xmlstring"</format>
+ <args>
+ <arg (value="literal" | expression="xpath")/>*
+ </args>
+</payloadFactory></div>
+
+ <p>
+ 'format' sub-element of the mediator configuration specifies the format of the
+ new payload. All $n occurrences in the format will be replaced by the value of
+ the n th argument at runtime. Each argument in the mediator configuration could
+ be a static value or an XPath expression. When an expression is used, value is
+ fetched at runtime by evaluating the provided XPath expression against the
+ existing SOAP message/message context.
+ </p>
+ </subsection>
+ <subsection name="URL Rewrite Mediator" id="URLRewrite">
+ <p>
+ URL Rewrite mediator can be used to modify and transform the URL values
+ available in the message. By default, this mediator takes the 'To' header of the
+ message and apples the provided rewrite rules on it. Alternatively, one can
+ specify a property name in the 'inProperty' attribute, in which case the
+ mediator takes the value of the specified property as the input URL.
+ </p>
+ <p>
+ Similarly the mediator by default sets the transformed URL as the 'To' header of
+ the message and alternatively you can use the 'outProperty' attribute to
+ instruct the mediator to set the resulting URL as a property.
+ </p>
+ <div class="xmlConf"><rewrite [inProperty="string"] [outProperty="string"]>
+ <rewriterule>
+ <condition>
+ ...
+ </condition>?
+ <action [type="append|prepend|replace|remove|set"] [value="string"]
+ [xpath="xpath"] [fragment="protocol|host|port|path|query|ref|user|full"] [regex="regex"]>+
+ </rewriterule>+
+</rewrite></div>
+ <p>
+ The mediator applies URL transformations by evaluating a set of rules on
+ the message. Rules are specified using the 'rewriterule' element. Rules are
+ evaluated in the order in which they are specified. A rule can consist of an
+ optional condition and one or more rewrite actions. If the condition is provided,
+ it is evaluated first and specified rewrite actions are executed only if the
+ condition evaluates to true. If no condition is specified, the provided rewrite
+ actions will be always executed. The condition should be wrapped in a 'condition'
+ element within the 'rewriterule' element. Rewrite actions are specified using
+ 'action' elements.
+ </p>
+ </subsection>
<subsection name="XQuery Mediator" id="XQuery">
<p>
The XQuery mediator can be used to perform an XQuery transformation. 'key'
@@ -466,106 +525,190 @@
</li>
</ul>
</subsection>
- <subsection name="MakeFault Mediator" id="MakeFault">
- <p>
- MakeFault mediator mediator transforms the current message into a fault message.
- It should be noted that makeFault mediator does NOT send the message after
- transforming it. A <send> mediator needs to be invoked separately to send
- a fault message created by this mediator.
- </p>
- <div class="xmlConf"><makefault [version="soap11|soap12|pox"] [response="true|false"]>
- <code (value="literal" | expression="xpath")/>
- <reason (value="literal" | expression="xpath")/>
- <node>...</node>?
- <role>...</role>?
- (<detail expression="xpath"/> | <detail>...</detail>)?
-</makefault></div>
+ <subsection name="XSLT Mediator" id="XSLT">
<p>
- The fault message "To" header is set to the "Fault-To" of the original message
- if such a header exists on the original message. Depending on the 'version'
- attribute, the fault message is created as a SOAP 1.1, SOAP 1.2
- or POX fault. If the optional response attribute value is set as 'true',
- makefault mediator marks the message as a response. Optional <node>,
- <role> and <detail> subelements in the mediator configuration can
- be used to set the corresponding elements in the resulting SOAP fault.
+ XSLT mediator applies the specified XSLT transformation to the selected
+ element of the current message payload. 'source' attribute selects the source
+ element to apply the transformation on. Where not specified, it defaults to the
+ first child of the SOAP body. Output of the transformation replaces the source
+ element when 'target' attribute is not specified. Otherwise, the output is
+ stored in the property specified by the 'target' attribute.
</p>
- </subsection>
- <subsection name="Header Mediator" id="Header">
+ <div class="xmlConf"><xslt key="string" [source="xpath"] [target="string"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+ <feature name="string" value="true | false" />*
+ <attribute name="string" value="string" />*
+ <resource location="..." key="..."/>*
+</xslt></div>
<p>
- Header mediator sets or removes a specified header from the current SOAP
- infoset. The optional 'action' attribute specifies whether the mediator should
- set or remove the header. If omitted, it defaults to set action.
+ If the output method specified by the stylesheet is text (i.e. the stylesheet
+ has the <tt><xsl:output method="text"/></tt> directive),
+ then the output of the transformation is wrapped in an element with name
+ <tt>{http://ws.apache.org/commons/ns/payload}text</tt>. Note that when an
+ element with this name is present as the first child of the SOAP body of an
+ outgoing message, JMS and VFS transports automatically unwrap the
+ content and send it out as plain text. XSLT mediator can therefore be used for
+ integration with systems relying on plain text messages.
</p>
- <div class="xmlConf"><header name="qname" (value="literal" | expression="xpath") [action="set"]/>
-<header name="qname" action="remove"/></div>
<p>
- The value of the 'name' attribute must be one of the following aliases or
- a valid QName with a namespace prefix. In the latter case the namespace prefix
- must be mapped to a valid namespace URI using the standard xmlns attribute.
+ Usage of sub-elements of XSLT mediator configuration is as follows:
</p>
<ul>
- <li>To</li>
- <li>From</li>
- <li>Action</li>
- <li>FaultTo</li>
- <li>ReplyTo</li>
- <li>RelatesTo</li>
+ <li>
+ property - Stylesheet parameters can be passed into the transformations
+ using 'property' elements.
+ </li>
+ <li>
+ feature - Defines any features which should be explicitly set to the
+ TransformerFactory. For example,
+ <tt>'http://ws.apache.org/ns/synapse/transform/feature/dom'</tt> feature
+ enables DOM based transformations instead of serializing elements into byte
+ streams and/or temporary files. Although enabling this feature could improve
+ performance of the transformation, it might not work for all transformations.
+ </li>
+ <li>
+ attribute - Defines attributes which should be explicitly set on the
+ TransformerFactory.
+ </li>
+ <li>
+ resource - Can be used to resolve XSLT imports and includes from the
+ repository. It works in exactly the same way as the corresponding element in
+ a <proxy> definition.
+ </li>
</ul>
</subsection>
- <subsection name="URL Rewrite Mediator" id="URLRewrite">
- <p>
- URL Rewrite mediator can be used to modify and transform the URL values
- available in the message. By default, this mediator takes the 'To' header of the
- message and apples the provided rewrite rules on it. Alternatively, one can
- specify a property name in the 'inProperty' attribute, in which case the
- mediator takes the value of the specified property as the input URL.
- </p>
- <p>
- Similarly the mediator by default sets the transformed URL as the 'To' header of
- the message and alternatively you can use the 'outProperty' attribute to
- instruct the mediator to set the resulting URL as a property.
- </p>
- <div class="xmlConf"><rewrite [inProperty="string"] [outProperty="string"]>
- <rewriterule>
- <condition>
- ...
- </condition>?
- <action [type="append|prepend|replace|remove|set"] [value="string"]
- [xpath="xpath"] [fragment="protocol|host|port|path|query|ref|user|full"] [regex="regex"]>+
- </rewriterule>+
-</rewrite></div>
- <p>
- The mediator applies URL transformations by evaluating a set of rules on
- the message. Rules are specified using the 'rewriterule' element. Rules are
- evaluated in the order in which they are specified. A rule can consist of an
- optional condition and one or more rewrite actions. If the condition is provided,
- it is evaluated first and specified rewrite actions are executed only if the
- condition evaluates to true. If no condition is specified, the provided rewrite
- actions will be always executed. The condition should be wrapped in a 'condition'
- element within the 'rewriterule' element. Rewrite actions are specified using
- 'action' elements.
- </p>
- </subsection>
- <subsection name="Payload Factory Mediator" id="PayloadFactory">
- <p>
- Payload-factory mediator creates a new SOAP payload for the message, replacing
- the existing one. <tt>printf()</tt> style formatting is used to configure the
- transformation performed by this mediator.
- </p>
- <div class="xmlConf"><payloadFactory>
- <format>"xmlstring"</format>
- <args>
- <arg (value="literal" | expression="xpath")/>*
- </args>
-</payloadFactory></div>
-
+ </section>
+ <section name="Extension Mediators" id="ExtensionMediators">
+ <subsection name="Class Mediator" id="Clazz">
<p>
- 'format' sub-element of the mediator configuration specifies the format of the
- new payload. All $n occurrences in the format will be replaced by the value of
- the n th argument at runtime. Each argument in the mediator configuration could
- be a static value or an XPath expression. When an expression is used, value is
- fetched at runtime by evaluating the provided XPath expression against the
- existing SOAP message/message context.
+ The class mediator makes it possible to use a custom class as a mediator. The
+ class must implement the org.apache.synapse.api.Mediator interface. If any properties are
+ specified, the corresponding setter methods are invoked on the class,
+ once, during initialization.
+ </p>
+ <div class="xmlConf"><class name="class-name">
+ <property name="string" value="literal">
+ (either literal or XML child)
+ </property>
+</class></div>
+ <p>
+ This mediator creates an instance of a specified class and sets it as a
+ mediator. If any properties are specified, the corresponding setter methods are
+ invoked on the class with the given values, once, during initialization.
+ </p>
+ </subsection>
+ <subsection name="POJO Command Mediator" id="POJOCommand">
+ <p>
+ POJO Command mediator implements the popular Command design pattern and can be
+ used to invoke an object which encapsulates a method call.
+ </p>
+ <div class="xmlConf"><pojoCommand name="class-name">
+ (
+ <property name="string" value="string"/> |
+ <property name="string" context-name="literal" [action=(ReadContext | UpdateContext | ReadAndUpdateContext)]>
+ (either literal or XML child)
+ </property> |
+ <property name="string" expression="xpath" [action=(ReadMessage | UpdateMessage | ReadAndUpdateMessage)]/>
+ )*
+</pojoCommand></div>
+ <p>
+ POJO Command mediator creates an instance of the specified command class,
+ which may implement the org.apache.synapse.Command interface or should have a
+ method with "public void execute()" signature. If any properties are specified,
+ the corresponding setter methods are invoked on the class before each message is
+ executed. It should be noted that a new instance of the POJO Command class is
+ created to process each message processed. After execution of the POJO Command
+ mediator, depending on the 'action' attribute of the property, the new value
+ returned by a call to the corresponding getter method is stored back to the
+ message or to the context. The 'action' attribute may specify whether this
+ behaviour is expected or not via the Read, Update and ReadAndUpdate values.
+ </p>
+ </subsection>
+ <subsection name="Script Mediator" id="Script">
+ <p>
+ Synapse supports mediators implemented in a variety of scripting languages such
+ as JavaScript, Python and Ruby. There are two ways of defining a script mediator,
+ either with the script program statements stored in a separate file which is
+ referenced via the local or remote registry entry, or with the script program
+ statements embedded in-line within the Synapse configuration. A script mediator
+ using a script off the registry (local or remote) is defined as follows:
+ </p>
+ <div class="xmlConf"><script key="string" language="string" [function="script-function-name"]/></div>
+ <p>
+ The property key is the registry key to load the script. The language
+ attribute specifies the scripting language of the script code (e.g. "js"
+ for Javascript, "rb" for ruby, "groovy" for Groovy, "py" for Python..).
+ The function is an optional attribute defining the name of the script
+ function to invoke, 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, and the script mediator returns this value. An
+ inline script mediator has the script source embedded in the configuration
+ as follows:
+ </p>
+ <div class="xmlConf"><script language="string">...script source code...<script/></div>
+ <p>
+ If the specified script calls a function defined in another script, then the
+ latter script should also be included in the script mediator configuration.
+ It's done using the 'include' sub-element of the mediator configuration. The key
+ attribute of the 'include' element should point to the script which has to be
+ included. The included script could be stored as a local entry or in the remote
+ registry. Script includes are defined as follows:
+ </p>
+ <div class="xmlConf"><script key="string" language="string" [function="script-function-name"]>
+ <include key="string"/>
+</script></div>
+ <p>
+ The execution context environment of the script has access to the Synapse
+ MessageContext predefined in a script variable named 'mc' . 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>
+ <div class="xmlConf"><script language="js">mc.getPayloadXML()..symbol != "IBM";<script/></div>
+ <p>
+ Synapse uses the Apache
+ <a href="http://jakarta.apache.org/bsf/">Bean Scripting Framework</a>
+ for the scripting 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. For both types of script mediator definition the
+ MessageContext passed into 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
+ getPayloadXML and setPayloadXML, E4X XML objects, and when using Ruby,
+ REXML documents.
+ </p>
+ <p>
+ The complete list of available methods can be found in the
+ <a href="apidocs/org/apache/synapse/mediators/bsf/ScriptMessageContext.html">
+ ScriptMessageContext Javadoc</a>.
+ </p>
+ </subsection>
+ <subsection name="Spring Mediator" id="Spring">
+ <p>
+ The Spring mediator exposes a spring bean as a mediator. In other terms, it
+ creates an instance of a mediator, which is managed by Spring. This Spring bean
+ must implement org.apache.synapse.api.Mediator interface.
+ </p>
+ <div class="xmlConf"><spring:spring bean="string" key="string" xmlns:spring="http://ws.apache.org/ns/synapse/spring"/></div>
+ <p>
+ 'key' attribute refers to the Spring ApplicationContext/Configuration
+ (i.e. spring configuration XML) used for the bean. This key can be a registry
+ key or local entry key. The bean attribute is used for looking up a Spring bean
+ from the spring Application Context. Therefore, a bean with same name must be in
+ the given spring configuration. In addition to that, that bean must implement
+ the Mediator interface.
</p>
</subsection>
</section>