You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2011/12/28 10:23:11 UTC
svn commit: r1225148 [12/15] - in /synapse/branches/2.1/src/site: ./
xdoc/1_0/ xdoc/1_1/ xdoc/1_1_1/ xdoc/1_2/
Added: synapse/branches/2.1/src/site/xdoc/1_2/Synapse_Configuration_Language.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/1_2/Synapse_Configuration_Language.xml?rev=1225148&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/1_2/Synapse_Configuration_Language.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/1_2/Synapse_Configuration_Language.xml Wed Dec 28 09:23:09 2011
@@ -0,0 +1,2048 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<document>
+ <properties>
+ <title>Apache Synapse - Configuration Language</title>
+ </properties>
+ <head>
+ <style type="text/css" xml:space="preserve">
+ .command {
+ border: 1px dashed #3c78b5;
+ text-align: left;
+ background-color: #f0f0f0;
+ padding: 3px;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ }
+ .consoleOutput {
+ border: 1px dashed #3c78b5;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ background-color: #f0f0f0;
+ border-bottom: 1px dashed #3c78b5;
+ padding: 3px;
+ border-style: solid;
+ }
+ .info {
+ border-style: solid;
+ border-width: 1px;
+ border-color: #090;
+ background-color: #dfd;
+ text-align:left;
+ margin-top: 5px;
+ margin-bottom: 5px;
+ }
+ li {
+ font-family: Verdana, arial, sans-serif;
+ font-size: 11px;
+ line-height: 16px;
+ color: #000000;
+ font-weight: normal;
+ }
+ p {
+ font-family: Verdana, arial, sans-serif;
+ font-size: 11px;
+ line-height: 16px;
+ color: #000000;
+ font-weight: normal;
+ }
+ pre {
+ padding: 0px;
+ margin-top: 5px;
+ margin-left: 15px;
+ margin-bottom: 5px;
+ margin-right: 5px;
+ text-align: left;
+ background-color: #f0f0f0;
+ padding: 3px;
+ border: 1px dashed #3c78b5;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ }
+ h1 {
+ font-size: 24px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ color: #003366;
+ border-bottom: 1px solid #3c78b5;
+ padding: 2px;
+ margin: 36px 0px 4px 0px;
+ }
+ h2 {
+ font-size: 18px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ border-bottom: 1px solid #3c78b5;
+ padding: 2px;
+ margin: 27px 0px 4px 0px;
+ }
+ h3 {
+ font-size: 14px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ padding: 2px;
+ margin: 21px 0px 4px 0px;
+ }
+ h4 {
+ font-size: 12px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ padding: 2px;
+ margin: 18px 0px 4px 0px;
+ }</style>
+ </head>
+ <body>
+ <div style="margin-top:-40px; float:right; _margin-top:0px;">
+ <img alt="Synapse logo"
+ src="images/synapse-logo-web2.png" width="197"
+ height="82"/>
+ </div>
+ <div>
+ <h1>
+ Apache Synapse ESB - Configuration
+ </h1>
+ </div>
+ <h3>
+ Overview
+ </h3>
+ <p>
+ An Apache Synapse Enterprise Service Bus (ESB) engine is driven off a set
+ of simple text/xml configuration files. This allows the configuration to
+ be easily hand edited, backed up from the file system, or even included
+ into version control for easier management and control (e.g. moving a
+ configuration from development, through QA, staging and into production).
+ The configuration files that drives the Synapse ESB are as follows:
+ </p>
+ <ul>
+ <li>
+ The Synapse configuration file - synapse.xml
+ </li>
+ <li>
+ The underlying Axis2 engine configuration file - axis2.xml
+ </li>
+ <li>
+ Resources referenced from the Registry
+ </li>
+ </ul>
+ <p>
+ While the axis2.xml configures the underlying transport and Web services
+ support, the synapse.xml configures the mediation rules and configuration
+ for the ESB. While any changes performed on the axis2.xml requires a
+ restart (e.g. for enabling a transport such as JMS), the synapse.xml could
+ be made to reference different configuration elements off a set of
+ multiple files - that are served through the built-in Registry. When using
+ the Registry to hold pieces of the configuration, certain elements such as
+ endpoint definitions, sequences and local entries could be updated
+ dynamically while the Synapse ESB executes, the the Registry could trigger
+ a re-load as configured.
+ </p>
+ <h2>
+ The Synapse Configuration (synapse.xml)
+ </h2>
+ <p>
+ As the diagram below depicts, the Synapse configuration defines the Proxy
+ services, Endpoints, Sequences and Startup jobs managed by the Synapse
+ ESB. It also defines the interface to the Registry/Repository being used
+ by the engine. Typically the Synapse ESB is deployed between the actual
+ client and a backend service implementation to mediate the message flow in
+ between. Thus the Synapse ESB can accept a message on behalf of the actual
+ service, perform authentication, validation, transformation, logging,
+ routing based on the content etc. and then decide the destination target
+ endpoint for the message and direct it to an actual service
+ implementation. The Synapse ESB can also detect timeouts, transport
+ failures during communication or introduce load balancing, throttling or
+ caching where necessary. For fault scenarios such as authentication
+ failure, or schema validation failure, the Synapse ESB can be configured
+ to return a custom message or a fault to the requesting client without
+ forwarding the request to the actual service.
+ </p>
+ <p>
+ <img alt="Synapse message flow"
+ src="images/synapse-flow.png" width="400" height="300"/>
+ </p>
+ <p/>
+ <p>
+ The Synapse ESB can operate in two modes:
+ </p>
+ <h3>
+ <a href="#service_mediation">Service mediation</a> / <a
+ href="#proxy">Proxy services</a>
+ </h3>
+ <p>
+ In Service mediation, the Synapse ESB exposes a service endpoint on the
+ ESB, that accepts messages from clients. Typically these services acts as
+ proxies for existing (external) services, and the role of Synapse would be
+ to "mediate" these messages before they are proxied to the actual service.
+ In this mode, Synapse could expose a service already available in one
+ transport, over a different transport; or expose a service that uses one
+ schema or WSDL as a service that uses a different schema or WSDL etc. A
+ Proxy service could define the transports over which the service is
+ exposed, and point to the mediation sequences that should be used to
+ process request and response messages through the proxy service. A proxy
+ service maybe a SOAP or REST/POX service over http/s or SOAP, POX, Plain
+ Text or Binary / Legacy service for other transports such as JMS and VFS
+ file systems - e.g. CSV content being the payload
+ </p>
+ <h3>
+ <a name="_message_mediation" id="_message_mediation">Message mediation</a>
+ </h3>
+ <p>
+ In Message mediation, Synapse can act as a transparent proxy for clients -
+ if they are directed to point to the Synapse ESB as a http proxy. This
+ way, Synapse could be configured to filter all messages on a network for
+ logging, access control etc, and could "mediate" messages without the
+ explicit knowledge of the original client. If Synapse receives a message
+ that is not accepted by any proxy service, this message is handled through
+ message mediation as well. Message mediation always processes messages
+ according to the mediation sequence defined as "main".
+ </p>
+ <h2>
+ Concepts and configuration elements overview
+ </h2>
+ <h3>
+ <a href="#mediator">Mediators</a> and <a href="#sequence">Mediation
+ Sequences</a>
+ </h3>
+ <p>
+ The Synapse ESB defines a 'mediator' as a component that is performs some
+ mediation action on a message during the process flow. Thus a mediator
+ gets full access to a message at the point where it is defined to gain
+ control, and could inspect the message, modify it or take an external
+ action depending on some attributes or values of the current message. A
+ mediation sequence, commonly called a 'sequence' is a list of such
+ mediators. A sequence may be named for re-use, or defined in-line or
+ anonymously within a configuration. Sequences may be defined within the
+ synapse.xml configuration or within the Registry. Writing a custom
+ mediator in Java is easy and the supplementary documentation provides more
+ details on this. The 'Class' and 'POJO (command)" mediators allows one to
+ plugin a Java class easily into the Synapse engine with minimal effort. In
+ addition, the Script mediator allows one to provide an Apache BSF script
+ (e.g. Javascript, Ruby, Groovy etc) for mediation.
+ </p>
+ <p>
+ A Synapse configuration holds two special sequences named as "main" and
+ "fault". These may be defined within the synapse.xml, or externally via
+ the Registry. If either is not found, a suitable default is generated at
+ runtime by the ESB. The default "main" sequence will simply send a message
+ without mediation, while the default "fault" sequence would log the
+ message including the payload and any error/exception encountered and stop
+ further processing. The 'fault' sequence executes whenever Synapse itself
+ encounters an error while processing a message - or when a fault handler
+ has not been defined to handle exceptions. A sequence can assign another
+ named sequence as its "fault" handler sequence, and control branches to
+ the fault handler if an error is encountered during the execution of the
+ initial sequence.
+ </p>
+ <h3>
+ <a href="#endpoint">Endpoints</a>
+ </h3>
+ <p>
+ An Endpoint definition within Synapse defines an external service endpoint
+ and any attributes or semantics that should be followed when communicating
+ with that endpoint. An endpoint definition can be named for re-use, or
+ defined in-line or anonymously within a configuration. Typically an
+ endpoint would be based on a service Address or a WSDL. Additionally the
+ Synapse ESB supports Failover and Load-balance endpoints - which are
+ defined over a group of endpoints. Endpoints may be defined within the
+ synapse.xml configuration or within the Registry.
+ </p>
+ <h3>
+ <a href="#task">Tasks</a>
+ </h3>
+ <p>
+ A Task is a custom Java class that implements the
+ org.apache.synapse.startup.Task interface that defines a single "public
+ void execute()" method. Such a task can be scheduled and managed via the
+ Synapse ESB. The scheduling information for a task can be specified in the
+ cron format or a simple format by the user. A task may also be specified
+ as a one-time task where required, and can be used to trigger a callout or
+ inject a message into the Synapse ESB.
+ </p>
+ <h3>
+ <a href="#registry">Remote Registry</a> and <a name="Local"
+ id="Local" href="#localEntry">Local Registry (Local Entries)</a>
+ </h3>
+ <p>
+ A Synapse configuration can refer to an external Registry / Repository for
+ resources used such as WSDL's, Schemas, Scripts, XSLT or XQuery
+ transformations etc. One or more remote registries may be hidden or merged
+ behind a local Registry interface defined to a Synapse configuration.
+ Resources from an external registry are looked up using "keys" - which are
+ known to the external registry. The Synapse ESB ships with a simple URL
+ based registry implementation that uses the file system for storage of
+ resources, and URL's or fragments as "keys".
+ </p>
+ <p>
+ A Registry may define a duration for which a resource served may be cached
+ by the Synapse runtime. If such a duration is specified, the Synapse ESB
+ is capable of refreshing the resource after cache expiry to support
+ dynamic re-loading of resource at runtime. Optionally, a configuration
+ could define certain "keys" to map to locally defined entities. These
+ entities may refer to a source URL or file, or defined as in-line XML or
+ text within the configuration itself. If a Registry contains a resource
+ whose "key" matches the key of a locally defined entry, the local entry
+ shadows the resource available in the Registry. Thus it is possible to
+ override Registry resources locally from within a configuration. To
+ integrate Synapse with a custom / new Registry or repository, one needs to
+ implement the org.apache.synapse.registry.Registry interface to suit the
+ actual Registry being used.
+ </p>
+ <h2>
+ The Axis2 Configuration (axis2.xml)
+ </h2>
+ <p>
+ The axis2.xml file configures the underlying Axis2 web services engine for
+ the Synapse ESB. The axis2.xml thus defines the transports enabled, and
+ other configuration parameters associated. A change to the axis2
+ configuration requires a hard re-start of the Synapse ESB. By default the
+ non-blocking http/s and the Apache VFS file system based transport are
+ enabled for listening of messages, while the non-blocking http/s, VFS and
+ JMS transports are enabled for sending messages out. Sample configurations
+ to enable/configure the other transports are provided within the default
+ axis2.xml file, and can be easily uncommented and modified. The sample JMS
+ configuration shipped is for a default ActiveMQ 4.1.x installation.
+ </p>
+ <h2>
+ The contents of the Synapse.xml configuration
+ </h2>
+ <p>
+ A Synapse configuration looks like the following at the top level:
+ </p>
+<pre xml:space="preserve"> <definitions>
+ <<a href="#registry">registry</a> provider="string">...</registry>?
+ <<a href="#localEntry">localEntry</a> key="string">...</localEntry>?
+ <<a href="#sequence">sequence</a> name="string">...</sequence>?
+ <<a href="#endpoint">endpoint</a> name="string">...</endpoint>?
+ <<a href="#proxy">proxy</a> name="string" ...>...</proxy>?
+ <<a href="#task">task</a> name="string" ...>...</task>?
+ <a href="#mediator">mediator</a>*
+ </definitions></pre>
+ <p/>
+ <p>
+ The <definitions> elements in a synapse.xml holds the Synapse ESB
+ configuration. While the <registry>, <sequence>, <endpoint>,
+ <proxy>, <task> and <localEntry> elements refer to those
+ discussed above, the built-in mediator elements names are already
+ registered with the Synapse engine. Custom mediators written by a user may
+ be included into the library directory, and would be dynamically picked up
+ in a Sun JDK environment. A list of mediators found directly as children
+ under the <definitions> element would be treated as the "main"
+ sequence, if a named sequence with the name "main" cannot be found.
+ </p>
+ <h2>
+ <a name="registry1" id="registry">Registry</a>
+ </h2>
+ <p>
+ The <registry> element is used to define the remote registry used by
+ the configuration. The registry provider specifies an implementation class
+ for the registry implementation used, and optionally a number of
+ configuration parameters as may be required for the configuration of the
+ connection to the registry.
+ </p>
+<pre xml:space="preserve"> <registry provider="string"/>
+ <parameter name="string">text | xml</parameter>*
+ </registry></pre>
+ <p>
+ Registry entries loaded from a remote registry may be cached as dictated
+ by the registry, and reloaded after the cache periods expires if a newer
+ version is found. Hence it is possible to define configuration elements
+ such as (dynamic) sequences and endpoints, as well as resources such as
+ XSLT's, Scripts or XSDs off the registry, and update the configuration as
+ these are allowed to dynamically change over time.
+ </p>
+ <p>
+ Synapse ships with a built-in URL based registry implementation called the
+ "SimpleURLRegistry" and this can be configured as follows:
+ </p>
+<pre xml:space="preserve">e.g.
+<registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <parameter name="root">file:./repository/conf/sample/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+</registry></pre>
+ <p>
+ The "root" parameter specifies the root URL of the Registry for loaded
+ resources. The SimpleURLRegistry keys are path fragments, that when
+ combined with the root prefix would form the full URL for the referenced
+ resource. The "cachableDuration" parameter specifies the number of
+ milliseconds for which resources loaded from the Registry should be
+ cached. More advanced registry implementations allows different cachable
+ durations to be specified for different resources, or mark some resources
+ as never expires. (e.g. Check the WSO2 ESB implementation built over the
+ Apache Synapse ESB core)
+ </p>
+ <p/>
+ <h3>
+ <a name="localEntry" id="localEntry">Local Registry / Local Entry</a>
+ </h3>
+ <p>
+ The <localEntry> element is used to declare registry entries that
+ are local to the Synapse instance, as shown below
+ </p>
+<pre xml:space="preserve"> <localEntry key="string" [src="url"]>text | xml</localEntry></pre>
+ <p>
+ These entries are top level entries which are globally visible within the
+ entire system. Values of these entries can be retrieved via the extension
+ XPath function "synapse:get-property(prop-name)" and the keys of these
+ entries could be specified wherever a registry key is expected within the
+ configuration.
+ </p>
+ <p>
+ An entry can be static text specified as inline text or static XML
+ specified as an inline XML fragment or specified as a URL (using the src
+ attribute). A local entry shadows any entry with the same name from a
+ remote Registry.
+ </p>
+<pre xml:space="preserve">e.g.
+<localEntry key="version">0.1</localEntry>
+<localEntry key="validate_schema">
+ <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ ...
+ </xs:schema>
+ </localEntry>
+<localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/></pre>
+ <h2>
+ <a name="sequence" id="sequence">Sequences</a>
+ </h2>
+ <p>
+ A <sequence> element is used to define a sequence of mediators that
+ can be invoked later by name. The sequences named "main" and "fault" has
+ special significance in a Synapse configuration. The "main" sequence
+ handles any message that is accepted for '<a href="#message_mediation">Message
+ Mediation</a>', and the "fault" sequence is invoked if Synapse
+ encounters a fault, and a custom fault handler is not specified for the
+ sequence via its "onError" attribute. If the "main" or "fault" sequences
+ are not defined locally or not found in the Registry, the Synapse ESB
+ defines suitable defaults at initialization.
+ </p>
+ <p>
+ A Dynamic Sequence may be defined by specifying a key reference to a
+ registry entry. As the remote registry entry changes, the sequence will
+ dynamically be updated according to the specified cache duration and
+ expiration. If tracing is enabled on a sequence, all messages being
+ processed through the sequence would write tracing information through
+ each mediation step to the trace.log file configured via the
+ log4j.properties configuration. Setting the trace log level to TRACE would
+ additionally dump the message and detailed trace information at each
+ mediation step. A tracing enabled sequence propagates this setting to
+ invoked sub-sequences.
+ </p>
+<pre xml:space="preserve"> <sequence name="string" [onError="string"] [key="string"] [trace="enable"]>
+ mediator*
+ </sequence></pre>
+<pre xml:space="preserve">e.g.
+<sequence name="main" onError="errorHandler">
+ .. <!-- a 'main' sequence that invokes the sequence named 'errorHandler' on a fault --> ..
+</sequence></pre>
+<pre xml:space="preserve"><sequence key="sequence/dynamic_seq_1.xml"/>
+where "sequence/dynamic_seq_1.xml" refers to the following sequence definition from the registry:
+
+<sequence name="dynamic_sequence" xmlns="http://ws.apache.org/ns/synapse">
+ ..
+</sequence></pre>
+ <h2>
+ <a name="endpoint" id="endpoint">Endpoints</a>
+ </h2>
+ <p>
+ An <endpoint> element defines a destination for an outgoing message.
+ An endpoint may be specified as an address endpoint, WSDL based endpoint,
+ a load balancing endpoint or a fail-over endpoint as follows:
+ </p>
+<pre xml:space="preserve"><endpoint [name="string"] [key="string"]>
+ <a href="#address-endpoint">address-endpoint</a> | <a href="#default-endpoint">default-endpoint</a> | <a href="#wsdl-endpoint">wsdl-endpoint</a> | <a href="#load-balanced-endpoint">load-balanced-endpoint</a> | <a href="#fail-over-endpoint">fail-over-endpoint</a>
+</endpoint> </pre>
+ <p>
+ All above endpoint types can have a name attribute, and such named
+ endpoints can be reffered by other endpoints, through the key attribute.
+ For example if there is an endpoint named as "foo", the following endpoint
+ can be used in any place, where "foo" has to be used.
+ </p>
+<pre xml:space="preserve"><endpoint key="foo"/></pre>
+ <p>
+ The "trace" attribute turns on detailed trace information for messages
+ being sent to the endpoint. These are available in the trace.log
+ configured via the log4j.properties file. Setting the trace log level to
+ TRACE will dump detailed trace information including message payloads.
+ </p>
+ <h4>
+ <a name="address-endpoint" id="address-endpoint">Address Endpoint</a>
+ </h4>
+ <p>
+ Address endpoint is an endpoint defined by specifying the EPR and other
+ attributes of the endpoint directly in the configuration. The 'uri'
+ attribute of the address element contains the EPR of the target endpoint.
+ Message format for the endpoint and the method to optimize attachments can
+ be specified in the format and optimize attributes respectively. Reliable
+ messaging and security policies for the endpoint can be specified in the
+ policy attribute of the enableRM and enableSec elements respectively.
+ WS-Addressing can be engaged for the messaging going to the endpoint by
+ the enableAddressing element. suspendDurationOnFailure attribute specifies
+ the time duration in seconds to suspend this endpoint, if it is detected
+ as failed. If this attribute is not specified, endpoint will never be
+ recovered after a failure.
+ </p>
+ <p>
+ Address endpoints can timeout if responses fail to arrive at Synapse by a
+ predefined timeout-duration specified in seconds. The timeout action
+ specifies whether to discard responses that arrives late, or to trigger a
+ fault. Synapse has a periodic timeout handler that triggers itself at each
+ 15 second interval. Thus endpoint timeouts will have a +/- error on actual
+ trigger time. Though this can be minimized by setting a System property
+ "synapse.timeout_handler_interval" to a millisecond duration below the
+ desired endpoint timeout, care must be taken as a lesser value may have a
+ higher overhead on the system.
+ </p>
+ <p>
+ An endpoint that fails may be suspended for a specified duration after
+ such a failure, during which new messages will not be processed through
+ the endpoint. The 'suspendDurationOnFailure' could specify an optional
+ value in seconds for which this endpoint should be suspended.
+ </p>
+ <p>
+ QoS aspects such as WS-RM and WS-Security and WS-Addressing may be enabled
+ on messages sent to an endpoint using the enableRM, enableSec and
+ enableAddressing elements. Optionally, the WS-RM and WS-Security policies
+ could be specified using the 'policy' attributes.
+ </p>
+<pre xml:space="preserve"><address uri="<em>endpoint address</em>" [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]
+ [encoding="<em>charset encoding</em>"]
+ [statistics="enable|disable"] [trace="enable|disable"]>
+ <enableRM [policy="<em>key</em>"]/>?
+ <enableSec [policy="<em>key</em>"]/>?
+ <enableAddressing [version="final|submission"] [separateListener="true|false"]/>?
+
+ <timeout>
+ <duration><em>timeout duration in seconds</em></duration>
+ <action>discard|fault</action>
+ </timeout>?
+
+ <suspendDurationOnFailure>
+ <em>suspend duration in seconds</em>
+ </suspendDurationOnFailure>?
+</address></pre>
+ <p>
+ Following are some sample address URI definitions.
+ </p>
+ <table border="1" cellpadding="0" cellspacing="0" style="width: 100%; font-size:small" class="data-table">
+ <tbody>
+ <tr><th>Transport</th><th>Sample address</th></tr>
+ <tr><td>HTTP</td><td><tt>http://localhost:9000/soap/SimpleStockQuoteService</tt></td></tr>
+ <tr><td>JMS</td><td><tt>jms:/SimpleStockQuoteService?<br/>
+    transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&<br/>
+    java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&<br/>
+    java.naming.provider.url=tcp://localhost:61616&<br/>
+    transport.jms.DestinationType=topic</tt></td></tr>
+ <tr><td>Mail</td><td><tt>mailto:guest@host</tt></td></tr>
+ <tr><td>VFS</td><td><tt>vfs:file:///home/user/directory</tt></td></tr>
+ <tr><td/><td><tt>vfs:file:///home/user/file</tt></td></tr>
+ <tr><td/><td><tt>vfs:ftp://guest:guest@localhost/directory?vfs.passive=true</tt></td></tr>
+ </tbody>
+ </table>
+ <h4>
+ <a name="default-endpoint" id="default-endpoint">Default Endpoint</a>
+ </h4>
+ <p>
+ Default endpoint is an endpoint defined for adding QoS and other configurations
+ to the endpoint which is resolved from the 'To' address of the message context.
+ All the configurations such as message format for the endpoint, the method
+ to optimize attachments, reliable messaging, security policies for the endpoint
+ can be specified as in the Address Endpoint. This endpoint differs from the address
+ endpoint only in the uri attribute which will not be present in this endpoint.
+ Following section describes the configuration of a default endpoint
+ </p>
+ <pre xml:space="preserve"><default [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]
+ [encoding="<em>charset encoding</em>"]
+ [statistics="enable|disable"] [trace="enable|disable"]>
+ <enableRM [policy="<em>key</em>"]/>?
+ <enableSec [policy="<em>key</em>"]/>?
+ <enableAddressing [version="final|submission"] [separateListener="true|false"]/>?
+
+ <timeout>
+ <duration><em>timeout duration in seconds</em></duration>
+ <action>discard|fault</action>
+ </timeout>?
+
+ <suspendDurationOnFailure>
+ <em>suspend duration in seconds</em>
+ </suspendDurationOnFailure>?
+</default></pre>
+ <h4>
+ <a name="wsdl-endpoint" id="wsdl-endpoint">WSDL Endpoint</a>
+ </h4>
+ <p>
+ WSDL endpoint is an endpoint definition based on a specified WSDL
+ document. The WSDL document can be specified either as a URI or as an
+ inlined definition within the configuration. The service and port name
+ containing the target EPR has to be specified with the 'service' and
+ 'port' (or 'endpoint') attributes respectively. enableRM, enableSec,
+ enableAddressing, suspendDurationOnFailure and timeout elements are same
+ as for an Address endpoint.
+ </p>
+<pre xml:space="preserve"><wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname">
+ <wsdl:definition>...</wsdl:definition>?
+ <wsdl20:description>...</wsdl20:description>?
+ <enableRM [policy="key"]/>?
+ <enableSec [policy="key"]/>?
+ <enableAddressing/>?
+ <suspendDurationOnFailure>suspend-duration</suspendDurationOnFailure>?
+ <timeout>
+ <duration>timeout-duration</duration>
+ <action>discard|fault</action>
+ </timeout>?
+</wsdl></pre>
+ <h4>
+ <a name="load-balanced-endpoint" id="load-balanced-endpoint">Load
+ balanced Endpoint</a>
+ </h4>
+ <p>
+ A Load balanced endpoint distributes the messages (load) arriving at it
+ among a set of listed endpoints by evaluating the load balancing policy
+ and any other relevant parameters. Policy attribute of the load balance
+ element specifies the load balance policy (algorithm) to be used for
+ selecting the target endpoint. Currently only the roundRobin policy is
+ supported. failover attribute determines if the next endpoint should be
+ selected once the currently selected endpoint has failed, and defaults to
+ true. The set of endpoints among which the load is distributed can be
+ listed under the 'loadBalance' element. Those endpoints can belong to any
+ endpoint type mentioned in this document. For example, failover endpoints
+ can be listed inside the load balance endpoint to load balance between
+ failover groups etc.
+ </p>
+ <p>
+ The optional 'session' element makes the endpoint a session affinity based
+ load balancing endpoint. If it is specified, sessions are bound to
+ endpoints in the first message and all successive messages for those
+ sessions are directed to their associated endpoints. Currently there are two types
+ of sessions supported in SAL endpoints. Namely HTTP transport based session
+ which identifies the sessions based on http cookies and the client session which
+ identifies the session by looking at a SOAP header sent by the client with the QName
+ '{http://ws.apache.org/ns/synapse}ClientID'. The 'failover' attribute mentioned above
+ is not applicable for session affinity based endpoints and it is always
+ considered as set to false. If it is required to have failover behavior in session
+ affinity based load balance endpoints, list failover endpoints as the target endpoints.
+ </p>
+<pre xml:space="preserve"><session type="http|simpleClientSession"/>?
+<loadBalance [policy="roundRobin"] [failover="true|false"]>
+ <endpoint .../>+
+</loadBalance></pre>
+ <h4>
+ <a name="fail-over-endpoint" id="fail-over-endpoint">Failover Endpoint</a>
+ </h4>
+ <p>
+ Failover endpoints send messages to the listed endpoints with the
+ following failover behavior. At the start, the first listed endpoint is
+ selected as the primary and all other endpoints are treated as backups.
+ Incoming messages are always sent only to the primary endpoint. If the
+ primary endpoint fails, next active endpoint is selected as the primary
+ and failed endpoint is marked as inactive. Thus it sends messages
+ successfully as long as there is at least one active endpoint among the
+ listed endpoints.
+ </p>
+<pre xml:space="preserve"><failover>
+ <endpoint .../>+
+</failover></pre>
+ <h2>
+ <a name="proxy" id="proxy">Proxy service</a>
+ </h2>
+ <p>
+ A <proxy> element is used to define a Synapse Proxy service.
+ </p>
+<pre xml:space="preserve"> <proxy name="string" [transports="(http |https |jms |.. )+|all"] [pinnedServers="(serverName )+"]>
+ <description>...</description>?
+ <target [inSequence="name"] [outSequence="name"] [faultSequence="name"] [endpoint="name"]>
+ <inSequence>...</inSequence>?
+ <outSequence>...</outSequence>?
+ <faultSequence>...</faultSequence>?
+ <endpoint>...</endpoint>?
+ </target>?
+ <publishWSDL key="string" uri="string">
+ ( <wsdl:definition>...</wsdl:definition> | <wsdl20:description>...</wsdl20:description> )?
+ <resource location="..." key="..."/>*
+ </publishWSDL>?
+ <enableSec/>?
+ <enableRM/>?
+ <policy key="string" [type="(in | out)"]/>? // optional service or message level policies such as (e.g. WS-Security and/or WS-RM policies)
+ <parameter name="string"> // optional service parameters such as (e.g. transport.jms.ConnectionFactory)
+ string | xml
+ </parameter>
+ </proxy></pre>
+ <p>
+ A proxy service is created and exposed on the specified transports through
+ the underlying Axis2 engine, exposing service EPR's as per the standard
+ Axis2 conventions - based on the service name. (Note: that currently Axis2
+ does not allow custom URI's to be set for services on some transports such
+ as http/s) The Proxy service could be exposed over all enabled Axis2
+ transports such as http, https, JMS, Mail and File etc. or on a subset of
+ these as specified with the optional 'transports' attribute.
+ </p>
+ <p>
+ You can give a list of Synapse server names where this proxy service
+ should be deployed using 'pinnedServers' attribute. It takes the server
+ names separated by comma or space character. If there is no pinned server
+ list then proxy service will be started in all server instances. If a
+ pinned server names list is given it will only start in the given named
+ Synapse server instances. The Synapse server name is picked up from the
+ system property 'SynapseServerName', failing which the hostname of the
+ machine would be used or default to 'localhost'. You can give a name to a
+ Synapse server instance as ./synapse.sh -DSynapseServerName=<ServerName>
+ or by editing the wrapper.conf where Synapse is started as a service.
+ </p>
+ <p>
+ Each service could define the target for received messages as a named
+ sequence or a direct endpoint. Target inSequence or endpoint is required
+ for the proxy configuration, and a target outSequence defines how
+ responses should be handled. Any supplied WS-Policies would apply as
+ service level policies, and any service parameters could be passed into
+ the proxy services' AxisService instance using the parameter elements
+ (e.g. the JMS destination etc). If the proxy service should enable
+ WS-Reliable Messaging or Security, the appropriate modules could be
+ engaged, and specified service level policies will apply.
+ </p>
+ <p>
+ A Dynamic Proxy may be defined by specifying the properties of the proxy
+ as dynamic entries by refering them with the key. (For example one could
+ specify the inSequence or endpoint with a remote key, without defining it
+ in the local configuration) As the remote registry entry changes, the
+ properties of the proxy will dynamically be updated accordingly. (Note:
+ proxy service definition itself can not be specified to be dynamic; i.e
+ <proxy key="string"/> is wrong)
+ </p>
+ <p>
+ A WSDL for the proxy service can be published using the <publishWSDL>
+ element. The WSDL document can be loaded from the registry by
+ specifying the 'key' attribute or from any other location by specifying the
+ 'uri' attribute. Alternatively the WSDL can be provided inline as a child
+ element of <publishWSDL>. Artifacts (schemas or other WSDL documents)
+ imported by the WSDL can be resolved from the registry by specifying
+ appropriate <resource> elements:
+ </p>
+<pre> <publishWSDL key="my.wsdl">
+ <resource location="http://www.standards.org/standard.wsdl" key="standard.wsdl"/>
+ </publishWSDL>
+</pre>
+ <p>
+ In this example the WSDL is retrieved from the registry using the key 'my.wsdl'. It
+ imports another WSDL from location 'http://www.standards.org/standard.wsdl'. Instead
+ of loading it from this location, Synapse will retrieve the imported WSDL from the
+ registry entry 'standard.wsdl'.
+ </p>
+ <p>
+ You can give the following as service parameters:
+ </p>
+ <table border="1" cellpadding="0" cellspacing="0" style="width: 100%; font-size:small" class="data-table">
+ <caption/>
+ <tbody>
+ <tr>
+ <th>
+ Parameter
+ </th>
+ <th>
+ Value
+ </th>
+ <th>
+ Default
+ </th>
+ <th>
+ Description
+ </th>
+ </tr>
+ <tr>
+ <td>
+ useOriginalwsdl
+ </td>
+ <td>
+ true|false
+ </td>
+ <td>
+ false
+ </td>
+ <td>
+ Use the given WSDL instead of generating the WSDL.
+ </td>
+ </tr>
+ <tr>
+ <td>
+ modifyUserWSDLPortAddress
+ </td>
+ <td>
+ true|false
+ </td>
+ <td>
+ true
+ </td>
+ <td>
+ (Effective only with useOriginalwsdl=true) If true (default) modify
+ the port addresses to current host.
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ <p/>
+ <p>
+ Transport specific parameters that may be set as service parameters:
+ </p>
+ <table border="1" cellpadding="0" cellspacing="0" style="width: 100%; font-size:small" class="data-table">
+ <caption/>
+ <tbody>
+ <tr>
+ <th>
+ Transport
+ </th>
+ <th>
+ Require
+ </th>
+ <th>
+ Parameter
+ </th>
+ <th>
+ Description
+ </th>
+ </tr>
+ <tr>
+ <td>
+ JMS
+ </td>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.jms.ConnectionFactory
+ </td>
+ <td>
+ The JMS connection factory definition (from axis2.xml) to be used to
+ listen for messages for this service
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.jms.Destination
+ </td>
+ <td>
+ The JMS destination name (Defaults to a Queue with the service name)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.jms.DestinationType
+ </td>
+ <td>
+ The JMS destination type. Accept values 'queue' or 'topic' (default:
+ queue)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.jms.ReplyDestination
+ </td>
+ <td>
+ The destination where a reply will be posted
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.jms.Wrapper
+ </td>
+ <td>
+ The wrapper element for the JMS message
+ </td>
+ </tr>
+ <tr>
+ <td>
+ VFS
+ </td>
+ <td>
+ Required
+ </td>
+ <td>
+ transport.vfs.FileURI
+ </td>
+ <td>
+ The primary File (or Directory) URI in the vfs* transport format,
+ for this service
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Required
+ </td>
+ <td>
+ transport.vfs.ContentType
+ </td>
+ <td>
+ The expected content type for files retrieved for this service. The
+ VFS transport uses this information to select the appropriate
+ message builder.
+ <br/>
+ Examples:
+ <ul>
+ <li><tt>text/xml</tt> for plain XML or SOAP</li>
+ <li><tt>text/plain; charset=ISO-8859-1</tt> for text files</li>
+ <li><tt>application/octet-stream</tt> for binary data</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.FileNamePattern
+ </td>
+ <td>
+ A file name regex pattern to match files against a directory
+ specified by the FileURI
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.PollInterval
+ </td>
+ <td>
+ The poll interval (in seconds)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.ActionAfterProcess
+ </td>
+ <td>
+ DELETE or MOVE
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.MoveAfterProcess
+ </td>
+ <td>
+ The directory to move files after processing (i.e. all files process
+ successfully)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.ActionAfterErrors
+ </td>
+ <td>
+ DELETE or MOVE
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.MoveAfterErrors
+ </td>
+ <td>
+ The directory to move files after errors (i.e. some of the files
+ succeed but some fail)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.ActionAfterFailure
+ </td>
+ <td>
+ DELETE or MOVE
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.MoveAfterFailure
+ </td>
+ <td>
+ The directory to move after failure (i.e. all files fail)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.ReplyFileURI
+ </td>
+ <td>
+ Reply file URI
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.ReplyFileName
+ </td>
+ <td>
+ Reply file name (defaults to response.xml)
+ </td>
+ </tr>
+ <tr>
+ <td/>
+ <td>
+ Optional
+ </td>
+ <td>
+ transport.vfs.MoveTimestampFormat
+ </td>
+ <td>
+ Timestamp prefix format for processed file name. java.text.SimpleDateFormat compatible string. e.g. yyMMddHHmmss'-'
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ <p>
+ VFS Transport URI examples (See <a
+ href="http://commons.apache.org/vfs/filesystems.html">http://commons.apache.org/vfs/filesystems.html</a>
+ for more samples)
+ </p>
+<pre xml:space="preserve">file:///directory/filename.ext
+file:////somehost/someshare/afile.txt
+jar:../lib/classes.jar!/META-INF/manifest.mf
+jar:zip:outer.zip!/nested.jar!/somedir
+ftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz[?vfs.passive=true]</pre>
+
+ <h2>
+ <a name="task" id="task">Tasks</a>
+ </h2>
+ <p>
+ A <task> element is used to define a Synapse Startup Task.
+ </p>
+<pre xml:space="preserve"> <task class="mypackage.MyTask" name="string" [pinnedServers="(serverName)+"]>
+ <property name="stringProp" value="String"/>
+ <property name="xmlProp">
+ <somexml>config</somexml>
+ </property>
+ <trigger ([[count="10"]? interval="1000"] | [cron="0 * 1 * * ?"] | [once=(true | false)])/>
+ </task></pre>
+ <p>
+ A task is created and scheduled to run at specified time intervals or as
+ specified by the cron expression. The Task class specifies the actual task
+ implementation class (which must implement org.apache.synapse.startup.Task
+ interface) to be executed at the specified interval/s, and name specifies
+ an identifier for the scheduled task.
+ </p>
+ <p>
+ Fields in the task class can be set using properties provided as string
+ literals or as XML fragments. (For example; if the task implementation
+ class has a field named "version" with a corresponding setter method, the
+ configuration value which will be assigned to this field before running
+ the task can be specified using a property with the name 'version')
+ </p>
+ <p>
+ There are three different trigger mechanisms to schedule tasks. A simple
+ trigger is specified specifying a 'count' and an 'interval', implying that
+ the task will run a 'count' number of times at specified intervals. A
+ trigger may also be specified as a cron trigger using a cron expression. A
+ one-time trigger is specified using the 'once' attribute as true in the
+ definition and could be specified as true in which case this task will be
+ executed only once just after the initialization of Synapse
+ </p>
+ <p>
+ You can give a list of Synapse server names where this task should be
+ started using pinnedServers attribute. Refer to the explanation of this
+ attribute under proxy services for more information.
+ </p>
+ <h2>
+ <a name="mediator" id="mediator">Mediators</a>
+ </h2>
+ <p>
+ A mediator token refers to any of the following tokens:
+ </p>
+<pre xml:space="preserve">
+ <a href="#send">send</a> | <a href="#drop">drop</a> | <a href="#log">log</a> | <a href="#property">property</a> | <a href="#sequence_ref">sequence</a> | <a href="#validate">validate</a> | <a href="#Callout">Callout</a> | <a href="#makefault">makefault</a> | <a href="#xslt">xslt</a> | <a href="#xquery">xquery</a> | <a href="#header">header</a> | <a href="#filter">filter</a> | <a href="#switch">switch</a> | <a href="#in">in</a> | <a href="#out">out</a>
+ | <a href="#dblookup">dblookup</a> | <a href="#dbreport">dbreport</a> | <a href="#throttle">throttle</a> | <a href="#cache">cache</a> | <a href="#clone">clone</a> | <a href="#iterate">iterate</a> | <a href="#aggregate">aggregate</a> | <a href="#class">class</a> | <a href="#pojoCommand">pojoCommand</a> | <a href="#spring">spring</a> | <a href="#script">script</a> | <a href="#RMSequence">RMSequence</a>
+ </pre>
+ <p>
+ In addition to the above, Synapse will be able to load custom mediators
+ via the J2SE Service Provider model. Mediator extensions must implement
+ the MediatorFactory interface. The Class and POJO Command mediators allow
+ custom Java code to be easily invoked during mediation, while the Script
+ mediator allows Apache BSF scripts such as Javascript, Ruby, Groovy etc to
+ be used for mediation.
+ </p>
+ <h3>
+ Core Mediators
+ </h3>
+ <h4>
+ <a name="send" id="send">Send</a>
+ </h4>
+ <p>
+ The send token represents a <send> element, used to send messages
+ out of Synapse to some endpoint. The send mediator also copies any message
+ context properties from the current message context to the reply message
+ received on the execution of the send operation so that the response could
+ be correlated back to the request. Messages may be correlated by WS-A
+ MessageID, or even simple custom text labels (see the property mediator
+ and samples)
+ </p>
+ <p>
+ In the simplest case shown below, the destination to send a message is
+ implicit in the message via the 'To' address. Thus a request message will
+ be sent to its 'To' address, and a response message would be sent back to
+ the client. Removing the 'To' address of a message targets it back to the
+ client, and thus a request message received may be returned to the client
+ after changing its direction. (Note: to mark a message as a response set
+ the property RESPONSE to true)
+ </p>
+ <p>
+ <strong>Note:</strong> A send operation may be blocking or
+ non-blocking depending on the actual transport implementation used. As the
+ default NIO based http/s implementation does not block on a send, care
+ must be taken if the same message must be sent and then further processed
+ (e.g. transformed). In such a scenario, it maybe required to first clone
+ the message into two copies and then perform processing to avoid
+ conflicts.
+ </p>
+<pre xml:space="preserve"> <send/></pre>
+ <p>
+ If the message is to be sent to one or more endpoints, then the following
+ is used:
+ </p>
+<pre xml:space="preserve"> <send>
+ (endpointref | endpoint)+
+ </send></pre>
+ <p>
+ where the endpointref token refers to the following:
+ </p>
+<pre xml:space="preserve"> <endpoint key="name"/></pre>
+ <p>
+ and the endpoint token refers to an anonymous endpoint definition.
+ </p>
+ <p/>
+ <h4>
+ <a name="drop" id="drop">Drop</a>
+ </h4>
+ <p>
+ The drop token refers to a <drop> element which is used to stop
+ further processing of a message:
+ </p>
+<pre xml:space="preserve"> <drop/></pre>
+ <p>
+ Once the <drop> mediator executes, further processing of the current
+ message stops. A the drop mediator does not necessarily close transports.
+ </p>
+ <p/>
+ <h4>
+ <a name="log" id="log">Log</a>
+ </h4>
+ <p>
+ The log token refers to a <log> element which may be used to log
+ messages being mediated:
+ </p>
+<pre xml:space="preserve"> <log [level="string"] [separator="string"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+ </log></pre>
+ <p>
+ The optional level attribute selects a pre-defined subset of properties to
+ be logged.
+ </p>
+ <p>
+ e.g.
+ </p>
+ <ul>
+ <li>
+ simple = To, From, WSAction, SOAPAction, ReplyTo, MessageID and any
+ properties
+ </li>
+ <li>
+ headers = All SOAP header blocks and any properties
+ </li>
+ <li>
+ full = all attributes included in log level 'simple' and the SOAP
+ envelope and any properties
+ </li>
+ <li>
+ custom = Only properties specified to the Log mediator
+ </li>
+ </ul>
+ <p>
+ A separator if defined will be used to separate the attributes being
+ logged. The default separator is the ',' comma.
+ </p>
+ <p/>
+ <h4>
+ <a name="property" id="property">Property</a>
+ </h4>
+<pre xml:space="preserve"> <property name="string" [action=set|remove] (value="literal" | expression="xpath") [scope=transport|axis2|axis2-client]/></pre>
+ <p>
+ The property token refers to a <property> element which is a
+ mediator that has no direct impact on the message but rather on the
+ message context flowing through Synapse. The properties set on a message
+ can be later retrieved through the synapse:get-property(prop-name) XPath
+ extension function. If a scope is specified for a property, the property
+ could be set as a transport header property or an (underlying) Axis2
+ message context property, or as a Axis2 client option. If a scope is not
+ specified, it will default to the Synapse message context scope. Using the
+ property element with action specified as "remove" you can remove any
+ existing message context properties.
+ </p>
+ <p>
+ There are some well-defined properties that you can get/set on the Synapse
+ message context scope:
+ </p>
+ <ul>
+ <li>
+ RESPONSE - 'true' means the message is to be marked as a response
+ message
+ </li>
+ <li>
+ OUT_ONLY - 'true' means the message is to be marked as an out-only
+ message that does not expect a response
+ </li>
+ <li>
+ ERROR_CODE - this is set to any error message code encountered during a
+ fault
+ </li>
+ <li>
+ ERROR_MESSAGE - this is set to any error message text encountered during
+ a fault
+ </li>
+ <li>
+ ERROR_DETAIL - this is set to any error message detail text encountered
+ during a fault
+ </li>
+ <li>
+ ERROR_EXCEPTION - this is set to any Java Exception encountered during a
+ fault
+ </li>
+ </ul>
+ <p>
+ There are some Axis2 and module properties that are useful which are set
+ at scope="axis2"
+ </p>
+ <ul>
+ <li>
+ Mercury2SequenceKey - can be an identifier specifying a Mercury
+ internal sequence key, and
+ </li>
+ <li>
+ Mercury2LastMessage - 'true' will make this the last message and
+ terminate the sequence
+ </li>
+ </ul>
+ <p>
+ There are some Axis2 client side properties/options that are useful which
+ are set at scope="axis2-client"
+ </p>
+ <ul>
+ <li>
+ FORCE_HTTP_1.0 - forces outgoing http/s messages to use HTTP 1.0
+ (instead of the default 1.1)
+ </li>
+ </ul>
+ <h5>
+ The synapse:get-property() XPath extension function
+ </h5>
+ <p>
+ The get-property() function allows any XPath expression used in a
+ configuration to lookup information from the current message context. It
+ is possible to retrieve properties previously set with the property
+ mediator, and/or information from the Synapse or Axis2 message contexts or
+ transport header. The function accepts the scope as an optional parameter
+ as shown below:
+ </p>
+ <p>
+ synapse:get-property( [(axis2 | axis2-client | transport),] <property_name>
+ [,<dateformat>] )
+ </p>
+ <p/>
+ <p>
+ Some useful properties from the Synapse message context follows:
+ </p>
+ <ul>
+ <li>
+ SYSTEM_DATE - Returns the current date as a String. Optionally a date
+ format as per standard date format may be supplied. e.g.
+ synapse:get-property("SYSTEM_DATE", "yyyy.MM.dd G 'at' HH:mm:ss z") or
+ get-property('SYSTEM_DATE')
+ </li>
+ <li>
+ SYSTEM_TIME - Returns the current time in milliseconds. (i.e. the
+ difference, measured in milliseconds, between the current time and
+ midnight, January 1, 1970 UTC)
+ </li>
+ <li>
+ To, From, Action, FaultTo, ReplyTo, MessageID the message To and Action
+ and WS-Addressing properties
+ </li>
+ <li>
+ MESSAGE_FORMAT - returns the message format - i.e. returns pox, get,
+ soap11 or soap12
+ </li>
+ <li>
+ OperationName - returns the operation name for the message
+ </li>
+ </ul>
+ <p>
+ In addition to the above, one may use the get-property() function to
+ retrieve Axis2 message context properties or transport headers. e.g.
+ synapse:get-property('transport', 'USER_AGENT')
+ </p>
+ <h5>
+ SynapseXpath variables
+ </h5>
+ <p>
+ There are a set of predefined XPath variables when writing XPaths in
+ the Synapse Configuration. Those are as follows;
+ </p>
+ <ul>
+ <li>
+ body - The SOAP 1.1 or 1.2 body element
+ </li>
+ <p>
+ For example; expression="$body/getQuote" refers to the first
+ getQuote element in the SOAP body regardless of whether the message
+ is SOAP-11 or SOAP-12
+ </p>
+ <li>
+ header - The SOAP 1.1 or 1.2 header element
+ </li>
+ <p>
+ For example; expression="$header/wsa:To" refers to the addressing
+ To header regardless of whether this message is SOAP-11 or SOAP-12
+ </p>
+ </ul>
+ <p>
+ Further there are some variable prefixes defined in Synapse XPaths
+ which can be usefull in writing the configurations;
+ </p>
+ <ul>
+ <li>
+ ctx - Prefix for Synapse MessageContext properties
+ </li>
+ <p>
+ For example; expression="$ctx:RESPONSE" gives the value of the
+ Synapse message context property with name 'RESPONSE'
+ </p>
+ <li>
+ axis2 - Prefix for Axis2 MessageContext properties
+ </li>
+ <p>
+ For example; expression="$axis2:messageType" gives the value of the
+ axis2 message context property with name 'messageType'
+ </p>
+ <li>
+ trp - Prefix for the transport headers
+ </li>
+ <p>
+ For example; expression="$trp:Content-Type" gives the value of the
+ 'Content-Type' transport header, which is going to be the
+ Content-Type of the current message
+ </p>
+ </ul>
+ <h4>
+ <a name="sequence_ref" id="sequence_ref">Sequence</a>
+ </h4>
+<pre xml:space="preserve"> <sequence key="name"/></pre>
+ <p>
+ A sequence ref token refers to a <sequence> element which is used to
+ invoke a named sequence of mediators.
+ </p>
+ <p/>
+ <h4>
+ <a name="validate" id="validate">Validate</a>
+ </h4>
+<pre xml:space="preserve"> <validate [source="xpath"]>
+ <property name="validation-feature-id" value="true|false"/>*
+ <schema key="string"/>+
+ <on-fail>
+ mediator+
+ </on-fail>
+ </validate></pre>
+ <p>
+ The <validate> mediator validates the result of the evaluation of
+ the source xpath expression, against the schema specified. 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. Properties could be used to
+ turn on/off some of the underlying features of the validator (See <a
+ href="http://xerces.apache.org/xerces2-j/features.html">http://xerces.apache.org/xerces2-j/features.html</a>)
+ </p>
+ <p/>
+ <h4>
+ <a name="Callout" id="Callout">Callout</a>
+ </h4>
+<pre xml:space="preserve"> <callout serviceURL="string" [action="string"]>
+ <configuration [axis2xml="string"] [repository="string"]/>?
+ <source xpath="expression" | key="string">
+ <target xpath="expression" | key="string"/>
+ </callout>
+</pre>
+ <p>
+ The <callout> mediator performs a blocking external service invocation during
+ mediation. The serviceURL and the optional action specifies the parameters for this external
+ call. The source element specifies the payload for the request message using an XPath expression;
+ or a registry key that will be used. The target element specifies a node, at which the resulting
+ 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>
+ <p>As 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 separately
+ </p>
+ <h3>
+ Transformation Mediators
+ </h3>
+ <h4>
+ <a name="makefault" id="makefault">Makefault</a>
+ </h4>
+<pre xml:space="preserve"> <makefault [version="soap11|soap12|pox"]>
+ <code (value="literal" | expression="xpath")/>
+ <reason (value="literal" | expression="xpath")>
+ <node>?
+ <role>?
+ <detail>?
+ </makefault></pre>
+ <p>
+ The <makefault> mediator transforms the current message into a fault
+ message, but does NOT send it. The <send> mediator needs to be
+ invoked to send a fault message created this way. The fault message "To"
+ header is set to the "Fault-To" of the original message if such a header
+ exists on the original message. If a 'version' attribute is specified,
+ the created fault message will be created as a selected SOAP 1.1, SOAP
+ 1.2 or POX fault.
+ </p>
+ <p/>
+ <h4>
+ <a name="xslt" id="xslt">XSLT</a>
+ </h4>
+<pre xml:space="preserve"> <xslt key="string" [source="xpath"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+ <feature name="string" value="true| false" />*
+ </xslt></pre>
+ <p>
+ The <xslt> mediator applies the specified XSLT transformation to the
+ selected element of the current message payload. If the source element is
+ not specified, it defaults to the first child of the soap body. Optionally
+ parameters (XSLT) could be passed into the transformations through the
+ 'property' elements. The 'feature' element defines any features which
+ should be explicitly set to the TransformerFactory. The feature
+ 'http://ws.apache.org/ns/synapse/transform/feature/dom' turns on DOM based
+ transformations instead of serializing elements into Byte streams and/or
+ temporary files. Though this would be better in performance than using
+ byte streams, sometimes it may not work for all transformations.
+ </p>
+ <h4>
+ <a name="xquery" id="xquery">XQuery</a>
+ </h4>
+<pre xml:space="preserve"><xquery key="string" [target="xpath"]>
+ <variable name="string" type="string" [key="string"] [expression="xpath"] [value="string"]/>?
+</xquery> </pre>
+ <p/>
+ <p>
+ The XQuery mediator can be used to perform an XQuery transformation. The
+ '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. The 'variable' elements define 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>
+ <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>
+ <p/>
+ <h4>
+ <a name="header" id="header">Header</a>
+ </h4>
+<pre xml:space="preserve"> <header name="qname" (value="literal" | expression="xpath") [action="set"]/>
+ <header name="qname" action="remove"/></pre>
+ <p>
+ The <header> mediator sets or removes a specified header from the
+ current soap infoset. Currently the set header only supports simple valued
+ headers. In the future we may extend this to have XML structured headers
+ by embedding the XML content within the element itself. The optional
+ action attribute specifies whether the mediator should set or remove the
+ header. If omitted, it defaults to a set-header.
+ </p>
+ <p/>
+ <h3>
+ Selection Mediators
+ </h3>
+ <h4>
+ <a name="filter" id="filter">Filter</a>
+ </h4>
+<pre xml:space="preserve"> <filter (source="xpath" regex="string") | xpath="xpath">
+ mediator+
+ </filter></pre>
+ <p>
+ The <filter> mediator either test the given xpath expression as a
+ boolean expression, or match the evaluation result of a source xpath
+ expression as a String against the given regular expression. If the test
+ succeeds, the filter mediator will execute the enclosed mediators in
+ sequence.
+ </p>
+ <p>One could also use this mediator to handle the failure case as well, in which case the
+ configuration would be as follows
+ </p>
+<pre xml:space="preserve"> <filter (source="xpath" regex="string") | xpath="xpath">
+ <then [sequence="string"]>
+ mediator+
+ </then>
+ <else [sequence="string"]>
+ mediator+
+ </else>
+ </filter></pre>
+ <p>In this case the filter condition remains as earlier and the succeeded messages will be
+ mediated using the the set of mediators enclosed in the 'then' element in sequence, while
+ failed messages will be mediated using the set of mediators enclosed in the else element
+ in sequence
+ </p>
+ <p/>
+ <h4>
+ <a name="switch" id="switch">Switch</a>
+ </h4>
+<pre xml:space="preserve"> <switch source="xpath">
+ <case regex="string">
+ mediator+
+ </case>+
+ <default>
+ mediator+
+ </default>?
+ </switch></pre>
+ <p>
+ The <switch> mediator will evaluate the given source xpath
+ expression into its string value, and match it against the given regular
+ expressions. If the specified cases does not match and a default case
+ exists, it will be executed.
+ </p>
+ <a name="in" id="in"/>
+ <h4>
+ <a name="out" id="out">In / Out</a>
+ </h4>
+<pre xml:space="preserve"><in><br/> mediator+
+</in><br/></pre>
+<pre xml:space="preserve"><out>
+ mediator+
+</out></pre>
+ <p>
+ <br/>
+ </p>
+ <p>
+ The In and Out mediators will execute the child mediators over the current
+ message if the message matches the direction of the mediator. Hence all
+ incoming messages would pass through the "<in>" mediators and vice
+ versa.
+ </p>
+ <p/>
+ <h3>
+ Database Mediators
+ </h3>
+ <h4>
+ <a name="dblookup" id="dblookup">DB-lookup</a>
+ </h4>
+<pre xml:space="preserve"><dblookup>
+ <connection>
+ <pool>
+ (
+ <driver/>
+ <url/>
+ <user/>
+ <password/>
+ |
+ <dsName/>
+ <icClass/>
+ <url/>
+ <user/>
+ <password/>
+ )
+ <property name="name" value="value"/>*
+ </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></pre>
+ <p/>
+ <p>
+ The dblookup 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. Apache DBCP connection pools
+ support the following 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>
+ More than one statement may be specified, and the SQL statement may
+ specify parameters which could be specified as values or XPath
+ expressions. The types of parameters could be any valid SQL types. Only
+ the first row of a result set will be considered and any others are
+ ignored. The single <result> element contains the 'name' and the
+ column' attributes. The 'name' attribute defines the name under which the
+ result is stored in the Synapse message context, and the column attribute
+ specifies a column number or name .
+ </p>
+ <h4>
+ <a name="dbreport" id="dbreport">DB-report</a>
+ </h4>
+<pre xml:space="preserve"><dbreport>
+ <connection>
+ <pool>
+ (
+ <driver/>
+ <url/>
+ <user/>
+ <password/>
+ |
+ <dsName/>
+ <icClass/>
+ <url/>
+ <user/>
+ <password/>
+ )
+ <property name="name" value="value"/>*
+ </pool>
+ </connection>
+ <statement>
+ <sql>insert into something values(?, ?, ?, ?)</sql>
+ <parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>*
+ </statement>+
+</dblreport></pre>
+ <p/>
+ <p>
+ The dbreport mediator is very similar to the dblookup mediator, but writes
+ information to a Database, using the specified insert SQL statement.
+ </p>
+ <p/>
+ <h3>
+ Advanced Mediators
+ </h3>
+ <h4>
+ <a name="throttle" id="throttle">Throttle</a>
+ </h4>
+<pre xml:space="preserve"><throttle [onReject="string"] [onAccept="string"] id="string">
+ (<policy key="string"/> | <policy>..</policy>)
+ <onReject>..</onReject>?
+ <onAccept>..</onAccept>?
+</throttle></pre>
+ <p/>
+ <p>
+ The Throttle mediator can be used for rate limiting as well as concurrency
+ based limiting. A WS-Policy dictates the throttling configuration and may
+ be specified inline or loaded from the registry. Please refer to the
+ samples document for sample throttling policies. The Throttle mediator
+ could be added in the request path for rate limiting and concurrent access
+ limitation. When using 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). The 'onReject' and 'onAccept' sequence references or
+ inline sequences define how accepted and rejected messages are to be
+ handled.
+ </p>
+ <h4>
+ <a name="cache" id="cache">Cache</a>
+ </h4>
+<pre xml:space="preserve"> <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></pre>
+ <p>
+ The <cache> 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. The 'collector' attribute '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 the 'implementation' element may
+ define if the cache is disk or memory based, and the 'maxSize' attribute
+ defines the maximum number of elements to be cached.
+ </p>
+ <h3>
+ EIP Mediators
+ </h3>
+ <h4>
+ <a name="clone" id="clone">Clone</a>
+ </h4>
+<pre xml:space="preserve"> <clone [continueParent=(true | false)]>
+ <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]>
+ <sequence>
+ (mediator)+
+ </sequence>?
+ <endpoint>
+ endpoint
+ </endpoint>?
+ </target>+
+ </clone></pre>
+ <p>
+ The clone mediator closely resembles the Message Splitter EIP and will
+ split the message into number of identical messages which will be
+ processed in parallel. The original message cloned 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
+ </p>
+ <h4>
+ <a name="iterate" id="iterate">Iterate</a>
+ </h4>
+<pre xml:space="preserve"> <iterate [continueParent=(true | false)] [preservePayload=(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></pre>
+ <p>
+ The iterate mediator implements another EIP and will split 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 and every matching element and processed in
+ parallel using either the specified sequence or endpoint. 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 splitted messages, and defaults to
+ 'false', in which case the splitted messages would contain the split
+ elements as the SOAP body.
+ </p>
+ <h4>
+ <a name="aggregate" id="aggregate">Aggregate</a>
+ </h4>
+<pre xml:space="preserve"> <aggregate>
+ <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></pre>
+ <p>
+ The aggregate mediator implements the Message Aggregator EIP and will
+ aggregate the messages or responses for splitted messages using either the
+ clone or iterate mediators. At the same time it can 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>
+ <h3>
+ Extension mediators
+ </h3>
+ <h4>
+ <a name="class" id="class">Class</a>
+ </h4>
+<pre xml:space="preserve"> <class name="class-name">
+ <property name="string" value="literal">
+ (either literal or XML child)
+ </property>
+ </class> </pre>
+ <p>
+ The class mediator creates an instance of a custom specified class and
+ sets it 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>
+ <p/>
+ <h4>
+ <a name="pojoCommand" id="pojoCommand">POJOCommand</a>
+ </h4>
+<pre xml:space="preserve"> <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> </pre>
+ <p>
+ The pojoCommand mediator creates an instance of the specified command
+ class - which may implement the org.apache.synapse.Command interface or
+ should have a public void method "public void execute()". 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 properties.
+ </p>
+ <p/>
+ <h3>
+ <a name="script" id="script">Scripting language mediators</a>
+ </h3>
+ <p/>
+ <p>
+ Synapse supports Mediators implemented in a variety of scripting languages
+ such as JavaScript, Python or Ruby. There are two ways of defining script
+ mediators, 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>
+<pre xml:space="preserve"> <script key="string" language="string" [function="script-function-name"]/></pre>
+ <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>
+<pre xml:space="preserve"> <script language="string">...script source code...<script/></pre>
+ <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>
+<pre xml:space="preserve"> <script language="js">mc.getPayloadXML()..symbol != "IBM";<script/></pre>
+ <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>
+ <h3>
+ Extensibility of Synapse
+ </h3>
+ <p>
+ The Synapse configuration language could be easily extended, with
+ configuration extensions as well as mediation extensions. The Spring
+ mediator is such an example.
+ </p>
+ <h4>
+ Spring Configuration
+ </h4>
+ <p>
+ A Spring configuration could be created as a localEntry or remote registry
+ entry providing a URL or a key reference to a Registry. The configuration
+ is then created on first use or as necessary (as per registry lookup
+ semantics) by the mediators which reference this configuration.
+ </p>
+<pre xml:space="preserve"> <localEntry key="string"/>
+ <localEntry key="string" src="url"/></pre>
+ <p>
+ The name attribute specifies a unique name for the configuration, and the
+ src, key or inlined XML references to the Spring configuration
+ </p>
+ <p/>
+ <h4>
+ <a name="spring" id="spring">Spring mediator</a>
+ </h4>
+<pre xml:space="preserve"> <spring:spring bean="exampleBean1" key="string"/></pre>
+ <p>
+ The <spring> element creates an instance of a mediator, which is
+ managed by Spring. This Spring bean must implement the Mediator interface
+ for it to act as a Mediator. The key will reference the Spring
+ ApplicationContext/Configuration used for the bean
+ </p>
+
+ <h3>
+ Other Mediators
+ </h3>
+ <h4>
+ <a name="RMSequence" id="RMSequence">RMSequence</a>
+ </h4>
+<pre xml:space="preserve"> <RMSequence (correlation="xpath" [last-message="xpath"]) | single="true" [version="1.0|1.1"]/></pre>
+ <p>
+ The <RMSequence> mediator can be used to create a sequence of
+ messages to communicate via WS-Reliable Messaging with an WS-RM enabled
+ endpoint (<enableRM>). The simple use case of this mediator is to
+ specify a single="true" property, because this means that only one message
+ is involved in the same sequence. However if multiple messages should be
+ sent in the same sequence, the correlation property should be used with a
+ XPath expression that selects an 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, for the last message of the sequence also an XPath expression
+ should be specified. With the version attribute the WS-RM specification
+ version to be used can be specified, 1.0 or 1.1.
+ </p>
+ <p/>
+ <p/>
+ </body>
+</document>
\ No newline at end of file