You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@synapse.apache.org by ru...@apache.org on 2008/01/28 12:05:55 UTC
svn commit: r615849 [1/11] - in /webservices/synapse/trunk/java/src/site: ./
resources/ resources/css/ resources/download/ xdoc/ xdoc/1_0/ xdoc/1_1/
xdoc/download/ xdoc/download/1.0/ xdoc/download/1.1.1/ xdoc/download/1.1/
Author: ruwan
Date: Mon Jan 28 03:05:41 2008
New Revision: 615849
URL: http://svn.apache.org/viewvc?rev=615849&view=rev
Log:
Automated the site generation for the synapse / added new content to match the new site generation based on xdocs
Added:
webservices/synapse/trunk/java/src/site/xdoc/1_0/
webservices/synapse/trunk/java/src/site/xdoc/1_0/configuration.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_0/content.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_0/extending.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_0/quickstart.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_0/samples.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_0/samples_setup.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_1/
webservices/synapse/trunk/java/src/site/xdoc/1_1/configuration.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_1/content.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_1/extending.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_1/quickstart.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_1/samples.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/1_1/samples_setup.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/Synapse_Configuration_Language.xml (contents, props changed)
- copied, changed from r614421, webservices/synapse/branches/1.1.1/src/site/resources/Synapse_Configuration_Language.html
webservices/synapse/trunk/java/src/site/xdoc/Synapse_Extending.xml (contents, props changed)
- copied, changed from r614421, webservices/synapse/branches/1.1.1/src/site/resources/Synapse_Extending.html
webservices/synapse/trunk/java/src/site/xdoc/Synapse_Samples.xml (contents, props changed)
- copied, changed from r614421, webservices/synapse/branches/1.1.1/src/site/resources/Synapse_Samples.html
webservices/synapse/trunk/java/src/site/xdoc/Synapse_Samples_Setup.xml (contents, props changed)
- copied, changed from r614421, webservices/synapse/branches/1.1.1/src/site/resources/Synapse_Samples_Setup.html
webservices/synapse/trunk/java/src/site/xdoc/docs_index.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/download/
webservices/synapse/trunk/java/src/site/xdoc/download.xml (contents, props changed)
- copied, changed from r614421, webservices/synapse/branches/1.1.1/src/site/resources/download.html
webservices/synapse/trunk/java/src/site/xdoc/download/1.0/
webservices/synapse/trunk/java/src/site/xdoc/download/1.0/download.cgi (with props)
webservices/synapse/trunk/java/src/site/xdoc/download/1.0/download.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/download/1.1/
webservices/synapse/trunk/java/src/site/xdoc/download/1.1.1/
webservices/synapse/trunk/java/src/site/xdoc/download/1.1.1/download.cgi (with props)
webservices/synapse/trunk/java/src/site/xdoc/download/1.1.1/download.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/download/1.1/download.cgi (with props)
webservices/synapse/trunk/java/src/site/xdoc/download/1.1/download.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/download_index.xml (with props)
webservices/synapse/trunk/java/src/site/xdoc/history.xml (with props)
Removed:
webservices/synapse/trunk/java/src/site/resources/Synapse_Configuration_Language.html
webservices/synapse/trunk/java/src/site/resources/Synapse_Extending.html
webservices/synapse/trunk/java/src/site/resources/Synapse_QuickStart.html
webservices/synapse/trunk/java/src/site/resources/Synapse_Samples.html
webservices/synapse/trunk/java/src/site/resources/Synapse_Samples_Setup.html
webservices/synapse/trunk/java/src/site/resources/download/
webservices/synapse/trunk/java/src/site/resources/download.html
webservices/synapse/trunk/java/src/site/xdoc/navigation.xml
Modified:
webservices/synapse/trunk/java/src/site/resources/css/site.css
webservices/synapse/trunk/java/src/site/site.xml
webservices/synapse/trunk/java/src/site/xdoc/index.xml
Modified: webservices/synapse/trunk/java/src/site/resources/css/site.css
URL: http://svn.apache.org/viewvc/webservices/synapse/trunk/java/src/site/resources/css/site.css?rev=615849&r1=615848&r2=615849&view=diff
==============================================================================
--- webservices/synapse/trunk/java/src/site/resources/css/site.css (original)
+++ webservices/synapse/trunk/java/src/site/resources/css/site.css Mon Jan 28 03:05:41 2008
@@ -2,6 +2,7 @@
body{
padding:0px;
margin:0px;
+width:1000px;
}
a{
color:#557f95;
@@ -24,6 +25,7 @@
background-color:#bcbcbc;
text-indent:10px;
margin-left:-15px;
+margin-right:-5px;
margin-top:-5px;
color:#000000;
}
@@ -46,14 +48,14 @@
padding-left:10px;
padding-right:10px;
}
-.page-external{
-/* Uncomment these lines to give a fixed width with centered positioning ....
+.composite{
+/* Uncomment these lines to give a fixed width with centered positioning ....*/
position:absolute;
left:50%;
width:980px;
margin-left:-490px;
border:solid 1px #83b0c0;
-*/
+margin-top:5px;
}
/* header styles */
@@ -171,7 +173,7 @@
background-color:#F3F3F3;
border:1px solid #B4B4B4;
margin-right:10px;
-margin-left:184px;
+margin-left:194px;
margin-top:10px;
padding-left:10px;
}
@@ -217,4 +219,53 @@
color:#929292;
margin-top:10px;
margin-left:10px;
-}
\ No newline at end of file
+}
+.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;
+ }
+.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;
+ }
\ No newline at end of file
Modified: webservices/synapse/trunk/java/src/site/site.xml
URL: http://svn.apache.org/viewvc/webservices/synapse/trunk/java/src/site/site.xml?rev=615849&r1=615848&r2=615849&view=diff
==============================================================================
--- webservices/synapse/trunk/java/src/site/site.xml (original)
+++ webservices/synapse/trunk/java/src/site/site.xml Mon Jan 28 03:05:41 2008
@@ -22,7 +22,7 @@
<bannerLeft>
<name></name>
- <href>ws.apache.org/synapse/</href>
+ <href>synapse.apache.org/</href>
</bannerLeft>
<bannerRight>
@@ -46,19 +46,22 @@
<menu name="Apache Synapse">
<item name="About" href="index.html"/>
- <item name="Downloads">
- <item name="Releases" href="download.cgi"/>
+ <item name="Downloads" href="download_index.html">
+ <item name="Releases" href="download.html"/>
<item name="Source Code" href="source-repository.html"/>
</item>
- <item name="Documentation">
- <item name="Configuration Language" href="Synapse_Configuration_Language.html"/>
+ <item name="Documentation" href="docs_index.html">
<item name="Quick Start Guide" href="Synapse_QuickStart.html"/>
<item name="Samples" href="Synapse_Samples.html"/>
<item name="Extending Synapse" href="Synapse_Extending.html"/>
+ <item name="Configuration Language" href="Synapse_Configuration_Language.html"/>
<item name="Javadocs" href="apidocs/index.html"/>
</item>
- <item name="Project Information">
- <item name="Project Information" href="project-info.html"/>
+ <item name="Previous Version" href="history.html">
+ <item name="Version 1.1" href="1_1/content.html"/>
+ <item name="Version 1_0" href="1_0/content.html"/>
+ </item>
+ <item name="Project Information" href="project-info.html">
<item name="Mailing Lists" href="mail-lists.html"/>
<item name="Issue Tracking" href="issue-tracking.html"/>
<item name="Dependencies" href="dependencies.html"/>
Added: webservices/synapse/trunk/java/src/site/xdoc/1_0/configuration.xml
URL: http://svn.apache.org/viewvc/webservices/synapse/trunk/java/src/site/xdoc/1_0/configuration.xml?rev=615849&view=auto
==============================================================================
--- webservices/synapse/trunk/java/src/site/xdoc/1_0/configuration.xml (added)
+++ webservices/synapse/trunk/java/src/site/xdoc/1_0/configuration.xml Mon Jan 28 03:05:41 2008
@@ -0,0 +1,801 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta content="text/html; charset=iso-8859-1" http-equiv="content-type"/>
+ <title>
+ Synapse Configuration Language
+ </title>
+ <style type="text/css" xml:space="preserve">
+ .command {
+ border: 1px dashed #3c78b5;
+ text-align: left;
+ background-color: #f0f0f0;
+ padding: 3px;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ }
+ .consoleOutput {
+ border: 1px dashed #3c78b5;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ background-color: #f0f0f0;
+ border-bottom: 1px dashed #3c78b5;
+ padding: 3px;
+ border-style: solid;
+ }
+ .info {
+ border-style: solid;
+ border-width: 1px;
+ border-color: #090;
+ background-color: #dfd;
+ text-align:left;
+ margin-top: 5px;
+ margin-bottom: 5px;
+ }
+ li {
+ font-family: Verdana, arial, sans-serif;
+ font-size: 11px;
+ line-height: 16px;
+ color: #000000;
+ font-weight: normal;
+ }
+ p {
+ font-family: Verdana, arial, sans-serif;
+ font-size: 11px;
+ line-height: 16px;
+ color: #000000;
+ font-weight: normal;
+ }
+ pre {
+ padding: 0px;
+ margin-top: 5px;
+ margin-left: 15px;
+ margin-bottom: 5px;
+ margin-right: 5px;
+ text-align: left;
+ background-color: #f0f0f0;
+ padding: 3px;
+ border: 1px dashed #3c78b5;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ }
+ h1 {
+ font-size: 24px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ color: #003366;
+ border-bottom: 1px solid #3c78b5;
+ padding: 2px;
+ margin: 36px 0px 4px 0px;
+ }
+ h2 {
+ font-size: 18px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ border-bottom: 1px solid #3c78b5;
+ padding: 2px;
+ margin: 27px 0px 4px 0px;
+ }
+ h3 {
+ font-size: 14px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ padding: 2px;
+ margin: 21px 0px 4px 0px;
+ }
+ h4 {
+ font-size: 12px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ padding: 2px;
+ margin: 18px 0px 4px 0px;
+ }</style>
+ </head>
+ <body>
+ <h1>
+ Synapse Configuration Language
+ </h1>
+ <p>
+ The Synapse configuration language is designed to support a processing
+ model where messages come into Synapse, are processed via some number of
+ mediators and then delivered to an endpoint somewhere. It is currently
+ direction agnostic, but directionality can easily be added as a selection
+ mechanism for mediators (see below for details).
+ </p>
+ <h3>
+ Overall Structure
+ </h3>
+ <p>
+ A Synapse configuration looks like the following at the top level:
+ </p>
+<pre xml:space="preserve"> <definitions>
+ <<a href="#registry">registry</a> provider="string">...</registry>?
+ <<a href="#localEntry">localEntry</a> key="string">...</localEntry>?
+ <<a href="#sequence">sequence</a> name="string">...</sequence>?
+ <<a href="#endpoint">endpoint</a> name="string">...</endpoint>?
+ <<a href="#proxy">proxy</a> name="string" ...>...</proxy>?
+ <a href="#mediator">mediator</a>*
+ </definitions></pre>
+ <h2>
+ <a name="registry" id="registry">Registry</a>
+ </h2>
+ <p>
+ The <registry> element is used to define the remote registry which
+ are referenced from within the configuration. The registry provider
+ specifies the implementation class for the registry used, and optionally a
+ number of configuration parameters may be specified to configure the
+ registry.
+ </p>
+<pre xml:space="preserve"> <registry provider="string"/>
+ <parameter name="string">text | xml</parameter>*
+ </registry></pre>
+ <p>
+ Registry entries loaded from a remote registry are cached within Synapase
+ as dictated by the registry, and reloaded after the cache periods expires.
+ Hence it is possible to define configuration elements such as (dynamic)
+ sequences and endpoints, as well as resources such as XSLT's or XSDs off
+ the registry, and update the configuration as these change dynamically
+ over time.
+ </p>
+ <p/>
+ <h3>
+ <a name="localEntry" id="localEntry">Local Entry</a>
+ </h3>
+ <p>
+ The <localEntry> element is used to declare registry entries that
+ are local to the Synapse instance, as shown below
+ </p>
+<pre xml:space="preserve"> <localEntry key="string" [src="url"]>text | xml</localEntry></pre>
+ <p>
+ These entries are top level entries which are set globally for the entire
+ system. Values of these entries can be retrieved via the extension XPath
+ function "synapse:get-property(prop-name)".
+ </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). These local entries can overide any existing entries with the
+ same keys of the remote registry.
+ </p>
+ <p/>
+ <h2>
+ <a name="sequence" id="sequence">Sequences</a>
+ </h2>
+ <p>
+ A <sequence> element is used to define a sequence of mediators that
+ can be invoked later by name as a sequence of mediators.
+ </p>
+<pre xml:space="preserve"> <sequence name="string" [onError="string"] [key="string"]>
+ mediator*
+ </sequence></pre>
+ <p>
+ If the configuration defines a sequence named "main" then it is considered
+ as the main mediation sequence of Synapse. If such a sequence is not
+ defined locally, and a registry has been specified, the registry is looked
+ up for a key named "main" to find the main mediator sequence. Synapse also
+ supports the specification of mediators directly within the <definitions>
+ tag, and if any mediators are present, will constitute the main sequence.
+ In the absence of a main sequence, the Synapse runtime will create a
+ default main sequence that consists of an implicit send mediator.
+ </p>
+ <p>
+ Synapse considers a sequence named "fault", or in its absence a registry
+ entry with a key "fault" as its general fault handler sequence. If Synapse
+ encounters an erroneous situation, it executes the defined error handling
+ sequence for the current context - which may be specified as the 'onError'
+ sequence for a sequence mediator. If a fault sequence is not specified or
+ cannot be found through the registry, Synapse will create a defualt fault
+ sequence that will perform a log of the message at the log level 'full'.
+ </p>
+ <p>
+ If an optional error handler sequence name is specified on any sequence
+ through the attribute 'onError', an exception on this sequence will invoke
+ the sequence specified by this key.
+ </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 accordingly.
+ </p>
+ <p/>
+ <h2>
+ <a name="endpoint" id="endpoint">Endpoints</a>
+ </h2>
+ <p>
+ An <endpoint> element defines a destination for an outgoing message.
+ An endpoint may be specified as an address endpoint, WSDL based endpoint,
+ a load balanced endpoint or a fail-over endpoint as follows:
+ </p>
+<pre xml:space="preserve"><endpoint [name="string"] [key="string"]>
+<a href="#address-endpoint">address-endpoint</a> | <a href="#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. Such named endpoints
+ can be reffered by other endpoints, which only contain the key attribute.
+ For example if there is an endpoint named as "foo", following endpoint can
+ be used in any place, where "foo" has to be used.
+ </p>
+<pre xml:space="preserve"><endpoint key="foo"/></pre>
+ <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. 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/>
+ <p>
+ Address endpoints can timeout the responses if they failed to arrive
+ Synapse in predefined time duration. This is done by the timeout elements.
+ duration element inside the timeout element contains duration for the
+ timeout in seconds. action element specifies the action to be performed
+ once a timeout occurs. Allowed actions are discard and fault. If discard
+ is specified, responses arriving after the timeout will be discarded
+ without further processing. If fault is specified as the action, fault
+ sequence applicable for the endpoint will be activated as soon as the
+ timeout occurs and responses will not be processed after that.
+ </p>
+<pre xml:space="preserve"><address uri="endpoint-address" format="soap|soap11|soap12|pox" [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>
+ <h4>
+ <a name="wsdl-endpoint" id="wsdl-endpoint">WSDL Endpoint</a>
+ </h4>
+ <p>
+ WSDL endpoint is an endpoint based on a WSDL document. It can extract the
+ target EPR from a given WSDL. Currently it only supports WSDL 1.1. WSDL
+ document can be specifed either as an uri or as inline with the
+ configuration. uri attribute can be set to specify the WSDL as an uri.
+ WSDL can be specified inline as a child element of the wsdl element.
+ Service and port name containing the target EPR has to be specified in
+ service and port attributes respectively. enableRM, enableSec,
+ enableAddressing, suspendDurationOnFailure and timeout elements are same
+ as in the Address endpoint.
+ </p>
+<pre xml:space="preserve"><wsdl [uri="wsdl-uri"] service="qname" port/endpoint="qname">
+ <wsdl:definition>...</wsdl:definition>?
+ <wsdl20:description>...</wsdl20:description>?
+ <enableRM [policy="key"]/>?
+ <enableSec [policy="key"]/>?
+ <enableAddressing/>?
+ <suspendDurationOnFailure>suspend-duration</suspendDurationOnFailure>?
+ <timeout>
+ <duration>timeout-duration</duration>
+ <action>discard|fault</action>
+ </timeout>?
+</wsdl></pre>
+ <h4>
+ <a name="load-balanced-endpoint" id="load-balanced-endpoint">Load
+ balanced Endpoint</a>
+ </h4>
+ <p>
+ Load balance endpoint distributes the messages (load) arriving at it among
+ the set of listed endpoints by evaluating the load balancing policy and
+ other 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. Default is 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.
+ </p>
+ <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. http sessions are
+ supported currently, which identifies sessions based on http cookies.
+ failover attribute mentioned above is not applicable for session affinity
+ based endpoints and it is always set to false. If it is required to have
+ failover behavior in session affinity based load balance endpoints, list
+ failover endpoints as the target endpoints.
+ </p>
+<pre xml:space="preserve"><session type="http"/>?
+<loadBalance [policy="roundRobin"] [failover="true|false"]>
+ <endpoint .../>+
+</loadBalance></pre>
+ <h4>
+ <a name="fail-over-endpoint" id="fail-over-endpoint">Failover Endpoint</a>
+ </h4>
+ <p>
+ Failover endpoints send messages to the listed endpoints with the
+ following failover behavior. At the start, 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 incative. Thus it sends messages
+ successfully as long as there is at least one active endpoint among the
+ listed endpoints.
+ </p>
+<pre xml:space="preserve"><failover>
+ <endpoint .../>+
+</failover></pre>
+ <h2>
+ <a name="proxy" id="proxy">Proxy service</a>
+ </h2>
+ <p>
+ A <proxy> element is used to define a Synapse Proxy service.
+ </p>
+<pre xml:space="preserve"> <proxy name="string" [transports="(http |https |jms )+|all"]>
+ <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/>? // These two tags will removed after the recognition of the Security and RM can be done by looking at policy
+ <enableRM/>?
+ <policy key="string">...</policy>? // optional service level policies
+ // (e.g. WS-Security and/or WS-RM policies)
+ <parameter name="string"> // optional service parameters
+ string | xml // (e.g. transport.jms.ConnectionFactory)
+ </parameter>
+ </proxy></pre>
+ <p>
+ A proxy service is created and exposed on the specified transports through
+ the underlying Axis2 instance, 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.)
+ The Proxy service could be exposed over all enabled Axis2 transports such
+ as http, https, JMS etc. or on a subset of these. 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. Any supplied policies would apply as service level
+ policies, and any properties could be passed into the proxy services'
+ AxisService instance (e.g. the JMS destination etc). If the proxy service
+ should enable WS-Reliable Messaging or Security, the appropriate modules
+ could be engaged.
+ </p>
+ <p>
+ A Dynamic Proxy may be defined by specifying a proxy with the key as its
+ definition. As the remote registry entry changes, the proxy will
+ dynamically be updated accordingly.
+ </p>
+ <p/>
+ <h2>
+ <a name="mediator" id="mediator">Mediators</a>
+ </h2>
+ <p>
+ A mediator token refers to any of the following tokens:
+ </p>
+<pre xml:space="preserve"><a href="#send">send</a> | <a href="#drop">drop</a> | <a href="#log">log</a> | <a href="#makefault">makefault</a> | <a href="#xslt">transform</a> | <a href="#header">header</a> | <a href="#filter">filter</a> | <a href="#switch">switch</a> | <a href="#class">class</a> | <a href="#validate">validate</a> | <a href="#property">property</a> | <a href="#sequence">sequence ref</a> | <a href="#in">in</a> | <a href="#out">out</a> | <a href="#rmsequence">RMSequence</a></pre>
+ <p>
+ In addition to the above, Synapse will be able to load mediators via the
+ J2SE Service Provider model. Mediator extensions must implement the
+ MediatorFactory interface, similarly to the configuration extensions
+ mentioned previously.
+ </p>
+ <h3>
+ Core Mediators
+ </h3>
+ <h4>
+ <a name="send" id="send">Send</a>
+ </h4>
+ <p>
+ The send token represents a <send> element. The <send> element
+ is used to send messages out of Synapse to some endpoint, and stop further
+ mediation of the message. 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. This allows the reply
+ messages to be correlated to the original messages in a flexible manner.
+ Messages may be correlated by WS-A MessageID, or even simple custom text
+ labels. Also see the property mediator.
+ </p>
+ <p>
+ In the simplest case, the place to send the message to is implicit in the
+ message (via a property of the message itself)- that is indicated by the
+ following:
+ </p>
+<pre xml:space="preserve"> <send/></pre>
+ <p>
+ If the message is to be sent to one or more endpoints, then the following
+ is used:
+ </p>
+<pre xml:space="preserve"> <send>
+ (endpointref | endpoint)+
+ </send></pre>
+ <p>
+ where the endpointref token refers to the following:
+ </p>
+<pre xml:space="preserve"> <endpoint key="name"/></pre>
+ <p>
+ and the endpoint token refers to an anonymous endpoint defined.
+ </p>
+ <p/>
+ <h4>
+ <a name="drop" id="drop">Drop</a>
+ </h4>
+ <p>
+ The drop token refers to a <drop> element which is used to drop a
+ message:
+ </p>
+<pre xml:space="preserve"> <drop/></pre>
+ <p>
+ Once the <drop> mediator executes, further processing of the current
+ message stops.
+ </p>
+ <p/>
+ <h4>
+ <a name="log" id="log">Log</a>
+ </h4>
+ <p>
+ The log token refers to a <log> element which may be used to log
+ messages being mediated:
+ </p>
+<pre xml:space="preserve"> <log [level="string"] [separator="string"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+ </log></pre>
+ <p>
+ The optional level attribute selects a pre-defined subset of properties to
+ be logged.
+ </p>
+ <p>
+ e.g.
+ </p>
+ <ul>
+ <li>
+ simple = To, From, WSAction, SOAPAction, ReplyTo, MessageID and any
+ properties
+ </li>
+ <li>
+ headers = All SOAP header blocks and any properties
+ </li>
+ <li>
+ full = all attributes included in log level 'simple' and the SOAP
+ envelope and any properties
+ </li>
+ <li>
+ custom = Only properties specified to the Log mediator
+ </li>
+ </ul>
+ <p>
+ A separator if defined will be used to seperate the attributes being
+ logged. The default separator is the ',' comma.
+ </p>
+ <p/>
+ <h4>
+ <a name="property" id="property">Property</a>
+ </h4>
+<pre xml:space="preserve"> <property name="string" [action=set|remove] (value="literal" | expression="xpath") [scope=transport|axis2]/></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 which does not
+ specify the action thus set on the message context applies only to the
+ current message and can be later retrieved through the
+ synapse:get-property(prop-name) 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. Using the
+ property element with action specified as "remove" you can remove the
+ message context properties if available.
+ </p>
+ <p>
+ There are some well-defined properties that you can get/set:
+ </p>
+ <ul>
+ <li>
+ RESPONSE - 'true' means the message is a response message
+ </li>
+ <li>
+ ERROR_MESSAGE - this is set to any error message
+ </li>
+ </ul>
+ <p>
+ There are also some Axis2 and module properties that are useful to set
+ (with 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/>
+ <h4>
+ <a name="sequence" id="sequence_">Sequence</a>
+ </h4>
+<pre xml:space="preserve"> <sequence key="name"/></pre>
+ <p>
+ A sequence ref token refers to a <sequence> element which is used to
+ invoke a named sequence of mediators.
+ </p>
+ <p/>
+ <h4>
+ <a name="validate" id="validate">Validate</a>
+ </h4>
+<pre xml:space="preserve"> <validate [source="xpath"]>
+ <property name="validation-feature-id" value="true|false"/>*
+ <schema key="string"/>+
+ <on-fail>
+ mediator+
+ </on-fail>
+ </validate></pre>
+ <p>
+ The <validate> mediator validates the result of the evaluation of
+ the source xpath expression, against the schema specified. If the source
+ attribute is not specified, the validation is performed against the first
+ child of the SOAP body of the current message. If the validation fails,
+ the on-fail sequence of mediators is executed. Properties could be used to
+ turn on/off some of the underlying features of the validator (See
+ http://xerces.apache.org/xerces2-j/features.html)
+ </p>
+ <p/>
+ <h3>
+ Message Transformations
+ </h3>
+ <h4>
+ <a name="makefault" id="makefault">Makefault</a>
+ </h4>
+<pre xml:space="preserve"> <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.
+ </p>
+ <p/>
+ <h4>
+ <a name="xslt" id="xslt">XSLT</a>
+ </h4>
+<pre xml:space="preserve"> <xslt key="string" [source="xpath"]>
+ <property name="string" (value="literal" | expression="xpath")/>*
+ </xslt></pre>
+ <p>
+ The <xslt> mediator applies the specified XSLT transformation to the
+ given element. 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.
+ </p>
+ <p/>
+ <h4>
+ <a name="header" id="header">Header</a>
+ </h4>
+<pre xml:space="preserve"> <header name="qname" (value="literal" | expression="xpath") [action="set"]/>
+ <header name="qname" action="remove"/></pre>
+ <p>
+ The <header> mediator sets or removes a specified header from the
+ current soap message. Currently the set header only supports simple valued
+ headers. In the future we may extend this to have XML structured headers
+ by embedding the XML content within the element itself. The optional
+ action attribute specifies whether the mediator should set or remove the
+ header. If omitted, it defaults to a set-header.
+ </p>
+ <p/>
+ <h3>
+ Selection
+ </h3>
+ <h4>
+ <a name="filter" id="filter">Filter</a>
+ </h4>
+<pre xml:space="preserve"> <filter (source="xpath" regex="string") | xpath="xpath">
+ mediator+
+ </filter></pre>
+ <p>
+ The <filter> mediator either test the given xpath expression as a
+ boolean expression, or match the evaluation result of a source xpath
+ expression against the given regular expression. If the test succeeds, the
+ filter mediator will execute the enclosed mediators in sequence.
+ </p>
+ <p/>
+ <h4>
+ <a name="switch" id="switch">Switch</a>
+ </h4>
+<pre xml:space="preserve"> <switch source="xpath">
+ <case regex="string">
+ mediator+
+ </case>+
+ <default>
+ mediator+
+ </default>?
+ </switch></pre>
+ <p>
+ The <switch> mediator will evaluate the given source xpath
+ expression into its string value, and match it against the given regular
+ expressions. If the specified cases does not match and a default case
+ exists, it will be executed.
+ </p>
+ <a name="in" id="in"/>
+ <h4>
+ <a name="out" id="out">In / Out</a>
+ </h4>
+<pre xml:space="preserve"><in><br/> mediator+
+</in><br/></pre>
+<pre xml:space="preserve"><out>
+ mediator+
+</out></pre>
+ <p>
+ <br/>
+ </p>
+ <p>
+ The In and Out mediators will execute the child mediators over the current
+ message if the message matches the direction of the mediator. Hence all
+ incoming messages would pass through the "<in>" mediators and vice
+ versa.
+ </p>
+ <p/>
+ <h3>
+ WS-Reliable Messaging
+ </h3>
+ <h4>
+ <a name="rmsequence" id="rmsequence">RMSequence</a>
+ </h4>
+<pre xml:space="preserve"> <RMSequence (correlation="xpath" [last-message="xpath"]) | single="true" [version="1.0|1.1"]/></pre>
+ <p>
+ The <RMSequence> mediator can be used to create a sequence of
+ messages to communicate via WS-Reliable Messaging with an WS-RM enabled
+ endpoint (<enableRM>). The simple use case of this mediator is to
+ specify a single="true" property, because this means that only one message
+ is involved in the same sequence. However if multiple messages should be
+ sent in the same sequence, the correlation property should be used with a
+ XPath expression that selects an unique element value from the incoming
+ message. With the result of the XPath expression, Synapse can group
+ messages together that belong to the same sequence. To close the sequence
+ neatly, for the last message of the sequence also an XPath expression
+ should be specified. With the version attribute the WS-RM specification
+ version to be used can be specified, 1.0 or 1.1.
+ </p>
+ <h3>
+ Extension mediator
+ </h3>
+ <h4>
+ <a name="class" id="class">Class Mediator</a>
+ </h4>
+<pre xml:space="preserve"> <class name="class-name">
+ <property name="string" (value="literal" | expression="xpath")/>*
+ </class> </pre>
+ <p>
+ The class mediator creates an instance of the 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.
+ However, Synapse currently supports only String properties.
+ </p>
+ <p/>
+ <h3>
+ Extensibility of Synapse
+ </h3>
+ <p>
+ The Synapse configuration language could be easily extended, with
+ configuration extensions as well as mediation extensions. The Spring
+ mediator is such an example.
+ </p>
+ <h4>
+ Spring Configuration
+ </h4>
+ <p>
+ A Spring configuration could be created as a localEntry or remote registry
+ entry providing a URL or a key reference to a Registry. The configuration
+ is then created on first use or as necessary (as per registry lookup
+ semantics) by the mediators which reference this configuration.
+ </p>
+<pre xml:space="preserve"> <localEntry key="string"/>
+ <localEntry key="string" src="url"/></pre>
+ <p>
+ The name attribute specifies a unique name for the configuration, and the
+ src, key or inlined XML references to the Spring configuration
+ </p>
+ <p/>
+ <h4>
+ Spring mediator
+ </h4>
+<pre xml:space="preserve"> <spring:spring bean="exampleBean1" key="string"/></pre>
+ <p>
+ The <spring> element creates an instance of a mediator, which is
+ managed by Spring. This Spring bean must implement the Mediator interface
+ for it to act as a Mediator. The key will reference the Spring
+ ApplicationContext/Configuration used for the bean
+ </p>
+ <p/>
+ <h3>
+ Scripting language mediators
+ </h3>
+ <p/>
+ <p>
+ Synapse supports Mediators implemented in a variety of scripting languages
+ such as JavaScript, Python or Ruby. There are two ways of defining script
+ mediators, either with the script program statements stored in a separate
+ file which is referenced via the local or remote registry entry, or with
+ the script program statements embedded in-line within the Synapse
+ configuration. A script mediator using a script off the registry (local or
+ remote) is defined as follows:
+ </p>
+<pre xml:space="preserve"> <script key="string" language="string" [function="script-function-name"]/></pre>
+ <p>
+ The property key is the registry key to load the script. The language
+ attribute specifies the scripting language of the script code (e.g. "js"
+ for Javascript, "rb" for ruby, "groovy" for Groovy, "py" for Python..).
+ The function is an optional attribute defining the name of the script
+ function to invoke, if not specified it defaults to a function named
+ 'mediate'. The function is passed a single parameter - which is the
+ Synapse MessageContext. The function may return a boolean, if it does not,
+ then true is assumed, and the script mediator returns this value. An
+ inline script mediator has the script source embedded in the configuration
+ as follows:
+ </p>
+<pre xml:space="preserve"> <script language="string">...script source code...<script/></pre>
+ <p>
+ The execution context environment of the script has access to the Synapse
+ MessageContext predefined in a script variable named 'mc' . An example of
+ an inline mediator using JavaScript/E4X which returns false if the SOAP
+ message body contains an element named 'symbol' which has a value of 'IBM'
+ would be:
+ </p>
+<pre xml:space="preserve"> <script language="js">mc.getPayloadXML()..symbol != "IBM";<script/></pre>
+ <p>
+ Synapse uses the Apache <a href="http://jakarta.apache.org/bsf/">Bean
+ Scripting Framework</a> for the scripting language support, any
+ script language supported by BSF may be used to implement a Synapse
+ Mediator.
+ </p>
+ <p>
+ Implementing a Mediator with a script language can have advantages over
+ using the built in Synapse Mediator types or implementing a custom Java
+ class Mediator. Script Mediators have all the flexibility of a class
+ Mediator with access to the Synapse MessageContext and SynapseEnvironment
+ APIs, and the ease of use and dynamic nature of scripting languages allows
+ rapid development and prototyping of custom mediators. An additional
+ benefit of some scripting languages is that they have very simple and
+ elegant XML manipulation capabilities, for example JavaScript E4X or Ruby
+ REXML, so this makes them well suited for use in the Synapse mediation
+ environment. For both types of script mediator definition the
+ MessageContext passed into the script has additional methods over the
+ standard Synapse MessageContext to enable working with the XML in a way
+ natural to the scripting language. For example when using JavaScript
+ getPayloadXML and setPayloadXML, E4X XML objects, and when using Ruby,
+ REXML documents.
+ </p>
+ <p/>
+ </body>
+</html>
\ No newline at end of file
Propchange: webservices/synapse/trunk/java/src/site/xdoc/1_0/configuration.xml
------------------------------------------------------------------------------
svn:executable = *
Added: webservices/synapse/trunk/java/src/site/xdoc/1_0/content.xml
URL: http://svn.apache.org/viewvc/webservices/synapse/trunk/java/src/site/xdoc/1_0/content.xml?rev=615849&view=auto
==============================================================================
--- webservices/synapse/trunk/java/src/site/xdoc/1_0/content.xml (added)
+++ webservices/synapse/trunk/java/src/site/xdoc/1_0/content.xml Mon Jan 28 03:05:41 2008
@@ -0,0 +1,66 @@
+<?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 - Version 1.0</title>
+ </properties>
+
+<body>
+
+<section name="Apache Synapse - the lightweight ESB">
+ <p>
+ Apache Synapse is 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 useful transports and mediators. We recommend you start by reading the QuickStart and then trying out the samples.
+ </p>
+ <p>For more information, see:</p>
+
+ <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 WS Wiki <a href="http://wiki.apache.org/ws/Synapse">http://wiki.apache.org/ws/Synapse</a></li>
+ </ul>
+</section>
+
+<section name="Status">
+ <p>Synapse graduated from the Apache Incubator on the 2nd of January 2007, and has been
+ officially accepted as a sub-project of the Apache Web Services project</p>
+
+ <p>This release of Synapse is <a href="http://synapse.apache.org/download/1.0/download.cgi">1.0</a>. Its key features are </p>
+
+ <ul>
+ <li><p>Proxy services - facilitating transport, interface (WSDL/Schema/Policy), message format (SOAP/POX), 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/Spring mediators, or BSF Scripting languages (Javascript, Ruby etc)</p></li>
+ <li><p>Load-balancing/Fail-over and Throttling support</p></li>
+ <li><p>WS-Security, WS-Reliable Messaging & Throttling configurable via WS-Policies</p></li>
+ <li><p>JMS message support for binary, plain text and XML and SOAP payloads</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 and restoration</p></li>
+ <li><p>Support for Error handling and timeouts, and recovery</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>
Propchange: webservices/synapse/trunk/java/src/site/xdoc/1_0/content.xml
------------------------------------------------------------------------------
svn:executable = *
Added: webservices/synapse/trunk/java/src/site/xdoc/1_0/extending.xml
URL: http://svn.apache.org/viewvc/webservices/synapse/trunk/java/src/site/xdoc/1_0/extending.xml?rev=615849&view=auto
==============================================================================
--- webservices/synapse/trunk/java/src/site/xdoc/1_0/extending.xml (added)
+++ webservices/synapse/trunk/java/src/site/xdoc/1_0/extending.xml Mon Jan 28 03:05:41 2008
@@ -0,0 +1,482 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<!DOCTYPE html
+ PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" >
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta content="text/html; charset=iso-8859-1" http-equiv="content-type"/>
+ <title>
+ Extending Synapse
+ </title>
+ <style type="text/css" xml:space="preserve">
+ .command {
+ border: 1px dashed #3c78b5;
+ text-align: left;
+ background-color: #f0f0f0;
+ padding: 3px;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ }
+ .consoleOutput {
+ border: 1px dashed #3c78b5;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ background-color: #f0f0f0;
+ border-bottom: 1px dashed #3c78b5;
+ padding: 3px;
+ border-style: solid;
+ }
+ .info {
+ border-style: solid;
+ border-width: 1px;
+ border-color: #090;
+ background-color: #dfd;
+ text-align:left;
+ margin-top: 5px;
+ margin-bottom: 5px;
+ }
+ li {
+ font-family: Verdana, arial, sans-serif;
+ font-size: 11px;
+ line-height: 16px;
+ color: #000000;
+ font-weight: normal;
+ }
+ p {
+ font-family: Verdana, arial, sans-serif;
+ font-size: 11px;
+ line-height: 16px;
+ color: #000000;
+ font-weight: normal;
+ }
+ pre {
+ padding: 0px;
+ margin-top: 5px;
+ margin-left: 15px;
+ margin-bottom: 5px;
+ margin-right: 5px;
+ text-align: left;
+ background-color: #f0f0f0;
+ padding: 3px;
+ border: 1px dashed #3c78b5;
+ font-size: 11px;
+ font-family: Courier;
+ margin: 10px;
+ line-height: 13px;
+ }
+ h1 {
+ font-size: 24px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ color: #003366;
+ border-bottom: 1px solid #3c78b5;
+ padding: 2px;
+ margin: 36px 0px 4px 0px;
+ }
+ h2 {
+ font-size: 18px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ border-bottom: 1px solid #3c78b5;
+ padding: 2px;
+ margin: 27px 0px 4px 0px;
+ }
+ h3 {
+ font-size: 14px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ padding: 2px;
+ margin: 21px 0px 4px 0px;
+ }
+ h4 {
+ font-size: 12px;
+ line-height: normal;
+ font-weight: bold;
+ background-color: #f0f0f0;
+ padding: 2px;
+ margin: 18px 0px 4px 0px;
+ }</style>
+ </head>
+ <body>
+ <h1>
+ Extending Synapse<br/>
+ </h1>
+ <h2>
+ Writing custom Mediator implementations
+ </h2>
+ <p>
+ The primary interface of the Synapse API is the MessageContext interface
+ defined below. This essentially defines the per-message context passed
+ through the chain of mediators, for each and every message received and
+ processed by Synapse. Each message instance is wrapped within a
+ MessageContext instance, and the message context is set with the
+ references to the SynapseConfiguration and SynapseEnvironments. The
+ SynapseConfiguration holds the global configuration model that defines
+ mediation rules, local registry entries and other and configuration, while
+ the environment gives access to the underlying SOAP implementation used -
+ Axis2. A typical mediator would need to manipulate the MessageContext by
+ referring to the SynapseConfiguration. However it is strongly recommended
+ that the SynapseConfiguration is not updated by mediator instances as it
+ is shared by all messages, and may be updated by Synapse administration or
+ configuration modules. Mediator instances may store local message
+ properties into the MessageContext for later retrieval by successive
+ mediators.<br/>
+ </p>
+ <h4>
+ <a
+ href="http://svn.apache.org/viewvc/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/MessageContext.java?view=markup">MessageContext
+ Interface</a>
+ </h4>
+ <p/>
+<pre xml:space="preserve">package org.apache.synapse;
+
+import ...
+
+public interface MessageContext {
+
+ /**
+ * Get a reference to the current SynapseConfiguration
+ *
+ * @return the current synapse configuration
+ */
+ public SynapseConfiguration getConfiguration();
+
+ /**
+ * Set or replace the Synapse Configuration instance to be used. May be used to
+ * programatically change the configuration at runtime etc.
+ *
+ * @param cfg The new synapse configuration instance
+ */
+ public void setConfiguration(SynapseConfiguration cfg);
+
+ /**
+ * Returns a reference to the host Synapse Environment
+ * @return the Synapse Environment
+ */
+ public SynapseEnvironment getEnvironment();
+
+ /**
+ * Sets the SynapseEnvironment reference to this context
+ * @param se the reference to the Synapse Environment
+ */
+ public void setEnvironment(SynapseEnvironment se);
+
+ /**
+ * Get the value of a custom (local) property set on the message instance
+ * @param key key to look up property
+ * @return value for the given key
+ */
+ public Object getProperty(String key);
+
+ /**
+ * Set a custom (local) property with the given name on the message instance
+ * @param key key to be used
+ * @param value value to be saved
+ */
+ public void setProperty(String key, Object value);
+
+ /**
+ * Returns the Set of keys over the properties on this message context
+ * @return a Set of keys over message properties
+ */
+ public Set getPropertyKeySet();
+
+ /**
+ * Get the SOAP envelope of this message
+ * @return the SOAP envelope of the message
+ */
+ public SOAPEnvelope getEnvelope();
+
+ /**
+ * Sets the given envelope as the current SOAPEnvelope for this message
+ * @param envelope the envelope to be set
+ * @throws org.apache.axis2.AxisFault on exception
+ */
+ public void setEnvelope(SOAPEnvelope envelope) throws AxisFault;
+
+ /**
+ * SOAP message related getters and setters
+ */
+ public ....get/set()...
+
+}</pre>
+ <p>
+ The MessageContext interface is based on the Axis2 <a>MessageContext</a>
+ interface, and uses the Axis2 <a>EndpointReference</a> and
+ SOAPEnvelope classes/interfaces. The purpose of this interface is to
+ capture a message as it flows through the system. As you will see the
+ message payload is represented using the SOAP infoset. Binary messages can
+ be embedded in the Envelope using MTOM or SwA attachments using the AXIOM
+ object model.
+ </p>
+ <h4>
+ <a
+ href="http://svn.apache.org/viewvc/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/Mediator.java?view=markup">Mediator
+ interface</a>
+ </h4>
+ <p>
+ The second key interface for mediator writers is the Mediator interface:
+ </p>
+<pre xml:space="preserve">package org.apache.synapse;
+
+import org.apache.synapse.MessageContext;
+
+/**
+ * All Synapse mediators must implement this Mediator interface. As a message passes
+ * through the synapse system, each mediator's mediate() method is invoked in the
+ * sequence/order defined in the SynapseConfiguration.
+ */
+public interface <span style="font-weight: bold;">Mediator </span>{
+
+ /**
+ * Invokes the mediator passing the current message for mediation. Each
+ * mediator performs its mediation action, and returns true if mediation
+ * should continue, or false if further mediation should be aborted.
+ *
+ * @param synCtx the current message for mediation
+ * @return true if further mediation should continue
+ */
+ public boolean mediate(MessageContext synCtx);
+
+ /**
+ * This is used for debugging purposes and exposes the type of the current
+ * mediator for logging and debugging purposes
+ * @return a String representation of the mediator type
+ */
+ public String getType();
+}</pre>
+ <p>
+ A mediator can read and/or modify the <a>SynapseMessage</a> in
+ any suitable manner - adjusting the routing headers or changing the
+ message body. If the mediate() method returns false, it signals to the
+ Synapse processing model to stop further processing of the message. For
+ example, if the mediator is a security agent it may decide that this
+ message is dangerous and should not be processed further. This is
+ generally the exception as mediators are usually designed to co-operate to
+ process the message onwards.
+ </p>
+ <h3>
+ Leaf and Node Mediators, List mediators and Filter mediators
+ </h3>
+ <p>
+ Mediators may be Node mediators (i.e. these that can contain child
+ mediators) or Leaf mediators (mediators that does not hold any other child
+ mediators). A Node mediator must implement the
+ org.apache.synapse.api.ListMediator interface listed below, or extend from
+ the org.apache.synapse.mediators.AbstractListMediator.
+ </p>
+ <h4>
+ <a
+ href="http://svn.apache.org/viewvc/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/ListMediator.java?view=markup">The
+ ListMediator interface</a>
+ </h4>
+<pre xml:space="preserve">package org.apache.synapse.mediators;
+
+import java.util.List;
+
+/**
+* The List mediator executes a given sequence/list of child mediators
+*/
+public interface ListMediator extends Mediator {
+ /**
+ * Appends the specified mediator to the end of this mediator's (children) list
+ * @param m the mediator to be added
+ * @return true (as per the general contract of the Collection.add method)
+ */
+ public boolean addChild(Mediator m);
+
+ /**
+ * Appends all of the mediators in the specified collection to the end of this mediator's (children)
+ * list, in the order that they are returned by the specified collection's iterator
+ * @param c the list of mediators to be added
+ * @return true if this list changed as a result of the call
+ */
+ public boolean addAll(List c);
+
+ /**
+ * Returns the mediator at the specified position
+ * @param pos index of mediator to return
+ * @return the mediator at the specified position in this list
+ */
+ public Mediator getChild(int pos);
+
+ /**
+ * Removes the first occurrence in this list of the specified mediator
+ * @param m mediator to be removed from this list, if present
+ * @return true if this list contained the specified mediator
+ */
+ public boolean removeChild(Mediator m);
+
+ /**
+ * Removes the mediator at the specified position in this list
+ * @param pos the index of the mediator to remove
+ * @return the mediator previously at the specified position
+ */
+ public Mediator removeChild(int pos);
+
+ /**
+ * Return the list of mediators of this List mediator instance
+ * @return the child/sub mediator list
+ */
+ public List getList();
+}</pre>
+ <p>
+ A ListMediator implementation should call super.mediate(synCtx) to process
+ its sub mediator sequence. A FilterMediator is a ListMediator which
+ executes its sequence of sub mediators on successful outcome of a test
+ condition. The Mediator instance which performs filtering should implement
+ the FilterMediator interface.
+ </p>
+ <h4>
+ <a
+ href="http://svn.apache.org/viewvc/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/mediators/FilterMediator.java?view=markup">FilterMediator
+ interface</a>
+ </h4>
+<pre xml:space="preserve">package org.apache.synapse.mediators;
+
+import org.apache.synapse.MessageContext;
+
+/**
+ * The filter mediator is a list mediator, which executes the given (sub) list of mediators
+ * if the specified condition is satisfied
+ *
+ * @see FilterMediator#test(org.apache.synapse.MessageContext)
+ */
+public interface <span style="font-weight: bold;">FilterMediator </span>extends ListMediator {
+
+ /**
+ * Should return true if the sub/child mediators should execute. i.e. if the filter
+ * condition is satisfied
+ * @param synCtx
+ * @return true if the configured filter condition evaluates to true
+ */
+ public boolean test(MessageContext synCtx);
+}</pre>
+ <h2>
+ Writing custom Configuration implementations for mediators
+ </h2>
+ <p>
+ You may write your own custom configurator for the Mediator implementation
+ you write without relying on the Class mediator or Spring extension for
+ its initialization. You could thus write a MediatorFactory implementation
+ which defines how to digest a custom XML configuration element to be used
+ to create and configure the custom mediator instance. A MediatorSerializer
+ implementation defines how a configuration should be serialized back into
+ an XML configuration. The custom MediatorFactory & MediatorSerializer
+ implementations and the mediator class/es must be bundled in a JAR file
+ conforming to the J2SE Service Provider model (See the description for
+ Extensions below for more details and examples) and placed into the
+ SYNAPSE_HOME/lib folder, so that the Synapse runtime could find and load
+ the definition. Essentially this means that a custom JAR file must bundle
+ your class implementing the Mediator interface, and the MediatorFactory
+ implementation class and contain two text files named
+ "org.apache.synapse.config.xml.MediatorFactory" and
+ "org.apache.synapse.config.xml.MediatorSerializer" which will contain the
+ fully qualified name(s) of your MediatorFactory and MediatorSerializer
+ implementation classes. You should also place any dependency JARs into the
+ same lib folder so that the correct classpath references could be made.
+ The MediatorFactory interface listing is given below, which you should
+ implement, and its getTagQName() method must define the fully qualified
+ element of interest for custom configuration. The Synapse initialization
+ will call back to this MediatorFactory instance through the
+ createMediator(OMElement elem) method passing in this XML element, so that
+ an instance of the mediator could be created utilizing the custom XML
+ specification and returned. See the ValidateMediator and the
+ ValidateMediatorFactory classes under modules/extensions in the Synapse
+ source distribution for examples.
+ </p>
+ <h4>
+ <a
+ href="http://svn.apache.org/viewvc/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorFactory.java?view=markup">The
+ MediatorFactory interface</a>
+ </h4>
+<pre xml:space="preserve">package org.apache.synapse.config.xml;
+
+import ...
+
+/**
+ * A mediator factory capable of creating an instance of a mediator through a given
+ * XML should implement this interface
+ */
+public interface MediatorFactory {
+ /**
+ * Creates an instance of the mediator using the OMElement
+ * @param elem
+ * @return the created mediator
+ */
+ public Mediator createMediator(OMElement elem);
+
+ /**
+ * The QName of this mediator element in the XML config
+ * @return QName of the mediator element
+ */
+ public QName getTagQName();
+}</pre>
+ <p/>
+ <h4>
+ <a
+ href="http://svn.apache.org/viewvc/webservices/synapse/trunk/java/modules/core/src/main/java/org/apache/synapse/config/xml/MediatorSerializer.java?view=markup">The
+ MediatorSerializer interface</a>
+ </h4>
+<pre xml:space="preserve">package org.apache.synapse.config.xml;
+
+import ...
+
+/**
+ * Interface which should be implemented by mediator serializers. Does the
+ * reverse of the MediatorFactory
+ */
+public interface MediatorSerializer {
+
+ /**
+ * Return the XML representation of this mediator
+ * @param m mediator to be serialized
+ * @param parent the OMElement to which the serialization should be attached
+ * @return the serialized mediator XML
+ */
+ public OMElement serializeMediator(OMElement parent, Mediator m);
+
+ /**
+ * Return the class name of the mediator which can be serialized
+ * @return the class name
+ */
+ public String getMediatorClassName();
+}</pre>
+ <h2>
+ Configuring mediators
+ </h2>
+ <p>
+ Mediators could access the Synapse registry to load resources and
+ configure the local behaviour. Refer to the Spring mediator and Script
+ mediator implementations for examples on how this could be achieved.
+ </p>
+ <h4>
+ Loading of Extensions by the Synapse runtime
+ </h4>
+ <p>
+ Synapse loads available extensions from the runtime classpath using the <a
+ href="http://java.sun.com/j2se/1.3/docs/guide/jar/jar.html#Service%20Provider">J2SE
+ Service Provider model</a>. This essentially iterates over the
+ available JAR files, for a META-INF/services directory within each file,
+ and looks for a text file with the name
+ org.apache.synapse.config.xml.MediatorFactory which contains a list of
+ fully qualified classname that implement the above interface, listing each
+ class in a separate line. e.g. The built-in synapse-extensions.jar
+ contains the following structure
+ </p>
+<pre xml:space="preserve">synapse-extensions.jar
+ /META-INF/services
+ org.apache.synapse.config.xml.MediatorFactory
+ org.apache.synapse.config.xml.MediatorSerializer
+ /... the implementation classes as usual...</pre>
+ </body>
+</html>
\ No newline at end of file
Propchange: webservices/synapse/trunk/java/src/site/xdoc/1_0/extending.xml
------------------------------------------------------------------------------
svn:executable = *
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@synapse.apache.org
For additional commands, e-mail: dev-help@synapse.apache.org