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>
