Apache Synapse ESB - Configuration

Send

The send token represents a <send> element, used to send messages out of Synapse to some endpoint. 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 so that the response could be correlated back to the request. Messages may be correlated by WS-A MessageID, or even simple custom text labels (see the property mediator and samples)

In the simplest case shown below, the destination to send a message is implicit in the message via the 'To' address. Thus a request message will be sent to its 'To' address, and a response message would be sent back to the client. Removing the 'To' address of a message targets it back to the client, and thus a request message received may be returned to the client after changing its direction. (Note: to mark a message as a response set the property RESPONSE to true)

Note: A send operation may be blocking or non-blocking depending on the actual transport implementation used. As the default NIO based http/s implementation does not block on a send, care must be taken if the same message must be sent and then further processed (e.g. transformed). In such a scenario, it maybe required to first clone the message into two copies and then perform processing to avoid conflicts.

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

Drop

The drop token refers to a <drop> element which is used to stop further processing of a message:

 <drop/>

Once the <drop> mediator executes, further processing of the current message stops. A the drop mediator does not necessarily close transports.

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 set on a message can be later retrieved through the synapse:get-property(prop-name) XPath 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. 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 any existing message context properties.

There are some well-defined properties that you can get/set on the Synapse message context scope:

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

There are some Axis2 and module properties that are useful which are set at 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

There are some Axis2 client side properties/options that are useful which are set at scope="axis2-client"

• FORCE_HTTP_1.0 - forces outgoing http/s messages to use HTTP 1.0 (instead of the default 1.1)

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. If a 'version' attribute is specified, the created fault message will be created as a selected SOAP 1.1 or SOAP 1.2 fault.

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 selected element of the current message payload. 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' elements defines any features 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. Though this would be better in performance than using byte streams, sometimes it may not work for all transformations.

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 infoset. 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 as a String 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="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>*
     <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 XPath 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="CHAR|VARCHAR|LONGVARCHAR|NUMERIC|DECIMAL|BIT|TINYINT|SMALLINT|INTEGER|BIGINT|REAL|FLOAT|DOUBLE|DATE|TIME|TIMESTAMP"/>*
    </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. Please refer to the samples document for sample throttling policies. 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. (i.e. two instances of the throttle mediator with the same 'id' attribute in the request and response flows). The 'onReject' and 'onAccept' sequence references or inline sequences define how accepted and rejected messages are to be handled.

XQuery

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

The XQuery mediator can be used to perform an XQuery transformation. The 'key' attribute specifies the XQuery transformation, and the optional 'target' attribute specifies the node of the message that should be transformed. This defaults to the first child of the SOAP body of the payload. 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 .

It is possible to specify just a literal 'value', or an XPath expression over the payload, or even specify a registry key or a registry key combined with an XPath expression that selects the variable. 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

Cache

 <cache id="string" [hashGenerator="class"] [timeout="seconds"] [scope=(per-host | per-mediator)]
     collector=(true | false) [maxMessageSize="in-bytes"]>
   <onCacheHit [sequence="key"]>
     (mediator)+
   </onCacheHit>?
   <implementation type=(memory | disk) maxSize="int"/>
 </cache>

The <cache> mediator will evaluate the hash value of an incoming message as described in the optional hash generator implementation (which should be a class implementing the org.wso2.caching.digest.DigestGenerator interface). The default hash generator is 'org.wso2.caching.digest.DOMHashGenerator'. 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 referenced. The cache mediator must be specified with an 'id' and two instances with this same 'id' that correlates the response message into the cache for the request message hash. The optional 'timeout' specifies the valid duration for cached elements, and the scope defines if mediator instances share a common cache per every host instance, or per every cache mediator pair (i.e. 'id') instance. The 'collector' attribute 'true' specifies that the mediator instance is a response collection instance, and 'false' specifies that its a cache serving instance. The maximum size of a message to be cached could be specified with the optional 'maxMessageSize' attributes in bytes and defaults to unlimited. Finally the 'implementation' element may define if the cache is disk or memory based, and the 'maxSize' attribute defines the maximum number of elements to be cached.

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 which will be processed in parallel. The original message cloned can be continued or dropped depending on the boolean value of the optional 'continueParent' attribute. Optionally a custom 'To' address and/or a 'Action' may be specified for cloned messages

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 into number of different messages derived from the parent message by finding matching elements for the XPath expression specified. New messages will be created for each and every matching element and processed in parallel using either the specified sequence or endpoint. Parent message can be continued or dropped in the same way as in the clone mediator. The 'preservePayload' attribute specifies if the original message should be used as a template when creating the splitted messages, and defaults to 'false', in which case the splitted messages would contain the split elements as the SOAP body.

Aggregate

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

The aggregate mediator implements the Message Aggregator EIP and will aggregate the messages or responses for splitted messages using either the clone or iterate mediators. At the same time it can aggregate messages on the presence of matching elements specified by the correlateOn XPATH expression. Aggregate will collect the messages coming into it until the messages collected on the aggregation satisfies the complete condition. The completion condition can specify a minimum or maximum number of messages to be collected, or a timeout value in seconds, after which the aggregation terminates. On completion of the aggregation it will merge all of the collected messages and invoke the onComplete sequence on it. The merged message would be created using the XPath expression specified by the attribute 'expression' on the 'onComplete' element.

Class

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

The class mediator creates an instance of a custom 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="string"/> |
   <property name="string" context-name="literal" [action=(ReadContext | UpdateContext | ReadAndUpdateContext)]>
     (either literal or XML child)
   </property> |
   <property name="string" expression="xpath" [action=(ReadMessage | UpdateMessage | ReadAndUpdateMessage)]/>
   )*
 </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 "public void execute()". If any properties are specified, the corresponding setter methods are invoked on the class before each message is executed. It should be noted that a new instance of the POJO Command class is created to process each message processed. After execution of the POJO Command mediator, depending on the 'action' attribute of the property, the new value returned by a call to the corresponding getter method is stored back to the message or to the context. The 'action' attribute may specify whether this behaviour is expected or not via the Read, Update and ReadAndUpdate properties.

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