Synapse Configuration Language

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.

• simple = To, From, WSAction, SOAPAction, ReplyTo, MessageID and any properties
• headers = All SOAP header blocks and any properties
• full = all attributes included in log level 'simple' and the SOAP envelope and any properties
• custom = Only properties specified to the Log mediator

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

Property

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

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, or as a Axis2 client option or as an Axis2 message context property. If a scope is not specified, it will default to the Synapse message context scope. Using the property element with action specified as "remove" you can remove the message context properties if available.

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

• RESPONSE - 'true' means the message is marked as a response message
• OUT_ONLY - 'true' means the message is marked as an out-only message that does not expect a response
• ERROR_CODE - this is set to any error message code encountered
• ERROR_MESSAGE - this is set to any error message text encountered
• ERROR_DETAIL - this is set to any error message detail text encountered

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

• Sandesha2RMSpecVersion - can be '1.0' or '1.1'
• Sandesha2SequenceKey - can be an identifier specifying an Sandesha internal sequence key, and
• Sandesha2LastMessage - 'true' will make this the last message and terminate the sequence

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)

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")/>*
   <feature name="string" value="true| false" />
 </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.The <feature> defines a any feature which should be set to the TransformerFactory by explicitly. The feature 'http://ws.apache.org/ns/synapse/transform/feature/dom' turns on DOM based transformations instead of serializing elements into Byte streams and/or temporary files. However, this may not prove to be stable for all scenarios - especially for large message transformation.

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.

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.

DB-lookup

<dblookup>
   <connection>
     <pool>
      (
       <driver/>
       <url/>
       <user/>
       <password/>
     |
       <dsName/>
       <icClass/>
       <url/>
       <user/>
       <password/>
     )
       <property name="name" value="value"/>*
     </pool>
   </connection>
   <statement>
     <sql>select something from table where something_else = ?</sql>
     <parameter [value="" | expression=""] type="int|string"/>*
     <result name="string" column="int|string"/>*
   </statement>+
</dblookup>

The dblookup mediator is capable of executing an arbitrary SQL select statement, and then set some resulting values as local message properties on the message context. The DB connection used maybe looked up from an external DataSource or specified in-line, in which case an Apache DBCP connection pool is established and used. Apache DBCP connection pools support the following properties:

• autocommit = true | false
• isolation = Connection.TRANSACTION_NONE | Connection.TRANSACTION_READ_COMMITTED | Connection.TRANSACTION_READ_UNCOMMITTED | Connection.TRANSACTION_REPEATABLE_READ | Connection.TRANSACTION_SERIALIZABLE
• initialsize = int
• maxactive = int
• maxidle = int
• maxopenstatements = int
• maxwait = long
• minidle = int
• poolstatements = true | false
• testonborrow = true | false
• testonreturn = true | false
• testwhileidle = true | false
• validationquery = String

More than one statement may be specified, and the SQL statement may specify parameters which could be specified as values or expressions. The types of parameters could be any valid SQL types. Only the first row of a result set will be considered and any others are ignored. The single <result> element contains the 'name' and the column' attributes. The 'name' attribute defines the name under which the result is stored in the Synapse message context, and the column attribute specifies a column number or name .

DB-report

<dbreport>
   <connection>
     <pool>
      (
       <driver/>
       <url/>
       <user/>
       <password/>
     |
       <dsName/>
       <icClass/>
       <url/>
       <user/>
       <password/>
     )
       <property name="name" value="value"/>*
     </pool>
   </connection>
   <statement>
     <sql>insert into something values(?, ?, ?, ?)</sql>
     <parameter [value="" | expression=""] type="int|string"/>*
    </statement>+
</dblreport>

The dbreport mediator is very similar to the dblookup mediator, but writes information to a Database, using the specified insert SQL statement.

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.

Throttle

<throttle [onReject="string"] [onAccept="string"] [id="string"]>
    <policy key="string"/> | <policy>..</policy>
    <onReject>..</onReject>
    <onAccept>..</onAccept>
</throttle>

The Throttle mediator can be used for rate limiting as well as concurrency based limiting. A WS-Policy dictates the throttling configuration and may be specified inline or loaded from the registry. The Throttle mediator could be added in the request path for rate limiting and concurrent access limitation. When using for concurrent access limitation, the same throttle mediator ID must be triggered on the response flow so that completed responses are deducted from the available limit. The acceptance or rejection sequence is executed depending on the evaluation of the throttling policy against the current message.

XQuery

<xquery [key="string"] [target="xpath"]>
    <variable name="string" type="string" [key="string"] [expression="xpath"]/>?
</xquery> 

The XQuery mediator can be used to perform an XQuery transformation. The 'variable' elements define a variable that could be bound to the dynamic context of the XQuery engine in order to access those variables through the XQuery script . The name of the variable corresponds to the name of variable declaration in the XQuery script. The 'type' of the variable must be a valid type defined by the JSR-000225 (XQJ API). The supported types are:

• XQItemType.XQBASETYPE_INT -> INT
• XQItemType.XQBASETYPE_INTEGER -> INTEGER
• XQItemType.XQBASETYPE_BOOLEAN -> BOOLEAN
• XQItemType.XQBASETYPE_BYTE - > BYTE
• XQItemType.XQBASETYPE_DOUBLE -> DOUBLE
• XQItemType.XQBASETYPE_SHORT -> SHORT
• XQItemType.XQBASETYPE_LONG -> LONG
• XQItemType.XQBASETYPE_FLOAT -> FLOAT
• XQItemType.XQBASETYPE_STRING -> STRING
• XQItemType.XQITEMKIND_DOCUMENT -> DOCUMENT
• XQItemType.XQITEMKIND_DOCUMENT_ELEMENT -> DOCUMENT_ELEMENT
• XQItemType.XQITEMKIND_ELEMENT -> ELEMENT

The expressions will be evaluated against the current SOAP envelope.

Cache

 <cache (id="string")? hashGenerator="class" scope="string" timeout="milliseconds">
   <onCacheHit (sequence="key")?>
     (mediator)+
   </onCacheHit>
   <implementation type=(memory | disk) maxSize="int"/>
 </cache>

The <cache> mediator will evaluate the hash value of the incoming message as described in the hash generator implementation (which should be a class implementing the org.wso2.caching.digest.DigestGenerator interface) and looks in a cache for a matching response. If the generated hash value has been found in the cache then the cache mediator will execute the onCacheHit sequence which can be specified inline or refered to the registry.

Clone

 <clone continueParent=(true | false)>
   <target to="uri" [soapAction="qname"] sequence="sequence_ref" endpoint="endpoint_ref">
     <sequence>
       (mediator)+
     </sequence>
     <endpoint>
       endpoint
     </endpoint>
   </target>
 </clone>

The <clone> mediator closely resembles the Message Splitter EIP and will split the message into number of identical messages all of which are identical with the cloning message and processed parallelly using either the specified sequence or endpoint (or both). Cloning message (parent) can be continued or dropped depending on the boolean value of the continueParent attribute which defaults to false and drops the parent when false. This drop is not a general drop, rather stop the message processing but does not closes the transport channel, leaving the ability of one or a set of cloned message responses to be sent back to the caller

Iterate

 <iterate continueParent=(true | false) preservePayload=(true | false) (attachPath="xpath")? expression="xpath">
   <target to="uri" [soapAction="qname"] sequence="sequence_ref" endpoint="endpoint_ref">
     <sequence>
       (mediator)+
     </sequence>
     <endpoint>
       endpoint
     </endpoint>
   </target>
 </iterate>

The <iterate> mediator implements another EIP and will split the message in to number of different messages derived from the parent message by finding the matching elements of the XPATH expression specified in the configuration. New messages will be created for each and every matching element and processed parallelly using either the specified sequence or endpoint or both. Parent message can be continued or dropped in the same way as in the clone mediator. Iterate parent drop also is a channel blocking drop as per in the clone mediator.

Aggregate

 <aggregate>
   <corelateOn expression="xpath"/>
   <completeCondition timeout="time-in-seconds">
     <messageCount min="int-min" max="int-max"/>
   </completeCondition>
   <onComplete expression="xpath" sequence="sequence-ref">
     (mediator +)?
   </onComplete>
   <invalidate sequence="sequence-ref" timeout="time-in-seconds">
     (mediator +)?
   </invalidate>
 </aggregate>

The <aggregate> mediator implements the Message Aggregator EIP and will aggregate the messages splitted using either the clone or iterate mediators. At the same time it can aggregate messages on the presence of matching elements specified by the corelateOn XPATH expression. Aggregate will collect the messages coming in to that until the messages on the aggregation satisfies the complete condition. On completion of the aggregation it will execute the aggregated message using the onComplete sequence. Aggregated message will be created by combining the messages participating in the aggregation using the onComplete XPATH expression. If a particular aggregation fails to complete in a pre configured time, then that particular aggregation will be invalidated using the invalidate sequence.

Class

 <class name="class-name">
   <property name="string" value="literal">
     (either literal or XML child)
   </property>
 </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, once, during initialization.

POJOCommand

 <pojoCommand name="class-name">
   <property name="string" value="literal">
     (either literal or XML child)
   </property>
   <property name="string" expression="xpath"/>
 </pojoCommand> 

The <pojoCommand> mediator creates an instance of the specified command class (which may implement the org.apache.synapse.Command interface or should have a public void method named "execute"). If any properties are specified, the corresponding setter methods are invoked on the class and called the execute method of the command executed.

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