You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@synapse.apache.org by hi...@apache.org on 2011/12/28 10:23:11 UTC
svn commit: r1225148 [8/15] - in /synapse/branches/2.1/src/site: ./
xdoc/1_0/ xdoc/1_1/ xdoc/1_1_1/ xdoc/1_2/
Added: synapse/branches/2.1/src/site/xdoc/1_1_1/configuration.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/1_1_1/configuration.xml?rev=1225148&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/1_1_1/configuration.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/1_1_1/configuration.xml Wed Dec 28 09:23:09 2011
@@ -0,0 +1,1540 @@
+<!--
+~ Licensed to the Apache Software Foundation (ASF) under one
+~ or more contributor license agreements. See the NOTICE file
+~ distributed with this work for additional information
+~ regarding copyright ownership. The ASF licenses this file
+~ to you under the Apache License, Version 2.0 (the
+~ "License"); you may not use this file except in compliance
+~ with the License. You may obtain a copy of the License at
+~
+~ http://www.apache.org/licenses/LICENSE-2.0
+~
+~ Unless required by applicable law or agreed to in writing,
+~ software distributed under the License is distributed on an
+~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~ KIND, either express or implied. See the License for the
+~ specific language governing permissions and limitations
+~ under the License.
+-->
+<html>
+<head>
+ <meta content="text/html; charset=iso-8859-1" http-equiv="content-type"/>
+ <title>Synapse Configuration Language</title>
+ <style type="text/css">
+ .command {
+ border: 1px dashed #3c78b5;
+ text-align: left;
+ background-color: #f0f0f0;
+ padding: 3px;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ }
+ .consoleOutput {
+ border: 1px dashed #3c78b5;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ background-color: #f0f0f0;
+ border-bottom: 1px dashed #3c78b5;
+ padding: 3px;
+ border-style: solid;
+ }
+ .info {
+ border-style: solid;
+ border-width: 1px;
+ border-color: #090;
+ background-color: #dfd;
+ text-align:left;
+ margin-top: 5px;
+ margin-bottom: 5px;
+ }
+ li {
+ font-family: Verdana, arial, sans-serif;
+ font-size: 11px;
+ line-height: 16px;
+ color: #000000;
+ font-weight: normal;
+ }
+ p {
+ font-family: Verdana, arial, sans-serif;
+ font-size: 11px;
+ line-height: 16px;
+ color: #000000;
+ font-weight: normal;
+ }
+ pre {
+ padding: 0px;
+ margin-top: 5px;
+ margin-left: 15px;
+ margin-bottom: 5px;
+ margin-right: 5px;
+ text-align: left;
+ background-color: #f0f0f0;
+ padding: 3px;
+ border: 1px dashed #3c78b5;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ }
+ h1 {
+ font-size: 24px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ color: #003366;
+ border-bottom: 1px solid #3c78b5;
+ padding: 2px;
+ margin: 36px 0px 4px 0px;
+ }
+ h2 {
+ font-size: 18px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ border-bottom: 1px solid #3c78b5;
+ padding: 2px;
+ margin: 27px 0px 4px 0px;
+ }
+ h3 {
+ font-size: 14px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ padding: 2px;
+ margin: 21px 0px 4px 0px;
+ }
+ h4 {
+ font-size: 12px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ padding: 2px;
+ margin: 18px 0px 4px 0px;
+ }
+ .data-table{
+ font-family:Verdana,Arial,Helvetica,sans-serif;
+ font-size:11px;
+ border:0px;
+ margin:0px;
+ border:solid 1px #cdcdcd;
+ }
+ .data-table th{
+ background-color:#eeeeee;
+ border-bottom:solid 1px #8d8d8d;
+ padding-top:5px;
+ padding-left:3px;
+ text-align:left;
+ }
+ .data-table td{
+ padding-top:4px;
+ padding-left:3px;
+ border-bottom:solid 1px #e1e1e1;
+ }</style>
+</head>
+
+<body>
+
+<table border="0" style="width: 100%">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <td><h1>Apache Synapse ESB - Configuration</h1>
+ </td>
+ <td><img alt="Synapse logo" src="../images/synapse-logo-web2.png"
+ width="197" height="82"/></td>
+ </tr>
+ </tbody>
+</table>
+
+<h3>Overview</h3>
+
+<p>An Apache Synapse Enterprise Service Bus (ESB) engine is driven off a set
+of simple text/xml configuration files. This allows the configuration to be
+easily hand edited, backed up from the file system, or even included into
+version control for easier management and control (e.g. moving a
+configuration from development, through QA, staging and into production). The
+configuration files that drives the Synapse ESB are as follows:</p>
+<ul>
+ <li>The Synapse configuration file - synapse.xml</li>
+ <li>The underlying Axis2 engine configuration file - axis2.xml</li>
+ <li>Resources referenced from the Registry</li>
+</ul>
+
+<p>While the axis2.xml configures the underlying transport and Web services
+support, the synapse.xml configures the mediation rules and configuration for
+the ESB. While any changes performed on the axis2.xml requires a restart
+(e.g. for enabling a transport such as JMS), the synapse.xml could be made to
+reference different configuration elements off a set of multiple files - that
+are served through the built-in Registry. When using the Registry to hold
+pieces of the configuration, certain elements such as endpoint definitions,
+sequences and local entries could be updated dynamically while the Synapse
+ESB executes, the the Registry could trigger a re-load as configured. </p>
+
+<h2>The Synapse Configuration (synapse.xml)</h2>
+
+<p>As the diagram below depicts, the Synapse configuration defines the Proxy
+services, Endpoints, Sequences and Startup jobs managed by the Synapse ESB.
+It also defines the interface to the Registry/Repository being used by the
+engine. Typically the Synapse ESB is deployed between the actual client and a
+backend service implementation to mediate the message flow in between. Thus
+the Synapse ESB can accept a message on behalf of the actual service, perform
+authentication, validation, transformation, logging, routing based on the
+content etc. and then decide the destination target endpoint for the message
+and direct it to an actual service implementation. The Synapse ESB can also
+detect timeouts, transport failures during communication or introduce load
+balancing, throttling or caching where necessary. For fault scenarios such as
+authentication failure, or schema validation failure, the Synapse ESB can be
+configured to return a custom message or a fault to the requesting client
+without forwarding the request to the actual service.</p>
+
+<p><img alt="Synapse message flow" src="../images/synapse-flow.png" width="400"
+height="300"/></p>
+
+<p></p>
+
+<p>The Synapse ESB can operate in two modes:</p>
+
+<h3><a href="#service_mediation">Service mediation</a> / <a
+href="#proxy">Proxy services</a></h3>
+
+<p>In Service mediation, the Synapse ESB exposes a service endpoint on the
+ESB, that accepts messages from clients. Typically these services acts as
+proxies for existing (external) services, and the role of Synapse would be to
+"mediate" these messages before they are proxied to the actual service. In
+this mode, Synapse could expose a service already available in one transport,
+over a different transport; or expose a service that uses one schema or WSDL
+as a service that uses a different schema or WSDL etc. A Proxy service could
+define the transports over which the service is exposed, and point to the
+mediation sequences that should be used to process request and response
+messages through the proxy service. A proxy service maybe a SOAP or REST/POX
+service over http/s or SOAP, POX, Plain Text or Binary / Legacy service for
+other transports such as JMS and VFS file systems - e.g. CSV content being
+the payload</p>
+
+<h3><a name="#message_mediation">Message mediation</a></h3>
+
+<p>In Message mediation, Synapse can act as a transparent proxy for clients -
+if they are directed to point to the Synapse ESB as a http proxy. This way,
+Synapse could be configured to filter all messages on a network for logging,
+access control etc, and could "mediate" messages without the explicit
+knowledge of the original client. If Synapse receives a message that is not
+accepted by any proxy service, this message is handled through message
+mediation as well. Message mediation always processes messages according to
+the mediation sequence defined as "main".</p>
+
+<h2>Concepts and configuration elements overview</h2>
+
+<h3><a href="#mediator">Mediators</a> and <a href="#sequence">Mediation
+Sequences</a></h3>
+
+<p>The Synapse ESB defines a 'mediator' as a component that is performs some
+mediation action on a message during the process flow. Thus a mediator gets
+full access to a message at the point where it is defined to gain control,
+and could inspect the message, modify it or take an external action depending
+on some attributes or values of the current message. A mediation sequence,
+commonly called a 'sequence' is a list of such mediators. A sequence may be
+named for re-use, or defined in-line or anonymously within a configuration.
+Sequences may be defined within the synapse.xml configuration or within the
+Registry. Writing a custom mediator in Java is easy and the supplementary
+documentation provides more details on this. The 'Class' and 'POJO (command)"
+mediators allows one to plugin a Java class easily into the Synapse engine
+with minimal effort. In addition, the Script mediator allows one to provide
+an Apache BSF script (e.g. Javascript, Ruby, Groovy etc) for mediation.</p>
+
+<p>A Synapse configuration holds two special sequences named as "main" and
+"fault". These may be defined within the synapse.xml, or externally via the
+Registry. If either is not found, a suitable default is generated at runtime
+by the ESB. The default "main" sequence will simple send a message without
+mediation, while the default "fault" sequence would log the message including
+the payload and any error/exception encountered and stop further processing.
+The 'fault' sequence executes whenever Synapse itself encounters an error
+while processing a message - or when a fault handler has not been defined to
+handle exceptions. A sequence can assign another named sequence as its
+"fault" handler sequence, and control branches to the fault handler if an
+error is encountered during the execution of the initial sequence.</p>
+
+<h3><a href="#endpoint">Endpoints</a></h3>
+
+<p>An Endpoint definition within Synapse defines an external service endpoint
+and any attributes or semantics that should be followed when communicating
+with that endpoint. An endpoint definition can be named for re-use, or
+defined in-line or anonymously within a configuration. Typically an endpoint
+would be based on a service Address or a WSDL. Additionally the Synapse ESB
+supports Failover and Load-balance endpoints - which are defined over a group
+of endpoints. Endpoints may be defined within the synapse.xml configuration
+or within the Registry.</p>
+
+<h3><a href="#task">Tasks</a></h3>
+
+<p>A Task is a custom Java class that implements the
+org.apache.synapse.startup.Task interface that defines a single "public void
+execute()" method. Such a task can be scheduled and managed via the Synapse
+ESB. The scheduling information for a task can be specified in the cron
+format or a simple format by the user. A task may also be specified as a
+one-time task where required, and can be used to trigger a callout or inject
+a message into the Synapse ESB.</p>
+
+<h3><a href="#registry">Remote Registry</a> and <a name="Local" id="Local"
+href="#localEntry">Local Registry (Local Entries)</a></h3>
+
+<p>A Synapse configuration can refer to an external Registry / Repository for
+resources used such as WSDL's, Schemas, Scripts, XSLT or XQuery
+transformations etc. One or more remote registries may be hidden or merged
+behind a local Registry interface defined to a Synapse configuration.
+Resources from an external registry are looked up using "keys" - which are
+known to the external registry. The Synapse ESB ships with a simple URL based
+registry implementation that uses the file system for storage of resources,
+and URL's or fragments as "keys". </p>
+
+<p>A Registry may define a duration for which a resource served may be cached
+by the Synapse runtime. If such a duration is specified, the Synapse ESB is
+capable of refreshing the resource after cache expiry to support dynamic
+re-loading of resource at runtime. Optionally, a configuration could define
+certain "keys" to map to locally defined entities. These entities may refer
+to a source URL or file, or defined as in-line XML or text within the
+configuration itself. If a Registry contains a resource whose "key" matches
+the key of a locally defined entry, the local entry shadows the resource
+available in the Registry. Thus it is possible to override Registry resources
+locally from within a configuration. To integrate Synapse with a custom / new
+Registry or repository, one needs to implement the
+org.apache.synapse.registry.Registry interface to suit the actual Registry
+being used.</p>
+
+<h2>The Axis2 Configuration (axis2.xml)</h2>
+
+<p>The axis2.xml file configures the underlying Axis2 web services engine for
+the Synapse ESB. The axis2.xml thus defines the transports enabled, and other
+configuration parameters associated. A change to the axis2 configuration
+requires a hard re-start of the Synapse ESB. By default the non-blocking
+http/s and the Apache VFS file system based transport are enabled for
+listening of messages, while the non-blocking http/s, VFS and JMS transports
+are enabled for sending messages out. Sample configurations to
+enable/configure the other transports are provided within the default
+axis2.xml file, and can be easily uncommented and modified. The sample JMS
+configuration shipped is for a default ActiveMQ 4.1.x installation.</p>
+
+<h2>The contents of the Synapse.xml configuration</h2>
+
+<p>A Synapse configuration looks like the following at the top level:</p>
+<pre> <definitions>
+ <<a href="#registry">registry</a> provider="string">...</registry>?
+ <<a href="#localEntry">localEntry</a> key="string">...</localEntry>?
+ <<a href="#sequence">sequence</a> name="string">...</sequence>?
+ <<a href="#endpoint">endpoint</a> name="string">...</endpoint>?
+ <<a href="#proxy">proxy</a> name="string" ...>...</proxy>?
+ <<a href="#task">task</a> name="string" ...>...</task>?
+ <a href="#mediator">mediator</a>*
+ </definitions></pre>
+
+<p></p>
+
+<p>The <definitions> elements in a synapse.xml holds the Synapse ESB
+configuration. While the <registry>, <sequence>,
+<endpoint>, <proxy>, <task> and <localEntry> elements
+refer to those discussed above, the built-in mediator elements names are
+already registered with the Synapse engine. Custom mediators written by a
+user may be included into the library directory, and would be dynamically
+picked up in a Sun JDK environment. A list of mediators found directly as
+children under the <definitions> element would be treated as the "main"
+sequence, if a named sequence with the name "main" cannot be found.</p>
+
+<h2><a name="registry1" id="registry">Registry</a></h2>
+
+<p>The <registry> element is used to define the remote registry used by
+the configuration. The registry provider specifies an implementation class
+for the registry implementation used, and optionally a number of
+configuration parameters as may be required for the configuration of the
+connection to the registry.</p>
+<pre> <registry provider="string"/>
+ <parameter name="string">text | xml</parameter>*
+ </registry></pre>
+
+<p>Registry entries loaded from a remote registry may be cached as dictated
+by the registry, and reloaded after the cache periods expires if a newer
+version is found. Hence it is possible to define configuration elements such
+as (dynamic) sequences and endpoints, as well as resources such as XSLT's,
+Scripts or XSDs off the registry, and update the configuration as these are
+allowed to dynamically change over time.</p>
+
+<p>Synapse ships with a built-in URL based registry implementation called the
+"SimpleURLRegistry" and this can be configured as follows:</p>
+<pre>e.g.
+<registry provider="org.apache.synapse.registry.url.SimpleURLRegistry">
+ <parameter name="root">file:./repository/conf/sample/resources/</parameter>
+ <parameter name="cachableDuration">15000</parameter>
+</registry></pre>
+
+<p>The "root" parameter specifies the root URL of the Registry for loaded
+resources. The SimpleURLRegistry keys are path fragments, that when combined
+with the root prefix would form the full URL for the referenced resource. The
+"cachableDuration" parameter specifies the number of milliseconds for which
+resources loaded from the Registry should be cached. More advanced registry
+implementations allows different cachable durations to be specified for
+different resources, or mark some resources as never expires. (e.g. Check the
+WSO2 ESB implementation built over the Apache Synapse ESB core)</p>
+
+<p></p>
+
+<h3><a name="localEntry">Local Registry / Local Entry</a></h3>
+
+<p>The <localEntry> element is used to declare registry entries that
+are local to the Synapse instance, as shown below</p>
+<pre> <localEntry key="string" [src="url"]>text | xml</localEntry></pre>
+
+<p>These entries are top level entries which are globally visible within the
+entire system. Values of these entries can be retrieved via the extension
+XPath function "synapse:get-property(prop-name)" and the keys of these
+entries could be specified wherever a registry key is expected within the
+configuration.</p>
+
+<p>An entry can be static text specified as inline text or static XML
+specified as an inline XML fragment or specified as a URL (using the src
+attribute). A local entry shadows any entry with the same name from a remote
+Registry.</p>
+<pre>e.g.
+<localEntry key="version">0.1</localEntry>
+<localEntry key="validate_schema">
+ <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
+ ...
+ </xs:schema>
+ </localEntry>
+<localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/></pre>
+
+<h2><a name="sequence">Sequences</a></h2>
+
+<p>A <sequence> element is used to define a sequence of mediators that
+can be invoked later by name. The sequences named "main" and "fault" has
+special significance in a Synapse configuration. The "main" sequence handles
+any message that is accepted for '<a href="#message_mediation">Message
+Mediation</a><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.</a></p>
+
+<p>A Dynamic Sequence may be defined by specifying a key reference to a
+registry entry. As the remote registry entry changes, the sequence will
+dynamically be updated according to the specified cache duration and
+expiration. If tracing is enabled on a sequence, all messages being processed
+through the sequence would write tracing information through each mediation
+step to the trace.log file configured via the log4j.properties configuration.
+Setting the trace log level to TRACE would additionally dump the message and
+detailed trace information at each mediation step. A tracing enabled sequence
+propagates this setting to invoked sub-sequences.</p>
+<pre> <sequence name="string" [onError="string"] [key="string"] [trace="enable"]>
+ mediator*
+ </sequence></pre>
+<pre>e.g.
+<sequence name="main" onError="errorHandler">
+ .. <!-- a 'main' sequence that invokes the sequence named 'errorHandler' on a fault --> ..
+</sequence></pre>
+<pre><sequence key="sequence/dynamic_seq_1.xml"/>
+where "sequence/dynamic_seq_1.xml" refers to the following sequence definition from the registry:
+
+<sequence name="dynamic_sequence" xmlns="http://ws.apache.org/ns/synapse">
+ ..
+</sequence></pre>
+
+<h2><a name="endpoint">Endpoints</a></h2>
+
+<p>An <endpoint> element defines a destination for an outgoing message.
+An endpoint may be specified as an address endpoint, WSDL based endpoint, a
+load balancing endpoint or a fail-over endpoint as follows:</p>
+<pre><endpoint [name="string"] [key="string"] [trace="enable"]>
+ <a href="#address-endpoint">address-endpoint</a> | <a href="#wsdl-endpoint">wsdl-endpoint</a> | <a href="#load-balanced-endpoint">load-balanced-endpoint</a> | <a href="#fail-over-endpoint">fail-over-endpoint</a>
+</endpoint> </pre>
+
+<p>All above endpoint types can have a name attribute, and such named
+endpoints can be reffered by other endpoints, through the key attribute. For
+example if there is an endpoint named as "foo", the following endpoint can be
+used in any place, where "foo" has to be used.</p>
+<pre><endpoint key="foo"/></pre>
+
+<p>The "trace" attribute turns on detailed trace information for messages
+being sent to the endpoint. These are available in the trace.log configured
+via the log4j.properties file. Setting the trace log level to TRACE will dump
+detailed trace information including message payloads. </p>
+
+<h4><a name="address-endpoint">Address Endpoint</a></h4>
+
+<p>Address endpoint is an endpoint defined by specifying the EPR and other
+attributes of the endpoint directly in the configuration.The 'uri' attribute
+of the address element contains the EPR of the target endpoint. Message
+format for the endpoint and the method to optimize attachments can be
+specified in the format and optimize attributes respectively. Reliable
+messaging and security policies for the endpoint can be specified in the
+policy attribute of the enableRM and enableSec elements respectively.
+WS-Addressing can be engaged for the messaging going to the endpoint by the
+enableAddressing element. suspendDurationOnFailure attribute specifies the
+time duration in seconds to suspend this endpoint, if it is detected as
+failed. If this attribute is not specified, endpoint will never be recovered
+after a failure.</p>
+
+<p>Address endpoints can timeout if responses fail to arrive at Synapse by a
+predefined timeout-duration specified in seconds. The timeout action
+specifies whether to discard responses that arrives late, or to trigger a
+fault. Synapse has a periodic timeout handler that triggers itself at each 15
+second interval. Thus endpoint timeouts will have a +/- error on actual
+trigger time. Though this can be minimized by setting a System property
+"synapse.timeout_handler_interval" to a millisecond duration below the
+desired endpoint timeout, care must be taken as a lesser value may have a
+higher overhead on the system. </p>
+
+<p>An endpoint that fails may be suspended for a specified duration after
+such a failure, during which new messages will not be processed through the
+endpoint. The 'suspendDurationOnFailure' could specify an optional value in
+seconds for which this endpoint should be suspended.</p>
+
+<p>QoS aspects such as WS-RM and WS-Security and WS-Addressing may be enabled
+on messages sent to an endpoint using the enableRM, enableSec and
+enableAddressing elements. Optionally, the WS-RM and WS-Security policies
+could be specified using the 'policy' attributes.</p>
+<pre><address uri="endpoint-address" [format="soap11|soap12|pox|get"] [optimize="mtom|swa"]>
+ <enableRM [policy="key"]/>?
+ <enableSec [policy="key"]/>?
+ <enableAddressing/>?
+ <suspendDurationOnFailure>suspend-duration</suspendDurationOnFailure>?
+ <timeout>
+ <duration>timeout-duration</duration>
+ <action>discard|fault</action>
+ </timeout>?
+</address></pre>
+
+<p>Following are some sample address URI definitions.</p>
+<pre>e.g.
+HTTP http://localhost:9000/soap/SimpleStockQuoteService
+JMS jms:/SimpleStockQuoteService?transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&
+ java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&
+ java.naming.provider.url=tcp://localhost:61616&transport.jms.DestinationType=topic
+Mail mailto:guest@host
+File vfs:file:///home/user/directory
+ vfs:file:///home/user/file
+ vfs:ftp://guest:guest@localhost/directory?vfs.passive=true</pre>
+
+<h4><a name="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><wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname">
+ <wsdl:definition>...</wsdl:definition>?
+ <wsdl20:description>...</wsdl20:description>?
+ <enableRM [policy="key"]/>?
+ <enableSec [policy="key"]/>?
+ <enableAddressing/>?
+ <suspendDurationOnFailure>suspend-duration</suspendDurationOnFailure>?
+ <timeout>
+ <duration>timeout-duration</duration>
+ <action>discard|fault</action>
+ </timeout>?
+</wsdl></pre>
+
+<h4><a name="load-balanced-endpoint">Load balanced Endpoint</a></h4>
+
+<p>A Load balanced endpoint distributes the messages (load) arriving at it
+among a set of listed endpoints by evaluating the load balancing policy and
+any other relevant parameters. Policy attribute of the load balance element
+specifies the load balance policy (algorithm) to be used for selecting the
+target endpoint. Currently only the roundRobin policy is supported. failover
+attribute determines if the next endpoint should be selected once the
+currently selected endpoint has failed, and defaults to true. The set of
+endpoints among which the load is distributed can be listed under the
+'loadBalance' element. Those endpoints can belong to any endpoint type
+mentioned in this document. For example, failover endpoints can be listed
+inside the load balance endpoint to load balance between failover groups
+etc.</p>
+
+<p>The optional 'session' element makes the endpoint a session affinity based
+load balancing endpoint. If it is specified, sessions are bound to endpoints
+in the first message and all successive messages for those sessions are
+directed to their associated endpoints. Only http sessions are currently
+supported, and identifies sessions based on http cookies. 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><session type="http"/>?
+<loadBalance [policy="roundRobin"] [failover="true|false"]>
+ <endpoint .../>+
+</loadBalance></pre>
+
+<h4><a name="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><failover>
+ <endpoint .../>+
+</failover></pre>
+
+<h2><a name="proxy">Proxy service</a></h2>
+
+<p>A <proxy> element is used to define a Synapse Proxy service.</p>
+<pre> <proxy name="string" [transports="(http |https |jms |.. )+|all"] [pinnedServers="(serverName )+"]>
+ <description>...</description>?
+ <target [inSequence="name"] [outSequence="name"] [faultSequence="name"] [endpoint="name"]>
+ <inSequence>...</inSequence>?
+ <outSequence>...</outSequence>?
+ <faultSequence>...</faultSequence>?
+ <endpoint>...</endpoint>?
+ </target>?
+ <publishWSDL key="string" uri="string">
+ <description>...</description> | <definitions>...</definitions>
+ </publishWSDL>?
+ <enableSec/>?
+ <enableRM/>?
+ <policy key="string">...</policy>? // optional service level policies such as (e.g. WS-Security and/or WS-RM policies)
+ <parameter name="string"> // optional service parameters such as (e.g. transport.jms.ConnectionFactory)
+ string | xml
+ </parameter>
+ </proxy></pre>
+
+<p>A proxy service is created and exposed on the specified transports through
+the underlying Axis2 engine, exposing service EPR's as per the standard Axis2
+conventions - based on the service name. (Note: that currently Axis2 does not
+allow custom URI's to be set for services on some transports such as http/s)
+The Proxy service could be exposed over all enabled Axis2 transports such as
+http, https, JMS, Mail and File etc. or on a subset of these as specified
+with the optional 'transports' attribute.</p>
+
+<p>You can give a list of synapse server names where this proxy service
+should be deployed using 'pinnedServers' attribute. It takes the server names
+separated by comma or space character. If there is no pinned server list then
+proxy service will be started in all server instances. If a pinned server
+names list is given it will only start in the given named Synapse server
+instances. The Synapse server name picked up from the system property
+'SynapseServerName', failing which the hostname of the machine would be used
+or default to 'localhost'. You can give a name to a Synapse server instance
+as ./synapse.sh -DSynapseServerName=<ServerName> or by editing the
+wrapper.conf where Synapse is started as a service.</p>
+
+<p>Each service could define the target for received messages as a named
+sequence or a direct endpoint. Target inSequence or endpoint is required for
+the proxy configuration, and a target outSequence defines how responses
+should be handled. Any supplied WS-Policies would apply as service level
+policies, and any service parameters could be passed into the proxy services'
+AxisService instance using the parameter elements (e.g. the JMS destination
+etc). If the proxy service should enable WS-Reliable Messaging or Security,
+the appropriate modules could be engaged, and specified service level
+policies will apply.</p>
+
+<p>A Dynamic Proxy may be defined by specifying the properties of the proxy
+as dynamic entries by refering them with the key. (For example one could
+specify the inSequence or endpoint with a remote key, without defining it in
+the local configuration) As the remote registry entry changes, the properties
+of the proxy will dynamically be updated accordingly. (Note: proxy service
+definition itself can not be specified to be dynamic; i.e <proxy
+key="string"/> is wrong)</p>
+
+<p></p>
+
+<p>You can give the following as service parameters:</p>
+
+<table border="0" cellpadding="0" cellspacing="0" style="width: 100%"
+class="data-table">
+ <caption></caption>
+ <tbody>
+ <tr>
+ <th>Parameter</th>
+ <th>Value</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td>useOriginalwsdl</td>
+ <td>true|false</td>
+ <td>false</td>
+ <td>Use the given WSDL instead of generating the WSDL.</td>
+ </tr>
+ <tr>
+ <td>modifyUserWSDLPortAddress</td>
+ <td>true|false</td>
+ <td>true</td>
+ <td>(Effective only with useOriginalwsdl=true) If true (default) modify
+ the port addresses to current host.</td>
+ </tr>
+ </tbody>
+</table>
+
+<p></p>
+
+<p>Transport specific parameters that may be set as service parameters:</p>
+
+<table border="0" cellpadding="0" cellspacing="0" style="width: 100%"
+class="data-table">
+ <caption></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>
+ <td>Optional</td>
+ <td>transport.jms.Destination</td>
+ <td>The JMS destination name (Defaults to the service name)</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.jms.DestinationType</td>
+ <td>The JMS destination type. Accept values 'queue' or 'topic'</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.jms.ReplyDestination</td>
+ <td>The destination where a reply will be posted</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td>VFS</td>
+ <td>Required</td>
+ <td>transport.vfs.FileURI</td>
+ <td>The primary File (or Directory) URI in the vfs* transport format,
+ for this service</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Required</td>
+ <td>transport.vfs.ContentType</td>
+ <td>The content type for messages for this service</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.FileNamePattern</td>
+ <td>A file name regex pattern to match files against a directory
+ specified by the FileURI</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.PollInterval</td>
+ <td>The poll interval (in seconds)</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.ActionAfterProcess</td>
+ <td>DELETE or MOVE</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.MoveAfterProcess</td>
+ <td>The directory to move files after processing (i.e. all files
+ process successfully)</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.ActionAfterErrors</td>
+ <td>DELETE or MOVE</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.MoveAfterErrors</td>
+ <td>The directory to move files after errors (i.e. some of the files
+ succeed but some fail)</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.ActionAfterFailure</td>
+ <td>DELETE or MOVE</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.MoveAfterFailure</td>
+ <td>The directory to move after failure (i.e. all files fail)</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.ReplyFileURI</td>
+ <td>Reply file URI</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td>Optional</td>
+ <td>transport.vfs.ReplyFileName</td>
+ <td>Reply file name (defaults to response.xml)</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td></td>
+ </tr>
+ </tbody>
+</table>
+
+<p>VFS Transport URI examples (See <a
+href="http://commons.apache.org/vfs/filesystems.html">http://commons.apache.org/vfs/filesystems.html
+for more samples</a>)</p>
+<pre>file:///directory/filename.ext
+file:////somehost/someshare/afile.txt
+jar:../lib/classes.jar!/META-INF/manifest.mf
+jar:zip:outer.zip!/nested.jar!/somedir
+ftp://myusername:mypassword@somehost/pub/downloads/somefile.tgz[?vfs.passive=true]</pre>
+
+<h2><a name="task">Tasks</a></h2>
+
+<p>A <task> element is used to define a Synapse Startup Task.</p>
+<pre> <task class="mypackage.MyTask" name="string" [pinnedServers="(serverName)+"]>
+ <property name="stringProp" value="String"/>
+ <property name="xmlProp">
+ <somexml>config</somexml>
+ </property>
+ <trigger ([[count="10"]? interval="1000"] | [cron="0 * 1 * * ?"] | [once=(true | false)])/>
+ </task></pre>
+
+<p>A task is created and scheduled to run at specified time intervals or as
+specified by the cron expression. The Task class specifies the actual task
+implementation class (which must implement org.apache.synapse.startup.Task
+interface) to be executed at the specified interval/s, and name specifies an
+identifier for the scheduled task. </p>
+
+<p>Fields in the task class can be set using properties provided as string
+literals or as XML fragments. (For example; if the task implementation class
+has a field named "version" with a corresponding setter method, the
+configuration value which will be assigned to this field before running the
+task can be specified using a property with the name 'version')</p>
+
+<p>There are three different trigger mechanisms to schedule tasks. A simple
+trigger is specified specifying a 'count' and an 'interval', implying that
+the task will run a 'count' number of times at specified intervals. A trigger
+may also be specified as a cron trigger using a cron expression. A one-time
+trigger is specified using the 'once' attribute as true in the definition and
+could be specified as true in which case this task will be executed only once
+just after the initialization of Synapse</p>
+
+<p>You can give a list of synapse server names where this task should be
+started using pinnedServers attribute. Refer to the explanation of this
+attribute under proxy services for more information.</p>
+
+<h2><a name="mediator">Mediators</a></h2>
+
+<p>A mediator token refers to any of the following tokens:</p>
+<pre><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="#makefault">makefault</a> | <a href="#xslt">xslt</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="#RMSequence">RMSequence</a> | <a href="#throttle">throttle</a> | <a href="#xquery">xquery</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="#script">script</a> | <a href="#spring">spring</a> </pre>
+
+<p>In addition to the above, Synapse will be able to load custom mediators
+via the J2SE Service Provider model. Mediator extensions must implement the
+MediatorFactory interface. The Class and POJO Command mediators allow custom
+Java code to be easily invoked during mediation, while the Script mediator
+allows Apache BSF scripts such as Javascript, Ruby, Groovy etc to be used for
+mediation.</p>
+
+<h3>Core Mediators</h3>
+
+<h4><a name="send">Send</a></h4>
+
+<p>The send token represents a <send> element, used to send messages
+out of Synapse to some endpoint. The send mediator also copies any message
+context properties from the current message context to the reply message
+received on the execution of the send operation so that the response could be
+correlated back to the request. Messages may be correlated by WS-A MessageID,
+or even simple custom text labels (see the property mediator and samples)</p>
+
+<p>In the simplest case shown below, the destination to send a message is
+implicit in the message via the 'To' address. Thus a request message will be
+sent to its 'To' address, and a response message would be sent back to the
+client. Removing the 'To' address of a message targets it back to the client,
+and thus a request message received may be returned to the client after
+changing its direction. (Note: to mark a message as a response set the
+property RESPONSE to true)</p>
+
+<p><strong>Note:</strong> A send operation may be blocking or non-blocking
+depending on the actual transport implementation used. As the default NIO
+based http/s implementation does not block on a send, care must be taken if
+the same message must be sent and then further processed (e.g. transformed).
+In such a scenario, it maybe required to first clone the message into two
+copies and then perform processing to avoid conflicts.</p>
+<pre> <send/></pre>
+
+<p>If the message is to be sent to one or more endpoints, then the following
+is used:</p>
+<pre> <send>
+ (endpointref | endpoint)+
+ </send></pre>
+
+<p>where the endpointref token refers to the following:</p>
+<pre> <endpoint key="name"/></pre>
+
+<p>and the endpoint token refers to an anonymous endpoint definition.</p>
+
+<p></p>
+
+<h4><a name="drop">Drop</a></h4>
+
+<p>The drop token refers to a <drop> element which is used to stop
+further processing of a message:</p>
+<pre> <drop/></pre>
+
+<p>Once the <drop> mediator executes, further processing of the current
+message stops. A the drop mediator does not necessarily close transports.</p>
+
+<p></p>
+
+<h4><a name="log">Log</a></h4>
+
+<p>The log token refers to a <log> element which may be used to log
+messages being mediated:</p>
+<pre> <log [level="string"] [separator="string"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+ </log></pre>
+
+<p>The optional level attribute selects a pre-defined subset of properties to
+be logged.</p>
+
+<p>e.g.</p>
+<ul>
+ <li>simple = To, From, WSAction, SOAPAction, ReplyTo, MessageID and any
+ properties</li>
+ <li>headers = All SOAP header blocks and any properties</li>
+ <li>full = all attributes included in log level 'simple' and the SOAP
+ envelope and any properties</li>
+ <li>custom = Only properties specified to the Log mediator</li>
+</ul>
+
+<p>A separator if defined will be used to separate the attributes being
+logged. The default separator is the ',' comma.</p>
+
+<p></p>
+
+<h4><a name="property">Property</a></h4>
+<pre> <property name="string" [action=set|remove] (value="literal" | expression="xpath") [scope=transport|axis2|axis2-client]/></pre>
+
+<p>The property token refers to a <property> element which is a
+mediator that has no direct impact on the message but rather on the message
+context flowing through Synapse. The properties set on a message can be later
+retrieved through the synapse:get-property(prop-name) XPath extension
+function. If a scope is specified for a property, the property could be set
+as a transport header property or an (underlying) Axis2 message context
+property, or as a Axis2 client option. If a scope is not specified, it will
+default to the Synapse message context scope. Using the property element with
+action specified as "remove" you can remove any existing message context
+properties.</p>
+
+<p>There are some well-defined properties that you can get/set on the Synapse
+message context scope:</p>
+<ul>
+ <li>RESPONSE - 'true' means the message is to be marked as a response
+ message</li>
+ <li>OUT_ONLY - 'true' means the message is to be marked as an out-only
+ message that does not expect a response</li>
+ <li>ERROR_CODE - this is set to any error message code encountered during a
+ fault</li>
+ <li>ERROR_MESSAGE - this is set to any error message text encountered
+ during a fault</li>
+ <li>ERROR_DETAIL - this is set to any error message detail text encountered
+ during a fault</li>
+ <li>ERROR_EXCEPTION - this is set to any Java Exception encountered during
+ a fault</li>
+</ul>
+
+<p>There are some Axis2 and module properties that are useful which are set
+at scope="axis2"</p>
+<ul>
+ <li>Sandesha2RMSpecVersion - can be '1.0' or '1.1'</li>
+ <li>Sandesha2SequenceKey - can be an identifier specifying an Sandesha
+ internal sequence key, and</li>
+ <li>Sandesha2LastMessage - 'true' will make this the last message and
+ terminate the sequence</li>
+</ul>
+
+<p>There are some Axis2 client side properties/options that are useful which
+are set at scope="axis2-client"</p>
+<ul>
+ <li>FORCE_HTTP_1.0 - forces outgoing http/s messages to use HTTP 1.0
+ (instead of the default 1.1)</li>
+</ul>
+
+<h5>The synapse:get-property() XPath extension function</h5>
+
+<p>The get-property() function allows any XPath expression used in a
+configuration to lookup information from the current message context. It is
+possible to retrieve properties previously set with the property mediator,
+and/or information from the Synapse or Axis2 message contexts or transport
+header. The function accepts the scope as an optional parameter as shown
+below:</p>
+
+<p>synapse:get-property( [(axis2 | axis2-client | transport),]
+<property_name> [,<dateformat>] ) </p>
+
+<p></p>
+
+<p>Some useful properties from the Synapse message context follows:</p>
+<ul>
+ <li>SYSTEM_DATE - Returns the current date as a String. Optionally a date
+ format as per standard date format may be supplied. e.g.
+ synapse:get-property(SYSTEM_DATE, "yyyy.MM.dd G 'at' HH:mm:ss z") or
+ get-property(SYSTEM_DATE)</li>
+ <li>SYSTEM_TIME - Returns the current time in milliseconds. (i.e. the
+ difference, measured in milliseconds, between the current time and
+ midnight, January 1, 1970 UTC)</li>
+ <li>To, From, Action, FaultTo, ReplyTo, MessageID the message To and Action
+ and WS-Addressing properties</li>
+ <li>MESSAGE_FORMAT - returns the message format - i.e. returns pox, get,
+ soap11 or soap12</li>
+ <li>OperationName - returns the operation name for the message</li>
+</ul>
+
+<p>In addition to the above, one may use the get-property() function to
+retrieve Axis2 message context properties or transport headers. e.g.
+synapse:get-property('transport', 'USER_AGENT')</p>
+
+<h4><a name="sequence_ref">Sequence</a></h4>
+<pre> <sequence key="name"/></pre>
+
+<p>A sequence ref token refers to a <sequence> element which is used to
+invoke a named sequence of mediators.</p>
+
+<p></p>
+
+<h4><a name="validate">Validate</a></h4>
+<pre> <validate [source="xpath"]>
+ <property name="validation-feature-id" value="true|false"/>*
+ <schema key="string"/>+
+ <on-fail>
+ mediator+
+ </on-fail>
+ </validate></pre>
+
+<p>The <validate> mediator validates the result of the evaluation of
+the source xpath expression, against the schema specified. If the source
+attribute is not specified, the validation is performed against the first
+child of the SOAP body of the current message. If the validation fails, the
+on-fail sequence of mediators is executed. Properties could be used to turn
+on/off some of the underlying features of the validator (See <a
+href="http://xerces.apache.org/xerces2-j/features.html">http://xerces.apache.org/xerces2-j/features.html</a>)</p>
+
+<p></p>
+
+<h3>Transformation Mediators</h3>
+
+<h4><a name="makefault">Makefault</a></h4>
+<pre> <makefault [version="soap11|soap12"]>
+ <code (value="literal" | expression="xpath")/>
+ <reason (value="literal" | expression="xpath")>
+ <node>?
+ <role>?
+ <detail>?
+ </makefault></pre>
+
+<p>The <makefault> mediator transforms the current message into a fault
+message, but does NOT send it. The <send> mediator needs to be invoked
+to send a fault message created this way. The fault message "to" header is
+set to the "faultTo" of the original message if such a header existed on the
+original message. If a 'version' attribute is specified, the created fault
+message will be created as a selected SOAP 1.1 or SOAP 1.2 fault.</p>
+
+<p></p>
+
+<h4><a name="xslt">XSLT</a></h4>
+<pre> <xslt key="string" [source="xpath"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+ <feature name="string" value="true| false" />*
+ </xslt></pre>
+
+<p>The <xslt> mediator applies the specified XSLT transformation to the
+selected element of the current message payload. If the source element is not
+specified, it defaults to the first child of the soap body. Optionally
+parameters (XSLT) could be passed into the transformations through the
+'property' elements.The 'feature' elements defines any features which should
+be set to the TransformerFactory by explicitly. The feature
+'http://ws.apache.org/ns/synapse/transform/feature/dom' turns on DOM based
+transformations instead of serializing elements into Byte streams and/or
+temporary files. Though this would be better in performance than using byte
+streams, sometimes it may not work for all transformations.</p>
+
+<p></p>
+
+<h4><a name="header">Header</a></h4>
+<pre> <header name="qname" (value="literal" | expression="xpath") [action="set"]/>
+ <header name="qname" action="remove"/></pre>
+
+<p>The <header> mediator sets or removes a specified header from the
+current soap infoset. Currently the set header only supports simple valued
+headers. In the future we may extend this to have XML structured headers by
+embedding the XML content within the element itself. The optional action
+attribute specifies whether the mediator should set or remove the header. If
+omitted, it defaults to a set-header.</p>
+
+<p></p>
+
+<h3>Selection Mediators</h3>
+
+<h4><a name="filter">Filter</a></h4>
+<pre> <filter (source="xpath" regex="string") | xpath="xpath">
+ mediator+
+ </filter></pre>
+
+<p>The <filter> mediator either test the given xpath expression as a
+boolean expression, or match the evaluation result of a source xpath
+expression as a String against the given regular expression. If the test
+succeeds, the filter mediator will execute the enclosed mediators in
+sequence.</p>
+
+<p></p>
+
+<h4><a name="switch">Switch</a></h4>
+<pre> <switch source="xpath">
+ <case regex="string">
+ mediator+
+ </case>+
+ <default>
+ mediator+
+ </default>?
+ </switch></pre>
+
+<p>The <switch> mediator will evaluate the given source xpath
+expression into its string value, and match it against the given regular
+expressions. If the specified cases does not match and a default case exists,
+it will be executed.</p>
+<a name="in"></a>
+
+<h4><a name="out">In / Out</a></h4>
+<pre><in><br/> mediator+
+</in><br/></pre>
+<pre><out>
+ mediator+
+</out></pre>
+
+<p><br/>
+</p>
+
+<p>The In and Out mediators will execute the child mediators over the current
+message if the message matches the direction of the mediator. Hence all
+incoming messages would pass through the "<in>" mediators and vice
+versa.</p>
+
+<p></p>
+
+<h3>Database Mediators </h3>
+
+<h4><a name="dblookup">DB-lookup</a></h4>
+<pre><dblookup>
+ <connection>
+ <pool>
+ (
+ <driver/>
+ <url/>
+ <user/>
+ <password/>
+ |
+ <dsName/>
+ <icClass/>
+ <url/>
+ <user/>
+ <password/>
+ )
+ <property name="name" value="value"/>*
+ </pool>
+ </connection>
+ <statement>
+ <sql>select something from table where something_else = ?</sql>
+ <parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>*
+ <result name="string" column="int|string"/>*
+ </statement>+
+</dblookup></pre>
+
+<p></p>
+
+<p>The dblookup mediator is capable of executing an arbitrary SQL select
+statement, and then set some resulting values as local message properties on
+the message context. The DB connection used maybe looked up from an external
+DataSource or specified in-line, in which case an Apache DBCP connection pool
+is established and used. Apache DBCP connection pools support the following
+properties:</p>
+<ul>
+ <li>autocommit = true | false</li>
+ <li>isolation = Connection.TRANSACTION_NONE |
+ Connection.TRANSACTION_READ_COMMITTED |
+ Connection.TRANSACTION_READ_UNCOMMITTED |
+ Connection.TRANSACTION_REPEATABLE_READ |
+ Connection.TRANSACTION_SERIALIZABLE</li>
+ <li>initialsize = int</li>
+ <li>maxactive = int</li>
+ <li>maxidle = int</li>
+ <li>maxopenstatements = int</li>
+ <li>maxwait = long</li>
+ <li>minidle = int</li>
+ <li>poolstatements = true | false</li>
+ <li>testonborrow = true | false</li>
+ <li>testonreturn = true | false</li>
+ <li>testwhileidle = true | false</li>
+ <li>validationquery = String</li>
+</ul>
+
+<p>More than one statement may be specified, and the SQL statement may
+specify parameters which could be specified as values or XPath expressions.
+The types of parameters could be any valid SQL types. Only the first row of a
+result set will be considered and any others are ignored. The single
+<result> element contains the 'name' and the column' attributes. The
+'name' attribute defines the name under which the result is stored in the
+Synapse message context, and the column attribute specifies a column number
+or name .</p>
+
+<h4><a name="dbreport">DB-report</a></h4>
+<pre><dbreport>
+ <connection>
+ <pool>
+ (
+ <driver/>
+ <url/>
+ <user/>
+ <password/>
+ |
+ <dsName/>
+ <icClass/>
+ <url/>
+ <user/>
+ <password/>
+ )
+ <property name="name" value="value"/>*
+ </pool>
+ </connection>
+ <statement>
+ <sql>insert into something values(?, ?, ?, ?)</sql>
+ <parameter [value="" | expression=""] type="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>*
+ </statement>+
+</dblreport></pre>
+
+<p></p>
+
+<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></p>
+
+<h3>Advanced Mediators</h3>
+
+<h4><a name="RMSequence">RMSequence</a></h4>
+<pre> <RMSequence (correlation="xpath" [last-message="xpath"]) | single="true" [version="1.0|1.1"]/></pre>
+
+<p>The <RMSequence> mediator can be used to create a sequence of
+messages to communicate via WS-Reliable Messaging with an WS-RM enabled
+endpoint (<enableRM>). The simple use case of this mediator is to
+specify a single="true" property, because this means that only one message is
+involved in the same sequence. However if multiple messages should be sent in
+the same sequence, the correlation property should be used with a XPath
+expression that selects an unique element value from the incoming message.
+With the result of the XPath expression, Synapse can group messages together
+that belong to the same sequence. To close the sequence neatly, for the last
+message of the sequence also an XPath expression should be specified. With
+the version attribute the WS-RM specification version to be used can be
+specified, 1.0 or 1.1. </p>
+
+<p></p>
+
+<h4><a name="throttle">Throttle</a></h4>
+<pre><throttle [onReject="string"] [onAccept="string"] id="string">
+ (<policy key="string"/> | <policy>..</policy>)
+ <onReject>..</onReject>?
+ <onAccept>..</onAccept>?
+</throttle></pre>
+
+<p></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="xquery">XQuery</a></h4>
+<pre><xquery key="string" [target="xpath"]>
+ <variable name="string" type="string" [key="string"] [expression="xpath"] [value="string"]/>?
+</xquery> </pre>
+
+<p></p>
+
+<p>The XQuery mediator can be used to perform an XQuery transformation. The
+'key' attribute specifies the XQuery transformation, and the optional
+'target' attribute specifies the node of the message that should be
+transformed. This defaults to the first child of the SOAP body of the
+payload. The 'variable' elements define a variable that could be bound to the
+dynamic context of the XQuery engine in order to access those variables
+through the XQuery script .</p>
+
+<p>It is possible to specify just a literal 'value', or an XPath expression
+over the payload, or even specify a registry key or a registry key combined
+with an XPath expression that selects the variable. The name of the variable
+corresponds to the name of variable declaration in the XQuery script. The
+'type' of the variable must be a valid type defined by the JSR-000225 (XQJ
+API). </p>
+
+<p>The supported types are:</p>
+<ul>
+ <li>XQItemType.XQBASETYPE_INT -> INT</li>
+ <li>XQItemType.XQBASETYPE_INTEGER -> INTEGER</li>
+ <li>XQItemType.XQBASETYPE_BOOLEAN -> BOOLEAN</li>
+ <li>XQItemType.XQBASETYPE_BYTE - > BYTE</li>
+ <li>XQItemType.XQBASETYPE_DOUBLE -> DOUBLE</li>
+ <li>XQItemType.XQBASETYPE_SHORT -> SHORT</li>
+ <li>XQItemType.XQBASETYPE_LONG -> LONG</li>
+ <li>XQItemType.XQBASETYPE_FLOAT -> FLOAT</li>
+ <li>XQItemType.XQBASETYPE_STRING -> STRING</li>
+ <li>XQItemType.XQITEMKIND_DOCUMENT -> DOCUMENT</li>
+ <li>XQItemType.XQITEMKIND_DOCUMENT_ELEMENT -> DOCUMENT_ELEMENT</li>
+ <li>XQItemType.XQITEMKIND_ELEMENT -> ELEMENT</li>
+</ul>
+
+<h4><a name="cache">Cache</a></h4>
+<pre> <cache id="string" [hashGenerator="class"] [timeout="seconds"] [scope=(per-host | per-mediator)]
+ collector=(true | false) [maxMessageSize="in-bytes"]>
+ <onCacheHit [sequence="key"]>
+ (mediator)+
+ </onCacheHit>?
+ <implementation type=(memory | disk) maxSize="int"/>
+ </cache></pre>
+
+<p>The <cache> mediator will evaluate the hash value of an incoming
+message as described in the optional hash generator implementation (which
+should be a class implementing the org.wso2.caching.digest.DigestGenerator
+interface). The default hash generator is
+'org.wso2.caching.digest.DOMHashGenerator'. If the generated hash value has
+been found in the cache then the cache mediator will execute the onCacheHit
+sequence which can be specified inline or referenced. The cache mediator must
+be specified with an 'id' and two instances with this same 'id' that
+correlates the response message into the cache for the request message hash.
+The optional 'timeout' specifies the valid duration for cached elements, and
+the scope defines if mediator instances share a common cache per every host
+instance, or per every cache mediator pair (i.e. 'id') instance. The
+'collector' attribute 'true' specifies that the mediator instance is a
+response collection instance, and 'false' specifies that its a cache serving
+instance. The maximum size of a message to be cached could be specified with
+the optional 'maxMessageSize' attributes in bytes and defaults to unlimited.
+Finally the 'implementation' element may define if the cache is disk or
+memory based, and the 'maxSize' attribute defines the maximum number of
+elements to be cached.</p>
+
+<h4><a name="clone">Clone</a></h4>
+<pre> <clone [continueParent=(true | false)]>
+ <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]>
+ <sequence>
+ (mediator)+
+ </sequence>?
+ <endpoint>
+ endpoint
+ </endpoint>?
+ </target>+
+ </clone></pre>
+
+<p>The clone mediator closely resembles the Message Splitter EIP and will
+split the message into number of identical messages which will be processed
+in parallel. The original message cloned can be continued or dropped
+depending on the boolean value of the optional 'continueParent' attribute.
+Optionally a custom 'To' address and/or a 'Action' may be specified for
+cloned messages</p>
+
+<h4><a name="iterate">Iterate</a></h4>
+<pre> <iterate [continueParent=(true | false)] [preservePayload=(true | false)] (attachPath="xpath")? expression="xpath">
+ <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]>
+ <sequence>
+ (mediator)+
+ </sequence>?
+ <endpoint>
+ endpoint
+ </endpoint>?
+ </target>+
+ </iterate></pre>
+
+<p>The iterate mediator implements another EIP and will split the message
+into number of different messages derived from the parent message by finding
+matching elements for the XPath expression specified. New messages will be
+created for each and every matching element and processed in parallel using
+either the specified sequence or endpoint. Parent message can be continued or
+dropped in the same way as in the clone mediator. The 'preservePayload'
+attribute specifies if the original message should be used as a template when
+creating the splitted messages, and defaults to 'false', in which case the
+splitted messages would contain the split elements as the SOAP body.</p>
+
+<h4><a name="aggregate">Aggregate</a></h4>
+<pre> <aggregate>
+ <correlateOn expression="xpath"/>?
+ <completeCondition [timeout="time-in-seconds"]>
+ <messageCount min="int-min" max="int-max"/>?
+ </completeCondition>?
+ <onComplete expression="xpath" [sequence="sequence-ref"]>
+ (mediator +)?
+ </onComplete>
+ </aggregate></pre>
+
+<p>The aggregate mediator implements the Message Aggregator EIP and will
+aggregate the messages or responses for splitted messages using either the
+clone or iterate mediators. At the same time it can aggregate messages on the
+presence of matching elements specified by the correlateOn XPATH expression.
+Aggregate will collect the messages coming into it until the messages
+collected on the aggregation satisfies the complete condition. The completion
+condition can specify a minimum or maximum number of messages to be
+collected, or a timeout value in seconds, after which the aggregation
+terminates. On completion of the aggregation it will merge all of the
+collected messages and invoke the onComplete sequence on it. The merged
+message would be created using the XPath expression specified by the
+attribute 'expression' on the 'onComplete' element.</p>
+
+<h3>Extension mediators</h3>
+
+<h4><a name="class">Class</a></h4>
+<pre> <class name="class-name">
+ <property name="string" value="literal">
+ (either literal or XML child)
+ </property>
+ </class> </pre>
+
+<p>The class mediator creates an instance of a custom specified class and
+sets it as a mediator. The class must implement the
+org.apache.synapse.api.Mediator interface. If any properties are specified,
+the corresponding setter methods are invoked on the class, once, during
+initialization.</p>
+
+<p></p>
+
+<h4><a name="pojoCommand">POJOCommand</a></h4>
+<pre> <pojoCommand name="class-name">
+ (
+ <property name="string" value="string"/> |
+ <property name="string" context-name="literal" [action=(ReadContext | UpdateContext | ReadAndUpdateContext)]>
+ (either literal or XML child)
+ </property> |
+ <property name="string" expression="xpath" [action=(ReadMessage | UpdateMessage | ReadAndUpdateMessage)]/>
+ )*
+ </pojoCommand> </pre>
+
+<p>The pojoCommand mediator creates an instance of the specified command
+class - which may implement the org.apache.synapse.Command interface or
+should have a public void method "public void execute()". If any properties
+are specified, the corresponding setter methods are invoked on the class
+before each message is executed. It should be noted that a new instance of
+the POJO Command class is created to process each message processed. After
+execution of the POJO Command mediator, depending on the 'action' attribute
+of the property, the new value returned by a call to the corresponding getter
+method is stored back to the message or to the context. The 'action'
+attribute may specify whether this behaviour is expected or not via the Read,
+Update and ReadAndUpdate properties.</p>
+
+<p></p>
+
+<h3><a name="script">Scripting language mediators</a></h3>
+
+<p></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> <script key="string" language="string" [function="script-function-name"]/></pre>
+
+<p>The property key is the registry key to load the script. The language
+attribute specifies the scripting language of the script code (e.g. "js" for
+Javascript, "rb" for ruby, "groovy" for Groovy, "py" for Python..). The
+function is an optional attribute defining the name of the script function to
+invoke, if not specified it defaults to a function named 'mediate'. The
+function is passed a single parameter - which is the Synapse MessageContext.
+The function may return a boolean, if it does not, then true is assumed, and
+the script mediator returns this value. An inline script mediator has the
+script source embedded in the configuration as follows:</p>
+<pre> <script language="string">...script source code...<script/></pre>
+
+<p>The execution context environment of the script has access to the Synapse
+MessageContext predefined in a script variable named 'mc' . An example of an
+inline mediator using JavaScript/E4X which returns false if the SOAP message
+body contains an element named 'symbol' which has a value of 'IBM' would
+be:</p>
+<pre> <script language="js">mc.getPayloadXML()..symbol != "IBM";<script/></pre>
+
+<p>Synapse uses the Apache <a href="http://jakarta.apache.org/bsf/">Bean
+Scripting Framework</a> for the scripting language support, any script
+language supported by BSF may be used to implement a Synapse Mediator. </p>
+
+<p>Implementing a Mediator with a script language can have advantages over
+using the built in Synapse Mediator types or implementing a custom Java class
+Mediator. Script Mediators have all the flexibility of a class Mediator with
+access to the Synapse MessageContext and SynapseEnvironment APIs, and the
+ease of use and dynamic nature of scripting languages allows rapid
+development and prototyping of custom mediators. An additional benefit of
+some scripting languages is that they have very simple and elegant XML
+manipulation capabilities, for example JavaScript E4X or Ruby REXML, so this
+makes them well suited for use in the Synapse mediation environment. For both
+types of script mediator definition the MessageContext passed into the script
+has additional methods over the standard Synapse MessageContext to enable
+working with the XML in a way natural to the scripting language. For example
+when using JavaScript getPayloadXML and setPayloadXML, E4X XML objects, and
+when using Ruby, REXML documents.</p>
+
+<h3>Extensibility of Synapse</h3>
+
+<p>The Synapse configuration language could be easily extended, with
+configuration extensions as well as mediation extensions. The Spring mediator
+is such an example.</p>
+
+<h4>Spring Configuration</h4>
+
+<p>A Spring configuration could be created as a localEntry or remote registry
+entry providing a URL or a key reference to a Registry. The configuration is
+then created on first use or as necessary (as per registry lookup semantics)
+by the mediators which reference this configuration.</p>
+<pre> <localEntry key="string"/>
+ <localEntry key="string" src="url"/></pre>
+
+<p>The name attribute specifies a unique name for the configuration, and the
+src, key or inlined XML references to the Spring configuration</p>
+
+<p></p>
+
+<h4><a name="spring">Spring mediator</a></h4>
+<pre> <spring:spring bean="exampleBean1" key="string"/></pre>
+
+<p>The <spring> element creates an instance of a mediator, which is
+managed by Spring. This Spring bean must implement the Mediator interface for
+it to act as a Mediator. The key will reference the Spring
+ApplicationContext/Configuration used for the bean</p>
+</body>
+</html>
Propchange: synapse/branches/2.1/src/site/xdoc/1_1_1/configuration.xml
------------------------------------------------------------------------------
svn:executable = *
Added: synapse/branches/2.1/src/site/xdoc/1_1_1/content.xml
URL: http://svn.apache.org/viewvc/synapse/branches/2.1/src/site/xdoc/1_1_1/content.xml?rev=1225148&view=auto
==============================================================================
--- synapse/branches/2.1/src/site/xdoc/1_1_1/content.xml (added)
+++ synapse/branches/2.1/src/site/xdoc/1_1_1/content.xml Wed Dec 28 09:23:09 2011
@@ -0,0 +1,96 @@
+<?xml version="1.0" encoding="ISO-8859-1" ?>
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+<document>
+
+ <properties>
+ <title>The lightweight ESB</title>
+ </properties>
+
+<body>
+
+<section name="Apache Synapse Enterprise Service Bus (ESB)">
+ <p>
+ Apache Synapse is designed to be a simple, lightweight and high performance
+ Enterprise Service Bus (ESB) from Apache. Based on a small asynchronous core,
+ Apache Synapse has excellent support for XML and Web services - as well as binary and text formats.
+ The Synapse engine is configured with a simple XML format and comes with a set of ready-to-use transports and mediators.
+ We recommend you start by reading the QuickStart and then trying out the samples. Synapse is made available under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache Software License 2.0</a>.
+ </p><p>
+ <b>Latest News</b>
+ </p><p>
+ In December 2007, Apache Synapse became a top level project (TLP) of the
+ Apache Software Foundation.
+ </p>
+ <p>For more information, see:
+ <ul>
+ <li><a href="./quickstart.html">Quick Start Guide</a></li>
+ <li><a href="./configuration.html">The Synapse Configuration Language</a></li>
+ <li><a href="./samples.html">A Quick start with Synapse Samples</a></li>
+ <li><a href="./extending.html">Extending Synapse</a></li>
+ <li>The Developer mailing list: <a href="mailto:dev-subscribe@synapse.apache.org">Subscribe</a></li>
+ <li>The User mailing list: <a href="mailto:user-subscribe@synapse.apache.org">Subscribe</a></li>
+ <!--li>The Synapse Wiki <a href="http://wiki.apache.org/ws/Synapse">http://wiki.apache.org/ws/Synapse</a></li-->
+ </ul>
+ </p>
+</section>
+
+<section name="Introduction">
+<p>
+ Apache Synapse is an ESB that has been designed to be simple to configure, very fast, and effective at solving many integration and gatewaying problems.
+ Synapse has support for HTTP, SOAP, SMTP, JMS, FTP and file system transports, as well as first class support for standards such as WS-Addressing,
+ Web Services Security (WSS), Web Services Reliable Messaging (WSRM), efficient binary attachments (MTOM/XOP).
+ Synapse can transform messages using key standards such as XSLT, XPath and XQuery, or simply using Java. Synapse supports a number of useful
+ functions out-of-the-box without programming, but it also can be extended using popular programming languages such as Java, JavaScript, Ruby, and Groovy.
+</p>
+<p>
+ Synapse has a completely asynchronous core, and supports non-blocking HTTP and HTTPS using the
+ excellent <a href="http://hc.apache.org/httpcomponents-core/index.html">Apache HttpCore</a> NIO module. In addition, Synapse supports JMS v1.0 and higher, Apache VFS File Systems (FTP, SFTP, File (including zip/jar/tar/gz), Webdav, CIFS), POP3/IMAP/SMTP transports. Apache Synapse can process
+ SOAP 1.1/1.2, pure XML/REST, Text and Binary messages with support for any-to-any conversion and transformation.
+</p>
+</section>
+
+<section name="Key Features">
+ <p>The latest release of Synapse is <a href="../download/1.1.1/download.cgi">1.1.1</a>. Its key features are </p>
+
+ <ul>
+ <li><p>Proxy services - facilitating transport, interface (WSDL/Schema/Policy), message format (SOAP 1.1/1.2, POX/REST, Text, Binary), QoS (WS-Security/RM) and optimization switching (MTOM/SwA)</p></li>
+ <li><p>Non-blocking http/s transports based on Apache <a target="_blank" href="http://hc.apache.org/httpcomponents-core/index.html">HttpCore</a> for ultrafast execution and support for thousands of connections</p></li>
+ <li><p>Built in Registry/Repository, facilitating dynamic updating and reloading of the configuration and associated resources (e.g. XSLTs, XSD, JS, ..)</p></li>
+ <li><p>Easily extended via custom Java class (mediator and command)/Spring mediators, or BSF Scripting languages (Javascript, Ruby, Groovy etc)</p></li>
+ <li><p>Built in support for scheduling tasks using the <a target="_blank" href="http://www.opensymphony.com/quartz">Quartz</a> scheduler</p></li>
+ <li><p>Load-balancing/Fail-over, and clustered Throttling and Caching support</p></li>
+ <li><p>WS-Security, WS-Reliable Messaging & Throttling configurable via WS-Policies</p></li>
+ <li><p>JMS (v1.x upwards) message support for binary, plain text and XML and SOAP payloads</p></li>
+ <li><p>Enhanced support for Apache VFS transports (s/ftp, file, zip/tar/gz, webdav, cifs..)</p></li>
+ <li><p>Support for message splitting & aggregation using the EIP</p></li>
+ <li><p>Database lookup & store support with DBMediators</p></li>
+ <li><p>Enhanced Mail transport with POP3/SMTP/IMAP protocols</p></li>
+ <li><p>Ability to pin a proxy service or a task to server instances on a cluster</p></li>
+ <li><p>Lightweight, XML and Web services centric messaging model</p></li>
+ <li><p>Configurations serialized into a file system for versioning/backup & restoration with built-in Registry support</p></li>
+ <li><p>Support for Error handling and timeouts, recovery with http/s aintainance mode & gracefull shutdown</p></li>
+ <li><p>JMX monitoring support</p></li>
+ <li><p>Many samples and a built-in Axis2 server to try out and experiment with samples (Samples includes WS-Security, JMS POX/Text messages, Script mediation and many more samples which can be run out of the box) </p></li>
+ <li><p>Enhanced documentation</p></li>
+ </ul>
+</section>
+</body>
+</document>
\ No newline at end of file
Propchange: synapse/branches/2.1/src/site/xdoc/1_1_1/content.xml
------------------------------------------------------------------------------
svn:executable = *