Monday, October 7, 2013

Common usage patterns for WSO2 ESB Mediators

Few weeks back, I spent a week digging into WSO2 ESB in detail. When you get started, it is bit tricky to figure out what parts should be used where and when. I thought it is useful to write down some of the common patterns/ best practices on using WSO2 ESB Mediators.


As shown by the diagram, ESB sits between the services and clients and provide mediation. Mediation provides one or more of the following functions.

1. Message conversion and Transport switching
2. Routing
3. Filtering (e.g. security termination)
4. Service Chaining & Aggregation

Let us look at each function and discuss some of the constructs from WSO2 ESB that you can use to implement them. WSO2 ESB provides an operator called mediator and most functionality is implemented as a Mediator.  When describing how you can get ESB to do something, I will just name the mediator at appropriate places. You can find more information about how to use the mediator from WSO2 ESB documentation (

You first start by receiving a message. You can receive a message via a Proxy Service, an API, or using a Main Sequence. After receiving the message you can use mediators to change or reroute messages as needed.

Message conversion and Transport switching 

When you do message conversion, if you are changing only small part of the message, then you can use the enrich mediator, However, if you mostly rebuilding the message from ground up, you are better off with the payload factory mediator that let you type in the message as a template and insert values at the right place. Finally if you are doing complex transformations like expanding a list in the source message, then you should use XSLT mediator. You may also use FastXSLT Mediator, Smooks Mediator, XQuery Mediator when applicable.

WSO2 ESB can receive and send messages via many transports like HTTP, SOAP, JMS, FTP, Email, FIX etc. You can switch a message from one to the other transport by configuring transports and using Send mediator with the correct transport.


Filtering stops some of the messages from proceeding further. You can use Filter Mediator, Throttle Mediator or security mediators like Entitlement Mediator, Validate Mediator, and OAuth Mediator.


Routing can change the path of the message based on runtime conditions.

Sometime this is done via endpoints like load balancing endpoints or fault tolerant endpoints to achieve load balancing or fault tolerance. You can also use Conditional Router Mediator, Event Mediator, Router Mediator, Switch Mediator, and URLRewrite Mediator. It is worth noting that if the routing send the message out more than once, you need to use clone mediator to make a copy before calling send mediator.

Service Chaining 

Service chaining let you add information retrieved from other sources like Web services databases etc., with the current service call. For this you can often use service-chaining pattern. There are two ways to implement service chaining. Out of those, it is recommended to use “receive” property in the send mediator to receive the service response for service chaining.

You can further use Callout Mediator, DBLookup Mediator, DBReport Mediator and EJB Mediator.

Sometime we need do calls with multiple threads and collect results of those calls. For that you can use Aggregate Mediator, Clone Mediator, and Iterate Mediator. Here Clone mediator is used to create another execution path for the message (e.g. Thread). Iterate Mediator is used to repeatedly do the same task using different inputs. You can use aggregate mediator to collect results from both Clone and iterate mediators.

There are other mediators like Cache Mediator, Drop Mediator, Fault Mediator, Log Mediator etc, and use can find more information from the WSO2 ESB documentation.