Author: asankha Date: Fri Jun 8 05:23:07 2007 New Revision: 545490 URL: http://svn.apache.org/viewvc?view=rev&rev=545490 Log: update site for 1.0 - part 1 Removed: webservices/synapse/site/Synapse_Userguide.html webservices/synapse/site/apidocs/ webservices/synapse/site/sample_103_1.txt webservices/synapse/site/sample_103_2.txt Modified: webservices/synapse/site/Synapse_Configuration_Language.html webservices/synapse/site/Synapse_Extending.html webservices/synapse/site/Synapse_Samples.html webservices/synapse/site/css/maven-base.css webservices/synapse/site/css/maven-theme.css webservices/synapse/site/css/print.css webservices/synapse/site/dependencies.html webservices/synapse/site/dependency-convergence.html webservices/synapse/site/download.html webservices/synapse/site/download/0.90/download.html webservices/synapse/site/download/0.91/download.html webservices/synapse/site/images/expanded.gif webservices/synapse/site/images/logos/maven-feather.png webservices/synapse/site/index.html webservices/synapse/site/integration.html webservices/synapse/site/issue-tracking.html webservices/synapse/site/license.html webservices/synapse/site/mail-lists.html webservices/synapse/site/navigation.html webservices/synapse/site/project-info.html webservices/synapse/site/project-reports.html webservices/synapse/site/project-summary.html webservices/synapse/site/source-repository.html webservices/synapse/site/team-list.html Modified: webservices/synapse/site/Synapse_Configuration_Language.html URL: http://svn.apache.org/viewvc/webservices/synapse/site/Synapse_Configuration_Language.html?view=diff&rev=545490&r1=545489&r2=545490 ============================================================================== --- webservices/synapse/site/Synapse_Configuration_Language.html (original) +++ webservices/synapse/site/Synapse_Configuration_Language.html Fri Jun 8 05:23:07 2007 @@ -1,506 +1,715 @@ - - - - - - Synapse Configuration Language - - - -

Synapse Configuration Language

- -

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).

- -

Overall Structure

- -

A Synapse configuration looks like the following at the top level:

-
 <synapse>
-   registrydef
-   <definitions>
-     (sequencedef | endpointdef | literalpropertydef)+
-   <definitions>?
-   <proxies>
-     proxyservice+
-   </proxies>?
-   <rules [key="string"]>
-     mediator*
-   </rules>
- </synapse>
- -

Registries

- -

A registrydef token represents a <registry> element which is used to -define a Registry which is referenced within the configuration.

-
 <registry [name="string"] provider="string"/>
-   <property name="string" value="string"/>*
- </registry>
- -

The registry definition without a name becomes the 'default' registry -instance for the Synapse instance, and any reference to a registry which does -not specify a registry name defaults to this instance. Optionally, a number -of configuration properties may be specified to configure an instance of a -registry.

- -

Definitions

- -

The <definitions> section defines reusable elements that can be used -from within the rules, and the <rules> section contains the sequence of -mediators that every message passes through during mediation.

- -

Properties

- -

The token literalpropertydef refers to a <set-property> element as -follows:

-
  <set-property name="string" [value="string"] [src="url"] [key="string"]>
-        <inline-xml/>?
-  <set-property/>
- -

These properties are top level properties which are set globally for the -entire system. Values of these properties can be retrieved via the extension -XPath function called "synapse:get-property(prop-name)".

- -

A property can be static literal text (specified with the value attribute) -or static XML specified as an inline XML fragment or specified as a URL -(using the src attribute). A property can alternatively be a DynamicProperty -which will reference a key on a Registry. If a property is a DynamicProperty, -it will be fetched from the Registry and cached locally as per meta -information provided by the Registry for caching. DynamicProperties are -automatically refreshed when expired, and thus can be used to specify dynamic -behaviour in Synapse.

- -

Dynamic properties allows the creation of Dynamic Sequences, Endpoints and -Proxies whose definition would change accordingly with any changes on the -property.

- -

Sequences

- -

A sequencedef token represents a <sequence> element which is used to -define a named sequence of mediators that can be invoked later by name as a -sequence of mediators.

-
 <sequence name="string" [onError="string"] [key="string"]>
-   mediator*
- </sequence>
- -

If an optional error handler sequence name is specified through the -attribute 'onError', an exception on this sequence will invoke the sequence -specified by this name.

- -

A Dynamic Sequence may be defined by specifying a Dynamic Property as its -definition. As the dynamic property changes, the sequence will dynamically be -updated accordingly.

- -

Endpoints

- -

An endpointdef token represents an <endpoint> element which is used -to give a logical name to an endpoint address. If the address is not just a -simple URL, then extensibility elements may be used to indicate the address -(i.e. to compute the address at runtime).

-
 <endpoint name="string" [address="url"] [key="string"]>
-   <enableRM/>?
-   <enableSec [policy="key"]/>?
-   <enableAddressing/>?
-   .. extensibility ..
- </endpoint>
- -

An Axis2 Parameter element within an endpoint definition with the name " -OutflowSecurity" describes the Apache Rampart security configuration to be -used for messages flowing to this endpoint. Please see Rampart/Axis2 -documentation for more details.

- -

A Policy element within an endpoint definition with an Id of "RMPolicy" -describes the Apache Sandesha2 RM configuration (or any overrides against the -default) to be used for messages flowing to this endpoint. Please see -Sandesha2/Axis2 documentation for more details.

- -

The enableRM/enableSec options turns on WS-Security or WS-RM on outgoing -messages to this endpoint.

- -

A Dynamic Endpoint may be defined by specifying a Dynamic Property as its -definition. As the dynamic property changes, the endpoint will dynamically be -updated accordingly.

- -

NOTE: The Rampart and/or Sandesha configuration options may change with -Axis2 changes currently in progress

- -

- -

Proxy services

- -

The <proxies> section defines Synapse Proxy services, which are real -Axis2 services hosted on Synapse, which allows WSDL mediation as well as the -ability to expose existing services on Synapse, with possibly different -semantics, such as WS-Security, WS-RM and Transport switching etc.

- -

A proxyservice token represents a <proxy> element which is used to -define a Synapse Proxy service.

-
 <proxy name="string" [description="string"] [transports="(http |https |jms )+|all"]>
-   <target (inSequence="name" outSequence="name") | endpoint="name"/>? // defaults to the synapse main sequence
-   <wsdl key="string">?
-   <enableRM/>?
-   <enableSec/>?
-   <policy key="string">*                       // optional service level policies
-                                                // (e.g. WS-Security and/or WS-RM policies)
-   <property name="string" value="string"/>*    // optional service parameters 
-                                                // (e.g. transport.jms.ConnectionFactory)
- </proxy>
- -

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. If a -target is not supplied, the default Synapse rules will apply for incoming -message mediation. 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.

- -

A Dynamic Proxy may be defined by specifying a Dynamic Property as its -definition. As the dynamic property changes, the proxy will dynamically be -updated accordingly.

- -

- -

Mediators

- -

A mediator token refers to any of the following tokens:

-
 send | drop | log | makefault | transform | header | filter | 
- switch | class | validate | setproperty | sequenceref | in | out | rm | try
- -

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.

- -

Send

- -

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 correlation -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 set-property mediator.

- -

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:

-
 <send/>
- -

If the message is to be sent to one or more endpoints, then the following -is used:

-
 <send>
-   (endpointref | endpoint)+
- </send>
- -

where the endpointref token refers to the following:

-
 <endpoint ref="name"/>
- -

and the endpoint token refers to an anonymous endpoint defined inline:

-
 <endpoint address="url"/>
- -

If the message is to be sent to an endpoint selected by load balancing -across a set of endpoints, then it is indicated by the following:

-
 <send>
-   <load-balance algorithm="uri">
-     (endpointref | endpoint)+
-   </load-balance>
- </send>
- -

Similarly, if the message is to be sent to an endpoint with failover -semantics, then it is indicated by the following:

-
 <send>
-   <failover>
-     (endpointref | endpoint)+
-   </failover>
- </send>
- -

Once the <send> mediator executes, further processing of the current -message stops.

- -

Note: Synapse does not yet support the load balancing or failover -semantics, and supports only a single endpoint reference.

- -

Drop

- -

The drop token refers to a <drop> element which is used to drop a -message:

-
 <drop/>
- -

Once the <drop> mediator executes, further processing of the current -message stops.

- -

Log

- -

The log token refers to a <log> element which may be used to log -messages being mediated:

-
 <log [level="string"] [separator="string"]>
-   <property name="string" (value="literal" | expression="xpath")/>*
- </log>
- -

The optional level attribute selects a pre-defined subset of properties to -be logged.

- -

e.g.

- - -

A separator if defined will be used to seperate the attributes being -logged. The default separator is the ',' comma.

- -

Transforms

- -
Faults
-
 <makefault [version="soap11|soap12"]>
-   <code (value="literal" | expression="xpath")/>
-   <reason (value="literal" | expression="xpath")>
-   <node>?
-   <role>?
-   <detail>?
- </makefault>
- -

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, else it is set it to the "replyTo" of the original -message.

- -
XSLT
-
 <xslt key="string" [source="xpath"]>
-   <property name="string" (value="literal" | expression="xpath")/>*
- </transform>
- -

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.

- -
Headers
-
 <header name="qname" (value="literal" | expression="xpath") [action="set"]/>
- <header name="qname" action="remove"/>
- -

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.

- -

Selection

- -
Filters
-
 <filter (source="xpath" regex="string") | xpath="xpath">
-   mediator+
- </filter>
- -

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.

- -
Switch
-
 <switch source="xpath">
-   <case regex="string">
-     mediator+
-   </case>+
-   <default>
-     mediator+
-   </default>?
- </switch>
- -

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.

- -

Validation

-
 <validate [source="xpath"]>
-   <schema key="string"/>+
-   <on-fail>
-     mediator+
-   </on-fail>
- </validate>
- -

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.

- -

Note: As the validation mediator is strongly dependent on the Xerces2-J -2.8.0 parser, it is bundled with the Synapse extensions, so that the Synapse -core will remain simple and lightweight.

- -

Properties

-
 <set-property name="string" (value="literal" | expression="xpath") [scope=correlate|axis2]/>
- -

The setproperty token refers to a <set-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 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 correlation property -or an (underlying) Axis2 message context property.

- -

Try

-
 <try>
-   <sequence>
-     mediator+
-   </sequence>
-   <onError>
-     mediator+
-   </onError>
-   <finally>
-     mediator+
-   </finally>
-  </try>
- -

The try token refers to a <try> element which is a mediator that has -a set of child mediators. If an exception is encountered during the execution -of these child mediators, the list of mediators specified as the 'onError' -sequence is executed. The 'finally' list of mediators is then executed -irrespective of whether an exception was encountered or not.

- -

Class Mediators

-
 <class name="class-name">
-   <property name="string" (value="literal" | expression="xpath")/>*
- </class> 
- -

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 will only support String -properties.

- -

Reusing Sequences

-
 <sequence ref="name"/>
- -

A sequenceref token refers to a <sequence> element which is used to -invoke a named sequence of mediators.

- -

- -

Extensibility of Synapse

- -

The Synapse configuration language could be easily extended, with -configuration extensions as well as mediation extensions. The Spring mediator -is such an example.

- -

Spring Configuration

- -

A Spring configuration could be created as a property or DynamicProperty -providing a URL or a reference to a Registry. The configuration is then -created on first use or as necessary (as per DynamicProperty semantics) by -the mediators which reference this configuration.

-
 <set-property name="string" key="string"/>
- <set-property name="string" src="url"/>
- -

The name attribute specifies a unique name for the configuration, and the -src, key or inlined XML references to the Spring configuration

- -

Spring mediator

-
 <spring:spring bean="exampleBean1" key="string"/>
- -

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

- -

Script Language Mediators

- -

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 a -Synapse property, or with the script program statements embedded in-line -within the Synapse configuration.

- -

A script mediator using a registry property is defined as follows:

- -

-
 <script key="property-key" [function="script-function-name"]/>
- -

The property-key is a Synapse registry property containing a URL to the -script source. The function is an optional attribute defining the name of the -script function to call, 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. The language the script is written in is determined from the file -name suffix of the property key value.

- -

An inline script mediator has the script source embedded in the config -XML:

-
 <script.LL>...script source code...<script.LL/>
- -

where LL is the script language name extension. For example, script.js -indicates a JavaScript program, script.rb a Ruby program, or script.py a -Python program. The environment of the script has 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:

- -

-
 <script.js>mc.getPayloadXML()..symbol != "IBM";<script.js/>
- -

The boolean response from the inlined mediator is either the response from -the evaluation of the script statements or if that result is not a boolean -then a response of true is assumed.

- -

Synapse uses the Apache Bean -Scripting Framework for the script language support, any script language -supported by BSF may be used to implement a Synapse Mediator.

- -

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 in -to 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 get/setPayloadXML use E4X XML objects, when -using Ruby they use REXML documents.

- -

- - + + + + + + Synapse Configuration Language + + + + +

Synapse Configuration Language

+ +

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).

+ +

Overall Structure

+ +

A Synapse configuration looks like the following at the top level:

+
 <definitions>
+   <registry provider="string">...</registry>?
+   <localEntry key="string">...</localEntry>?
+   <sequence name="string">...</sequence>?
+   <endpoint name="string">...</endpoint>?
+   <proxy name="string" ...>...</proxy>?
+   mediator*
+ </definitions>
+ +

Registry

+ +

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.

+
 <registry provider="string"/>
+   <parameter name="string">text | xml</parameter>*
+ </registry>
+ +

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.

+ +

+ +

Local Entry

+ +

The <localEntry> element is used to declare registry entries that +are local to the Synapse instance, as shown below

+
  <localEntry key="string" [src="url"]>text | xml</localEntry>
+ +

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)".

+ +

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.

+ +

+ +

Sequences

+ +

A <sequence> element is used to define a sequence of mediators that +can be invoked later by name as a sequence of mediators.

+
 <sequence name="string" [onError="string"] [key="string"]>
+   mediator*
+ </sequence>
+ +

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.

+ +

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'.

+ +

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.

+ +

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.

+ +

+ +

Endpoints

+ +

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:

+
<endpoint [name="string"] [key="string"]>
+address-endpoint | wsdl-endpoint | load-balanced-endpoint | fail-over-endpoint </endpoint> 
+ +

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.

+
<endpoint key="foo"/>
+ +

Address Endpoint

+ +

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.

+ +

+ +

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.

+
<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>
+ +

WSDL Endpoint

+ +

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.

+
<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>
+ +

Load balanced Endpoint

+ +

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.

+ +

+ +

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.

+
<session type="http"/>?
+<loadBalance [policy="roundRobin"] [failover="true|false"]>
+  <endpoint .../>+
+</loadBalance>
+ +

Failover Endpoint

+ +

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.

+
<failover>
+  <endpoint .../>+
+</failover>
+ +

Proxy service

+ +

A <proxy> element is used to define a Synapse Proxy service.

+
 <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>
+ +

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.

+ +

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.

+ +

+ +

Mediators

+ +

A mediator token refers to any of the following tokens:

+
send | drop | log | makefault | transform | header | filter | switch | class | validate | property | sequence ref | in | out | RMSequence
+ +

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.

+ +

Core Mediators

+ +

Send

+ +

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.

+ +

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:

+
 <send/>
+ +

If the message is to be sent to one or more endpoints, then the following +is used:

+
 <send>
+   (endpointref | endpoint)+
+ </send>
+ +

where the endpointref token refers to the following:

+
 <endpoint key="name"/>
+ +

and the endpoint token refers to an anonymous endpoint defined.

+ +

+ +

Drop

+ +

The drop token refers to a <drop> element which is used to drop a +message:

+
 <drop/>
+ +

Once the <drop> mediator executes, further processing of the current +message stops.

+ +

+ +

Log

+ +

The log token refers to a <log> element which may be used to log +messages being mediated:

+
 <log [level="string"] [separator="string"]>
+   <property name="string" (value="literal" | expression="xpath")/>*
+ </log>
+ +

The optional level attribute selects a pre-defined subset of properties to +be logged.

+ +

e.g.

+ + +

A separator if defined will be used to seperate the attributes being +logged. The default separator is the ',' comma.

+ +

+ +

Property

+
 <property name="string" [action=set|remove] (value="literal" | expression="xpath") [scope=transport|axis2]/>
+ +

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.

+ +

There are some well-defined properties that you can get/set:

+ + +

There are also some Axis2 and module properties that are useful to set +(with scope="axis2"):

+ + +

+ +

Sequence

+
 <sequence key="name"/>
+ +

A sequence ref token refers to a <sequence> element which is used to +invoke a named sequence of mediators.

+ +

+ +

Validate

+
 <validate [source="xpath"]>
+   <property name="validation-feature-id" value="true|false"/>*
+   <schema key="string"/>+
+   <on-fail>
+     mediator+
+   </on-fail>
+ </validate>
+ +

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)

+ +

+ +

Message Transformations

+ +

Makefault

+
 <makefault [version="soap11|soap12"]>
+   <code (value="literal" | expression="xpath")/>
+   <reason (value="literal" | expression="xpath")>
+   <node>?
+   <role>?
+   <detail>?
+ </makefault>
+ +

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.

+ +

+ +

XSLT

+
 <xslt key="string" [source="xpath"]>
+   <property name="string" (value="literal" | expression="xpath")/>*
+ </xslt>
+ +

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.

+ +

+ +

Header

+
 <header name="qname" (value="literal" | expression="xpath") [action="set"]/>
+ <header name="qname" action="remove"/>
+ +

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.

+ +

+ +

Selection

+ +

Filter

+
 <filter (source="xpath" regex="string") | xpath="xpath">
+   mediator+
+ </filter>
+ +

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.

+ +

+ +

Switch

+
 <switch source="xpath">
+   <case regex="string">
+     mediator+
+   </case>+
+   <default>
+     mediator+
+   </default>?
+ </switch>
+ +

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.

+ + +

In / Out

+
<in>
mediator+ +</in>
+
<out>
+  mediator+
+</out>
+ +


+

+ +

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.

+ +

+ +

WS-Reliable Messaging

+ +

RMSequence

+
 <RMSequence (correlation="xpath" [last-message="xpath"]) | single="true" [version="1.0|1.1"]/>
+ +

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.

+ +

Extension mediator

+ +

Class Mediator

+
 <class name="class-name">
+   <property name="string" (value="literal" | expression="xpath")/>*
+ </class> 
+ +

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.

+ +

+ +

Extensibility of Synapse

+ +

The Synapse configuration language could be easily extended, with +configuration extensions as well as mediation extensions. The Spring mediator +is such an example.

+ +

Spring Configuration

+ +

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.

+
 <localEntry key="string"/>
+ <localEntry key="string" src="url"/>
+ +

The name attribute specifies a unique name for the configuration, and the +src, key or inlined XML references to the Spring configuration

+ +

+ +

Spring mediator

+
 <spring:spring bean="exampleBean1" key="string"/>
+ +

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

+ +

+ +

Scripting language mediators

+ +

+ +

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:

+
 <script key="string" language="string" [function="script-function-name"]/>
+ +

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:

+
 <script language="string">...script source code...<script/>
+ +

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:

+
 <script language="js">mc.getPayloadXML()..symbol != "IBM";<script/>
+ +

Synapse uses the Apache Bean Scripting Framework for the +scripting language support, any script language supported by BSF may be used +to implement a Synapse Mediator. + +

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.

+ +

+ + Modified: webservices/synapse/site/Synapse_Extending.html URL: http://svn.apache.org/viewvc/webservices/synapse/site/Synapse_Extending.html?view=diff&rev=545490&r1=545489&r2=545490 ============================================================================== --- webservices/synapse/site/Synapse_Extending.html (original) +++ webservices/synapse/site/Synapse_Extending.html Fri Jun 8 05:23:07 2007 @@ -1,32 +1,125 @@ Extending Synapse +

Extending Synapse

-
-

Writing custom Mediator implementations

@@ -35,16 +128,16 @@ 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 to be used. The -SynapseConfiguration holds the global configuration model that defines -message mediation rules and common definitions to be used, while the -environment gives access to the underlying SOAP implementation used. A -typical mediator would need to manipulate the MessageContext by referring to -the SynapseConfiguration. However it is strongly recommended that the -SynapseConfiguration should not be 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 custom named properties -into the MessageContext for later retrieval by successive mediators.
+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.

The MessageContext interface is based on the Axis2 MessageContext interface, and uses the Axis2 EndpointReference 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 messages are represented using the SOAP -infoset. Binary messages can be embedded in the Envelope using the MTOM -support built into Axis2's AXIOM object model.

+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.

Mediator @@ -178,10 +269,12 @@ usually designed to co-operate to process the message onwards.

Leaf and Node Mediators, List mediators and Filter mediators

-Mediators may be Node mediators (i.e. these contain sub mediators) or Leaf -mediators (mediators that does not hold any sub mediators). A Node mediator  -must implement the org.apache.synapse.api.ListMediator interface listed -below, or extend from the org.apache.synapse.mediators.AbstractListMediator. + +

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.

The @@ -236,11 +329,12 @@ */ public List getList(); } -A ListMediator implementation should call super.mediate(synCtx) to process + +

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. +its sequence of sub mediators on successful outcome of a test condition. The Mediator instance which performs filtering should implement the -FilterMediator interface. +FilterMediator interface.

FilterMediator @@ -267,7 +361,8 @@ }

Writing custom Configuration implementations for mediators

-You may write your own custom configurator for the Mediator implementation + +

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 @@ -280,19 +375,20 @@ 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 a text file by the name -"org.apache.synapse.config.xml.MediatorFactory" which will contain the fully -qualified name(s) of your MediatorFactory implementation class(es). 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 +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. +modules/extensions in the Synapse source distribution for examples.

The @@ -325,45 +421,51 @@

The MediatorSerializer interface

-
/**
-
* 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();
-
}
+
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();
+}

Configuring mediators

-Mediators could access properties defined into the Synapse configuration to + +

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. +mediator implementations for examples on how this could be achieved.

Loading of Extensions by the Synapse runtime

-Synapse loads available extensions from the runtime classpath using the Synapse loads available extensions from the runtime classpath using the J2SE Service Provider model. 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.ExtensionFactory which +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 +synapse-extensions.jar contains the following structure

synapse-extensions.jar
     /META-INF/services
-        org.apache.synapse.config.xml.ExtensionFactory
         org.apache.synapse.config.xml.MediatorFactory
+        org.apache.synapse.config.xml.MediatorSerializer
     /... the implementation classes as usual...
--------------------------------------------------------------------- To unsubscribe, e-mail: synapse-dev-unsubscribe@ws.apache.org For additional commands, e-mail: synapse-dev-help@ws.apache.org