| <?xml version="1.0" encoding="ISO-8859-1"?> |
| |
| <!DOCTYPE html |
| PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" > |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta content="text/html; charset=iso-8859-1" http-equiv="content-type"/> |
| <title> |
| Synapse Configuration Language |
| </title> |
| <style type="text/css" xml:space="preserve"> |
| .command { |
| border: 1px dashed #3c78b5; |
| text-align: left; |
| background-color: #f0f0f0; |
| padding: 3px; |
| font-size: 11px; |
| font-family: Courier; |
| margin: 10px; |
| line-height: 13px; |
| } |
| .consoleOutput { |
| border: 1px dashed #3c78b5; |
| font-size: 11px; |
| font-family: Courier; |
| margin: 10px; |
| line-height: 13px; |
| background-color: #f0f0f0; |
| border-bottom: 1px dashed #3c78b5; |
| padding: 3px; |
| border-style: solid; |
| } |
| .info { |
| border-style: solid; |
| border-width: 1px; |
| border-color: #090; |
| background-color: #dfd; |
| text-align:left; |
| margin-top: 5px; |
| margin-bottom: 5px; |
| } |
| li { |
| font-family: Verdana, arial, sans-serif; |
| font-size: 11px; |
| line-height: 16px; |
| color: #000000; |
| font-weight: normal; |
| } |
| p { |
| font-family: Verdana, arial, sans-serif; |
| font-size: 11px; |
| line-height: 16px; |
| color: #000000; |
| font-weight: normal; |
| } |
| pre { |
| padding: 0px; |
| margin-top: 5px; |
| margin-left: 15px; |
| margin-bottom: 5px; |
| margin-right: 5px; |
| text-align: left; |
| background-color: #f0f0f0; |
| padding: 3px; |
| border: 1px dashed #3c78b5; |
| font-size: 11px; |
| font-family: Courier; |
| margin: 10px; |
| line-height: 13px; |
| } |
| h1 { |
| font-size: 24px; |
| line-height: normal; |
| font-weight: bold; |
| background-color: #f0f0f0; |
| color: #003366; |
| border-bottom: 1px solid #3c78b5; |
| padding: 2px; |
| margin: 36px 0px 4px 0px; |
| } |
| h2 { |
| font-size: 18px; |
| line-height: normal; |
| font-weight: bold; |
| background-color: #f0f0f0; |
| border-bottom: 1px solid #3c78b5; |
| padding: 2px; |
| margin: 27px 0px 4px 0px; |
| } |
| h3 { |
| font-size: 14px; |
| line-height: normal; |
| font-weight: bold; |
| background-color: #f0f0f0; |
| padding: 2px; |
| margin: 21px 0px 4px 0px; |
| } |
| h4 { |
| font-size: 12px; |
| line-height: normal; |
| font-weight: bold; |
| background-color: #f0f0f0; |
| padding: 2px; |
| margin: 18px 0px 4px 0px; |
| }</style> |
| </head> |
| <body> |
| <h1> |
| Synapse Configuration Language |
| </h1> |
| <p> |
| 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). |
| </p> |
| <h3> |
| Overall Structure |
| </h3> |
| <p> |
| A Synapse configuration looks like the following at the top level: |
| </p> |
| <pre xml:space="preserve"> <definitions> |
| <<a href="#registry">registry</a> provider="string">...</registry>? |
| <<a href="#localEntry">localEntry</a> key="string">...</localEntry>? |
| <<a href="#sequence">sequence</a> name="string">...</sequence>? |
| <<a href="#endpoint">endpoint</a> name="string">...</endpoint>? |
| <<a href="#proxy">proxy</a> name="string" ...>...</proxy>? |
| <a href="#mediator">mediator</a>* |
| </definitions></pre> |
| <h2> |
| <a name="registry" id="registry">Registry</a> |
| </h2> |
| <p> |
| 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. |
| </p> |
| <pre xml:space="preserve"> <registry provider="string"/> |
| <parameter name="string">text | xml</parameter>* |
| </registry></pre> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h3> |
| <a name="localEntry" id="localEntry">Local Entry</a> |
| </h3> |
| <p> |
| The <localEntry> element is used to declare registry entries that |
| are local to the Synapse instance, as shown below |
| </p> |
| <pre xml:space="preserve"> <localEntry key="string" [src="url"]>text | xml</localEntry></pre> |
| <p> |
| 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)". |
| </p> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h2> |
| <a name="sequence" id="sequence">Sequences</a> |
| </h2> |
| <p> |
| A <sequence> element is used to define a sequence of mediators that |
| can be invoked later by name as a sequence of mediators. |
| </p> |
| <pre xml:space="preserve"> <sequence name="string" [onError="string"] [key="string"]> |
| mediator* |
| </sequence></pre> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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'. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h2> |
| <a name="endpoint" id="endpoint">Endpoints</a> |
| </h2> |
| <p> |
| 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: |
| </p> |
| <pre xml:space="preserve"><endpoint [name="string"] [key="string"]> |
| <a href="#address-endpoint">address-endpoint</a> | <a href="#wsdl-endpoint">wsdl-endpoint</a> | <a href="#load-balanced-endpoint">load-balanced-endpoint</a> | <a href="#fail-over-endpoint">fail-over-endpoint</a> </endpoint> </pre> |
| <p> |
| 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. |
| </p> |
| <pre xml:space="preserve"><endpoint key="foo"/></pre> |
| <h4> |
| <a name="address-endpoint" id="address-endpoint">Address Endpoint</a> |
| </h4> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <p> |
| 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. |
| </p> |
| <pre xml:space="preserve"><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></pre> |
| <h4> |
| <a name="wsdl-endpoint" id="wsdl-endpoint">WSDL Endpoint</a> |
| </h4> |
| <p> |
| 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. |
| </p> |
| <pre xml:space="preserve"><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></pre> |
| <h4> |
| <a name="load-balanced-endpoint" id="load-balanced-endpoint">Load |
| balanced Endpoint</a> |
| </h4> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <p> |
| 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. |
| </p> |
| <pre xml:space="preserve"><session type="http"/>? |
| <loadBalance [policy="roundRobin"] [failover="true|false"]> |
| <endpoint .../>+ |
| </loadBalance></pre> |
| <h4> |
| <a name="fail-over-endpoint" id="fail-over-endpoint">Failover Endpoint</a> |
| </h4> |
| <p> |
| 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. |
| </p> |
| <pre xml:space="preserve"><failover> |
| <endpoint .../>+ |
| </failover></pre> |
| <h2> |
| <a name="proxy" id="proxy">Proxy service</a> |
| </h2> |
| <p> |
| A <proxy> element is used to define a Synapse Proxy service. |
| </p> |
| <pre xml:space="preserve"> <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></pre> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h2> |
| <a name="mediator" id="mediator">Mediators</a> |
| </h2> |
| <p> |
| A mediator token refers to any of the following tokens: |
| </p> |
| <pre xml:space="preserve"><a href="#send">send</a> | <a href="#drop">drop</a> | <a href="#log">log</a> | <a href="#makefault">makefault</a> | <a href="#xslt">transform</a> | <a href="#header">header</a> | <a href="#filter">filter</a> | <a href="#switch">switch</a> | <a href="#class">class</a> | <a href="#validate">validate</a> | <a href="#property">property</a> | <a href="#sequence">sequence ref</a> | <a href="#in">in</a> | <a href="#out">out</a> | <a href="#rmsequence">RMSequence</a></pre> |
| <p> |
| 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. |
| </p> |
| <h3> |
| Core Mediators |
| </h3> |
| <h4> |
| <a name="send" id="send">Send</a> |
| </h4> |
| <p> |
| 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. |
| </p> |
| <p> |
| 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: |
| </p> |
| <pre xml:space="preserve"> <send/></pre> |
| <p> |
| If the message is to be sent to one or more endpoints, then the following |
| is used: |
| </p> |
| <pre xml:space="preserve"> <send> |
| (endpointref | endpoint)+ |
| </send></pre> |
| <p> |
| where the endpointref token refers to the following: |
| </p> |
| <pre xml:space="preserve"> <endpoint key="name"/></pre> |
| <p> |
| and the endpoint token refers to an anonymous endpoint defined. |
| </p> |
| <p/> |
| <h4> |
| <a name="drop" id="drop">Drop</a> |
| </h4> |
| <p> |
| The drop token refers to a <drop> element which is used to drop a |
| message: |
| </p> |
| <pre xml:space="preserve"> <drop/></pre> |
| <p> |
| Once the <drop> mediator executes, further processing of the current |
| message stops. |
| </p> |
| <p/> |
| <h4> |
| <a name="log" id="log">Log</a> |
| </h4> |
| <p> |
| The log token refers to a <log> element which may be used to log |
| messages being mediated: |
| </p> |
| <pre xml:space="preserve"> <log [level="string"] [separator="string"]> |
| <property name="string" (value="literal" | expression="xpath")/>* |
| </log></pre> |
| <p> |
| The optional level attribute selects a pre-defined subset of properties to |
| be logged. |
| </p> |
| <p> |
| e.g. |
| </p> |
| <ul> |
| <li> |
| simple = To, From, WSAction, SOAPAction, ReplyTo, MessageID and any |
| properties |
| </li> |
| <li> |
| headers = All SOAP header blocks and any properties |
| </li> |
| <li> |
| full = all attributes included in log level 'simple' and the SOAP |
| envelope and any properties |
| </li> |
| <li> |
| custom = Only properties specified to the Log mediator |
| </li> |
| </ul> |
| <p> |
| A separator if defined will be used to seperate the attributes being |
| logged. The default separator is the ',' comma. |
| </p> |
| <p/> |
| <h4> |
| <a name="property" id="property">Property</a> |
| </h4> |
| <pre xml:space="preserve"> <property name="string" [action=set|remove] (value="literal" | expression="xpath") [scope=transport|axis2]/></pre> |
| <p> |
| 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. |
| </p> |
| <p> |
| There are some well-defined properties that you can get/set: |
| </p> |
| <ul> |
| <li> |
| RESPONSE - 'true' means the message is a response message |
| </li> |
| <li> |
| ERROR_MESSAGE - this is set to any error message |
| </li> |
| </ul> |
| <p> |
| There are also some Axis2 and module properties that are useful to set |
| (with scope="axis2"): |
| </p> |
| <ul> |
| <li> |
| Sandesha2RMSpecVersion - can be '1.0' or '1.1' |
| </li> |
| <li> |
| Sandesha2SequenceKey - can be an identifier specifying an Sandesha |
| internal sequence key, and |
| </li> |
| <li> |
| Sandesha2LastMessage - 'true' will make this the last message and |
| terminate the sequence |
| </li> |
| </ul> |
| <p/> |
| <h4> |
| <a name="sequence" id="sequence_">Sequence</a> |
| </h4> |
| <pre xml:space="preserve"> <sequence key="name"/></pre> |
| <p> |
| A sequence ref token refers to a <sequence> element which is used to |
| invoke a named sequence of mediators. |
| </p> |
| <p/> |
| <h4> |
| <a name="validate" id="validate">Validate</a> |
| </h4> |
| <pre xml:space="preserve"> <validate [source="xpath"]> |
| <property name="validation-feature-id" value="true|false"/>* |
| <schema key="string"/>+ |
| <on-fail> |
| mediator+ |
| </on-fail> |
| </validate></pre> |
| <p> |
| 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) |
| </p> |
| <p/> |
| <h3> |
| Message Transformations |
| </h3> |
| <h4> |
| <a name="makefault" id="makefault">Makefault</a> |
| </h4> |
| <pre xml:space="preserve"> <makefault [version="soap11|soap12"]> |
| <code (value="literal" | expression="xpath")/> |
| <reason (value="literal" | expression="xpath")> |
| <node>? |
| <role>? |
| <detail>? |
| </makefault></pre> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h4> |
| <a name="xslt" id="xslt">XSLT</a> |
| </h4> |
| <pre xml:space="preserve"> <xslt key="string" [source="xpath"]> |
| <property name="string" (value="literal" | expression="xpath")/>* |
| </xslt></pre> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h4> |
| <a name="header" id="header">Header</a> |
| </h4> |
| <pre xml:space="preserve"> <header name="qname" (value="literal" | expression="xpath") [action="set"]/> |
| <header name="qname" action="remove"/></pre> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h3> |
| Selection |
| </h3> |
| <h4> |
| <a name="filter" id="filter">Filter</a> |
| </h4> |
| <pre xml:space="preserve"> <filter (source="xpath" regex="string") | xpath="xpath"> |
| mediator+ |
| </filter></pre> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h4> |
| <a name="switch" id="switch">Switch</a> |
| </h4> |
| <pre xml:space="preserve"> <switch source="xpath"> |
| <case regex="string"> |
| mediator+ |
| </case>+ |
| <default> |
| mediator+ |
| </default>? |
| </switch></pre> |
| <p> |
| 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. |
| </p> |
| <a name="in" id="in"/> |
| <h4> |
| <a name="out" id="out">In / Out</a> |
| </h4> |
| <pre xml:space="preserve"><in><br/> mediator+ |
| </in><br/></pre> |
| <pre xml:space="preserve"><out> |
| mediator+ |
| </out></pre> |
| <p> |
| <br/> |
| </p> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h3> |
| WS-Reliable Messaging |
| </h3> |
| <h4> |
| <a name="rmsequence" id="rmsequence">RMSequence</a> |
| </h4> |
| <pre xml:space="preserve"> <RMSequence (correlation="xpath" [last-message="xpath"]) | single="true" [version="1.0|1.1"]/></pre> |
| <p> |
| 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. |
| </p> |
| <h3> |
| Extension mediator |
| </h3> |
| <h4> |
| <a name="class" id="class">Class Mediator</a> |
| </h4> |
| <pre xml:space="preserve"> <class name="class-name"> |
| <property name="string" (value="literal" | expression="xpath")/>* |
| </class> </pre> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h3> |
| Extensibility of Synapse |
| </h3> |
| <p> |
| The Synapse configuration language could be easily extended, with |
| configuration extensions as well as mediation extensions. The Spring |
| mediator is such an example. |
| </p> |
| <h4> |
| Spring Configuration |
| </h4> |
| <p> |
| 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. |
| </p> |
| <pre xml:space="preserve"> <localEntry key="string"/> |
| <localEntry key="string" src="url"/></pre> |
| <p> |
| The name attribute specifies a unique name for the configuration, and the |
| src, key or inlined XML references to the Spring configuration |
| </p> |
| <p/> |
| <h4> |
| Spring mediator |
| </h4> |
| <pre xml:space="preserve"> <spring:spring bean="exampleBean1" key="string"/></pre> |
| <p> |
| 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 |
| </p> |
| <p/> |
| <h3> |
| Scripting language mediators |
| </h3> |
| <p/> |
| <p> |
| 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: |
| </p> |
| <pre xml:space="preserve"> <script key="string" language="string" [function="script-function-name"]/></pre> |
| <p> |
| 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: |
| </p> |
| <pre xml:space="preserve"> <script language="string">...script source code...<script/></pre> |
| <p> |
| 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: |
| </p> |
| <pre xml:space="preserve"> <script language="js">mc.getPayloadXML()..symbol != "IBM";<script/></pre> |
| <p> |
| Synapse uses the Apache <a href="http://jakarta.apache.org/bsf/">Bean |
| Scripting Framework</a> for the scripting language support, any |
| script language supported by BSF may be used to implement a Synapse |
| Mediator. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p/> |
| </body> |
| </html> |
