<?xml version="1.0" encoding="iso-8859-1"?>
<!--
  ~  Copyright (c) 2005-2008, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
  ~
  ~  WSO2 Inc. licenses this file to you under the Apache License,
  ~  Version 2.0 (the "License"); you may not use this file except
  ~  in compliance with the License.
  ~  You may obtain a copy of the License at
  ~
  ~    http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~  Unless required by applicable law or agreed to in writing,
  ~  software distributed under the License is distributed on an
  ~  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  ~  KIND, either express or implied.  See the License for the
  ~  specific language governing permissions and limitations
  ~  under the License.
  ~
  -->
<!DOCTYPE html
     PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=iso-8859-1"/>
  <title>
      WSO2 ESB - Mediator Catalog
  </title>
  <link href="css/esb-docs.css" rel="stylesheet" />
  <link href="styles/dist-docs.css" rel="stylesheet" type="text/css"
  media="all" />
</head>

<body xml:lang="en">
    [ <a href="docs_index.html"> Documentation Index </a> ]
<h1>WSO2 Enterprise Service Bus (ESB) Mediator Catalog</h1>
    <p>Mediators are the basic component of a mediation framework and the WSO2 ESB has a
        comprehensive set of mediators. This guide will walk you through the genral concept of
        mediation inside the WSO2 ESB and will also describe each and every mediator shipped with
        WSO2 ESB, one by one</p>
<h2>Contents</h2>
<ul>
    <li><a href="#Intro">Introduction</a></li>
    <li><a href="#HowMediatorWorks">How does a mediator work?</a></li>
    <li><a href="#Sequences">Sequences</a>
        <ul>
            <li><a href="#InLineSequence">In-line Sequences</a></li>
            <li><a href="#NamedSequence">Named Sequences</a></li>
        </ul>
    </li>
    <li><a href="#HowMessageMediate">How does a message comes to a mediator?</a>
        <ul>
            <li><a href="#MessageMediation">Message Mediation</a></li>
            <li><a href="#ProxyServices">Proxy Services</a></li>
        </ul>
    </li>
    <li><a href="#MediatorCatalog">The Mediator Catalog</a></li>
</ul>
<h2 id="Intro">Introduction</h2>
<p>Message mediation is a fundamental part of any ESB. WSO2 ESB achieves
message mediation through it's mediators. ESB comes with a rich set of 30 plus
mediators to support the most common mediation functionalities as well as
advanced functionalities.</p>

<p>Built in mediator capabilities of ESB provide functionality to match
incompatible protocols, data formats and interaction patterns across different
resources. Data can be split, cloned, aggregated and enriched, allowing ESB to
match the different capabilities of services. XQuery and XSLT allows rich
transformations on the messages. Rule based message mediation allows user to
cope with the uncertainty of business logic. Content based routing using XPath
filtering is supported in different flavors, allowing users to get the most
convenient configuration experience. Built in capability to handle transactions
allows message mediation to be done transactionally inside the ESB. With the
Eventing capabilities of ESB, EDA based components can be easily
interconnected. With features like throttling and caching integrated in to the
message mediation, powerful interconnections can be made, allowing ESB to be
used in the front end of organizations SOA infrastructure.</p>

<p>ESB mediation framework is designed from the ground up to be extensible.
Everyday users write their own custom mediators to facilitate their custom
requirements. </p>

<p>Now let's briefly look at how the mediation framework works. </p>

<h2 id="HowMediatorWorks">How does a mediator work?</h2>

<p>A mediator is a full powered processing unit in ESB. In run-time it has
access to all the parts of ESB along with the current message. Usually a
mediator is configured using XML. Different mediators have their own XML
configurations. </p>

<p>At the run-time a Message is injected in to the mediator with the ESB
run-time information. Then this mediator can do virtually anything with the
message. Here are some examples of mediator functionalities. </p>
<ul>
  <li><a href="mediators/drop.html">Drop Mediator</a> : Drops a message, stopping further processing of the
    message</li>
  <li><a href="mediators/send.html">Send Mediator</a> : Send the message out, using information inside the
    message or according to some external configuration</li>
  <li><a href="mediators/script.html">Script Mediator</a> : Executes a scripting language with the message</li>
  <li><a href="mediators/filter.html">Filter Mediator</a> : Filter messages using XPath</li>
  <li><a href="mediators/xslt.html">XSLT Mediator</a> : Do XSLT transformations on messages </li>
</ul>

<p>Wide range usage of mediators is visible through the above few examples.</p>

<p>Also mediators are considered as one of the main mechanisms for extending
ESB. A user can write a mediator and put it in to ESB. This custom mediator and
any other built in mediator will be exactly same from the API and the
privileges.</p>

<h2 id="Sequences">Sequences</h2>

<p>Sequence is a List Mediator of the ESB. That means it can hold other
mediators and execute them. It is a part of the core of ESB and message
mediation cannot live without this mediator. When a message is delivered to a
sequence, it sends the message through all it's child mediators.</p>

<p>There are two types of sequences.</p>

<h3 id="InLineSequence">In-line Sequences</h3>

<p>&lt;sequence name="string"&gt;other mediators&lt;/sequence&gt;</p>

<p>In-line sequences has their child mediators defined inside the sequence
itself.</p>

<h3 id="NamedSequence">Named Sequences</h3>

<p>&lt;sequence key="name"/&gt;</p>

<p>Named sequences refer other sequences using a key. This allows re-using of
sequences.</p>

<p>There are two predefined sequences. They are called "main" and "fault". If a
user doesn't specify these two sequences in the configuration, default
sequences will be created automatically.</p>

<p>Here are the default configurations for main and fault</p>

<p>Main:</p>
<pre xml:space="preserve">  &lt;syn:sequence name="main" xmlns:syn="http://ws.apache.org/ns/synapse"&gt;
      &lt;syn:log/&gt;
      &lt;syn:drop/&gt;
  &lt;/syn:sequence&gt;</pre>

<p>Fault:</p>
<pre xml:space="preserve">  &lt;syn:sequence name="fault" xmlns:syn="http://ws.apache.org/ns/synapse"&gt;
      &lt;syn:log level="full"&gt;
      &lt;syn:property name="MESSAGE" value="Executing default&amp;quot;fault&amp;quot; sequence"/&gt;
      &lt;syn:property name="ERROR_CODE" expression="get-property('ERROR_CODE')"/&gt;
      &lt;syn:property name="ERROR_MESSAGE" expression="get-property('ERROR_MESSAGE')"/&gt;
      &lt;/syn:log&gt;
      &lt;syn:drop/&gt;
  &lt;/syn:sequence&gt;
  </pre>

<p>All the messages that are not for proxy services, will be sent through the
Main Sequence.</p>

<p>A sequence can have an error handler. Error handler is again another
sequence. If an error occurs while executing a sequence, its error handler will
be called. Every sequence has an error handler. If one isn't explicitly
specified, fault sequence will be treated as the error handler.</p>

<h2 id="HowMessageMediate">How does a message comes to a mediator?</h2>

<p>There are two operational modes in the ESB. They are message mediation and
proxy services. Message mediation is all about mediators. Proxy services can
use message mediation as well.</p>

<h3 id="MessageMediation">Message Mediation</h3>

<p>A message comes to the main sequence of the ESB if the message is not for
any of the proxy services defined in the ESB.</p>

<p>Then this message goes through each of the mediators inside the main
sequence.</p>

<p>If the message is sent to an Endpoint from the main sequence, response
message will also comes to the main sequence.</p>

<p>Response message will also go through every child mediator of main
sequence</p>

<p>If an error occurs in a sequence, message will go through sequence's fault
sequence.</p>

<h3 id="ProxyServices">Proxy Services</h3>

<p>Proxy service can have 3 sequences. Depending on the message path these
three sequences can be executed. All the three sequences are optional.</p>
<ol>
  <li>In Sequence : A request message coming to a proxy service will go through
    this sequence if the sequence is specified.</li>
  <li>Out Sequence : A response message coming from the actual endpoint will go
    through this sequence if the sequence is specified.</li>
  <li>Fault Sequence : If an error occurs withing the proxy service operation,
    message will go through this sequence</li>
</ol>

<p>As mentioned earlier, every sequence is a collection of mediators. A message
delivered to a sequence will go through all its child mediators.</p>

<p>WSO2 ESB has a built in sequence editor which helps user to develop/edit
sequences. The <a href="sequence_editor.html">Sequence Editor Guide</a> gives
an introduction to the usage of the sequence editor. Following is the catalog
of the built in mediators of WSO2 ESB.</p>

<h2 id="MediatorCatalog">The Mediator Catalog</h2>

<table border="1">
  <thead>
    <tr>
      <td>Category </td>
      <td>Name </td>
      <td>Description </td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Core</td>
      <td><a href="mediators/send.html">Send</a></td>
      <td>Send a message out </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/log.html">Log</a> </td>
      <td>Logs a message </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/property.html">Property</a> </td>
      <td>Set or remove properties associated with the message </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/sequence.html">Sequence</a> </td>
      <td>Refer a sequence </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/event.html">Event</a></td>
      <td>Send event notifications to an event source </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/drop.html">Drop</a> </td>
        <td>Drops a message </td>
    </tr>
    <tr>
          <td/>
          <td><a href="mediators/enrich.html">Enrich</a> </td>
          <td>Enriches a message </td>
    </tr>
	<tr>
      <td/>
      <td><a href="mediators/enqueue.html">Enqueue</a></td>
      <td>Create a enqueue meadiator </td>
    </tr>
    <tr>
      <td>Filter</td>
      <td><a href="mediators/filter.html">Filter</a> </td>
      <td>Filter a messages using XPath, If else kind of logic </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/in-out.html">Out</a> </td>
      <td>Inbuilt filter for choosing messages in ESB out path </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/in-out.html">In</a></td>
      <td>Inbuilt filter for choosing messages in ESB in path </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/switch.html">Switch</a> </td>
      <td>Filter messages using XPath, Switch logic </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/router.html">Router</a></td>
      <td>Route messages based on XPath filtering </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/conditionalrouter.html">Conditional Router</a></td>
      <td>Route messages based on 'Condition' </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/validate.html">Validate</a></td>
      <td>Schema validation for messages </td>
    </tr>	
    <tr>
      <td>Transform </td>
      <td><a href="mediators/xslt.html">XSLT</a> </td>
      <td>XSLT transformations</td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/xquery.html">XQuery</a></td>
      <td>XQuey </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/header.html">Header</a> </td>
      <td>Sets or remove SOAP headers </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/fault.html">Fault</a> </td>
      <td>Create SOAP Faults </td>
    </tr>
	<tr>
      <td/>
      <td><a href="mediators/rewrite.html">URLRewrite</a></td>
      <td>Create a rewrite mediator </td>
    </tr>
     <tr>
      <td/>
      <td><a href="mediators/relaytransformer.html">Relay Transformer</a> </td>
      <td>XSLT transformations</td>
    </tr>
    <tr>
      <td>Advanced </td>
      <td><a href="mediators/cache.html">Cache</a></td>
      <td>Evaluate messages based on weather the same message came to the ESB
      </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/clone.html">Clone</a> </td>
      <td>Clones a message </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/iterate.html">Iterate</a> </td>
      <td>Splits a message </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/aggregate.html">Aggregate</a></td>
      <td>Combines messages </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/callout.html">Callout</a></td>
      <td>Blocking web services calls</td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/transaction.html">Transaction</a></td>
      <td>Executes a set of mediators transactionally </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/throttle.html">Throttle</a></td>
      <td>Limit the number of messages </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/rmsequence.html">RMSequence</a></td>
      <td>Reliable messaging </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/dbreport.html">DBReport</a></td>
      <td>Writes data to a database </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/dblookup.html">DBLookup</a></td>
      <td>Retrieve information from a database </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/rule.html">Rule</a></td>
      <td>Executes Rules </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/entitlement.html">Entitlement</a></td>
      <td>Fine grained authorization</td>
    </tr>
     <tr>
      <td/>
      <td><a href="mediators/oauth.html">OAuth</a></td>
      <td>2-legged OAuth support</td>
    </tr>
    <tr>
      <td>Extension </td>
      <td><a href="mediators/class.html">Class</a> </td>
      <td>Create and execute a custom mediator</td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/pojo-command.html">POJOCommand</a> </td>
      <td>Executes a custom command </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/script.html">Script</a></td>
      <td>Executes a mediator written in a Scripting language </td>
    </tr>
    <tr>
      <td/>
      <td><a href="mediators/spring.html">Spring</a></td>
      <td>Create a mediator managed by Spring </td>
    </tr>	
	<tr>
      <td/>
      <td><a href="mediators/smooks.html">Smooks</a></td>
      <td>Create a smooks meadiator </td>
    </tr>
      <tr>
          <td/>
          <td>
              <a href="mediators/store.html">Store</a>
          </td>
          <td>Create Mediator to Store messages in a Message store</td>
      </tr>
  </tbody>
</table>

</body>
</html>
