incubator-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Incubator Wiki] Update of "Synapse/SynapseConfigurationLanguage" by Asankha Perera
Date Tue, 25 Apr 2006 13:13:47 GMT
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/Synapse/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


Mime
View raw message