[prev in list] [next in list] [prev in thread] [next in thread] 

List:       incubator-cvs
Subject:    [Incubator Wiki] Update of "SynapseConfigurationLanguage" by Asankha Perera
From:       Apache Wiki <wikidiffs () apache ! org>
Date:       2006-04-25 12:50:49
Message-ID: 20060425125049.3977.28643 () ajax ! apache ! org
[Download RAW message or body]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Incubator Wiki" for change \
notification.

The following page has been changed by Asankha Perera:
http://wiki.apache.org/incubator/SynapseConfigurationLanguage

New page:
====== 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. This design currently does not support the \
concept of "service mediation." It is also 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>
    <definitions>
      (sequencedef | endpointdef | literalpropertydef)+
    <definitions>?
    <rules>
      mediator+
    </rules>
  </synapse>

===== Definitions =====

The <definitions> section defines reusable elements that can be used from inside the \
rules and the <rules> section contains the sequence of mediators that every message \
is processed through.


==== Sequences ====

A sequencedef token represents a <sequence> element which is used to define a \
sequence of mediators that can be included later as a mediator.  <sequence \
name="string">  mediator+
  </sequence>

==== 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.  <endpoint name="string" \
                [address="url"]>
    .. extensibility ..
  </endpoint>



==== Properties ====

The token literalpropertydef refers to a <set-property> element as follows:
  <set-property name="string" value="string"/>
which is used to set a glboal property with a constant value.

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

===== Mediators =====

A mediator token refers to any of the following tokens:
  send | drop | log | makefault | transform | edit | filter | switch | class | \
validate | setproperty | sequenceref

==== Send ====

The send token represents a <send> element. The <send> element is used to send \
messages out of Synapse to some endpoint. 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>

==== Drop ====

The drop token refers to a <drop> element which is used to drop a message:
  <drop/>
Once the <drop> mediator is executed, the message processing is finished.


==== Log ====

The log token refers to a <log> element which is used to log the message:
  <log [level="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. level=simple|headers|full


==== Transforms ====

=== Faults ===

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

=== XSLT/XQuery ===

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

=== Headers ===

The edit token refers to any of the following elements: <remove-header> and \
<set-header>:  <remove-header name="qname"/>
  <set-header name="qname" (value="literal" | expression="xpath")/>
Note that <set-header> currently only supports simple valued headers. In the future \
we may extend this to have XML structured headers by embedding the XML content in the \
set-header element itself.

==== Selection ====

=== Filters ===

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

=== Switch ===

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


==== Validation ====

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

If the source attribute is not specified, the validation is performed against the \
soap envelope

==== Properties ====

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.  <set-property name="string" (value="literal" | expression="xpath")/>

These properties are set on the message context of the message currently flowing \
through the system. The value of property can be queried via the XPath extension \
function "synapse:get-property(prop-name)".

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

==== Reusing Sequences ====

A sequenceref token refers to a <sequence> element which is used to invoke a named \
sequence of mediators:  <sequence ref="name"/>







===== Examples =====

The sample configuration presented below applies in the following hypothetical \
scenario. Assume that two web service endpoints exists, where registration requests \
could be processed. Requests may fall into Gold and Silver categories, and a \
specialized endpoint exists to process the Gold requests. If the Gold endpoint cannot \
be reached for whatever reason, requests should be processed via the Silver endpoint \
(i.e. failover).

Once message arrive at Synapse, the 'to' address is looked up and different mediation \
rules applied depending on it. For registration messages, first we need to validate \
the incoming message against a schema, and if the validation fails, a log entry \
should be made and a fault reply should be sent back. For valid messages, we \
determine its category and attempt to use the Gold endpoint, failing which the Silver \
endpoint is tried. For requests that does not fall into the Gold category the default \
silver endpoint is used always.

  <synapse>
    <definitions>
  
      <sequence name="registration_flow">
        <validate schema="http://registry/xsd/registration.xsd" \
source="//regRequest">  <on-fail>
            <set-property name="error-code" value="100"/>
            <set-property name="error-reason" value="validation failed"/>
            <sequence ref="fault_flow"/>
          </on-fail>
        </validate>          
        <filter xpath="/regRequest[@Category='GOLD']">
           <send>
             <failover>
               <endpoint ref="gold_registration"/>
               <endpoint ref="silver_registration"/>
             </failover>
           </send>
        <filter>  
        <send>
          <endpoint ref="silver_registration"/>
        </send>
      <sequence>
  
      <sequence name="fault_flow">
        <log level="simple">
          <property name="application" value="synapse:get-property('reg-app')"/>
        </log>
        <makefault version="soap11">
          <code value="synapse:get-property('error-code')"/>
          <reason expression="synapse:get-property('error-reason')">
        <makefault>
        <send/>
      <sequence>
  
      <endpoint name="gold_registration" address="http://gold/registration"/>
      <endpoint name="silver_registration" address="http://silver/registration"/>
  
      <property>
        <set-property name="reg_app" value="Registration Application"/>
      </property>
      
    <definitions>
  
    <rules>
      <switch source="synapse:get-property('to')">
        <case regex="/registration">
          <sequence ref="registration_flow"/>
        </case>
        <case regex="someother">
          ...
        </case>
        <default>
          <drop/>
        </default>
    </rules>
  
  </synapse>  


---------------------------------------------------------------------
To unsubscribe, e-mail: cvs-unsubscribe@incubator.apache.org
For additional commands, e-mail: cvs-help@incubator.apache.org


[prev in list] [next in list] [prev in thread] [next in thread]