| <document> |
| <properties> |
| <title>Apache Synapse - Mediators Catalog</title> |
| </properties> |
| <body> |
| <section name="Mediators Catalog"> |
| <p> |
| This document lists all the built-in mediators of Synapse and describes their |
| usage, functionality and configuration syntax. |
| </p> |
| </section> |
| <section name="Contents"> |
| <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> |
| </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> |
| </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> |
| </section> |
| <section name="Introduction" id="Intro"> |
| <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> |
| </section> |
| <section name="Mediator Categories" id="Categories"> |
| <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> |
| </section> |
| <section name="Core Mediators" id="CoreMediators"> |
| <subsection name="Drop Mediator" id="Drop"> |
| <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> |
| </subsection> |
| <subsection name="Log Mediator" id="Log"> |
| <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. |
| </p> |
| </subsection> |
| <subsection name="Property Mediator" id="Property"> |
| <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> |
| </subsection> |
| <subsection name="Send Mediator" id="Send"> |
| <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> |
| </subsection> |
| </section> |
| <section name="Filter Mediators" id="FilterMediators"> |
| <subsection name="Filter Mediator" id="Filter"> |
| <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 too 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> |
| </subsection> |
| <subsection name="In/Out Mediators" id="InOut"> |
| <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 anf the Out |
| mediator will process responses through the child mediators. |
| </p> |
| </subsection> |
| <subsection name="Switch Mediator" id="Switch"> |
| <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 handed to the 'default' |
| case (if available). |
| </p> |
| </subsection> |
| </section> |
| <section name="Transformation Mediators" id="TransformationMediators"> |
| <subsection name="Header Mediator" id="Header"> |
| <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. |
| </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. |
| </p> |
| <ul> |
| <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' |
| 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> |
| </subsection> |
| <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> |
| <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> |
| </subsection> |
| </section> |
| <section name="Extension Mediators" id="ExtensionMediators"> |
| <subsection name="Class Mediator" id="Clazz"> |
| <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> |
| </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> |
| <section name="Advanced Mediators" id="AdvancedMediators"> |
| <subsection name="Aggregate Mediator" id="Aggregate"> |
| <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> |
| </subsection> |
| <subsection name="Cache Mediator" id="Cache"> |
| <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> |
| </subsection> |
| <subsection name="Callout Mediator" id="Callout"> |
| <p> |
| Callout mediator performs a blocking external service invocation during |
| mediation. 'serviceURL' and optional 'action' attributes specify the parameters |
| for the external service call. The source element specifies the payload for the |
| request message using an XPath expression; or a registry key. 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. |
| </p> |
| <div class="xmlConf"><callout serviceURL="string" [action="string"]> |
| <configuration [axis2xml="string"] [repository="string"]/>? |
| <source xpath="expression" | key="string"> |
| <target xpath="expression" | key="string"/> |
| </callout></div> |
| <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 |
| samples/axis2Client/client_repo/conf/axis2.xml as the Axis2 configuration, and |
| samples/axis2Client/client_repo as the client repository unless these are |
| specified otherwise inside the 'configuration' sub-element. |
| </p> |
| </subsection> |
| <subsection name="Clone Mediator" id="Clone"> |
| <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> |
| </subsection> |
| <subsection name="DBLookup" id="DBLookup"> |
| <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> |
| 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> |
| </subsection> |
| <subsection name="DBReport" id="DBReport"> |
| <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> |
| </subsection> |
| <subsection name="Iterate Mediator" id="Iterate"> |
| <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> |
| </subsection> |
| <subsection name="RMSequence" id="RMSequence"> |
| <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> |
| </subsection> |
| <subsection name="Store" id="Store"> |
| <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> |
| </subsection> |
| <subsection name="Throttle Mediator" id="Throttle"> |
| <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> |
| </subsection> |
| <subsection name="Transaction Mediator" id="Transaction"> |
| <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> |
| </subsection> |
| </section> |
| </body> |
| </document> |