Added: synapse/site/3_0_2/userguide/mediators.html URL: http://svn.apache.org/viewvc/synapse/site/3_0_2/userguide/mediators.html?rev=1909775&view=auto ============================================================================== --- synapse/site/3_0_2/userguide/mediators.html (added) +++ synapse/site/3_0_2/userguide/mediators.html Fri May 12 16:09:34 2023 @@ -0,0 +1,1603 @@ +<!DOCTYPE html> +<!-- + | Generated by Apache Maven Doxia Site Renderer 1.7.4 at 2023-05-04 + | Rendered using Apache Maven Fluido Skin 1.6 +--> +<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en" lang="en"> + <head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta name="Date-Revision-yyyymmdd" content="20230504" /> + <meta http-equiv="Content-Language" content="en" /> + <title>Apache Synapse – Apache Synapse - Mediators Catalog</title> + <link rel="stylesheet" href="../css/apache-maven-fluido-1.6.min.css" /> + <link rel="stylesheet" href="../css/site.css" /> + <link rel="stylesheet" href="../css/print.css" media="print" /> + <script type="text/javascript" src="../js/apache-maven-fluido-1.6.min.js"></script> + </head> + <body class="topBarDisabled"> + <div class="container-fluid"> + <div id="banner"> + <div class="pull-left"><div id="bannerLeft"><h2>Apache Synapse</h2> +</div> +</div> + <div class="pull-right"></div> + <div class="clear"><hr/></div> + </div> + + <div id="breadcrumbs"> + <ul class="breadcrumb"> + <li id="publishDate">Last Published: 2023-05-04<span class="divider">|</span> +</li> + <li id="projectVersion">Version: 3.0.2</li> + </ul> + </div> + <div class="row-fluid"> + <div id="leftColumn" class="span2"> + <div class="well sidebar-nav"> +<ul class="nav nav-list"> + <li class="nav-header">Main Menu</li> + <li><a href="../index.html" title="Home"><span class="none"></span>Home</a> </li> + <li><a href="../download.html" title="Download"><span class="none"></span>Download</a> </li> + <li><a href="../history.html" title="History"><span class="none"></span>History</a> </li> + <li><a href="http://www.apache.org/licenses/LICENSE-2.0"; class="externalLink" title="License"><span class="none"></span>License</a> </li> + <li><a href="http://www.apache.org/foundation/thanks.html"; class="externalLink" title="Thanks"><span class="none"></span>Thanks</a> </li> + <li><a href="http://www.apache.org/foundation/sponsorship.html"; class="externalLink" title="Sponsorship"><span class="none"></span>Sponsorship</a> </li> + <li><a href="http://www.apache.org/security/"; class="externalLink" title="Security"><span class="none"></span>Security</a> </li> + <li class="nav-header">Documentation</li> + <li><a href="../userguide/installation.html" title="Installation Guide"><span class="none"></span>Installation Guide</a> </li> + <li><a href="../userguide/quick_start.html" title="Quick Start Guide"><span class="none"></span>Quick Start Guide</a> </li> + <li><a href="../userguide/samples/setup/index.html" title="Samples Setup Guide"><span class="none"></span>Samples Setup Guide</a> </li> + <li><a href="../userguide/samples.html" title="Samples Catalog"><span class="none"></span>Samples Catalog</a> </li> + <li><a href="../userguide/config.html" title="Configuration Language"><span class="none"></span>Configuration Language</a> </li> + <li class="active"><a href="#"><span class="none"></span>Mediators Catalog</a> + </li> + <li><a href="../userguide/transports.html" title="Transports Catalog"><span class="none"></span>Transports Catalog</a> </li> + <li><a href="../userguide/properties.html" title="Properties Catalog"><span class="none"></span>Properties Catalog</a> </li> + <li><a href="../userguide/xpath.html" title="XPath functions and Variables"><span class="none"></span>XPath functions and Variables</a> </li> + <li><a href="../userguide/extending.html" title="Extending Synapse"><span class="none"></span>Extending Synapse</a> </li> + <li><a href="../userguide/template_library.html" title="Synapse Template Libraries"><span class="none"></span>Synapse Template Libraries</a> </li> + <li><a href="../userguide/upgrading.html" title="Upgrading"><span class="none"></span>Upgrading</a> </li> + <li><a href="../userguide/deployment.html" title="Deployment"><span class="none"></span>Deployment</a> </li> + <li><a href="../apidocs/" title="Javadocs"><span class="none"></span>Javadocs</a> </li> + <li><a href="../userguide/faq.html" title="FAQ"><span class="none"></span>FAQ</a> </li> + <li class="nav-header">Developer Resources</li> + <li><a href="../dev/developer-guide.html" title="Developer Guide"><span class="none"></span>Developer Guide</a> </li> + <li><a href="../dev/best-practices.html" title="Development Best Practices"><span class="none"></span>Development Best Practices</a> </li> + <li><a href="../dev/release-process.html" title="Release Process"><span class="none"></span>Release Process</a> </li> + <li class="nav-header">Project Details</li> + <li><a href="../project-info.html" title="Overview"><span class="none"></span>Overview</a> </li> + <li><a href="../mail-lists.html" title="Mailing Lists"><span class="none"></span>Mailing Lists</a> </li> + <li><a href="../source-repository.html" title="Source Repository"><span class="none"></span>Source Repository</a> </li> + <li><a href="../issue-tracking.html" title="Issue Tracking"><span class="none"></span>Issue Tracking</a> </li> + <li><a href="../dependency-management.html" title="Dependencies"><span class="none"></span>Dependencies</a> </li> + <li><a href="../team-list.html" title="Project Team"><span class="none"></span>Project Team</a> </li> + </ul> + <hr /> + <div id="poweredBy"> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <div class="clear"></div> + <a href="http://maven.apache.org/"; title="Built by Maven" class="poweredBy"><img class="builtBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /></a> + </div> + </div> + </div> + <div id="bodyColumn" class="span10" > + + + <div class="section"> +<h2><a name="Mediators_Catalog"></a>Mediators Catalog</h2> + +<p> + This document lists all the built-in mediators of Synapse and describes their + usage, functionality and configuration syntax. + </p> + </div> + +<div class="section"> +<h2><a name="Contents"></a>Contents</h2> + +<ul> + +<li><a href="#Intro">Introduction</a></li> + +<li><a href="#Categories">Mediator Categories</a></li> + +<li> + <a href="#CoreMediators">Core Mediators</a> + +<ul> + +<li><a href="#Drop">Drop Mediator</a></li> + +<li><a href="#Log">Log Mediator</a></li> + +<li><a href="#Property">Property Mediator</a></li> + +<li><a href="#Send">Send Mediator</a></li> + +<li><a href="#Respond">Respond Mediator</a></li> + +<li><a href="#Loopback">Loopback Mediator</a></li> + </ul> + </li> + +<li> + <a href="#FilterMediators">Filter Mediators</a> + +<ul> + +<li><a href="#Filter">Filter Mediator</a></li> + +<li><a href="#InOut">In/Out Mediator</a></li> + +<li><a href="#Switch">Switch Mediator</a></li> + +<li><a href="#Validate">Validate Mediator</a></li> + </ul> + </li> + +<li> + <a href="#TransformationMediators">Transformation Mediators</a> + +<ul> + +<li><a href="#Header">Header 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> + +<li> + <a href="#AdvancedMediators">Advanced Mediators</a> + +<ul> + +<li><a href="#Aggregate">Aggregate Mediator</a></li> + +<li><a href="#Cache">Cache Mediator</a></li> + +<li><a href="#Callout">Callout Mediator</a></li> + +<li><a href="#Clone">Clone Mediator</a></li> + +<li><a href="#DBLookup">DBLookup Mediator</a></li> + +<li><a href="#DBReport">DBReport Mediator</a></li> + +<li><a href="#Iterate">Iterate Mediator</a></li> + +<li><a href="#RMSequence">RMSequence Mediator</a></li> + +<li><a href="#Store">Store Mediator</a></li> + +<li><a href="#Throttle">Throttle Mediator</a></li> + +<li><a href="#Transaction">Transaction Mediator</a></li> + </ul> + </li> + </ul> + </div> + <a name="Intro"></a> +<div class="section" id="Intro"> +<h2><a name="Introduction"></a>Introduction</h2> + +<p> + Mediator is the basic message processing unit in Synapse. A mediator takes an + input message, carries out some processing on it, and provides an output message. + Mediators can be linked up and arranged into chains to implement complex message + flows (sequences). Mediators can manipulate message content (payload), properties, + headers and if needed can also execute additional tasks such as database lookup, + service invocation and script execution. + </p> + +<p> + Apache Synapse ships with an array of useful mediators that can be used out of the + box to implement message flows, services and integration patterns. Rest of this + article describes these mediators in detail, along with their use cases and + configuration syntax. + </p> + </div> + <a name="Categories"></a> +<div class="section" id="Categories"> +<h2><a name="Mediator_Categories"></a>Mediator Categories</h2> + +<p> + Built-in mediators of Synapse can be classified into several groups depending + on the nature of their functionality and use cases. + </p> + +<ul> + +<li> + Core mediators - Utility mediators that are useful in a variety of scenarios + </li> + +<li> + Filter mediators - Mediators used to filter out messages + </li> + +<li> + Transform mediators - Mediators used to transform message content, headers and + attributes + </li> + +<li> + Extension mediators - Mediators used to extend the Synapse mediation engine by + plugging in custom developed code + </li> + +<li> + Advanced mediators - Mediators used to implement advanced integration scenarios + and patterns + </li> + </ul> + +<p> + Rest of this article is structured according to the above classification. Mediators + in each section are arranged in the alphabetical order. + </p> + </div> + <a name="CoreMediators"></a> +<div class="section" id="CoreMediators"> +<h2><a name="Core_Mediators"></a>Core Mediators</h2> + <a name="Drop"></a> +<div class="section" id="Drop"> +<h3><a name="Drop_Mediator"></a>Drop Mediator</h3> + +<p> + Drop mediator can be used to drop the current message being processed and + terminate a message flow. This mediator is configured as follows and it + does not take any additional parameters or arguments. + </p> + +<div class="xmlConf"><drop/></div> + </div> + <a name="Log"></a> +<div class="section" id="Log"> +<h3><a name="Log_Mediator"></a>Log Mediator</h3> + +<p> + Log mediator can be used in any sequence or proxy service to log the messages + being mediated. Log entries generated by the log mediator will go into the + standard Synapse log files. This can be further configured using the + log4j.properties file. + </p> + +<p> + By default, the log mediator only logs a minimalistic set of details to avoid + the message content being parsed. But if needed it can be configured to log the + full message payload, headers and even custom user defined properties. The log + mediator configuration takes the following general form. + </p> + +<div class="xmlConf"><log [level="simple|full|headers|custom"] [separator="string"] + [category="INFO|DEBUG|WARN|ERROR|TRACE|FATAL"]> + <property name="string" (value="literal" | expression="xpath")/>* +</log></div> + +<p> + The 'level' attribute is used to specify how much information should be logged + by the log mediator. This attribute can take one of following four values. + </p> + +<ul> + +<li> + simple - Logs a set of standard headers (To, From, WSAction, SOAPAction, + ReplyTo and MessageID). If no log level is specified, this level will be + used by default. + </li> + +<li> + full - Logs all standard headers logged in the log level 'simple' and also + the full payload of the message. This log level causes the message content + to be parsed and hence incurs a performance overhead. + </li> + +<li> + headers - Logs all SOAP header blocks + </li> + +<li> + custom - Only logs the user defined properties (see the next section) + </li> + </ul> + +<p> + Users can define custom attributes and properties to be logged by the log mediator + by specifying some 'property' elements. Each property must be named, and can + have a constant value or an XPath expression. If a constant value is specified, + that value will be logged with each and every entry logged by the mediator. If + an XPath is specified instead, that XPath will be evaluated on the message being + mediated and the outcome will be included in the generated log entry. + </p> + +<p> + By default, all properties and attributes logged by the log mediator are separated + by commas (,). This can be configured using the 'separator' attribute. Further + all logs generated by the mediator are logged at log4j log level 'INFO' by default. + This behavior can also be configured using the 'category' attribute. + In addition to this behaviour, when 'category' is set to debug, logs can be printed + at log4j log level 'INFO' by starting the server with the following flag. This is + especially helpful during the development time to quickly debug the mediation flow. + + +<div class="command"> + Linux / Unix: ./synapse.sh -synapseDebug<br /> + Windows: synapse.bat -synapseDebug + </div> + </p> + </div> + <a name="Property"></a> +<div class="section" id="Property"> +<h3><a name="Property_Mediator"></a>Property Mediator</h3> + +<p> + Every message mediated through Synapse can have a set of associated properties. + Synapse engine and the underlying transports set a number of properties on + each message processed which can be manipulated by the user to modify the + runtime behavior of the message flows. In addition, user can set his/her own + properties on the message which is very helpful when it comes to managing + message flow state and storing scenario specific variables. For an example in + some situations a user might want to access a particular value in the request + payload while processing a response. This can be easily achieved by setting the + required value to a property in the request (in) sequence and then later accessing + that property in the response (out) sequence. + </p> + +<p> + Property mediator is used to manipulate the properties of a message. This + mediator can be used to set and remove property values. When it comes to setting + property values, the input could be a constant or a variable value generated + by an XPath expression. The syntax for configuring the property mediator is as + follows. + </p> + +<div class="xmlConf"><property name="string" [action=set|remove] [type="string"] (value="literal" | expression="xpath") [scope=default|transport|axis2|axis2-client] [pattern="regex" [group="integer"]]> + <xml-element/>? +</property></div> + +<p> + The 'name' attribute specifies the name of the property which needs to be either + set or removed while the 'action' attribute specifies the exact action that needs + to be carried out by the mediator. If not specified action will default to 'set'. + </p> + +<p> + When setting a property value, either the 'value' or the 'expression' attribute + must be specified. The 'value' attribute can be used to set a constant as + the property value whereas the 'expression' attribute can be used to specify an + XPath expression. If an XPath expression is specified, Synapse will evaluate that + on the message to determine the value that needs to be assigned to the property. + </p> + +<p> + Synapse properties are scoped. Therefore, when using this mediator the user should + specify the scope at which the property will be set or removed from. If not + specified, property mediator will work at the 'default' scope. Properties set in + this scope last as long as the transaction (request-response) exists. Properties + set on scope 'axis2' has a shorter life span and it's mainly used for passing + parameters to the underlying Axis2 engine. Properties set in the 'transport' + scope will be treated as transport headers. For an example if it is required to + send an HTTP header named 'CustomHeader' with an outgoing request, one may use + the property mediator configuration. + </p> + +<div class="xmlConf"><property name="CustomHeader" value="some value" scope="transport" type="type name"/></div> + +<p> + This will force Synapse to send a transport header named 'CustomHeader' along + with the outgoing message. Property mediator also supports a scope named + 'axis2-client'. Properties set in this scope will be treated as Axis2 client + options. + </p> + +<p> + When using properties to store user or scenario specific information it is + recommended to always use the 'default' scope. Other scopes should not be used + for custom development or mediation work since they have the potential to + alter the behavior of the underlying Axis2 engine and transports framework. + </p> + +<p> + By default, property mediator sets all property values as strings. It is possible + to set properties in other types by specifying the 'type' attribute. This attribute + can accept one of following values. + </p> + +<ul> + +<li>STRING</li> + +<li>BOOLEAN</li> + +<li>DOUBLE</li> + +<li>FLOAT</li> + +<li>INTEGER</li> + +<li>LONG</li> + +<li>SHORT</li> + +<li>OM</li> + </ul> + +<p> + The type names are case sensitive. Type 'OM' can be used to set XML property + values on the message context. This becomes useful when the expression associated + with the property mediator evaluates to an XML node during mediation. With the + type attribute set to 'OM' the resulting XML will be converted to an AXIOM + OMElement before assigning it to a property. + </p> + +<p> + It is also possible to use the property mediator to set some static XML content + as a property value. To do this specify the static XML content as a child node + of the 'property' element instead of using the 'value' attribute. + </p> + </div> + <a name="Send"></a> +<div class="section" id="Send"> +<h3><a name="Send_Mediator"></a>Send Mediator</h3> + +<p> + Send mediator is used to send requests to endpoints. The same can be used + to send response messages back to clients. The send mediator is configured using + the following XML syntax. + </p> + +<div class="xmlConf"><send [receive="string"]> + (endpointref | endpoint)? +</send></div> + +<p> + Messages are sent to the endpoint specified as the child of the + 'send' element. An optional receiving sequence can be configured using the + 'receive' attribute. When specified, response messages from the endpoint will + be dispatched to the referred sequence. This makes it easier to implement + complex service chaining scenarios, where the response from one service needs + to be processed and directed to another service. + </p> + +<p> + The send mediator can be configured without any child endpoints. For an example + following is a perfectly valid send mediator configuration. + </p> + +<div class="xmlConf"><send/></div> + +<p> + In this case the messages will be sent to an implicit endpoint. If the message + is a request from a client, Synapse will lookup the 'To' header of the request and + simply forward it to the service addressed by that header. If it is a response + from a back-end service, Synapse will simply send it back to the original + client who initiated the original message flow. + </p> + +<p> + The service invocations done by the send mediator may or may not be + synchronous based on the underlying transport used. If the default non-blocking + HTTP transport is used, the send mediator will make an asynchronous invocation + and release the calling thread as soon as possible. Synapse will asynchronously + handle the response from the endpoint while the giving the illusion that Synapse + is making blocking service calls. + </p> + </div> + <a name="Respond"></a> +<div class="section" id="Respond"> +<h3><a name="Respond_Mediator"></a>Respond Mediator</h3> + +<p> + The Respond Mediator stops the processing on the current message flow and sends + the message back to the client as a response. + </p> + +<div class="xmlConf"><respond/></div> + </div> + <a name="Loopback"></a> +<div class="section" id="Loopback"> +<h3><a name="Loopback_Mediator"></a>Loopback Mediator</h3> + +<p> + The Loopback Mediator moves the message from the In flow to the Out flow. + All the configuration in the In flow that appears after the Loopback mediator is skipped. + </p> + +<div class="xmlConf"><loopback/></div> + </div> + </div> + <a name="FilterMediators"></a> +<div class="section" id="FilterMediators"> +<h2><a name="Filter_Mediators"></a>Filter Mediators</h2> + <a name="Filter"></a> +<div class="section" id="Filter"> +<h3><a name="Filter_Mediator"></a>Filter Mediator</h3> + +<p> + Filter mediator adds 'if-else' like semantics to the Synapse configuration language. + It can be used to evaluate a condition on a message and take some action + based on the outcome. The configuration of the filter mediator takes the + following form. + </p> + +<div class="xmlConf"><filter (source="xpath" regex="string") | xpath="xpath"> + mediator+ +</filter></div> + +<p> + The filter mediator either tests the given XPath expression as a boolean + expression, or matches the result of the source XPath expression as a string + against the given regular expression. If the condition evaluates to true, the + filter mediator will execute the enclosed child mediators. + </p> + +<p> + Alternatively, one can use the following syntax to configure the filter mediator. + </p> + +<div class="xmlConf"><filter (source="xpath" regex="string") | xpath="xpath"> + <then [sequence="string"]> + mediator+ + </then> + <else [sequence="string"]> + mediator+ + </else> +</filter></div> + +<p> + In this case also the filter condition is evaluated in the same manner as + described above. Messages for which the condition evaluates to true will be + mediated through the mediators enclosed by the 'then' element. Failed messages + will be mediated through the mediators enclosed by the 'else' element. + </p> + </div> + <a name="InOut"></a> +<div class="section" id="InOut"> +<h3><a name="InOut_Mediators"></a>In/Out Mediators</h3> + +<p> + In mediator and Out mediator are used to filter out traffic based on the + direction of the messages. As their names imply, In mediator processes only + the requests (in messages) while ignoring the responses (out messages). The + out mediator does the exact opposite by processing only the responses while + ignoring the requests. In many occasions these two mediators are deployed + together to create separate flows for requests and responses. The syntax + outline for the two mediators is given below. + </p> + +<div class="xmlConf"><in> + mediator+ +</in> + +<out> + mediator+ +</out></div> + +<p> + In mediator will process requests through the child mediators and the Out + mediator will process responses through the child mediators. + </p> + </div> + <a name="Switch"></a> +<div class="section" id="Switch"> +<h3><a name="Switch_Mediator"></a>Switch Mediator</h3> + +<p> + Switch mediator provides switch-case semantics in the Synapse configuration + language. + </p> + +<div class="xmlConf"><switch source="xpath"> + <case regex="string"> + mediator+ + </case>+ + <default> + mediator+ + </default>? +</switch></div> + +<p> + The source XPath is executed on the messages. The resulting value is then + tested against the regular expressions defined in each 'case' element. When + a matching case is found, the message will be mediated through its child + mediators. If none of the cases match, the message will be handed to the 'default' + case (if available). + </p> + </div> + <a name="Validate"></a> +<div class="section" id="Validate"> +<h3><a name="Validate_Mediator"></a>Validate Mediator</h3> + +<p> + The validate mediator validates the XML node selected by + the source xpath expression, against the specified XML schema. If the source + attribute is not specified, the validation is performed against the first + child of the SOAP body of the current message. If the validation fails, + the on-fail sequence of mediators is executed. Feature elements could be used to + turn on/off some of the underlying features of the schema validator (See <a class="externalLink" href="http://xerces.apache.org/xerces2-j/features.html";>http://xerces.apache.org/xerces2-j/features.html</a>). + The schema can be specified as a static or dynamic key. When + needed, imports can be specified using additional resources. + </p> + +<div class="xmlConf"><validate [source="xpath"]> + <schema key="string" />+ + <resource location="<external-schema>" key="string">* + <feature name="<validation-feature-name>" value="true|false"/>* + <on-fail> + mediator+ + </on-fail> +</validate></div> + </div> + </div> + <a name="TransformationMediators"></a> +<div class="section" id="TransformationMediators"> +<h2><a name="Transformation_Mediators"></a>Transformation Mediators</h2> + <a name="Header"></a> +<div class="section" id="Header"> +<h3><a name="Header_Mediator"></a>Header Mediator</h3> + +<p> + Header mediator sets or removes a specified header from the message. + The optional 'scope' attribute specifies the scope of the header. + Scope can be either 'soap' or 'transport'. + If the scope is set to 'soap', header is treated as a soap header and if it is 'transport', + header is treated as a transport header. + If the scope is omitted, header is treated as a soap header or one of the below mentioned known headers. + 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"] [scope="soap | transport"]> + [<embeddedxml/>] +</header></div> + + +<div class="xmlConf"><header name="qname" action="remove" [scope="soap | transport"]/></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. + When setting an embedded xml element as a soap header, 'name' attribute is not required. + </p> + +<ul> + +<li>To</li> + +<li>From</li> + +<li>Action</li> + +<li>FaultTo</li> + +<li>ReplyTo</li> + +<li>RelatesTo</li> + </ul> + </div> + <a name="MakeFault"></a> +<div class="section" id="MakeFault"> +<h3><a name="MakeFault_Mediator"></a>MakeFault Mediator</h3> + +<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> + </div> + <a name="PayloadFactory"></a> +<div class="section" id="PayloadFactory"> +<h3><a name="Payload_Factory_Mediator"></a>Payload Factory Mediator</h3> + +<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> + </div> + <a name="URLRewrite"></a> +<div class="section" id="URLRewrite"> +<h3><a name="URL_Rewrite_Mediator"></a>URL Rewrite Mediator</h3> + +<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> + </div> + <a name="XQuery"></a> +<div class="section" id="XQuery"> +<h3><a name="XQuery_Mediator"></a>XQuery Mediator</h3> + +<p> + The XQuery mediator can be used to perform an XQuery transformation. 'key' + attribute specifies the XQuery transformation, and the optional 'target' + attribute specifies the node of the message that should be transformed. + This defaults to the first child of the SOAP body of the payload. 'variable' + element defines a variable that could be bound to the dynamic context of the + XQuery engine in order to access those variables through the XQuery script. + </p> + +<div class="xmlConf"><xquery key="string" [target="xpath"]> + <variable name="string" type="string" [key="string"] [expression="xpath"] [value="string"]/>? +</xquery></div> + +<p> + It is possible to specify just a literal 'value', or an XPath expression + over the payload, or even specify a registry key or a registry key + combined with an XPath expression that selects the variable. The name of + the variable corresponds to the name of variable declaration in the XQuery + script. The 'type' of the variable must be a valid type defined by the + JSR-000225 (XQJ API). + </p> + +<p> + The supported types are: + </p> + +<ul> + +<li> + XQItemType.XQBASETYPE_INT -> INT + </li> + +<li> + XQItemType.XQBASETYPE_INTEGER -> INTEGER + </li> + +<li> + XQItemType.XQBASETYPE_BOOLEAN -> BOOLEAN + </li> + +<li> + XQItemType.XQBASETYPE_BYTE - > BYTE + </li> + +<li> + XQItemType.XQBASETYPE_DOUBLE -> DOUBLE + </li> + +<li> + XQItemType.XQBASETYPE_SHORT -> SHORT + </li> + +<li> + XQItemType.XQBASETYPE_LONG -> LONG + </li> + +<li> + XQItemType.XQBASETYPE_FLOAT -> FLOAT + </li> + +<li> + XQItemType.XQBASETYPE_STRING -> STRING + </li> + +<li> + XQItemType.XQITEMKIND_DOCUMENT -> DOCUMENT + </li> + +<li> + XQItemType.XQITEMKIND_DOCUMENT_ELEMENT -> DOCUMENT_ELEMENT + </li> + +<li> + XQItemType.XQITEMKIND_ELEMENT -> ELEMENT + </li> + </ul> + </div> + <a name="XSLT"></a> +<div class="section" id="XSLT"> +<h3><a name="XSLT_Mediator"></a>XSLT Mediator</h3> + +<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> + +<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. + </p> + +<p> + Usage of sub-elements of XSLT mediator configuration is as follows: + </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> + </ul> + </div> + </div> + <a name="ExtensionMediators"></a> +<div class="section" id="ExtensionMediators"> +<h2><a name="Extension_Mediators"></a>Extension Mediators</h2> + <a name="Clazz"></a> +<div class="section" id="Clazz"> +<h3><a name="Class_Mediator"></a>Class Mediator</h3> + +<p> + 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> + </div> + <a name="POJOCommand"></a> +<div class="section" id="POJOCommand"> +<h3><a name="POJO_Command_Mediator"></a>POJO Command Mediator</h3> + +<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> + </div> + <a name="Script"></a> +<div class="section" id="Script"> +<h3><a name="Script_Mediator"></a>Script Mediator</h3> + +<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 class="externalLink" 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> + </div> + <a name="Spring"></a> +<div class="section" id="Spring"> +<h3><a name="Spring_Mediator"></a>Spring Mediator</h3> + +<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> + </div> + </div> + <a name="AdvancedMediators"></a> +<div class="section" id="AdvancedMediators"> +<h2><a name="Advanced_Mediators"></a>Advanced Mediators</h2> + <a name="Aggregate"></a> +<div class="section" id="Aggregate"> +<h3><a name="Aggregate_Mediator"></a>Aggregate Mediator</h3> + +<p> + Aggregate mediator implements the Message Aggregator EIP by aggregating the + messages or responses for split messages generated using either the clone or + iterate mediator. + </p> + +<div class="xmlConf"><aggregate [id="string"]> + <correlateOn expression="xpath"/>? + <completeCondition [timeout="time-in-seconds"]> + <messageCount min="int-min" max="int-max"/>? + </completeCondition>? + <onComplete expression="xpath" [sequence="sequence-ref"]> + (mediator +)? + </onComplete> +</aggregate></div> + +<p> + This mediator can also aggregate messages on the presence of matching elements + specified by the correlateOn XPath expression. Aggregate will collect the + messages coming into it until the messages collected on the aggregation + satisfies the complete condition. The completion condition can specify a minimum + or maximum number of messages to be collected, or a timeout value in seconds, + after which the aggregation terminates. On completion of the aggregation it will + merge all of the collected messages and invoke the onComplete sequence on it. + The merged message would be created using the XPath expression specified by the + attribute 'expression' on the 'onComplete' element. + </p> + </div> + <a name="Cache"></a> +<div class="section" id="Cache"> +<h3><a name="Cache_Mediator"></a>Cache Mediator</h3> + +<p> + Cache mediator is used for simple response message caching in Synapse. When a + message reaches the cache mediator, it checks weather an equivalent message is + already cached using a hash value. + </p> + +<p> + When the cache mediator detects that the message is a cached message, it fetches + the cached response and prepares Synapse for sending the response. If a sequence + is specified for a cache hit, user can send back the response message within + this sequence using a send mediator. If a sequence is not specified, then cached + response is sent back to the client. + </p> + +<div class="xmlConf"><cache [id="string"] [hashGenerator="class"] [timeout="seconds"] [scope=(per-host | per-mediator)] + collector=(true | false) [maxMessageSize="in-bytes"]> + <onCacheHit [sequence="key"]> + (mediator)+ + </onCacheHit>? + <implementation type=(memory | disk) maxSize="int"/> +</cache></div> + +<p> + This mediator will evaluate the hash value of an incoming message as described + in the optional hash generator implementation (which should be a class + implementing the org.wso2.caching.digest.DigestGenerator interface). The default + hash generator is 'org.wso2.caching.digest.DOMHashGenerator'. If the generated + hash value has been found in the cache then the cache mediator will execute the + onCacheHit sequence which can be specified inline or referenced. The cache + mediator must be specified with an 'id' and two instances with this same 'id' + that correlates the response message into the cache for the request message + hash. The optional 'timeout' specifies the valid duration for cached elements, + and the scope defines if mediator instances share a common cache per every host + instance, or per every cache mediator pair (i.e. 'id') instance. 'collector' + attribute value 'true' specifies that the mediator instance is a response + collection instance, and 'false' specifies that its a cache serving instance. + The maximum size of a message to be cached could be specified with the optional + 'maxMessageSize' attributes in bytes and defaults to unlimited. Finally, + 'implementation' element may define if the cache is disk or memory based, and + 'maxSize' attribute defines the maximum number of elements to be cached. + </p> + </div> + <a name="Callout"></a> +<div class="section" id="Callout"> +<h3><a name="Callout_Mediator"></a>Callout Mediator</h3> + +<p> + Callout mediator performs a blocking external service invocation during mediation. + The target external service can be configured either using a child endpoint element + or using the 'serviceURL' attribute. When serviceURL is specified, it is used as + the EPR of the external service. We can specify the endpoint element if we want to + leverage endpoint functionality like format conversions, security, etc. + The target endpoint can be defined inline or we can refer to an existing named + endpoint in the configuration. + Only Leaf endpoint types (Address/WSDL/Default) are supported. + When both serviceURL and endpoint is not present, 'To' header on the request is + used as the target endpoint. + </p> + +<div class="xmlConf"><callout [serviceURL="string"] [action="string"][passHeaders="true|false"] [initAxis2ClientOptions="true|false"] > + <configuration [axis2xml="string"] [repository="string"]/>? + <endpoint/>? + <source xpath="expression" | key="string">? + <target xpath="expression" | key="string"/>? + <enableSec policy="string" | outboundPolicy="String" | inboundPolicy="String" />? +</callout></div> + +<p> + 'action' attribute can be used to specify the SOAP Action of the external service + call. When 'initAxis2ClientOptions' is set to false, axis2 client options available + in the incoming message context is reused for the service invocation. + When 'passHeaders' is set to true, SOAP Headers of the received message is parsed + to the external service. + </p> + +<p> + The source element specifies the payload for the request message using an XPath + expression or a registry key. + When source element is not defined, entire SOAP Envelope arrived at the Callout + mediator is treated as the source. + The target element specifies a node, at which the response payload will be + attached into the current message, or the name of a key/property using which the + response would be attached to the current message context as a property. + When target element is not specified, entire SOAP Envelope arrived to the + Callout mediator is replaced from the response received from the external service + invocation. + + </p> + +<p> + Since the callout mediator performs a blocking call, it cannot use the default + non-blocking http/s transports based on Java NIO, and thus defaults to + using the repository/conf/axis2_blocking_client.xml as the + Axis2 configuration, and repository/ as the client repository + unless these are specified inside the 'configuration' sub-element. + </p> + +<p> + To invoke secured services, Callout mediator can be configured to enable WS-Security + using the 'enableSec' element. Security policy should be specified using the 'policy' + attribute which may point to a registry key or a local entry. You can also specify + two different policies for inbound and outbound messages (flows). This is done by + using the 'inboundPolicy' and 'outboundPolicy' attributes. These security + configurations will not get activated if we configure the external service using + the endpoint element. When endpoint is defined, security settings can be + configured at the endpoint. + </p> + </div> + <a name="Clone"></a> +<div class="section" id="Clone"> +<h3><a name="Clone_Mediator"></a>Clone Mediator</h3> + +<p> + Clone mediator can be used to create several clones or copies of a message. This + mediator implements the Message Splitter EIP by splitting the message into + number of identical messages which will be processed in parallel. They can also + be set to process sequentially by setting the value of the optional 'sequential' + attribute to 'true'. + </p> + +<div class="xmlConf"><clone [id="string"] [sequential=(true | false)] [continueParent=(true | false)]> + <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]> + <sequence> + (mediator)+ + </sequence>? + <endpoint> + endpoint + </endpoint>? + </target>+ +</clone></div> + +<p> + The original message can be continued or dropped depending on the boolean value + of the optional 'continueParent' attribute. Optionally a custom 'To' address + and/or a 'Action' may be specified for cloned messages. The optional 'id' + attribute can be used to identify the clone mediator which created a particular + split message when nested clone mediators are used. This is particularly useful + when aggregating responses of messages that were created using nested clone + mediators. + </p> + </div> + <a name="DBLookup"></a> +<div class="section" id="DBLookup"> +<h3><a name="DBLookup"></a>DBLookup</h3> + +<p> + DB Lookup mediator is capable of executing an arbitrary SQL SELECT statement, + and then set some resulting values as local message properties on the message + context. The DB connection used maybe looked up from an external DataSource or + specified in-line, in which case an Apache DBCP connection pool is established + and used. + </p> + +<div class="xmlConf"><dblookup> + <connection> + <pool> + ( + <driver/> + <url/> + <user/> + <password/> + <property name="name" value="value"/>* + | + <dsName/> + <inClass/> + <url/> + <user/> + <password/> + ) + </pool> + </connection> + <statement> + <sql>SELECT something FROM table WHERE something_else = ?</sql> + <parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>* + <result name="string" column="int|string"/>* + </statement>+ +</dblookup></div> + +<p> + For in-lined data sources the following parameters have to be specified. + </p> + +<ul> + +<li>driver: Fully qualified class name of the database driver.</li> + +<li>url: Database URL.</li> + +<li>user: Username for database access.</li> + +<li>password: Password for database access.</li> + </ul> + +<p> + This new data source is based on Apache DBCP connection pools. This connection + pool support the following configuration properties: + </p> + +<ul> + +<li>autocommit = true | false</li> + +<li>isolation = Connection.TRANSACTION_NONE | Connection.TRANSACTION_READ_COMMITTED | Connection.TRANSACTION_READ_UNCOMMITTED | + Connection.TRANSACTION_REPEATABLE_READ | Connection.TRANSACTION_SERIALIZABLE</li> + +<li>initialsize = int</li> + +<li>maxactive = int</li> + +<li>maxidle = int</li> + +<li>maxopenstatements = int</li> + +<li>maxwait = long</li> + +<li>minidle = int</li> + +<li>poolstatements = true | false</li> + +<li>testonborrow = true | false</li> + +<li>testonreturn = true | false</li> + +<li>testwhileidle = true | false</li> + +<li>validationquery = String</li> + </ul> + +<p></p> + +<p> + When an external data source is used the following parameters have to be + specified. + </p> + +<ul> + +<li>dsName: The name of the data source to be looked up.</li> + +<li>icClass: Initial context factory class. The corresponding Java environment property is java.naming.factory.initial</li> + +<li>url: The naming service provider URL. The corresponding Java environment property is java.naming.provider.url</li> + +<li>user: Username corresponding to the Java environment property java.naming.security.principal</li> + +<li>password: Password corresponding to the Java environment property java.naming.security.credentials</li> + </ul> + +<p> + More than one statement can be included in the mediator configuration. SQL + statement may specify parameters which could be specified as values or XPath + expressions. The type of a parameter could be any valid SQL type. 'result' + sub-element contains 'name' and 'column' attributes which define the name + under which the result is stored in the Synapse message context, and a column + number or name respectively. + </p> + </div> + <a name="DBReport"></a> +<div class="section" id="DBReport"> +<h3><a name="DBReport"></a>DBReport</h3> + +<p> + DB Report mediator is quite similar to the + <a href="#DBReport">DB Lookup</a> + mediator, but writes data into a database instead of reading data from a + database. + </p> + +<div class="xmlConf"><dbreport useTransaction=(true|false)> + <connection> + <pool> + ( + <driver/> + <url/> + <user/> + <password/> + <property name="name" value="value"/>* + | + <dsName/> + <icClass/> + <url/> + <user/> + <password/> + ) + </pool> + </connection> + <statement> + <sql>INSERT INTO table VALUES (?, ?, ?, ?)</sql> + <parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>* + </statement>+ +</dblreport></div> + + +<p> + This mediator executes the specified SQL INSERT on the database specified + in-line or as an external data source. For information on configuring database + related mediators, refer<a href="#DBReport">DB Lookup mediator guide</a>. + </p> + </div> + <a name="Iterate"></a> +<div class="section" id="Iterate"> +<h3><a name="Iterate_Mediator"></a>Iterate Mediator</h3> + +<p> + Iterate mediator splits the message into number of different messages + derived from the parent message by finding matching elements for the XPath + expression specified. New messages will be created for each matching element and + processed in parallel (default behavior) using either the specified sequence or + endpoint. + </p> + +<div class="xmlConf"><iterate [id="string"] [continueParent=(true | false)] [preservePayload=(true | false)] [sequential=(true | false)] + (attachPath="xpath")? expression="xpath"> + <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]> + <sequence> + (mediator)+ + </sequence>? + <endpoint> + endpoint + </endpoint>? + </target>+ + </iterate></div> + +<p> + Created messages can also be set to process sequentially by setting the optional + 'sequential' attribute to 'true'. Parent message can be continued or dropped in + the same way as in the clone mediator. The 'preservePayload' attribute specifies + if the original message should be used as a template when creating the split + messages, and defaults to 'false', in which case the split messages would + contain the split elements as the SOAP body. The optional 'id' attribute can be + used to identify the iterator which created a particular split message when + nested iterate mediators are used. This is particularly useful when aggregating + responses of messages that are created using nested iterate mediators. + </p> + </div> + <a name="RMSequence"></a> +<div class="section" id="RMSequence"> +<h3><a name="RMSequence"></a>RMSequence</h3> + +<p> + RM Sequence mediator can be used to create a sequence of messages to communicate + via WS-Reliable Messaging with a WS-RM enabled endpoint. + </p> + +<div class="xmlConf"><RMSequence (correlation="xpath" [last-message="xpath"]) | single="true" [version="1.0|1.1"]/></div> + +<p> + The simplest use case of this mediator sets 'single' attribute to "true", + which means that only one message is involved in the same sequence. However, if + multiple messages should be sent in the same sequence, 'correlation' attribute + should be used with an XPath expression that selects a unique element value from + the incoming message. With the result of the XPath expression, Synapse can group + messages together that belong to the same sequence. To close the sequence + neatly, an XPath expression should be specified for the last message of the + sequence as well. The optional 'version' attribute, which specifies the WS-RM + specification version as 1.0 or 1.1, defaults to 1.0. + </p> + </div> + <a name="Store"></a> +<div class="section" id="Store"> +<h3><a name="Store"></a>Store</h3> + +<p> + Store mediator can be used to store the current message in a specific message + store. + </p> + +<div class="xmlConf"><store messageStore="string" [sequence="sequence-ref"]></div> + +<p> + In the mediator configuration 'messageStore' attribute is used to specify the + message store to store the message in. The optional 'sequence' attribute + specifies a sequence through which the message is sent before storing it. + </p> + </div> + <a name="Throttle"></a> +<div class="section" id="Throttle"> +<h3><a name="Throttle_Mediator"></a>Throttle Mediator</h3> + +<p> + Throttle mediator can be used for rate limiting as well as concurrency based + limiting. A WS-Policy dictates the throttling configuration and can be + specified inline or loaded from the registry. Please refer to the samples + document for sample throttling policies. + </p> + +<div class="xmlConf"><throttle [onReject="string"] [onAccept="string"] id="string"> + (<policy key="string"/> | <policy>..</policy>) + <onReject>..</onReject>? + <onAccept>..</onAccept>? +</throttle></div> + +<p> + The throttle mediator could be used in the request path for rate limiting and + concurrent access limiting. When it's used for concurrent access limitation, + the same throttle mediator 'id' must be triggered on the response flow so that + completed responses are deducted from the available limit. (i.e. two instances + of the throttle mediator with the same 'id' attribute in the request and + response flows). 'onReject' and 'onAccept' sequence references or inline + sequences define how accepted and rejected messages are handled. + </p> + </div> + <a name="Transaction"></a> +<div class="section" id="Transaction"> +<h3><a name="Transaction_Mediator"></a>Transaction Mediator</h3> + +<p> + Transaction mediator can provide transaction facility for a set of mediators + defined as its child mediators. A transaction mediator with the action "new" + indicates the entry point for the transaction. A transaction is marked completed + by a transaction mediator with the action "commit". The suspend and resume + actions are used to pause a transaction at some point and start it again later. + Additionally, the transaction mediator supports three other actions, i.e. + use-existing-or-new, fault-if-no-tx, rollback. + </p> + +<div class="xmlConf"><transaction action="new|use-existing-or-new|fault-if-no-tx|commit|rollback|suspend|resume"/></div> + +<ul> + +<li>new: Initiate a new transaction.</li> + +<li>use-existing-or-new: If a transaction already exists + continue it, otherwise create a new transaction.</li> + +<li>fault-if-no-tx: Go to the error handler if no transaction exists.</li> + +<li>commit: End the transaction.</li> + +<li>rollback: Rollback a transaction.</li> + +<li>suspend: Pause a transaction.</li> + +<li>resume: Resume a paused transaction.</li> + </ul> + </div> + </div> + + + </div> + </div> + </div> + <hr/> + <footer> + <div class="container-fluid"> + <div class="row-fluid"> + <p>Copyright ©2005–2023 +<a href="http://www.apache.org/";>Apache Software Foundation</a>. +All rights reserved.</p> + </div> + </div> + </footer> + </body> +</html>
