Adding Mediation to WSO2 WSAS

In this article, Ruwan Linton, Product Manager of WSO2 ESB, explains how to add the mediation functionalities of the WSO2 ESB to a WSO2 WSAS 3.0 instance. Date: Tue, 10th Feb, 2009 Level: Intermediate Reads: 6013 Comments: 0 | Login or register to post comments

Ruwan Linton Product Manager and Technical Lead WSO2 Inc

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

Abstract

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 WSAS
• Why is Mediation Important for SOAs?
• Mediation on WSAS Services
• Adding Mediation to WSAS
  • Step 1: Download and install WSAS
  • Step 2: Download and extract the mediation component
  • Step 3: Start the WSAS server
• Mediate a Message to the HelloService Service
  • Step 1: Define the incoming mediation sequence
  • Step 2: Define the outgoing mediation sequence
  • Step 3: Create the association of these two sequences to the HelloService
• Conclusion

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 WSAS

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.

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

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 wso2wsas-3.0.zip 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 wso2server.sh 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)
   
   

   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.
   
   

   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 wso2servicemediation-feature-2.0.1-beta.zip 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.
   
   

   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.
   
   

   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.
   
   

   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)

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
   
   

   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
   
   

   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
   
   

   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
   
   

   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.
   
   

   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)

Conclusion

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.

References

1. WSO2 WSAS Documentation
2. WSO2 ESB Documentation

Author

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

Related Resources: