<?xml version="1.0" encoding="ISO-8859-1"?>
<document>
    <properties>
        <title>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;
    }
    </style>
    </head>
    <body>
    <div class="section">
    <div>
      <h2>
        Apache Synapse ESB - Configuration
      </h2>
    </div>
    <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 hierarchy - synapse-config directory with sequences, endpoints, proxies, etc...
      </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-config directory)
    </h2>
    <p>
      As the diagram below depicts, the Synapse configuration defines the Proxy
      services, Endpoints, Sequences, Startup jobs, Event sources, Priority
      executors and Dead letter channels managed by the Synapse ESB. It also defines the
      interface to the Registry/Repository being used by the engine. Synapse Configuration is
      now available with a XML Schema which defines the
      <a href="./ns/2010/04/configuration/synapse_config.xsd">configuration language</a> using a set
      of XSD's. Typically the Synapse ESB is deployed between the actual client and a back-end
      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>
        <!--TODO: we need to update the image to add priority queues and envent sources-->
      <img alt="Synapse message flow"
      src="images/synapse-flow.png" width="400" height="300"/>
    </p>
    <p/>
    <p>
      The Synapse ESB can operate in multiple 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>
    <h3>
      <a name="_task_scheduling" id="_task_scheduling">Task Scheduling</a>
    </h3>
    <p>
      In Task scheduling, Synapse can schedule a bit of work to be triggered at the specified
      trigger mechanism. You could use simple triggers such as a count and an interval meaning
      that it runs count number of times in the specified intervals, or you could use cron
      scheduling meaning that you specify a standard cron expression adn the scheduler will
      trigger your task implementation at the cron trigger. This mode of operation is much
      important for work that has to be initiated by the ESB, for example to poll a service at
      a given interval and so forth.
    </p>
    <h3>
      <a name="_eventing" id="_eventing">Eventing</a>
    </h3>
    <p>
      In eventing, or in other wards Event Driven Architecture, synapse can be used as
      one or more event sources and users or systems can subscribe to those event sources.
      On the other hand systems can send events to Synapse ESB and it will be possible for
      synapse to act as an event broker and re-deliver the events it received to the respective
      subscribers according to the filtering criteria, with or without mediation. This again is
      a very powerful operational mode as it helps to integrated systems based on an EDA.
    </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.task.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>
    <h3>
      <a href="#eventsource">Event Source</a>
    </h3>
    <p>
      An Event Source use to define the Event Source and the Subscription Manager configurations
      use in the eventing implementation of Synapse. Event source provides a service URL that can be
      used to the send subscriptions and events (events that do not required to go through a
      mediation flow).

    </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"> &lt;definitions&gt;
   &lt;<a href="#registry">registry</a> provider="string"&gt;...&lt;/registry&gt;?
   &lt;<a href="#localEntry">localEntry</a> key="string"&gt;...&lt;/localEntry&gt;?
   &lt;<a href="#sequence">sequence</a> name="string"&gt;...&lt;/sequence&gt;?
   &lt;<a href="#endpoint">endpoint</a> name="string"&gt;...&lt;/endpoint&gt;?
   &lt;<a href="#proxy">proxy</a> name="string" ...&gt;...&lt;/proxy&gt;?
   &lt;<a href="#task">task</a> name="string" ...&gt;...&lt;/task&gt;?
   &lt;<a href="#eventsource">eventsource</a> name="string" ...&gt;...&lt;/eventsource&gt;?
 &lt;/definitions&gt;</pre>
    <p/>
    <p>
      The &lt;definitions&gt; elements in a synapse.xml holds the Synapse ESB
      configuration. While the &lt;registry&gt;, &lt;sequence&gt;, &lt;endpoint&gt;,
      &lt;proxy&gt;, &lt;task&gt; and &lt;localEntry&gt; 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 &lt;definitions&gt; 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 &lt;registry&gt; 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>
    <p>Registry schema can be found at <a href="./ns/2010/04/configuration/registry.xsd">here</a></p>
<pre xml:space="preserve"> &lt;registry provider="string"/&gt;
   &lt;parameter name="string"&gt;text | xml&lt;/parameter&gt;*
 &lt;/registry&gt;</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.
&lt;registry provider="org.apache.synapse.registry.url.SimpleURLRegistry"&gt;
  &lt;parameter name="root"&gt;file:./repository/conf/sample/resources/&lt;/parameter&gt;
  &lt;parameter name="cachableDuration"&gt;15000&lt;/parameter&gt;
&lt;/registry&gt;</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 &lt;localEntry&gt; element is used to declare registry entries that
      are local to the Synapse instance, as shown below
    </p>
    <p>Local entry schema can be found at <a href="./ns/2010/04/configuration/local_entry.xsd">here</a></p>
<pre xml:space="preserve">  &lt;localEntry key="string" [src="url"]&gt;text | xml&lt;/localEntry&gt;</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.
&lt;localEntry key="version"&gt;0.1&lt;/localEntry&gt;
&lt;localEntry key="validate_schema"&gt;
        &lt;xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
         ...
        &lt;/xs:schema&gt;
    &lt;/localEntry&gt;
&lt;localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/&gt;</pre>
    <h2>
      <a name="sequence" id="sequence">Sequences</a>
    </h2>
    <p>
      A &lt;sequence&gt; 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>
    <p>Sequence schema can be found at <a href="./ns/2010/04/configuration/sequence.xsd">here</a></p>
<pre xml:space="preserve"> &lt;sequence name="string" [onError="string"] [key="string"] [trace="enable"]&gt;
   mediator*
 &lt;/sequence&gt;</pre>
<pre xml:space="preserve">e.g.
&lt;sequence name="main" onError="errorHandler"&gt;
  .. &lt;!-- a 'main' sequence that invokes the sequence named 'errorHandler' on a fault --&gt; ..
&lt;/sequence&gt;</pre>
<pre xml:space="preserve">&lt;sequence key="sequence/dynamic_seq_1.xml"/&gt;
where "sequence/dynamic_seq_1.xml" refers to the following sequence definition from the registry:

&lt;sequence name="dynamic_sequence" xmlns="http://synapse.apache.org/ns/2010/04/configuraiton"&gt;
  ..
&lt;/sequence&gt;</pre>
    <h2>
      <a name="endpoint" id="endpoint">Endpoints</a>
    </h2>
    <p>
      An &lt;endpoint&gt; 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>
    <p>Endpoint schema can be found at <a href="./ns/2010/04/configuration/endpoint.xsd">here</a></p>
<pre xml:space="preserve">&lt;endpoint [name="string"] [key="string"]&gt;
  <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>
&lt;/endpoint&gt; </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">&lt;endpoint key="foo"/&gt;</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>
        Endpoint can be in one of the four states Active, TimeOut, Suspended and
        Switch Off. Endpoint can be active which represent the Active state of the
        endpoint. With the new endpoint enhancements there is possibility to retry
        in case of endpoint invocation failure. This behavior can be configured
        at the endpoint level through synapse endpoint API. Configuration is called
        'markForSuspension'. 'errorCodes' represent a list
        of error codes. If these error codes are received from the endpoint,
        the endpoint will be suspended. 'retriesBeforeSuspension' represents
        the number of re-tries in case of a timeout, caused by the above listed error codes.
        'retryDelay' is the delay between re-tries, in milli seconds. If the endpoint
        required to retry it is moved to TimeOut state. If the endpoint fails in
        subsequent re-tries it'll move to Suspended state. If endpoint succeeded in
        further re-tries it'll move into Active state. Suspended state defines
        configuration 'suspendOnFailure'. 'initialDuration' represent the duration that the endpoint
        is suspended for the first time after receiving the suspend error codes.
        'progressionFactor' is the duration to suspend can vary from the first time
        suspension to the subsequent time. The factor value decides the suspense duration
        variance between subsequent suspensions. 'maximumDuration' the maximum
        duration that the endpoint is suspended after the receiving the suspend error codes.
        Finally an endpoint can be in the Switch off state, where the endpoint is moved to
        maintenance. State changes between Switch off and other states only can be done
        manually through JMX based API that is provided. Endpoint which is in
        'Switch Off' state can only be moved to 'Active' state and it too can only be
        done through JMX.
    </p>	
    <p>
      Address endpoints can timeout if responses fail to arrive at Synapse by a
      predefined timeout-duration specified in seconds. The timeout responseAction
      specifies whether to discard responses that arrive 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">&lt;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"]&gt;
  &lt;enableRM [policy="<em>key</em>"]/&gt;?
  &lt;enableSec [policy="<em>key</em>"]/&gt;?
  &lt;enableAddressing [version="final|submission"] [separateListener="true|false"]/&gt;?
  
  &lt;timeout&gt;
    &lt;duration&gt;<em>timeout duration in seconds</em>&lt;/duration&gt;
    &lt;responseAction&gt;discard|fault&lt;/responseAction&gt;
  &lt;/timeout&gt;?
  
  &lt;markForSuspension&gt;
        [&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
        &lt;retriesBeforeSuspension&gt;m&lt;/retriesBeforeSuspension&gt;
        &lt;retryDelay&gt;d&lt;/retryDelay&gt;
    &lt;/markForSuspension&gt;

  &lt;suspendOnFailure&gt;
        [&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
        &lt;initialDuration&gt;n&lt;/initialDuration&gt;
        &lt;progressionFactor&gt;r&lt;/progressionFactor&gt;
        &lt;maximumDuration&gt;l&lt;/maximumDuration&gt;
    &lt;/suspendOnFailure&gt;
&lt;/address&gt;</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/services/SimpleStockQuoteService</tt></td></tr>
        <tr><td>JMS</td><td><tt>jms:/SimpleStockQuoteService?<br/>
              &#160;&#160;&#160;transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&amp;<br/>
              &#160;&#160;&#160;java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&amp;<br/>
              &#160;&#160;&#160;java.naming.provider.url=tcp://localhost:61616&amp;<br/>
              &#160;&#160;&#160;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">&lt;default [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]
         [encoding="<em>charset encoding</em>"]
         [statistics="enable|disable"] [trace="enable|disable"]&gt;
  &lt;enableRM [policy="<em>key</em>"]/&gt;?
  &lt;enableSec [policy="<em>key</em>"]/&gt;?
  &lt;enableAddressing [version="final|submission"] [separateListener="true|false"]/&gt;?

  &lt;timeout&gt;
    &lt;duration&gt;<em>timeout duration in seconds</em>&lt;/duration&gt;
    &lt;responseAction&gt;discard|fault&lt;/responseAction&gt;
  &lt;/timeout&gt;?

   &lt;markForSuspension&gt;
        [&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
        &lt;retriesBeforeSuspension&gt;m&lt;/retriesBeforeSuspension&gt;
        &lt;retryDelay&gt;d&lt;/retryDelay&gt;
    &lt;/markForSuspension&gt;

  &lt;suspendOnFailure&gt;
        [&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
        &lt;initialDuration&gt;n&lt;/initialDuration&gt;
        &lt;progressionFactor&gt;r&lt;/progressionFactor&gt;
        &lt;maximumDuration&gt;l&lt;/maximumDuration&gt;
    &lt;/suspendOnFailure&gt;
&lt;/default&gt;</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">&lt;wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname"&gt;
  &lt;wsdl:definition&gt;...&lt;/wsdl:definition&gt;?
  &lt;wsdl20:description&gt;...&lt;/wsdl20:description&gt;?
  &lt;enableRM [policy="key"]/&gt;?
  &lt;enableSec [policy="key"]/&gt;?
  &lt;enableAddressing/&gt;?
  
  &lt;timeout&gt;
    &lt;duration&gt;timeout-duration&lt;/duration&gt;
    &lt;responseAction&gt;discard|fault&lt;/responseAction&gt;
  &lt;/timeout&gt;?
  &lt;markForSuspension&gt;
        [&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
        &lt;retriesBeforeSuspension&gt;m&lt;/retriesBeforeSuspension&gt;
        &lt;retryDelay&gt;d&lt;/retryDelay&gt;
    &lt;/markForSuspension&gt;

  &lt;suspendOnFailure&gt;
        [&lt;errorCodes&gt;xxx,yyy&lt;/errorCodes&gt;]
        &lt;initialDuration&gt;n&lt;/initialDuration&gt;
        &lt;progressionFactor&gt;r&lt;/progressionFactor&gt;
        &lt;maximumDuration&gt;l&lt;/maximumDuration&gt;
    &lt;/suspendOnFailure&gt; 
	
&lt;/wsdl&gt;</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 or static members by evaluating the load balancing policy
      and any other relevant parameters. The policy attribute of the load balance
      element specifies the load balance policy (algorithm) to be used for
      selecting the target endpoint or static member. Currently only the roundRobin policy is
      supported. The failover attribute determines if the next endpoint or static member should be
      selected once the currently selected endpoint or static member has failed, and defaults to
      true. The set of endpoints or static members amongst which the load has to be distributed
      can be listed under the 'loadbalance' element. These 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. The loadbalance element cannot have both endpoint &amp; member child
      elements in the same configuration. In the case of the member child element, the hostName,
      httpPort and/or httpsPort attributes could be specified.
    </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://synapse.apache.org/ns/2010/04/configuraiton}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">
    &lt;session type="http|simpleClientSession"/&gt;?
    &lt;loadbalance [policy="roundRobin"] [algorithm="impl of org.apache.synapse.endpoints.algorithms.LoadbalanceAlgorithm"]
                    [failover="true|false"]&gt;
      &lt;endpoint .../&gt;+
      &lt;member hostName="host" [httpPort="port"] [httpsPort="port2"]&gt;+  
    &lt;/loadbalance&gt;
    </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">&lt;failover&gt;
  &lt;endpoint .../&gt;+
&lt;/failover&gt;</pre>

            <h4>
      <a name="dynamic-load-balanced-endpoint" id="dynamic-load-balanced-endpoint">Dynamic Load
      balance Endpoint</a>
    </h4>
    <p>
      A Dynamic Load balanced endpoint distributes the messages (load) arriving at it
      among a application members by evaluating the load balancing policy
      and any other relevant parameters. These application members will be discovered
      using the membershipHandler class. Generally, this class will use a group
      communication mechanism to discover the application members. The class attribute of the
      membershipHandler element should be an implementation of
      org.apache.synapse.core.LoadBalanceMembershipHandler. membershipHandler specific properties
      can be specified using the property elements.  The policy attribute of the
      dynamicLoadbalance
      element specifies the load balance policy (algorithm) to be used for
      selecting the next member to which the message has to be forwaded to.
      Currently only the roundRobin policy is
      supported. The failover attribute determines if the next member should be
      selected once the currently selected member has failed, and defaults to
      true.
    </p>
        <!--TODO: Session affinity documentation-->
    <pre xml:space="preserve">
    &lt;dynamicLoadBalance [policy="roundRobin"] [failover="true|false"]&gt;
          &lt;membershipHandler
                    class="impl of org.apache.synapse.core.LoadBalanceMembershipHandler"&gt;
                    &lt;property name="name" value="value"/&gt;+
          &lt;/membershipHandler&gt;
    &lt;/dynamicLoadBalance&gt;
    </pre>
    <h2>
      <a name="proxy" id="proxy">Proxy service</a>
    </h2>
    <p>
      A &lt;proxy&gt; element is used to define a Synapse Proxy service.
    </p>
    <p>Proxy service schema can be found at <a href="./ns/2010/04/configuration/proxy.xsd">here</a></p>
<pre xml:space="preserve"> &lt;proxy name="string" [transports="(http |https |jms |.. )+|all"] [pinnedServers="(serverName )+"] [serviceGroup="string"]&gt;
   &lt;description&gt;...&lt;/description&gt;?
   &lt;target [inSequence="name"] [outSequence="name"] [faultSequence="name"] [endpoint="name"]&gt;
      &lt;inSequence&gt;...&lt;/inSequence&gt;?
      &lt;outSequence&gt;...&lt;/outSequence&gt;?
      &lt;faultSequence&gt;...&lt;/faultSequence&gt;?
      &lt;endpoint&gt;...&lt;/endpoint&gt;?
   &lt;/target&gt;?
   &lt;publishWSDL key="string" uri="string"&gt;
      ( &lt;wsdl:definition&gt;...&lt;/wsdl:definition&gt; | &lt;wsdl20:description&gt;...&lt;/wsdl20:description&gt; )?
      &lt;resource location="..." key="..."/&gt;*
   &lt;/publishWSDL&gt;?
   &lt;enableAddressing/&gt;? 
   &lt;enableSec/&gt;?
   &lt;enableRM/&gt;?
   &lt;policy key="string" [type="(in | out)"]/&gt;?       // optional service or message level policies such as (e.g. WS-Security and/or WS-RM policies)
   &lt;parameter name="string"&gt;                 // optional service parameters such as (e.g. transport.jms.ConnectionFactory)
      string | xml
   &lt;/parameter&gt;
 &lt;/proxy&gt;</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 -serverName=&lt;ServerName&gt;
      or by editing the wrapper.conf where Synapse is started as a service.
    </p>
    <p>
      By default when a proxy service is created it is added to an Axis service
      group which has the same name as the proxy service. With the 'serviceGroup'
      attribute this behavior can be further configured. A custom Axis service
      group can be specified for a proxy service using the 'serviceGroup' attribute.
      This way multiple proxy services can be grouped together at Axis2 level
      thus greeatly simplifying service management tasks.
    </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
      &lt;proxy key="string"/&gt; is wrong)
    </p>
    <p>
      A WSDL for the proxy service can be published using the &lt;publishWSDL&gt;
      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 &lt;publishWSDL&gt;. Artifacts (schemas or other WSDL documents)
      imported by the WSDL can be resolved from the registry by specifying
      appropriate &lt;resource&gt; elements:
    </p>
<pre> &lt;publishWSDL key="my.wsdl"&gt;
   &lt;resource location="http://www.standards.org/standard.wsdl" key="standard.wsdl"/&gt;
 &lt;/publishWSDL&gt;
</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>
        <tr>
          <td>
            showAbsoluteSchemaURL
          </td>
          <td>
            true|false
          </td>
          <td>
            false
          </td>
          <td>
            Show the absolute path of the referred schemas of the WSDL without
              showing the relative paths.
          </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>
      </tbody>
    </table>
    <h2>
      <a name="task" id="task">Tasks</a>
    </h2>
    <p>
      A &lt;task&gt; element is used to define a Synapse Startup Task.
    </p>
    <p>Task schema can be found at <a href="./ns/2010/04/configuration/task.xsd">here</a></p>
<pre xml:space="preserve"> &lt;task class="mypackage.MyTask" name="string" [pinnedServers="(serverName)+"]&gt;
   &lt;property name="stringProp" value="String"/&gt;
   &lt;property name="xmlProp"&gt;
     &lt;somexml&gt;config&lt;/somexml&gt;
   &lt;/property&gt;
   &lt;trigger ([[count="10"]? interval="1000"] | [cron="0 * 1 * * ?"] | [once=(true | false)])/&gt;
 &lt;/task&gt;</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.task.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="eventsource" id="eventsource">Event Source</a>
    </h2>
    <p>
      A &lt;eventSource&gt; element is used to define a Synapse event source.
    </p>
    <p>Event source schema can be found at <a href="./ns/2010/04/configuration/event_source.xsd">here</a></p>
<pre xml:space="preserve">&lt;eventSource name="string"&gt;
	&lt;subscriptionManager class="mypackage.MyClass"&gt;
		   &lt;parameter name="string"/&gt;
	&lt;/subscriptionManager&gt;
&lt;/eventSource&gt;</pre>
    <p>
      An event source required to implement eventing in Synpase. Event source used to inject
      subscription messages in to Synpase and provide a service URL for the users to send subscriptions
      to Synapse. User can send messages to manage the subscriptions (unsubscribe, renew, get-status)
      to the event source.
    </p>
    <p>
      Subscription manager configured inside the event source will be responsible to hold the subscriptions,
      and provide operations to manage the subscriptions. Subscription storage will decide
      based on the implementation of the subscription manager , e.g. Registry, memory, database.
      Additional information required to setup the subscription manager can be set as properties. 
    </p>
    <h2>
      <a name="mediator" id="mediator">Mediators</a>
    </h2>
    <p>
      A mediator token refers to any of the following tokens:
    </p>
<p>
    <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="#rewrite">rewrite</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> | <a href="#eventPublisher">eventPublisher</a> | <a href="#transaction">transaction</a>

    </p>
    <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>
    <p>All mediator schema can be found at <a href="./ns/2010/04/configuration/mediators/">here</a></p>
    <h3>
      Core Mediators
    </h3>
    <h4>
      <a name="send" id="send">Send</a>
    </h4>
    <p>
      The send token represents a &lt;send&gt; 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"> &lt;send/&gt;</pre>
    <p>
      If the message is to be sent to one or more endpoints, then the following
      is used:
    </p>
<pre xml:space="preserve"> &lt;send&gt;
   (endpointref | endpoint)+
 &lt;/send&gt;</pre>
    <p>
      where the endpointref token refers to the following:
    </p>
<pre xml:space="preserve"> &lt;endpoint key="name"/&gt;</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 &lt;drop&gt; element which is used to stop
      further processing of a message:
    </p>
<pre xml:space="preserve"> &lt;drop/&gt;</pre>
    <p>
      Once the &lt;drop&gt; 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 &lt;log&gt; element which may be used to log
      messages being mediated:
    </p>
<pre xml:space="preserve"> &lt;log [level="string"] [separator="string"]&gt;
   &lt;property name="string" (value="literal" | expression="xpath")/&gt;*
 &lt;/log&gt;</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"> &lt;property name="string" [action=set|remove] [type="string"] (value="literal" | expression="xpath") [scope=transport|axis2|axis2-client] [pattern="regex" [group="integer"]]&gt;
     &lt;xml-element/&gt;?
&lt;/property&gt;</pre>
    <p>
      The property token refers to a &lt;property&gt; 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>
      If a pattern is specified, this regular expression will be applied on
      top of the value of the property. If group number is specified the matching
      group will be set as the value of the property. If group is not specified,
      it defaults to 0. If a patter is specified and it is not matched, the
      value will be set to empty string.
    </p>  
    <p>
      Using the type attribute one can set properties with specific types on
      the message context. Currently the type attribute accepts following
      data types.
    </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. If a type is not explicitly specified
      properties will be set as string values. 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 value during mediation.
      With the type attribute set to 'OM' the resulting XML will be converted to
      an AXIOM OMElement before setting it to the message context.
    </p>
    <p>
      You can use the property mediator to set fixed XML property values on the
      message context too. To do that instead of specifying a 'value' attribute
      specify the XML property value as a child element of the property element.
      The type attribute has no significance in this situation as the type of the
      property value is always 'OM'.
    </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>
      <li>
        FORCE_HTTP_1.0 - forces outgoing http/s messages to use HTTP 1.0
        (instead of the default 1.1)
      </li>
      <li>
        POST_TO_URI - forces outgoing http/s messages to use the full URI
          in a POST (instead of the default PATH)
      </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),] &lt;property_name&gt;
      [,&lt;dateformat&gt;] )
    </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>
      <li>
        OperationNamespace - returns the namespace of the operation 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"> &lt;sequence key="name"/&gt;</pre>
    <p>
      A sequence ref token refers to a &lt;sequence&gt; 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"> &lt;validate [source="xpath"]&gt;
   &lt;property name="validation-feature-id" value="true|false"/&gt;*
   &lt;schema key="string"/&gt;+
   &lt;on-fail&gt;
     mediator+
   &lt;/on-fail&gt;
 &lt;/validate&gt;</pre>
    <p>
      The &lt;validate&gt; 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"> &lt;callout serviceURL="string" [action="string"]&gt;
   &lt;configuration [axis2xml="string"] [repository="string"]/&gt;?
   &lt;source xpath="expression" | key="string"&gt;
   &lt;target xpath="expression" | key="string"/&gt;
 &lt;/callout&gt;
</pre>
    <p>
      The &lt;callout&gt; 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"> &lt;makefault [version="soap11|soap12|pox"] [response="true|false"]&gt;
   &lt;code (value="literal" | expression="xpath")/&gt;
   &lt;reason (value="literal" | expression="xpath")/&gt;
   &lt;node&gt;...&lt;/node&gt;?
   &lt;role&gt;...&lt;/role&gt;?
   (&lt;detail expression="xpath"/&gt; | &lt;detail&gt;...&lt;/detail&gt;)?
 &lt;/makefault&gt;</pre>
    <p>
      The &lt;makefault&gt; mediator transforms the current message into a fault
      message, but does NOT send it. The &lt;send&gt; 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. At the same time if you specify the optional response
      attribute value as 'true' makefault will mark the mesage as a response
      regardless of whether the message is a request or a response.
      The optional &lt;node&gt;, &lt;role&gt; and &lt;detail&gt; directives can
      be used to set the corresponding elements in the resulting SOAP fault.
    </p>
    <p/>
    <h4>
      <a name="xslt" id="xslt">XSLT</a>
    </h4>
<pre xml:space="preserve"> &lt;xslt key="string" [source="xpath"] [target="string"]&gt;
   &lt;property name="string" (value="literal" | expression="xpath")/&gt;*
   &lt;feature name="string" value="true | false" /&gt;*
   &lt;attribute name="string" value="string" /&gt;*
   &lt;resource location="..." key="..."/&gt;*
 &lt;/xslt&gt;</pre>
    <p>
      The &lt;xslt&gt; 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.
      If no 'target' attribute is specified, the source node will be replaced
      with the output of the transformation. Otherwise the output will be stored in
      the specified property.
    </p>
    <p>
      If the output method specified by the stylesheet is text (i.e. the stylesheet
      has the following directive: <tt>&lt;xsl:output method="text"/&gt;</tt>),
      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, the JMS and VFS transports will automatically unwrap the
      content and send it out as plain text. The XSLT mediator can therefore be used
      for integration with systems relying on plain text messages.
    </p>
    <p>
      Stylesheet parameters can be passed into the transformations through the
      'property' elements.
    </p>
    <p>
      The 'feature' element defines any features which
      should be explicitly set to the TransformerFactory. The feature
      'http://synapse.apache.org/ns/2010/04/configuraiton/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>
    <p>
      The 'attribute' element allows to define attributes which should be explicitly
      set to the TransformerFactory.
    </p>
    <p>
      Finally, the 'resource' element 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
      &lt;proxy&gt; definition.
    </p>
    <h4>
      <a name="xquery" id="xquery">XQuery</a>
    </h4>
<pre xml:space="preserve">&lt;xquery key="string" [target="xpath"]&gt;
    &lt;variable name="string" type="string" [key="string"] [expression="xpath"] [value="string"]/&gt;?
&lt;/xquery&gt; </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 -&gt; INT
      </li>
      <li>
        XQItemType.XQBASETYPE_INTEGER -&gt; INTEGER
      </li>
      <li>
        XQItemType.XQBASETYPE_BOOLEAN -&gt; BOOLEAN
      </li>
      <li>
        XQItemType.XQBASETYPE_BYTE - &gt; BYTE
      </li>
      <li>
        XQItemType.XQBASETYPE_DOUBLE -&gt; DOUBLE
      </li>
      <li>
        XQItemType.XQBASETYPE_SHORT -&gt; SHORT
      </li>
      <li>
        XQItemType.XQBASETYPE_LONG -&gt; LONG
      </li>
      <li>
        XQItemType.XQBASETYPE_FLOAT -&gt; FLOAT
      </li>
      <li>
        XQItemType.XQBASETYPE_STRING -&gt; STRING
      </li>
      <li>
        XQItemType.XQITEMKIND_DOCUMENT -&gt; DOCUMENT
      </li>
      <li>
        XQItemType.XQITEMKIND_DOCUMENT_ELEMENT -&gt; DOCUMENT_ELEMENT
      </li>
      <li>
        XQItemType.XQITEMKIND_ELEMENT -&gt; ELEMENT
      </li>
    </ul>
    <p/>
    <h4>
      <a name="rewrite" id="rewrite">URLRewrite</a>
    </h4>
<pre xml:space="preserve">&lt;rewrite [inProperty="string"] [outProperty="string"]&gt;
   &lt;rule&gt;
      &lt;condition&gt;
         ...
      &lt;/condition&gt;?
      &lt;action [type="append|prepend|replace|remove|set"] [value="string"]
          [xpath="xpath"] [fragment="protocol|host|port|path|query|ref|user|full"] [regex="regex"]&gt;+
   &lt;/rule&gt;+
&lt;/rewrite&gt;</pre>
    <p/>
    <p>
      The URL rewrite mediator is used to modify and transform the URL values available
      in the message. By default the mediator will take the 'To' header of the message and
      apply the provided rewrite rules on it. Alternatively one can specify a property name
      in the 'inProperty' attribute, in which case the mediator will take the value of the
      specified property as the input URL. Similarly the mediator by default sets the transformed
      URL as the 'To' header of the message. Alternatively you can use the 'outProperty'
      attribute to instruct the mediator to set the resulting URL as a property.
    </p>
    <p>
      The rewrite mediator applies URL transformations by evaluating a set of rules on
      the message. Rules are specified using the 'rule' element. Rules are evaluated in the
      order they are specified. A rule can consist of an optional condition and one or more
      rewrite actions. If the condition is provided it will be evaluated first. If it evaluates
      to 'true' all the specified rewrite actions will be executed. Otherwise the set of
      actions will be skipped. If no condition is specified, the provided rewrite actions
      will be always executed. The condition should be wrapped in a 'condition' element within
      the 'rule' element. Rewrite actions are specified using 'action' elements.
    </p>
    <p>
      The 'type' attribute on the 'action' element states which type of action should be
      executed on the URL. This defaults to 'set' value. The 'fragment' attribute can be
      used to specify the URL fragment on which the action should be executed. If not specified
      this will be taken as 'full' URL, which is the complete URL. The value to 'set', 'append'
      or 'prepend' must be specified using either the 'value' attribute or the 'xpath' attribute.
      One of these two attributes are always needed unless the value of the 'type' attribute is
      set to 'remove'. When the 'type' is set to 'replace' an additional 'regex' attribute must
      be specified which indicates the portion that should be replaced with the given value.
    </p>
    <p/>
    <h4>
      <a name="header" id="header">Header</a>
    </h4>
<pre xml:space="preserve"> &lt;header name="qname" (value="literal" | expression="xpath") [action="set"]/&gt;
 &lt;header name="qname" action="remove"/&gt;</pre>
    <p>
      The &lt;header&gt; 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>
      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>
    <p/>
    <h3>
      Selection Mediators
    </h3>
    <h4>
      <a name="filter" id="filter">Filter</a>
    </h4>
<pre xml:space="preserve"> &lt;filter (source="xpath" regex="string") | xpath="xpath"&gt;
   mediator+
 &lt;/filter&gt;</pre>
    <p>
      The &lt;filter&gt; 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"> &lt;filter (source="xpath" regex="string") | xpath="xpath"&gt;
   &lt;then [sequence="string"]&gt;
     mediator+
   &lt;/then&gt;
   &lt;else [sequence="string"]&gt;
     mediator+
   &lt;/else&gt;
 &lt;/filter&gt;</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"> &lt;switch source="xpath"&gt;
   &lt;case regex="string"&gt;
     mediator+
   &lt;/case&gt;+
   &lt;default&gt;
     mediator+
   &lt;/default&gt;?
 &lt;/switch&gt;</pre>
    <p>
      The &lt;switch&gt; 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">&lt;in&gt;<br/>  mediator+
&lt;/in&gt;<br/></pre>
<pre xml:space="preserve">&lt;out&gt;
  mediator+
&lt;/out&gt;</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 "&lt;in&gt;" mediators and vice
      versa.
    </p>
    <p/>
    <h3>
      Database Mediators
    </h3>
    <h4>
      <a name="dblookup" id="dblookup">DB-lookup</a>
    </h4>
<pre xml:space="preserve">&lt;dblookup&gt;
   &lt;connection&gt;
     &lt;pool&gt;
      (
       &lt;driver/&gt;
       &lt;url/&gt;
       &lt;user/&gt;
       &lt;password/&gt;
       &lt;property name="name" value="value"/&gt;*
     |
       &lt;dsName/&gt;
     |
       &lt;dsName/&gt;
       &lt;icClass/&gt;
       &lt;url/&gt;
       &lt;user/&gt;
       &lt;password/&gt;
     )
     &lt;/pool&gt;
   &lt;/connection&gt;
   &lt;statement&gt;
     &lt;sql&gt;select something from table where something_else = ?&lt;/sql&gt;
     &lt;parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/&gt;*
     &lt;result name="string" column="int|string"/&gt;*
   &lt;/statement&gt;+
&lt;/dblookup&gt;</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 &lt;result&gt; 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">&lt;dbreport useTransaction=(true|false)&gt;
   &lt;connection&gt;
     &lt;pool&gt;
      (
       &lt;driver/&gt;
       &lt;url/&gt;
       &lt;user/&gt;
       &lt;password/&gt;
       &lt;property name="name" value="value"/&gt;* 
     |
       &lt;dsName/&gt;
     |
       &lt;dsName/&gt;
       &lt;icClass/&gt;
       &lt;url/&gt;
       &lt;user/&gt;
       &lt;password/&gt;
     )
     &lt;/pool&gt;
   &lt;/connection&gt;
   &lt;statement&gt;
     &lt;sql&gt;insert into something values(?, ?, ?, ?)&lt;/sql&gt;
     &lt;parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/&gt;*
    &lt;/statement&gt;+
&lt;/dblreport&gt;</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">&lt;throttle [onReject="string"] [onAccept="string"] id="string"&gt;
    (&lt;policy key="string"/&gt; | &lt;policy&gt;..&lt;/policy&gt;)
    &lt;onReject&gt;..&lt;/onReject&gt;?
    &lt;onAccept&gt;..&lt;/onAccept&gt;?
&lt;/throttle&gt;</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"> &lt;cache [id="string"] [hashGenerator="class"] [timeout="seconds"] [scope=(per-host | per-mediator)]
     collector=(true | false) [maxMessageSize="in-bytes"]&gt;
   &lt;onCacheHit [sequence="key"]&gt;
     (mediator)+
   &lt;/onCacheHit&gt;?
   &lt;implementation type=(memory | disk) maxSize="int"/&gt;
 &lt;/cache&gt;</pre>
    <p>
      The &lt;cache&gt; 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"> &lt;clone [continueParent=(true | false)]&gt;
   &lt;target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]&gt;
     &lt;sequence&gt;
       (mediator)+
     &lt;/sequence&gt;?
     &lt;endpoint&gt;
       endpoint
     &lt;/endpoint&gt;?
   &lt;/target&gt;+
 &lt;/clone&gt;</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"> &lt;iterate [continueParent=(true | false)] [preservePayload=(true | false)] (attachPath="xpath")? expression="xpath"&gt;
   &lt;target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]&gt;
     &lt;sequence&gt;
       (mediator)+
     &lt;/sequence&gt;?
     &lt;endpoint&gt;
       endpoint
     &lt;/endpoint&gt;?
   &lt;/target&gt;+
 &lt;/iterate&gt;</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"> &lt;aggregate&gt;
   &lt;correlateOn expression="xpath"/&gt;?
   &lt;completeCondition [timeout="time-in-seconds"]&gt;
     &lt;messageCount min="int-min" max="int-max"/&gt;?
   &lt;/completeCondition&gt;?
   &lt;onComplete expression="xpath" [sequence="sequence-ref"]&gt;
     (mediator +)?
   &lt;/onComplete&gt;
 &lt;/aggregate&gt;</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"> &lt;class name="class-name"&gt;
   &lt;property name="string" value="literal"&gt;
     (either literal or XML child)
   &lt;/property&gt;
 &lt;/class&gt; </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"> &lt;pojoCommand name="class-name"&gt;
   (
   &lt;property name="string" value="string"/&gt; |
   &lt;property name="string" context-name="literal" [action=(ReadContext | UpdateContext | ReadAndUpdateContext)]&gt;
     (either literal or XML child)
   &lt;/property&gt; |
   &lt;property name="string" expression="xpath" [action=(ReadMessage | UpdateMessage | ReadAndUpdateMessage)]/&gt;
   )*
 &lt;/pojoCommand&gt; </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"> &lt;script key="string" language="string" [function="script-function-name"]/&gt;</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"> &lt;script language="string"&gt;...script source code...&lt;script/&gt;</pre>

<p>           
      If the script you specified is calling a function defined in another script,
      then the latter script should also be included in the script mediator
      configuration. It's done using the &lt;include&gt; element. The key attribute of the 
      &lt;include&gt; 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>
<pre xml:space="preserve"> &lt;script key="string" language="string" [function="script-function-name"]&gt;
   &lt;include key="string"/&gt;
 &lt;/script&gt;</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"> &lt;script language="js"&gt;mc.getPayloadXML()..symbol != "IBM";&lt;script/&gt;</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.
      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>
    <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"> &lt;localEntry key="string"/&gt;
 &lt;localEntry key="string" src="url"/&gt;</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"> &lt;spring:spring bean="exampleBean1" key="string" xmlns:spring="http://synapse.apache.org/ns/2010/04/configuraiton/spring"/&gt;</pre>
    <p>
      The &lt;spring&gt; 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"> &lt;RMSequence (correlation="xpath" [last-message="xpath"]) | single="true" [version="1.0|1.1"]/&gt;</pre>
    <p>
      The &lt;RMSequence&gt; mediator can be used to create a sequence of
      messages to communicate via WS-Reliable Messaging with an WS-RM enabled
      endpoint (&lt;enableRM&gt;). 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>
    <h4>
      <a name="eventPublisher" id="eventPublisher">eventPublisher</a>
    </h4>
<pre xml:space="preserve"> &lt;eventPublisher eventSourceName="string"/&gt;</pre>
    <p>
      The &lt;eventPublisher&gt; mediator use to send events to the subscribers that match
      the given filter criteria. A pre defined event source need to be provided with the mediator.
    </p>
    <p>The eventPublisher mediator handover the event to the defined event source in the mediator
        and event source picks the valid subscriptions from the subscription manager
        by applying the define filter.
        Any mediation required before dispatching the events can be done by adding
        mediators using sequences before the eventPublisher mediator. Quality of service like security
        can add to the events by applying QOS to the proxy service that holds the  eventPublisher mediator.
    </p>

        <h4>
            <a name="transaction" id="transaction">Transaction</a>
        </h4>
      <pre xml:space="preserve">&lt;transaction action="new|use-existing-or-new|fault-if-no-tx|commit|rollback|suspend|resume"/&gt;
      </pre>
        <p>The action attribute has the following meanings.</p>
        <ol>
        <li>1. new - Create a new jta transaction. Generate a fault if a transaction already exist.
        </li>
        <li>2. use-existing-or-new - Create a new jta transaction. Do nothing if a transaction exist.
        </li>
        <li>3. fault-if-no-tx - Generate a fault if no transaction exist. Do nothing if a transaction
            exist.
        </li>
        <li>4. commit - Commit transaction. Generate a fault if no transaction exist.</li>
        <li>5. rollback - Rollback transaction. Generate a fault if no transaction exist.</li>
        <li>6. suspend - Suspend transaction. Generate a fault if no transaction exist.</li>
        <li>7. resume - Resume transaction. Generate a fault if no transaction exist.</li>
        </ol>

        <p>
            The transaction mediator can use to define a distributed transaction. It has the
            transaction markers which can be used to mark the start and end of
            a transaction. Transaction mediator required a JTA provider in the system to work.
        </p>

        <p/>
    <p/>
    </div>
  </body>
</document>