Adding Mediation to WSO2 WSAS

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By Ruwan Linton
  • 10 Feb, 2009

Featuring step-by-step instructions, this how-to guide demonstrates the componentization capabilities of WSO2 Carbon. 


WSO2 Carbon (Middleware à la carte), based on OSGi, is the base framework for the WSO2 product platform.  Carbon promises seamless integration of WSO2 products including WSO2 WSAS, WSO2 Registry, WSO2 ESB and WSO2 BPS.  To show this integration in practice, the following article describes how to add ESB functionalities to WSAS. In addition, because the WSO2 Registry is integrated into WSAS and all the other products by default, this use case actually shows the integration of three total products (WSAS, Registry and ESB). The use case featured here is also explained in the Adding Mediation to WSO2 WSAS screencast.

Table of Contents

WSO2 Carbon

WSO2 Carbon is an OSGi-based platform implementation on which all the Java products by WSO2 are based. Carbon provides the core runtime for the features of these products to be implemented as components, which makes each and every product simply a Carbon runtime and a set of feature components. For example, WSO2 ESB by default ships with the Mediation component, Proxy Services component, Task component, etc...

This enables WSO2 products to be highly extensible and customizable, which is one of many advantages of Carbon. Most interestingly, you could take features from one product and apply those features on to another product to customize the behavior of the middleware application. With this, WSO2 provides the ability to adapt the middleware to your architecture where as in many other cases it adapts your architecture to the middleware.


WSO2 Web Services Application Server (WSAS), is the service hosting environment of the WSO2 SOA stack. It provides the ability to host Axis2 services, Axis services, EJB services, Data services, POJO services, Spring services and many more.  Additionally, it provides the ability to configure the Quality of Service (QoS) parameters of the hosted services.

WSAS also provides a set of monitoring tools to monitor the system such as, SOAP Tracer, System Statistics, System Logs and so on.

Why is Mediation Important for SOAs?

Mediation in its English meaning is the conflict resolution between two parties. In the case of inter-device communication, it refers to the conflict resolution in messaging between client and the server. If you design the Service Oriented Architecture (SOA) for your enterprise in a way that it suffices all the client requirements, then you might not need mediation.  However, the fact that the world is evolving either requires you to upgrade your SOA implementation periodically, or you need mediation to adapt your implementation to current requirements.

Most organizations have legacy services that they cannot change, but they require those legacy services to be adopted by the current SOA. For example, you may want to add security to an existing non-secure service in order to make it usable by the current architecture.  In this way mediation is vital for a successful implementation of the SOA, as it provides much-needed extensibility for your enterprise.

Mediation on WSAS Services

Mediation on WSAS services will be different from ESB layer mediation, in which case there is a third party who is doing the mediation between the service invoker and the service host. The mediation capability that can be added to WSAS brings the mediation to be bundled into the service host.

ESB layer mediation
Figure 01: ESB layer mediation between service invoker and service host


ESB layer mediation
Figure 02: Service host has mediaiton bundled to itself

The Figure 01 illustrates how you can use the ESB to mediate while the Figure 02 shows the scenario that we are trying to explain in this particular article, where the mediation capability is built into the service host (WSAS).

Adding Mediation to WSAS

Adding mediation to WSAS is very straight forward, and described in the following set of steps. The Carbon platform provides the technology to make it so easy to add mediation functionality to WSAS.

Step 1: Download and install WSAS

  1. WSAS binary distribution can be downloaded from the WSO2 web site; if you need the documentation it is available for you to download on the project page or the online version is available here
  2. After completing the binary package download extract the to a folder with at least 150 MB of disk space. We will be referring to the extracted folder as WSAS_HOME from here onwards.
  3. Go to the bin directory of WSAS_HOME and start the WSAS server by starting the or wso2server.bat as appropriate to your operating system. (Note: at the first start up you should provide the -Dsetup option to prepare the WSAS server for running samples)
    Console output of WSAS
    Figure 03: Console output when starting the WSAS
  4. Point your browser to https://localhost:9443/carbon to see whether you got it running properly. Use the default user name admin and password admin to login as an administrator to the console.
    WSAS Administration Console
    Figure 04: WSAS administration console

Step 2: Download and extract the mediation component

  1. You can download the mediation pack from the Carbon page, and you may refer to the Sequences section of the ESB documentation as a reference to the mediation pack.
  2. Extract the in to a temporary directory and copy all the jar files in the plugins directory of the extracted directory into the $WSAS_HOME/webapps/ROOT/WEB-INF/plugins directory.

Step 3: Start the WSAS server

  1. Restart the WSAS server using the Shutdown/Restart tab in the console. (Note: On MS Windows this functionality might not work, in which case you will have to stop the server and start again from the command prompt)
  2. You should be able to see the Mediation tabs on the left navigation menu as shown in Figure 05.
    WSAS Administration Console with mediation
    Figure 05: WSAS administration console with mediation

Mediate a Message to the HelloService Service

Adding mediation to an existing service is just a three step process in which you define two sequences for the incoming and outgoing messages in the sequences tab, and then create the association of those sequences to the service through service parameters.

Step 1: Define the incoming mediation sequence

  1. Go to the Sequences tab and click on the Add Sequence link on the bottom of the sequence list table to add a new sequence.
  2. Provide the Sequence Name as "hello_in".
  3. Click on the Add Child link on the Root and select the Log mediator from the Core mediators as shown on the Figure 06.
    Add Log mediator
    Figure 06: Add Log mediator to the "hello_in" sequence
  4. Click on the Log in the design tree and change the "Log Level" to Full to log the full message as shown in the Figure 07. At the same time you could add a property with the name IN-MESSAGE and add the value ********** In message logged *********** to clearly see the incoming message mediation. These properties will be printed on to the log while this Log mediator is being executed to do the mediation. You need to click on the Update button to update the Log mediator configuration into the sequence.
    Configure log mediator
    Figure 07: Configuring the Log mediator
  5. Then save the sequence by clicking on the Save button on the bottom button panel of the sequence editor.

Step 2: Define the outgoing mediation sequence

Follow the above steps to create a sequence named "hello_out", with a log mediator with "Full" log level and a custom property with the name OUT-MESSAGE and value ********** Out message logged ***********. Save this sequence as well using the bottom button panel. Now you should see these two sequence on the sequence listing page as shown in Figure 08

(Note: WSO2 ESB by default does not persist sequences, and if you need these sequences to be present on the next startup as well, go to the Synapse tab and use the Save button to persist the sequences)

Sequences List
Figure 08: Sequences List

Step 3: Create the association of these two sequences to the HelloService

  1. Go to Manage > Service > List and click on the HelloService and you will see the service dashboard of the "HelloService" as shown in the Figure 09
    HelloService service dashboard
    Figure 09: HelloService service dashboard
  2. Click on the Modules link on the Quality of Service Configuration section to go to the module management page of the HelloService.
  3. Select the "synapse-handler-1.30" from the drop down menu and click on the Engage button to engage synapse handler module to do the mediation. Now you should be able to see that the synapse-handler-1.30 has been engaged on the service level as shown in Figure 10
    synapse-handler-1.30 module engaged
    Figure 10: synapse-handler-1.30 module engaged
  4. Come back to the Service Dashboard and click on the Parameters link on the Quality of Service Configuration section to go to the service parameter editing page.
  5. Add a parameter named mediation-in-sequence and specify the "hello_in" sequence as the parameter value as shown in the Figure 11
    Service parameters
    Figure 11: Service parameters configuration
  6. Follow the same steps to add a parameter called mediation-out-sequence and specify "hello_out" as the value.

These "hello_in" and the "hello_out" are the sequences that we have created in the above two steps respectively and we have now created the association of the sequences to the "HelloService"

Now we have set up the "HelloService" for mediation at the service host side itself and you could use the Try-It tool to try this service which will generate a web based client to try this service. To invoke this service through Try-It;

  1. Go back to the Service Dashboard, (you could use the bread crumbs on the top to navigate to the service dashboard)
  2. Click on the Try this service link which will open up another browser with a simple user interface to specify the name as shown in the Figure 12
    HelloService Try-It
    Figure 12: Try the HelloService
  3. Now click on the greet button which is the operation name of the service that you are trying to see the mediation on the service host in action.
  4. Now if you go to the System Logs section you should be able to see the following log entries in there which are resulted from the mediation by the mediation component.
    System Logs
    Figure 13: System Logs

(Note: here you can see three entries with the same log, one for the SERVICE_LOGGER and the other two from the Log mediator to the console log and standard output log)


This article has shown how we can use the mediation functionalities on the service hosting environment, and how this mediation can be very powerful in certain cases. We have only explored logging the message at the mediation, but we could easily extend this to provide more interesting and complex mediations including message transformation, message validation, message filtering and throttling, response caching for time consuming steady services, database reporting and so on.

This particular scenario can be directly applied to the BPS processes as well because they are again services. In the same way of adding the mediation functionality to the WSAS, it is trivial to add the service hosting capabilities to the ESB as well. You could store all these configuration bits in the Registry built in to each of these products so that it demonstrates the integrity between Registry as well. Finally Carbon platform lets you manage the middleware for your exact requirement.

Note: Even though we can have everything in one single server it may not be the best deployment model for your architecture, so please be careful in designing the deployment by customizing the servers.


  1. WSO2 WSAS Documentation
  2. WSO2 ESB Documentation


Ruwan Linton Product Manager - WSO2 ESB WSO2 Inc ruwan AT wso2 DOT com


Related Resources:

About Author

  • Ruwan Linton
  • Director, Delivery
  • WSO2 Inc