| <?xml version="1.0" encoding="ISO-8859-1"?> |
| <document> |
| <properties> |
| <title>Configuration Language</title> |
| </properties> |
| <head> |
| <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; |
| } |
| </style> |
| </head> |
| <body> |
| <div class="section"> |
| <div> |
| <h2> |
| Apache Synapse ESB - Configuration |
| </h2> |
| </div> |
| <p> |
| An Apache Synapse Enterprise Service Bus (ESB) engine is driven off a set |
| of simple text/xml configuration files. This allows the configuration to |
| be easily hand edited, backed up from the file system, or even included |
| into version control for easier management and control (e.g. moving a |
| configuration from development, through QA, staging and into production). |
| The configuration files that drives the Synapse ESB are as follows: |
| </p> |
| <ul> |
| <li> |
| The Synapse configuration hierarchy - synapse-config directory with sequences, endpoints, proxies, etc... |
| </li> |
| <li> |
| The underlying Axis2 engine configuration file - axis2.xml |
| </li> |
| <li> |
| Resources referenced from the Registry |
| </li> |
| </ul> |
| <p> |
| While the axis2.xml configures the underlying transport and Web services |
| support, the synapse.xml configures the mediation rules and configuration |
| for the ESB. While any changes performed on the axis2.xml requires a |
| restart (e.g. for enabling a transport such as JMS), the synapse.xml could |
| be made to reference different configuration elements off a set of |
| multiple files - that are served through the built-in Registry. When using |
| the Registry to hold pieces of the configuration, certain elements such as |
| endpoint definitions, sequences and local entries could be updated |
| dynamically while the Synapse ESB executes, the the Registry could trigger |
| a re-load as configured. |
| </p> |
| <h2> |
| The Synapse Configuration (synapse-config directory) |
| </h2> |
| <p> |
| As the diagram below depicts, the Synapse configuration defines the Proxy |
| services, Endpoints, Sequences, Startup jobs, Event sources, Priority |
| executors and Dead letter channels managed by the Synapse ESB. It also defines the |
| interface to the Registry/Repository being used by the engine. Synapse Configuration is |
| now available with a XML Schema which defines the |
| <a href="./ns/2010/04/configuration/synapse_config.xsd">configuration language</a> using a set |
| of XSD's. Typically the Synapse ESB is deployed between the actual client and a back-end |
| service implementation to mediate the message flow in between. Thus the Synapse ESB can |
| accept a message on behalf of the actual service, perform authentication, validation, |
| transformation, logging, routing based on the content etc. and then decide the destination |
| target endpoint for the message and direct it to an actual service |
| implementation. The Synapse ESB can also detect timeouts, transport |
| failures during communication or introduce load balancing, throttling or |
| caching where necessary. For fault scenarios such as authentication |
| failure, or schema validation failure, the Synapse ESB can be configured |
| to return a custom message or a fault to the requesting client without |
| forwarding the request to the actual service. |
| </p> |
| <p> |
| <!--TODO: we need to update the image to add priority queues and envent sources--> |
| <img alt="Synapse message flow" |
| src="images/synapse-flow.png" width="400" height="300"/> |
| </p> |
| <p/> |
| <p> |
| The Synapse ESB can operate in multiple modes: |
| </p> |
| <h3> |
| <a href="#service_mediation">Service mediation</a> / <a |
| href="#proxy">Proxy services</a> |
| </h3> |
| <p> |
| In Service mediation, the Synapse ESB exposes a service endpoint on the |
| ESB, that accepts messages from clients. Typically these services acts as |
| proxies for existing (external) services, and the role of Synapse would be |
| to "mediate" these messages before they are proxied to the actual service. |
| In this mode, Synapse could expose a service already available in one |
| transport, over a different transport; or expose a service that uses one |
| schema or WSDL as a service that uses a different schema or WSDL etc. A |
| Proxy service could define the transports over which the service is |
| exposed, and point to the mediation sequences that should be used to |
| process request and response messages through the proxy service. A proxy |
| service maybe a SOAP or REST/POX service over http/s or SOAP, POX, Plain |
| Text or Binary / Legacy service for other transports such as JMS and VFS |
| file systems - e.g. CSV content being the payload |
| </p> |
| <h3> |
| <a name="_message_mediation" id="_message_mediation">Message mediation</a> |
| </h3> |
| <p> |
| In Message mediation, Synapse can act as a transparent proxy for clients - |
| if they are directed to point to the Synapse ESB as a http proxy. This |
| way, Synapse could be configured to filter all messages on a network for |
| logging, access control etc, and could "mediate" messages without the |
| explicit knowledge of the original client. If Synapse receives a message |
| that is not accepted by any proxy service, this message is handled through |
| message mediation as well. Message mediation always processes messages |
| according to the mediation sequence defined as "main". |
| </p> |
| <h3> |
| <a name="_task_scheduling" id="_task_scheduling">Task Scheduling</a> |
| </h3> |
| <p> |
| In Task scheduling, Synapse can schedule a bit of work to be triggered at the specified |
| trigger mechanism. You could use simple triggers such as a count and an interval meaning |
| that it runs count number of times in the specified intervals, or you could use cron |
| scheduling meaning that you specify a standard cron expression adn the scheduler will |
| trigger your task implementation at the cron trigger. This mode of operation is much |
| important for work that has to be initiated by the ESB, for example to poll a service at |
| a given interval and so forth. |
| </p> |
| <h3> |
| <a name="_eventing" id="_eventing">Eventing</a> |
| </h3> |
| <p> |
| In eventing, or in other wards Event Driven Architecture, synapse can be used as |
| one or more event sources and users or systems can subscribe to those event sources. |
| On the other hand systems can send events to Synapse ESB and it will be possible for |
| synapse to act as an event broker and re-deliver the events it received to the respective |
| subscribers according to the filtering criteria, with or without mediation. This again is |
| a very powerful operational mode as it helps to integrated systems based on an EDA. |
| </p> |
| <h2> |
| Concepts and configuration elements overview |
| </h2> |
| <h3> |
| <a href="#mediator">Mediators</a> and <a href="#sequence">Mediation |
| Sequences</a> |
| </h3> |
| <p> |
| The Synapse ESB defines a 'mediator' as a component that is performs some |
| mediation action on a message during the process flow. Thus a mediator |
| gets full access to a message at the point where it is defined to gain |
| control, and could inspect the message, modify it or take an external |
| action depending on some attributes or values of the current message. A |
| mediation sequence, commonly called a 'sequence' is a list of such |
| mediators. A sequence may be named for re-use, or defined in-line or |
| anonymously within a configuration. Sequences may be defined within the |
| synapse.xml configuration or within the Registry. Writing a custom |
| mediator in Java is easy and the supplementary documentation provides more |
| details on this. The 'Class' and 'POJO (command)" mediators allows one to |
| plugin a Java class easily into the Synapse engine with minimal effort. In |
| addition, the Script mediator allows one to provide an Apache BSF script |
| (e.g. Javascript, Ruby, Groovy etc) for mediation. |
| </p> |
| <p> |
| A Synapse configuration holds two special sequences named as "main" and |
| "fault". These may be defined within the synapse.xml, or externally via |
| the Registry. If either is not found, a suitable default is generated at |
| runtime by the ESB. The default "main" sequence will simply send a message |
| without mediation, while the default "fault" sequence would log the |
| message including the payload and any error/exception encountered and stop |
| further processing. The 'fault' sequence executes whenever Synapse itself |
| encounters an error while processing a message - or when a fault handler |
| has not been defined to handle exceptions. A sequence can assign another |
| named sequence as its "fault" handler sequence, and control branches to |
| the fault handler if an error is encountered during the execution of the |
| initial sequence. |
| </p> |
| <h3> |
| <a href="#endpoint">Endpoints</a> |
| </h3> |
| <p> |
| An Endpoint definition within Synapse defines an external service endpoint |
| and any attributes or semantics that should be followed when communicating |
| with that endpoint. An endpoint definition can be named for re-use, or |
| defined in-line or anonymously within a configuration. Typically an |
| endpoint would be based on a service Address or a WSDL. Additionally the |
| Synapse ESB supports Failover and Load-balance endpoints - which are |
| defined over a group of endpoints. Endpoints may be defined within the |
| synapse.xml configuration or within the Registry. |
| </p> |
| <h3> |
| <a href="#task">Tasks</a> |
| </h3> |
| <p> |
| A Task is a custom Java class that implements the |
| org.apache.synapse.task.Task interface that defines a single "public |
| void execute()" method. Such a task can be scheduled and managed via the |
| Synapse ESB. The scheduling information for a task can be specified in the |
| cron format or a simple format by the user. A task may also be specified |
| as a one-time task where required, and can be used to trigger a callout or |
| inject a message into the Synapse ESB. |
| </p> |
| <h3> |
| <a href="#registry">Remote Registry</a> and <a name="Local" |
| id="Local" href="#localEntry">Local Registry (Local Entries)</a> |
| </h3> |
| <p> |
| A Synapse configuration can refer to an external Registry / Repository for |
| resources used such as WSDL's, Schemas, Scripts, XSLT or XQuery |
| transformations etc. One or more remote registries may be hidden or merged |
| behind a local Registry interface defined to a Synapse configuration. |
| Resources from an external registry are looked up using "keys" - which are |
| known to the external registry. The Synapse ESB ships with a simple URL |
| based registry implementation that uses the file system for storage of |
| resources, and URL's or fragments as "keys". |
| </p> |
| <p> |
| A Registry may define a duration for which a resource served may be cached |
| by the Synapse runtime. If such a duration is specified, the Synapse ESB |
| is capable of refreshing the resource after cache expiry to support |
| dynamic re-loading of resource at runtime. Optionally, a configuration |
| could define certain "keys" to map to locally defined entities. These |
| entities may refer to a source URL or file, or defined as in-line XML or |
| text within the configuration itself. If a Registry contains a resource |
| whose "key" matches the key of a locally defined entry, the local entry |
| shadows the resource available in the Registry. Thus it is possible to |
| override Registry resources locally from within a configuration. To |
| integrate Synapse with a custom / new Registry or repository, one needs to |
| implement the org.apache.synapse.registry.Registry interface to suit the |
| actual Registry being used. |
| </p> |
| <h3> |
| <a href="#eventsource">Event Source</a> |
| </h3> |
| <p> |
| An Event Source use to define the Event Source and the Subscription Manager configurations |
| use in the eventing implementation of Synapse. Event source provides a service URL that can be |
| used to the send subscriptions and events (events that do not required to go through a |
| mediation flow). |
| |
| </p> |
| <h2> |
| The Axis2 Configuration (axis2.xml) |
| </h2> |
| <p> |
| The axis2.xml file configures the underlying Axis2 web services engine for |
| the Synapse ESB. The axis2.xml thus defines the transports enabled, and |
| other configuration parameters associated. A change to the axis2 |
| configuration requires a hard re-start of the Synapse ESB. By default the |
| non-blocking http/s and the Apache VFS file system based transport are |
| enabled for listening of messages, while the non-blocking http/s, VFS and |
| JMS transports are enabled for sending messages out. Sample configurations |
| to enable/configure the other transports are provided within the default |
| axis2.xml file, and can be easily uncommented and modified. The sample JMS |
| configuration shipped is for a default ActiveMQ 4.1.x installation. |
| </p> |
| <h2> |
| The contents of the Synapse.xml configuration |
| </h2> |
| <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="#task">task</a> name="string" ...>...</task>? |
| <<a href="#eventsource">eventsource</a> name="string" ...>...</eventsource>? |
| </definitions></pre> |
| <p/> |
| <p> |
| The <definitions> elements in a synapse.xml holds the Synapse ESB |
| configuration. While the <registry>, <sequence>, <endpoint>, |
| <proxy>, <task> and <localEntry> elements refer to those |
| discussed above, the built-in mediator elements names are already |
| registered with the Synapse engine. Custom mediators written by a user may |
| be included into the library directory, and would be dynamically picked up |
| in a Sun JDK environment. A list of mediators found directly as children |
| under the <definitions> element would be treated as the "main" |
| sequence, if a named sequence with the name "main" cannot be found. |
| </p> |
| <h2> |
| <a name="registry1" id="registry">Registry</a> |
| </h2> |
| <p> |
| The <registry> element is used to define the remote registry used by |
| the configuration. The registry provider specifies an implementation class |
| for the registry implementation used, and optionally a number of |
| configuration parameters as may be required for the configuration of the |
| connection to the registry. |
| </p> |
| <p>Registry schema can be found at <a href="./ns/2010/04/configuration/registry.xsd">here</a></p> |
| <pre xml:space="preserve"> <registry provider="string"/> |
| <parameter name="string">text | xml</parameter>* |
| </registry></pre> |
| <p> |
| Registry entries loaded from a remote registry may be cached as dictated |
| by the registry, and reloaded after the cache periods expires if a newer |
| version is found. Hence it is possible to define configuration elements |
| such as (dynamic) sequences and endpoints, as well as resources such as |
| XSLT's, Scripts or XSDs off the registry, and update the configuration as |
| these are allowed to dynamically change over time. |
| </p> |
| <p> |
| Synapse ships with a built-in URL based registry implementation called the |
| "SimpleURLRegistry" and this can be configured as follows: |
| </p> |
| <pre xml:space="preserve">e.g. |
| <registry provider="org.apache.synapse.registry.url.SimpleURLRegistry"> |
| <parameter name="root">file:./repository/conf/sample/resources/</parameter> |
| <parameter name="cachableDuration">15000</parameter> |
| </registry></pre> |
| <p> |
| The "root" parameter specifies the root URL of the Registry for loaded |
| resources. The SimpleURLRegistry keys are path fragments, that when |
| combined with the root prefix would form the full URL for the referenced |
| resource. The "cachableDuration" parameter specifies the number of |
| milliseconds for which resources loaded from the Registry should be |
| cached. More advanced registry implementations allows different cachable |
| durations to be specified for different resources, or mark some resources |
| as never expires. (e.g. Check the WSO2 ESB implementation built over the |
| Apache Synapse ESB core) |
| </p> |
| <p/> |
| <h3> |
| <a name="localEntry" id="localEntry">Local Registry / 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> |
| <p>Local entry schema can be found at <a href="./ns/2010/04/configuration/local_entry.xsd">here</a></p> |
| <pre xml:space="preserve"> <localEntry key="string" [src="url"]>text | xml</localEntry></pre> |
| <p> |
| These entries are top level entries which are globally visible within the |
| entire system. Values of these entries can be retrieved via the extension |
| XPath function "synapse:get-property(prop-name)" and the keys of these |
| entries could be specified wherever a registry key is expected within the |
| configuration. |
| </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). A local entry shadows any entry with the same name from a |
| remote Registry. |
| </p> |
| <pre xml:space="preserve">e.g. |
| <localEntry key="version">0.1</localEntry> |
| <localEntry key="validate_schema"> |
| <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" |
| ... |
| </xs:schema> |
| </localEntry> |
| <localEntry key="xslt-key-req" src="file:repository/conf/sample/resources/transform/transform.xslt"/></pre> |
| <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. The sequences named "main" and "fault" has |
| special significance in a Synapse configuration. The "main" sequence |
| handles any message that is accepted for '<a href="#message_mediation">Message |
| Mediation</a>', and the "fault" sequence is invoked if Synapse |
| encounters a fault, and a custom fault handler is not specified for the |
| sequence via its "onError" attribute. If the "main" or "fault" sequences |
| are not defined locally or not found in the Registry, the Synapse ESB |
| defines suitable defaults at initialization. |
| </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 according to the specified cache duration and |
| expiration. If tracing is enabled on a sequence, all messages being |
| processed through the sequence would write tracing information through |
| each mediation step to the trace.log file configured via the |
| log4j.properties configuration. Setting the trace log level to TRACE would |
| additionally dump the message and detailed trace information at each |
| mediation step. A tracing enabled sequence propagates this setting to |
| invoked sub-sequences. |
| </p> |
| <p>Sequence schema can be found at <a href="./ns/2010/04/configuration/sequence.xsd">here</a></p> |
| <pre xml:space="preserve"> <sequence name="string" [onError="string"] [key="string"] [trace="enable"]> |
| mediator* |
| </sequence></pre> |
| <pre xml:space="preserve">e.g. |
| <sequence name="main" onError="errorHandler"> |
| .. <!-- a 'main' sequence that invokes the sequence named 'errorHandler' on a fault --> .. |
| </sequence></pre> |
| <pre xml:space="preserve"><sequence key="sequence/dynamic_seq_1.xml"/> |
| where "sequence/dynamic_seq_1.xml" refers to the following sequence definition from the registry: |
| |
| <sequence name="dynamic_sequence" xmlns="http://ws.apache.org/ns/synapse"> |
| .. |
| </sequence></pre> |
| <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 balancing endpoint or a fail-over endpoint as follows: |
| </p> |
| <p>Endpoint schema can be found at <a href="./ns/2010/04/configuration/endpoint.xsd">here</a></p> |
| <pre xml:space="preserve"><endpoint [name="string"] [key="string"]> |
| <a href="#address-endpoint">address-endpoint</a> | <a href="#default-endpoint">default-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, and such named |
| endpoints can be reffered by other endpoints, through the key attribute. |
| For example if there is an endpoint named as "foo", the following endpoint |
| can be used in any place, where "foo" has to be used. |
| </p> |
| <pre xml:space="preserve"><endpoint key="foo"/></pre> |
| <p> |
| The "trace" attribute turns on detailed trace information for messages |
| being sent to the endpoint. These are available in the trace.log |
| configured via the log4j.properties file. Setting the trace log level to |
| TRACE will dump detailed trace information including message payloads. |
| </p> |
| <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. The '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> |
| Endpoint can be in one of the four states Active, TimeOut, Suspended and |
| Switch Off. Endpoint can be active which represent the Active state of the |
| endpoint. With the new endpoint enhancements there is possibility to retry |
| in case of endpoint invocation failure. This behavior can be configured |
| at the endpoint level through synapse endpoint API. Configuration is called |
| 'markForSuspension'. 'errorCodes' represent a list |
| of error codes. If these error codes are received from the endpoint, |
| the endpoint will be suspended. 'retriesBeforeSuspension' represents |
| the number of re-tries in case of a timeout, caused by the above listed error codes. |
| 'retryDelay' is the delay between re-tries, in milli seconds. If the endpoint |
| required to retry it is moved to TimeOut state. If the endpoint fails in |
| subsequent re-tries it'll move to Suspended state. If endpoint succeeded in |
| further re-tries it'll move into Active state. Suspended state defines |
| configuration 'suspendOnFailure'. 'initialDuration' represent the duration that the endpoint |
| is suspended for the first time after receiving the suspend error codes. |
| 'progressionFactor' is the duration to suspend can vary from the first time |
| suspension to the subsequent time. The factor value decides the suspense duration |
| variance between subsequent suspensions. 'maximumDuration' the maximum |
| duration that the endpoint is suspended after the receiving the suspend error codes. |
| Finally an endpoint can be in the Switch off state, where the endpoint is moved to |
| maintenance. State changes between Switch off and other states only can be done |
| manually through JMX based API that is provided. Endpoint which is in |
| 'Switch Off' state can only be moved to 'Active' state and it too can only be |
| done through JMX. |
| </p> |
| <p> |
| Address endpoints can timeout if responses fail to arrive at Synapse by a |
| predefined timeout-duration specified in seconds. The timeout responseAction |
| specifies whether to discard responses that arrive late, or to trigger a |
| fault. Synapse has a periodic timeout handler that triggers itself at each |
| 15 second interval. Thus endpoint timeouts will have a +/- error on actual |
| trigger time. Though this can be minimized by setting a System property |
| "synapse.timeout_handler_interval" to a millisecond duration below the |
| desired endpoint timeout, care must be taken as a lesser value may have a |
| higher overhead on the system. |
| </p> |
| <p> |
| An endpoint that fails may be suspended for a specified duration after |
| such a failure, during which new messages will not be processed through |
| the endpoint. The 'suspendDurationOnFailure' could specify an optional |
| value in seconds for which this endpoint should be suspended. |
| </p> |
| <p> |
| QoS aspects such as WS-RM and WS-Security and WS-Addressing may be enabled |
| on messages sent to an endpoint using the enableRM, enableSec and |
| enableAddressing elements. Optionally, the WS-RM and WS-Security policies |
| could be specified using the 'policy' attributes. |
| </p> |
| <pre xml:space="preserve"><address uri="<em>endpoint address</em>" [format="soap11|soap12|pox|get"] [optimize="mtom|swa"] |
| [encoding="<em>charset encoding</em>"] |
| [statistics="enable|disable"] [trace="enable|disable"]> |
| <enableRM [policy="<em>key</em>"]/>? |
| <enableSec [policy="<em>key</em>"]/>? |
| <enableAddressing [version="final|submission"] [separateListener="true|false"]/>? |
| |
| <timeout> |
| <duration><em>timeout duration in seconds</em></duration> |
| <responseAction>discard|fault</responseAction> |
| </timeout>? |
| |
| <markForSuspension> |
| [<errorCodes>xxx,yyy</errorCodes>] |
| <retriesBeforeSuspension>m</retriesBeforeSuspension> |
| <retryDelay>d</retryDelay> |
| </markForSuspension> |
| |
| <suspendOnFailure> |
| [<errorCodes>xxx,yyy</errorCodes>] |
| <initialDuration>n</initialDuration> |
| <progressionFactor>r</progressionFactor> |
| <maximumDuration>l</maximumDuration> |
| </suspendOnFailure> |
| </address></pre> |
| <p> |
| Following are some sample address URI definitions. |
| </p> |
| <table border="1" cellpadding="0" cellspacing="0" style="width: 100%; font-size:small" class="data-table"> |
| <tbody> |
| <tr><th>Transport</th><th>Sample address</th></tr> |
| <tr><td>HTTP</td><td><tt>http://localhost:9000/services/SimpleStockQuoteService</tt></td></tr> |
| <tr><td>JMS</td><td><tt>jms:/SimpleStockQuoteService?<br/> |
|    transport.jms.ConnectionFactoryJNDIName=QueueConnectionFactory&<br/> |
|    java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory&<br/> |
|    java.naming.provider.url=tcp://localhost:61616&<br/> |
|    transport.jms.DestinationType=topic</tt></td></tr> |
| <tr><td>Mail</td><td><tt>mailto:guest@host</tt></td></tr> |
| <tr><td>VFS</td><td><tt>vfs:file:///home/user/directory</tt></td></tr> |
| <tr><td/><td><tt>vfs:file:///home/user/file</tt></td></tr> |
| <tr><td/><td><tt>vfs:ftp://guest:guest@localhost/directory?vfs.passive=true</tt></td></tr> |
| </tbody> |
| </table> |
| <h4> |
| <a name="default-endpoint" id="default-endpoint">Default Endpoint</a> |
| </h4> |
| <p> |
| Default endpoint is an endpoint defined for adding QoS and other configurations |
| to the endpoint which is resolved from the 'To' address of the message context. |
| All the configurations such as message format for the endpoint, the method |
| to optimize attachments, reliable messaging, security policies for the endpoint |
| can be specified as in the Address Endpoint. This endpoint differs from the address |
| endpoint only in the uri attribute which will not be present in this endpoint. |
| Following section describes the configuration of a default endpoint |
| </p> |
| <pre xml:space="preserve"><default [format="soap11|soap12|pox|get"] [optimize="mtom|swa"] |
| [encoding="<em>charset encoding</em>"] |
| [statistics="enable|disable"] [trace="enable|disable"]> |
| <enableRM [policy="<em>key</em>"]/>? |
| <enableSec [policy="<em>key</em>"]/>? |
| <enableAddressing [version="final|submission"] [separateListener="true|false"]/>? |
| |
| <timeout> |
| <duration><em>timeout duration in seconds</em></duration> |
| <responseAction>discard|fault</responseAction> |
| </timeout>? |
| |
| <markForSuspension> |
| [<errorCodes>xxx,yyy</errorCodes>] |
| <retriesBeforeSuspension>m</retriesBeforeSuspension> |
| <retryDelay>d</retryDelay> |
| </markForSuspension> |
| |
| <suspendOnFailure> |
| [<errorCodes>xxx,yyy</errorCodes>] |
| <initialDuration>n</initialDuration> |
| <progressionFactor>r</progressionFactor> |
| <maximumDuration>l</maximumDuration> |
| </suspendOnFailure> |
| </default></pre> |
| <h4> |
| <a name="wsdl-endpoint" id="wsdl-endpoint">WSDL Endpoint</a> |
| </h4> |
| <p> |
| WSDL endpoint is an endpoint definition based on a specified WSDL |
| document. The WSDL document can be specified either as a URI or as an |
| inlined definition within the configuration. The service and port name |
| containing the target EPR has to be specified with the 'service' and |
| 'port' (or 'endpoint') attributes respectively. enableRM, enableSec, |
| enableAddressing, suspendDurationOnFailure and timeout elements are same |
| as for an 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/>? |
| |
| <timeout> |
| <duration>timeout-duration</duration> |
| <responseAction>discard|fault</responseAction> |
| </timeout>? |
| <markForSuspension> |
| [<errorCodes>xxx,yyy</errorCodes>] |
| <retriesBeforeSuspension>m</retriesBeforeSuspension> |
| <retryDelay>d</retryDelay> |
| </markForSuspension> |
| |
| <suspendOnFailure> |
| [<errorCodes>xxx,yyy</errorCodes>] |
| <initialDuration>n</initialDuration> |
| <progressionFactor>r</progressionFactor> |
| <maximumDuration>l</maximumDuration> |
| </suspendOnFailure> |
| |
| </wsdl></pre> |
| <h4> |
| <a name="load-balanced-endpoint" id="load-balanced-endpoint">Load |
| balanced Endpoint</a> |
| </h4> |
| <p> |
| A Load balanced endpoint distributes the messages (load) arriving at it |
| among a set of listed endpoints or static members by evaluating the load balancing policy |
| and any other relevant parameters. The policy attribute of the load balance |
| element specifies the load balance policy (algorithm) to be used for |
| selecting the target endpoint or static member. Currently only the roundRobin policy is |
| supported. The failover attribute determines if the next endpoint or static member should be |
| selected once the currently selected endpoint or static member has failed, and defaults to |
| true. The set of endpoints or static members amongst which the load has to be distributed |
| can be listed under the 'loadbalance' element. These 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 etc. The loadbalance element cannot have both endpoint & member child |
| elements in the same configuration. In the case of the member child element, the hostName, |
| httpPort and/or httpsPort attributes could be specified. |
| </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. Currently there are two types |
| of sessions supported in SAL endpoints. Namely HTTP transport based session |
| which identifies the sessions based on http cookies and the client session which |
| identifies the session by looking at a SOAP header sent by the client with the QName |
| '{http://ws.apache.org/ns/synapse}ClientID'. The 'failover' attribute mentioned above |
| is not applicable for session affinity based endpoints and it is always |
| considered as 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|simpleClientSession"/>? |
| <loadbalance [policy="roundRobin"] [algorithm="impl of org.apache.synapse.endpoints.algorithms.LoadbalanceAlgorithm"] |
| [failover="true|false"]> |
| <endpoint .../>+ |
| <member hostName="host" [httpPort="port"] [httpsPort="port2"]>+ |
| </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, the 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 inactive. 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> |
| |
| <h4> |
| <a name="dynamic-load-balanced-endpoint" id="dynamic-load-balanced-endpoint">Dynamic Load |
| balance Endpoint</a> |
| </h4> |
| <p> |
| A Dynamic Load balanced endpoint distributes the messages (load) arriving at it |
| among a application members by evaluating the load balancing policy |
| and any other relevant parameters. These application members will be discovered |
| using the membershipHandler class. Generally, this class will use a group |
| communication mechanism to discover the application members. The class attribute of the |
| membershipHandler element should be an implementation of |
| org.apache.synapse.core.LoadBalanceMembershipHandler. membershipHandler specific properties |
| can be specified using the property elements. The policy attribute of the |
| dynamicLoadbalance |
| element specifies the load balance policy (algorithm) to be used for |
| selecting the next member to which the message has to be forwaded to. |
| Currently only the roundRobin policy is |
| supported. The failover attribute determines if the next member should be |
| selected once the currently selected member has failed, and defaults to |
| true. |
| </p> |
| <!--TODO: Session affinity documentation--> |
| <pre xml:space="preserve"> |
| <dynamicLoadBalance [policy="roundRobin"] [failover="true|false"]> |
| <membershipHandler |
| class="impl of org.apache.synapse.core.LoadBalanceMembershipHandler"> |
| <property name="name" value="value"/>+ |
| </membershipHandler> |
| </dynamicLoadBalance> |
| </pre> |
| <h2> |
| <a name="proxy" id="proxy">Proxy service</a> |
| </h2> |
| <p> |
| A <proxy> element is used to define a Synapse Proxy service. |
| </p> |
| <p>Proxy service schema can be found at <a href="./ns/2010/04/configuration/proxy.xsd">here</a></p> |
| <pre xml:space="preserve"> <proxy name="string" [transports="(http |https |jms |.. )+|all"] [pinnedServers="(serverName )+"] [serviceGroup="string"]> |
| <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"> |
| ( <wsdl:definition>...</wsdl:definition> | <wsdl20:description>...</wsdl20:description> )? |
| <resource location="..." key="..."/>* |
| </publishWSDL>? |
| <enableAddressing/>? |
| <enableSec/>? |
| <enableRM/>? |
| <policy key="string" [type="(in | out)"]/>? // optional service or message level policies such as (e.g. WS-Security and/or WS-RM policies) |
| <parameter name="string"> // optional service parameters such as (e.g. transport.jms.ConnectionFactory) |
| string | xml |
| </parameter> |
| </proxy></pre> |
| <p> |
| A proxy service is created and exposed on the specified transports through |
| the underlying Axis2 engine, 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 such |
| as http/s) The Proxy service could be exposed over all enabled Axis2 |
| transports such as http, https, JMS, Mail and File etc. or on a subset of |
| these as specified with the optional 'transports' attribute. |
| </p> |
| <p> |
| You can give a list of Synapse server names where this proxy service |
| should be deployed using 'pinnedServers' attribute. It takes the server |
| names separated by comma or space character. If there is no pinned server |
| list then proxy service will be started in all server instances. If a |
| pinned server names list is given it will only start in the given named |
| Synapse server instances. The Synapse server name is picked up from the |
| system property 'SynapseServerName', failing which the hostname of the |
| machine would be used or default to 'localhost'. You can give a name to a |
| Synapse server instance as ./synapse.sh -serverName=<ServerName> |
| or by editing the wrapper.conf where Synapse is started as a service. |
| </p> |
| <p> |
| By default when a proxy service is created it is added to an Axis service |
| group which has the same name as the proxy service. With the 'serviceGroup' |
| attribute this behavior can be further configured. A custom Axis service |
| group can be specified for a proxy service using the 'serviceGroup' attribute. |
| This way multiple proxy services can be grouped together at Axis2 level |
| thus greeatly simplifying service management tasks. |
| </p> |
| <p> |
| 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, and a target outSequence defines how |
| responses should be handled. Any supplied WS-Policies would apply as |
| service level policies, and any service parameters could be passed into |
| the proxy services' AxisService instance using the parameter elements |
| (e.g. the JMS destination etc). If the proxy service should enable |
| WS-Reliable Messaging or Security, the appropriate modules could be |
| engaged, and specified service level policies will apply. |
| </p> |
| <p> |
| A Dynamic Proxy may be defined by specifying the properties of the proxy |
| as dynamic entries by refering them with the key. (For example one could |
| specify the inSequence or endpoint with a remote key, without defining it |
| in the local configuration) As the remote registry entry changes, the |
| properties of the proxy will dynamically be updated accordingly. (Note: |
| proxy service definition itself can not be specified to be dynamic; i.e |
| <proxy key="string"/> is wrong) |
| </p> |
| <p> |
| A WSDL for the proxy service can be published using the <publishWSDL> |
| element. The WSDL document can be loaded from the registry by |
| specifying the 'key' attribute or from any other location by specifying the |
| 'uri' attribute. Alternatively the WSDL can be provided inline as a child |
| element of <publishWSDL>. Artifacts (schemas or other WSDL documents) |
| imported by the WSDL can be resolved from the registry by specifying |
| appropriate <resource> elements: |
| </p> |
| <pre> <publishWSDL key="my.wsdl"> |
| <resource location="http://www.standards.org/standard.wsdl" key="standard.wsdl"/> |
| </publishWSDL> |
| </pre> |
| <p> |
| In this example the WSDL is retrieved from the registry using the key 'my.wsdl'. It |
| imports another WSDL from location 'http://www.standards.org/standard.wsdl'. Instead |
| of loading it from this location, Synapse will retrieve the imported WSDL from the |
| registry entry 'standard.wsdl'. |
| </p> |
| <p> |
| You can give the following as service parameters: |
| </p> |
| <table border="1" cellpadding="0" cellspacing="0" style="width: 100%; font-size:small" class="data-table"> |
| <caption/> |
| <tbody> |
| <tr> |
| <th> |
| Parameter |
| </th> |
| <th> |
| Value |
| </th> |
| <th> |
| Default |
| </th> |
| <th> |
| Description |
| </th> |
| </tr> |
| <tr> |
| <td> |
| useOriginalwsdl |
| </td> |
| <td> |
| true|false |
| </td> |
| <td> |
| false |
| </td> |
| <td> |
| Use the given WSDL instead of generating the WSDL. |
| </td> |
| </tr> |
| <tr> |
| <td> |
| modifyUserWSDLPortAddress |
| </td> |
| <td> |
| true|false |
| </td> |
| <td> |
| true |
| </td> |
| <td> |
| (Effective only with useOriginalwsdl=true) If true (default) modify |
| the port addresses to current host. |
| </td> |
| </tr> |
| <tr> |
| <td> |
| showAbsoluteSchemaURL |
| </td> |
| <td> |
| true|false |
| </td> |
| <td> |
| false |
| </td> |
| <td> |
| Show the absolute path of the referred schemas of the WSDL without |
| showing the relative paths. |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <p/> |
| <p> |
| Transport specific parameters that may be set as service parameters: |
| </p> |
| <table border="1" cellpadding="0" cellspacing="0" style="width: 100%; font-size:small" class="data-table"> |
| <caption/> |
| <tbody> |
| <tr> |
| <th> |
| Transport |
| </th> |
| <th> |
| Require |
| </th> |
| <th> |
| Parameter |
| </th> |
| <th> |
| Description |
| </th> |
| </tr> |
| <tr> |
| <td> |
| JMS |
| </td> |
| <td> |
| Optional |
| </td> |
| <td> |
| transport.jms.ConnectionFactory |
| </td> |
| <td> |
| The JMS connection factory definition (from axis2.xml) to be used to |
| listen for messages for this service |
| </td> |
| </tr> |
| <tr> |
| <td/> |
| <td> |
| Optional |
| </td> |
| <td> |
| transport.jms.Destination |
| </td> |
| <td> |
| The JMS destination name (Defaults to a Queue with the service name) |
| </td> |
| </tr> |
| <tr> |
| <td/> |
| <td> |
| Optional |
| </td> |
| <td> |
| transport.jms.DestinationType |
| </td> |
| <td> |
| The JMS destination type. Accept values 'queue' or 'topic' (default: |
| queue) |
| </td> |
| </tr> |
| <tr> |
| <td/> |
| <td> |
| Optional |
| </td> |
| <td> |
| transport.jms.ReplyDestination |
| </td> |
| <td> |
| The destination where a reply will be posted |
| </td> |
| </tr> |
| <tr> |
| <td/> |
| <td> |
| Optional |
| </td> |
| <td> |
| transport.jms.Wrapper |
| </td> |
| <td> |
| The wrapper element for the JMS message |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| <h2> |
| <a name="task" id="task">Tasks</a> |
| </h2> |
| <p> |
| A <task> element is used to define a Synapse Startup Task. |
| </p> |
| <p>Task schema can be found at <a href="./ns/2010/04/configuration/task.xsd">here</a></p> |
| <pre xml:space="preserve"> <task class="mypackage.MyTask" name="string" [pinnedServers="(serverName)+"]> |
| <property name="stringProp" value="String"/> |
| <property name="xmlProp"> |
| <somexml>config</somexml> |
| </property> |
| <trigger ([[count="10"]? interval="1000"] | [cron="0 * 1 * * ?"] | [once=(true | false)])/> |
| </task></pre> |
| <p> |
| A task is created and scheduled to run at specified time intervals or as |
| specified by the cron expression. The Task class specifies the actual task |
| implementation class (which must implement org.apache.synapse.task.Task |
| interface) to be executed at the specified interval/s, and name specifies |
| an identifier for the scheduled task. |
| </p> |
| <p> |
| Fields in the task class can be set using properties provided as string |
| literals or as XML fragments. (For example; if the task implementation |
| class has a field named "version" with a corresponding setter method, the |
| configuration value which will be assigned to this field before running |
| the task can be specified using a property with the name 'version') |
| </p> |
| <p> |
| There are three different trigger mechanisms to schedule tasks. A simple |
| trigger is specified specifying a 'count' and an 'interval', implying that |
| the task will run a 'count' number of times at specified intervals. A |
| trigger may also be specified as a cron trigger using a cron expression. A |
| one-time trigger is specified using the 'once' attribute as true in the |
| definition and could be specified as true in which case this task will be |
| executed only once just after the initialization of Synapse |
| </p> |
| <p> |
| You can give a list of Synapse server names where this task should be |
| started using pinnedServers attribute. Refer to the explanation of this |
| attribute under proxy services for more information. |
| </p> |
| <h2> |
| <a name="eventsource" id="eventsource">Event Source</a> |
| </h2> |
| <p> |
| A <eventSource> element is used to define a Synapse event source. |
| </p> |
| <p>Event source schema can be found at <a href="./ns/2010/04/configuration/event_source.xsd">here</a></p> |
| <pre xml:space="preserve"><eventSource name="string"> |
| <subscriptionManager class="mypackage.MyClass"> |
| <parameter name="string"/> |
| </subscriptionManager> |
| </eventSource></pre> |
| <p> |
| An event source required to implement eventing in Synpase. Event source used to inject |
| subscription messages in to Synpase and provide a service URL for the users to send subscriptions |
| to Synapse. User can send messages to manage the subscriptions (unsubscribe, renew, get-status) |
| to the event source. |
| </p> |
| <p> |
| Subscription manager configured inside the event source will be responsible to hold the subscriptions, |
| and provide operations to manage the subscriptions. Subscription storage will decide |
| based on the implementation of the subscription manager , e.g. Registry, memory, database. |
| Additional information required to setup the subscription manager can be set as properties. |
| </p> |
| <h2> |
| <a name="mediator" id="mediator">Mediators</a> |
| </h2> |
| <p> |
| A mediator token refers to any of the following tokens: |
| </p> |
| <p> |
| <a href="#send">send</a> | <a href="#drop">drop</a> | <a href="#log">log</a> | <a href="#property">property</a> | <a href="#sequence_ref">sequence</a> | <a href="#validate">validate</a> | <a href="#Callout">Callout</a> | <a href="#makefault">makefault</a> | <a href="#xslt">xslt</a> | <a href="#xquery">xquery</a> | <a href="#rewrite">rewrite</a> | <a href="#header">header</a> | <a href="#filter">filter</a> | <a href="#switch">switch</a> | <a href="#in">in</a> | <a href="#out">out</a> |
| | <a href="#dblookup">dblookup</a> | <a href="#dbreport">dbreport</a> | <a href="#throttle">throttle</a> | <a href="#cache">cache</a> | <a href="#clone">clone</a> | <a href="#iterate">iterate</a> | <a href="#aggregate">aggregate</a> | <a href="#class">class</a> | <a href="#pojoCommand">pojoCommand</a> | <a href="#spring">spring</a> | <a href="#script">script</a> | <a href="#RMSequence">RMSequence</a> | <a href="#eventPublisher">eventPublisher</a> | <a href="#transaction">transaction</a> |
| |
| </p> |
| <p> |
| In addition to the above, Synapse will be able to load custom mediators |
| via the J2SE Service Provider model. Mediator extensions must implement |
| the MediatorFactory interface. The Class and POJO Command mediators allow |
| custom Java code to be easily invoked during mediation, while the Script |
| mediator allows Apache BSF scripts such as Javascript, Ruby, Groovy etc to |
| be used for mediation. |
| </p> |
| <p>All mediator schema can be found at <a href="./ns/2010/04/configuration/mediators/">here</a></p> |
| <h3> |
| Core Mediators |
| </h3> |
| <h4> |
| <a name="send" id="send">Send</a> |
| </h4> |
| <p> |
| 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) |
| </p> |
| <p> |
| 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) |
| </p> |
| <p> |
| <strong>Note:</strong> 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. |
| </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 definition. |
| </p> |
| <p/> |
| <h4> |
| <a name="drop" id="drop">Drop</a> |
| </h4> |
| <p> |
| The drop token refers to a <drop> element which is used to stop |
| further processing of a message: |
| </p> |
| <pre xml:space="preserve"> <drop/></pre> |
| <p> |
| Once the <drop> mediator executes, further processing of the current |
| message stops. A the drop mediator does not necessarily close transports. |
| </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 separate 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] [type="string"] (value="literal" | expression="xpath") [scope=transport|axis2|axis2-client] [pattern="regex" [group="integer"]]> |
| <xml-element/>? |
| </property></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 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. |
| </p> |
| <p> |
| If a pattern is specified, this regular expression will be applied on |
| top of the value of the property. If group number is specified the matching |
| group will be set as the value of the property. If group is not specified, |
| it defaults to 0. If a patter is specified and it is not matched, the |
| value will be set to empty string. |
| </p> |
| <p> |
| Using the type attribute one can set properties with specific types on |
| the message context. Currently the type attribute accepts following |
| data types. |
| </p> |
| <ul> |
| <li>STRING</li> |
| <li>BOOLEAN</li> |
| <li>DOUBLE</li> |
| <li>FLOAT</li> |
| <li>INTEGER</li> |
| <li>LONG</li> |
| <li>SHORT</li> |
| <li>OM</li> |
| </ul> |
| <p> |
| The type names are case sensitive. If a type is not explicitly specified |
| properties will be set as string values. Type 'OM' can be used to set XML |
| property values on the message context. This becomes useful when the expression |
| associated with the property mediator evaluates to an XML value during mediation. |
| With the type attribute set to 'OM' the resulting XML will be converted to |
| an AXIOM OMElement before setting it to the message context. |
| </p> |
| <p> |
| You can use the property mediator to set fixed XML property values on the |
| message context too. To do that instead of specifying a 'value' attribute |
| specify the XML property value as a child element of the property element. |
| The type attribute has no significance in this situation as the type of the |
| property value is always 'OM'. |
| </p> |
| <p> |
| There are some well-defined properties that you can get/set on the Synapse |
| message context scope: |
| </p> |
| <ul> |
| <li> |
| RESPONSE - 'true' means the message is to be marked as a response |
| message |
| </li> |
| <li> |
| OUT_ONLY - 'true' means the message is to be marked as an out-only |
| message that does not expect a response |
| </li> |
| <li> |
| ERROR_CODE - this is set to any error message code encountered during a |
| fault |
| </li> |
| <li> |
| ERROR_MESSAGE - this is set to any error message text encountered during |
| a fault |
| </li> |
| <li> |
| ERROR_DETAIL - this is set to any error message detail text encountered |
| during a fault |
| </li> |
| <li> |
| ERROR_EXCEPTION - this is set to any Java Exception encountered during a |
| fault |
| </li> |
| </ul> |
| <p> |
| There are some Axis2 and module properties that are useful which are set |
| at scope="axis2" |
| </p> |
| <ul> |
| <li> |
| Mercury2SequenceKey - can be an identifier specifying a Mercury |
| internal sequence key, and |
| </li> |
| <li> |
| Mercury2LastMessage - 'true' will make this the last message and |
| terminate the sequence |
| </li> |
| <li> |
| FORCE_HTTP_1.0 - forces outgoing http/s messages to use HTTP 1.0 |
| (instead of the default 1.1) |
| </li> |
| <li> |
| POST_TO_URI - forces outgoing http/s messages to use the full URI |
| in a POST (instead of the default PATH) |
| </li> |
| </ul> |
| <h5> |
| The synapse:get-property() XPath extension function |
| </h5> |
| <p> |
| The get-property() function allows any XPath expression used in a |
| configuration to lookup information from the current message context. It |
| is possible to retrieve properties previously set with the property |
| mediator, and/or information from the Synapse or Axis2 message contexts or |
| transport header. The function accepts the scope as an optional parameter |
| as shown below: |
| </p> |
| <p> |
| synapse:get-property( [(axis2 | axis2-client | transport),] <property_name> |
| [,<dateformat>] ) |
| </p> |
| <p/> |
| <p> |
| Some useful properties from the Synapse message context follows: |
| </p> |
| <ul> |
| <li> |
| SYSTEM_DATE - Returns the current date as a String. Optionally a date |
| format as per standard date format may be supplied. e.g. |
| synapse:get-property("SYSTEM_DATE", "yyyy.MM.dd G 'at' HH:mm:ss z") or |
| get-property('SYSTEM_DATE') |
| </li> |
| <li> |
| SYSTEM_TIME - Returns the current time in milliseconds. (i.e. the |
| difference, measured in milliseconds, between the current time and |
| midnight, January 1, 1970 UTC) |
| </li> |
| <li> |
| To, From, Action, FaultTo, ReplyTo, MessageID the message To and Action |
| and WS-Addressing properties |
| </li> |
| <li> |
| MESSAGE_FORMAT - returns the message format - i.e. returns pox, get, |
| soap11 or soap12 |
| </li> |
| <li> |
| OperationName - returns the operation name for the message |
| </li> |
| <li> |
| OperationNamespace - returns the namespace of the operation for the message |
| </li> |
| </ul> |
| <p> |
| In addition to the above, one may use the get-property() function to |
| retrieve Axis2 message context properties or transport headers. e.g. |
| synapse:get-property('transport', 'USER_AGENT') |
| </p> |
| <h5> |
| SynapseXpath variables |
| </h5> |
| <p> |
| There are a set of predefined XPath variables when writing XPaths in |
| the Synapse Configuration. Those are as follows; |
| </p> |
| <ul> |
| <li> |
| body - The SOAP 1.1 or 1.2 body element |
| </li> |
| <p> |
| For example; expression="$body/getQuote" refers to the first |
| getQuote element in the SOAP body regardless of whether the message |
| is SOAP-11 or SOAP-12 |
| </p> |
| <li> |
| header - The SOAP 1.1 or 1.2 header element |
| </li> |
| <p> |
| For example; expression="$header/wsa:To" refers to the addressing |
| To header regardless of whether this message is SOAP-11 or SOAP-12 |
| </p> |
| </ul> |
| <p> |
| Further there are some variable prefixes defined in Synapse XPaths |
| which can be usefull in writing the configurations; |
| </p> |
| <ul> |
| <li> |
| ctx - Prefix for Synapse MessageContext properties |
| </li> |
| <p> |
| For example; expression="$ctx:RESPONSE" gives the value of the |
| Synapse message context property with name 'RESPONSE' |
| </p> |
| <li> |
| axis2 - Prefix for Axis2 MessageContext properties |
| </li> |
| <p> |
| For example; expression="$axis2:messageType" gives the value of the |
| axis2 message context property with name 'messageType' |
| </p> |
| <li> |
| trp - Prefix for the transport headers |
| </li> |
| <p> |
| For example; expression="$trp:Content-Type" gives the value of the |
| 'Content-Type' transport header, which is going to be the |
| Content-Type of the current message |
| </p> |
| </ul> |
| <h4> |
| <a name="sequence_ref" id="sequence_ref">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 <a |
| href="http://xerces.apache.org/xerces2-j/features.html">http://xerces.apache.org/xerces2-j/features.html</a>) |
| </p> |
| <p/> |
| <h4> |
| <a name="Callout" id="Callout">Callout</a> |
| </h4> |
| <pre xml:space="preserve"> <callout serviceURL="string" [action="string"]> |
| <configuration [axis2xml="string"] [repository="string"]/>? |
| <source xpath="expression" | key="string"> |
| <target xpath="expression" | key="string"/> |
| </callout> |
| </pre> |
| <p> |
| The <callout> mediator performs a blocking external service invocation during |
| mediation. The serviceURL and the optional action specifies the parameters for this external |
| call. The source element specifies the payload for the request message using an XPath expression; |
| or a registry key that will be used. The target element specifies a node, at which the resulting |
| payload will be attached into the current message, or the name of a key/property using which |
| the response would be attached to the current message context as a property. |
| </p> |
| <p>As the callout mediator performs a blocking call, it cannot use the default non-blocking http/s |
| transports based on Java NIO, and thus defaults to using the samples/axis2Client/client_repo/conf/axis2.xml |
| as the Axis2 configuration, and samples/axis2Client/client_repo as the client repository unless |
| these are specified separately |
| </p> |
| <h3> |
| Transformation Mediators |
| </h3> |
| <h4> |
| <a name="makefault" id="makefault">Makefault</a> |
| </h4> |
| <pre xml:space="preserve"> <makefault [version="soap11|soap12|pox"] [response="true|false"]> |
| <code (value="literal" | expression="xpath")/> |
| <reason (value="literal" | expression="xpath")/> |
| <node>...</node>? |
| <role>...</role>? |
| (<detail expression="xpath"/> | <detail>...</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 "Fault-To" of the original message if such a header |
| exists on the original message. If a 'version' attribute is specified, |
| the created fault message will be created as a selected SOAP 1.1, SOAP |
| 1.2 or POX fault. At the same time if you specify the optional response |
| attribute value as 'true' makefault will mark the mesage as a response |
| regardless of whether the message is a request or a response. |
| The optional <node>, <role> and <detail> directives can |
| be used to set the corresponding elements in the resulting SOAP fault. |
| </p> |
| <p/> |
| <h4> |
| <a name="xslt" id="xslt">XSLT</a> |
| </h4> |
| <pre xml:space="preserve"> <xslt key="string" [source="xpath"] [target="string"]> |
| <property name="string" (value="literal" | expression="xpath")/>* |
| <feature name="string" value="true | false" />* |
| <attribute name="string" value="string" />* |
| <resource location="..." key="..."/>* |
| </xslt></pre> |
| <p> |
| 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. |
| If no 'target' attribute is specified, the source node will be replaced |
| with the output of the transformation. Otherwise the output will be stored in |
| the specified property. |
| </p> |
| <p> |
| If the output method specified by the stylesheet is text (i.e. the stylesheet |
| has the following directive: <tt><xsl:output method="text"/></tt>), |
| then the output of the transformation is wrapped in an element with name |
| <tt>{http://ws.apache.org/commons/ns/payload}text</tt>. Note that when an |
| element with this name is present as the first child of the SOAP body of an |
| outgoing message, the JMS and VFS transports will automatically unwrap the |
| content and send it out as plain text. The XSLT mediator can therefore be used |
| for integration with systems relying on plain text messages. |
| </p> |
| <p> |
| Stylesheet parameters can be passed into the transformations through the |
| 'property' elements. |
| </p> |
| <p> |
| The 'feature' element defines any features which |
| should be explicitly set to the TransformerFactory. 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. |
| </p> |
| <p> |
| The 'attribute' element allows to define attributes which should be explicitly |
| set to the TransformerFactory. |
| </p> |
| <p> |
| Finally, the 'resource' element can be used to resolve XSLT imports and includes from the |
| repository. It works in exactly the same way as the corresponding element in a |
| <proxy> definition. |
| </p> |
| <h4> |
| <a name="xquery" id="xquery">XQuery</a> |
| </h4> |
| <pre xml:space="preserve"><xquery key="string" [target="xpath"]> |
| <variable name="string" type="string" [key="string"] [expression="xpath"] [value="string"]/>? |
| </xquery> </pre> |
| <p/> |
| <p> |
| 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 . |
| </p> |
| <p> |
| 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). |
| </p> |
| <p> |
| The supported types are: |
| </p> |
| <ul> |
| <li> |
| XQItemType.XQBASETYPE_INT -> INT |
| </li> |
| <li> |
| XQItemType.XQBASETYPE_INTEGER -> INTEGER |
| </li> |
| <li> |
| XQItemType.XQBASETYPE_BOOLEAN -> BOOLEAN |
| </li> |
| <li> |
| XQItemType.XQBASETYPE_BYTE - > BYTE |
| </li> |
| <li> |
| XQItemType.XQBASETYPE_DOUBLE -> DOUBLE |
| </li> |
| <li> |
| XQItemType.XQBASETYPE_SHORT -> SHORT |
| </li> |
| <li> |
| XQItemType.XQBASETYPE_LONG -> LONG |
| </li> |
| <li> |
| XQItemType.XQBASETYPE_FLOAT -> FLOAT |
| </li> |
| <li> |
| XQItemType.XQBASETYPE_STRING -> STRING |
| </li> |
| <li> |
| XQItemType.XQITEMKIND_DOCUMENT -> DOCUMENT |
| </li> |
| <li> |
| XQItemType.XQITEMKIND_DOCUMENT_ELEMENT -> DOCUMENT_ELEMENT |
| </li> |
| <li> |
| XQItemType.XQITEMKIND_ELEMENT -> ELEMENT |
| </li> |
| </ul> |
| <p/> |
| <h4> |
| <a name="rewrite" id="rewrite">URLRewrite</a> |
| </h4> |
| <pre xml:space="preserve"><rewrite [inProperty="string"] [outProperty="string"]> |
| <rule> |
| <condition> |
| ... |
| </condition>? |
| <action [type="append|prepend|replace|remove|set"] [value="string"] |
| [xpath="xpath"] [fragment="protocol|host|port|path|query|ref|user|full"] [regex="regex"]>+ |
| </rule>+ |
| </rewrite></pre> |
| <p/> |
| <p> |
| The URL rewrite mediator is used to modify and transform the URL values available |
| in the message. By default the mediator will take the 'To' header of the message and |
| apply the provided rewrite rules on it. Alternatively one can specify a property name |
| in the 'inProperty' attribute, in which case the mediator will take the value of the |
| specified property as the input URL. Similarly the mediator by default sets the transformed |
| URL as the 'To' header of the message. Alternatively you can use the 'outProperty' |
| attribute to instruct the mediator to set the resulting URL as a property. |
| </p> |
| <p> |
| The rewrite mediator applies URL transformations by evaluating a set of rules on |
| the message. Rules are specified using the 'rule' element. Rules are evaluated in the |
| order they are specified. A rule can consist of an optional condition and one or more |
| rewrite actions. If the condition is provided it will be evaluated first. If it evaluates |
| to 'true' all the specified rewrite actions will be executed. Otherwise the set of |
| actions will be skipped. If no condition is specified, the provided rewrite actions |
| will be always executed. The condition should be wrapped in a 'condition' element within |
| the 'rule' element. Rewrite actions are specified using 'action' elements. |
| </p> |
| <p> |
| The 'type' attribute on the 'action' element states which type of action should be |
| executed on the URL. This defaults to 'set' value. The 'fragment' attribute can be |
| used to specify the URL fragment on which the action should be executed. If not specified |
| this will be taken as 'full' URL, which is the complete URL. The value to 'set', 'append' |
| or 'prepend' must be specified using either the 'value' attribute or the 'xpath' attribute. |
| One of these two attributes are always needed unless the value of the 'type' attribute is |
| set to 'remove'. When the 'type' is set to 'replace' an additional 'regex' attribute must |
| be specified which indicates the portion that should be replaced with the given value. |
| </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 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. |
| </p> |
| <p> |
| The value of the 'name' attribute must be one of the following aliases or |
| a valid QName with a namespace prefix. (In the latter case the namespace prefix |
| must be mapped to a valid namespace URI using the standard xmlns attribute) |
| </p> |
| <ul> |
| <li>To</li> |
| <li>From</li> |
| <li>Action</li> |
| <li>FaultTo</li> |
| <li>ReplyTo</li> |
| <li>RelatesTo</li> |
| </ul> |
| <p/> |
| <h3> |
| Selection Mediators |
| </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 as a String against the given regular expression. If the test |
| succeeds, the filter mediator will execute the enclosed mediators in |
| sequence. |
| </p> |
| <p>One could also use this mediator to handle the failure case as well, in which case the |
| configuration would be as follows |
| </p> |
| <pre xml:space="preserve"> <filter (source="xpath" regex="string") | xpath="xpath"> |
| <then [sequence="string"]> |
| mediator+ |
| </then> |
| <else [sequence="string"]> |
| mediator+ |
| </else> |
| </filter></pre> |
| <p>In this case the filter condition remains as earlier and the succeeded messages will be |
| mediated using the the set of mediators enclosed in the 'then' element in sequence, while |
| failed messages will be mediated using the set of mediators enclosed in the else element |
| 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> |
| Database Mediators |
| </h3> |
| <h4> |
| <a name="dblookup" id="dblookup">DB-lookup</a> |
| </h4> |
| <pre xml:space="preserve"><dblookup> |
| <connection> |
| <pool> |
| ( |
| <driver/> |
| <url/> |
| <user/> |
| <password/> |
| <property name="name" value="value"/>* |
| | |
| <dsName/> |
| | |
| <dsName/> |
| <icClass/> |
| <url/> |
| <user/> |
| <password/> |
| ) |
| </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></pre> |
| <p/> |
| <p> |
| 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: |
| </p> |
| <ul> |
| <li> |
| autocommit = true | false |
| </li> |
| <li> |
| isolation = Connection.TRANSACTION_NONE | |
| Connection.TRANSACTION_READ_COMMITTED | |
| Connection.TRANSACTION_READ_UNCOMMITTED | |
| Connection.TRANSACTION_REPEATABLE_READ | |
| Connection.TRANSACTION_SERIALIZABLE |
| </li> |
| <li> |
| initialsize = int |
| </li> |
| <li> |
| maxactive = int |
| </li> |
| <li> |
| maxidle = int |
| </li> |
| <li> |
| maxopenstatements = int |
| </li> |
| <li> |
| maxwait = long |
| </li> |
| <li> |
| minidle = int |
| </li> |
| <li> |
| poolstatements = true | false |
| </li> |
| <li> |
| testonborrow = true | false |
| </li> |
| <li> |
| testonreturn = true | false |
| </li> |
| <li> |
| testwhileidle = true | false |
| </li> |
| <li> |
| validationquery = String |
| </li> |
| </ul> |
| <p> |
| 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. |
| </p> |
| <h4> |
| <a name="dbreport" id="dbreport">DB-report</a> |
| </h4> |
| <pre xml:space="preserve"><dbreport useTransaction=(true|false)> |
| <connection> |
| <pool> |
| ( |
| <driver/> |
| <url/> |
| <user/> |
| <password/> |
| <property name="name" value="value"/>* |
| | |
| <dsName/> |
| | |
| <dsName/> |
| <icClass/> |
| <url/> |
| <user/> |
| <password/> |
| ) |
| </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></pre> |
| <p/> |
| <p> |
| The dbreport mediator is very similar to the dblookup mediator, but writes |
| information to a Database, using the specified insert SQL statement. |
| </p> |
| <p/> |
| <h3> |
| Advanced Mediators |
| </h3> |
| <h4> |
| <a name="throttle" id="throttle">Throttle</a> |
| </h4> |
| <pre xml:space="preserve"><throttle [onReject="string"] [onAccept="string"] id="string"> |
| (<policy key="string"/> | <policy>..</policy>) |
| <onReject>..</onReject>? |
| <onAccept>..</onAccept>? |
| </throttle></pre> |
| <p/> |
| <p> |
| 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. |
| </p> |
| <h4> |
| <a name="cache" id="cache">Cache</a> |
| </h4> |
| <pre xml:space="preserve"> <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></pre> |
| <p> |
| 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. |
| </p> |
| <h3> |
| EIP Mediators |
| </h3> |
| <h4> |
| <a name="clone" id="clone">Clone</a> |
| </h4> |
| <pre xml:space="preserve"> <clone [continueParent=(true | false)]> |
| <target [to="uri"] [soapAction="qname"] [sequence="sequence_ref"] [endpoint="endpoint_ref"]> |
| <sequence> |
| (mediator)+ |
| </sequence>? |
| <endpoint> |
| endpoint |
| </endpoint>? |
| </target>+ |
| </clone></pre> |
| <p> |
| 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 |
| </p> |
| <h4> |
| <a name="iterate" id="iterate">Iterate</a> |
| </h4> |
| <pre xml:space="preserve"> <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></pre> |
| <p> |
| 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. |
| </p> |
| <h4> |
| <a name="aggregate" id="aggregate">Aggregate</a> |
| </h4> |
| <pre xml:space="preserve"> <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></pre> |
| <p> |
| 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. |
| </p> |
| <h3> |
| Extension mediators |
| </h3> |
| <h4> |
| <a name="class" id="class">Class</a> |
| </h4> |
| <pre xml:space="preserve"> <class name="class-name"> |
| <property name="string" value="literal"> |
| (either literal or XML child) |
| </property> |
| </class> </pre> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h4> |
| <a name="pojoCommand" id="pojoCommand">POJOCommand</a> |
| </h4> |
| <pre xml:space="preserve"> <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> </pre> |
| <p> |
| 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. |
| </p> |
| <p/> |
| <h3> |
| <a name="script" id="script">Scripting language mediators</a> |
| </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> |
| If the script you specified is calling a function defined in another script, |
| then the latter script should also be included in the script mediator |
| configuration. It's done using the <include> element. The key attribute of the |
| <include> element should point to the script which has to be included. The included |
| script could be stored as a local entry or in the remote registry. |
| Script includes are defined as follows: |
| </p> |
| <pre xml:space="preserve"> <script key="string" language="string" [function="script-function-name"]> |
| <include key="string"/> |
| </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. |
| The complete list of available methods can be found in the |
| <a href="apidocs/org/apache/synapse/mediators/bsf/ScriptMessageContext.html">ScriptMessageContext Javadoc</a>. |
| </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> |
| <a name="spring" id="spring">Spring mediator</a> |
| </h4> |
| <pre xml:space="preserve"> <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> |
| |
| <h3> |
| Other Mediators |
| </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> |
| <h4> |
| <a name="eventPublisher" id="eventPublisher">eventPublisher</a> |
| </h4> |
| <pre xml:space="preserve"> <eventPublisher eventSourceName="string"/></pre> |
| <p> |
| The <eventPublisher> mediator use to send events to the subscribers that match |
| the given filter criteria. A pre defined event source need to be provided with the mediator. |
| </p> |
| <p>The eventPublisher mediator handover the event to the defined event source in the mediator |
| and event source picks the valid subscriptions from the subscription manager |
| by applying the define filter. |
| Any mediation required before dispatching the events can be done by adding |
| mediators using sequences before the eventPublisher mediator. Quality of service like security |
| can add to the events by applying QOS to the proxy service that holds the eventPublisher mediator. |
| </p> |
| |
| <h4> |
| <a name="transaction" id="transaction">Transaction</a> |
| </h4> |
| <pre xml:space="preserve"><transaction action="new|use-existing-or-new|fault-if-no-tx|commit|rollback|suspend|resume"/> |
| </pre> |
| <p>The action attribute has the following meanings.</p> |
| <ol> |
| <li>1. new - Create a new jta transaction. Generate a fault if a transaction already exist. |
| </li> |
| <li>2. use-existing-or-new - Create a new jta transaction. Do nothing if a transaction exist. |
| </li> |
| <li>3. fault-if-no-tx - Generate a fault if no transaction exist. Do nothing if a transaction |
| exist. |
| </li> |
| <li>4. commit - Commit transaction. Generate a fault if no transaction exist.</li> |
| <li>5. rollback - Rollback transaction. Generate a fault if no transaction exist.</li> |
| <li>6. suspend - Suspend transaction. Generate a fault if no transaction exist.</li> |
| <li>7. resume - Resume transaction. Generate a fault if no transaction exist.</li> |
| </ol> |
| |
| <p> |
| The transaction mediator can use to define a distributed transaction. It has the |
| transaction markers which can be used to mark the start and end of |
| a transaction. Transaction mediator required a JTA provider in the system to work. |
| </p> |
| |
| <p/> |
| <p/> |
| </div> |
| </body> |
| </document> |
| |