WSO2 ESB error handling in Endpoints

I’ve written an article, WSO2 Enterprise Service Bus - Endpoint Error Handling, to the WSO2 Oxygen Tank. It is written aiming the advanced users who are already familiar with WSO2 ESB and want to do real deployments. It covers lot of details in depth. So a beginner can quickly grasp some of the internal workings by reading the article as well.

A Rock Solid Release of WSO2 ESB 2.1.1

We did a very stable release of WSO2 ESB 2.1 some time ago. Now we have a more robust version of it available. This version has many bug fixes for app server deployment. Also quite a number of general bug fixes. We have changed the registry to support transactions. All the ESB features are very stable and ready to go in to production.

You can grab the latest release from

http://wso2.org/downloads/esb

Java Double checked locking – don’t use it!!

First lets look at what is double checked locking. Double checked locking has 4 steps

1. Check a variable
2. Synchronize
3. Check the variable again
4. Change the variable

Here is a scenario where this can be used theoretically. There is a object shared by multiple threads. Creation of this object happens at the runtime. Multiple threads can see the need for creating this object. Even if multiple threads want to create the object we only want a single thread to create the object.

Here is a simple demonstration.

public class Test {
    // this is the shared variable accessed by many threads
    private MyObject myObject = null;

    /**
     * This method is invoked by many threads.
     */
    public void doWork() {
        if (myObject == null) {
            synchronized (this) {
                if (myObject == null) {
                    myObject = new MyObject("Supun", 24);
                }
            }
        }
        // do our work
    }
}

class MyObject {
    private String name;    
    private int age;
    MyObject(String name, int age) {
        this.name = name;
        this.age = age;
    }
}

You might think this will work. Theoretically it should work. But in practice it won’t work. Specially in production servers with multiple CPU’s and shared memory there is a high chance for this to fail.

Let me explain why it fails. Here is a demonstration of how java may be implementing the call to new. This order can be different in different compilers. But there is no guarantee.

    public void doWork() {
        if (myObject == null) {
            synchronized (this) {
                if (myObject == null) {
                    // here is how the java code may be actually executed by the JVM
                    myObject = allocateMemory;
                    myObject_constructor();
                }
            }
        }
        // do our work
    }

It first allocates memory and assign it to the reference. At this point myObject is not null. But the myObject is not fully initialized yet. At this point a thread can come to the first null check and see it is not null and can try to access the object fields. This will produce unexpected behavior.

You can solve this problem by using volatile keyword for myObject reference. But volatile is not guaranteed to work across JVMs and the most of the implementations of volatile are slower than synchronization.

So avoid using double checked locking in Java.

Fancy cars, Beautiful houses, Bank loans & SRI LANKA

Everybody loves to have a fancy car and a peaceful beautiful place to live in. This is the dream of Sri Lankans. They all want to by a car. They all want to build the biggest and the most beautiful house possible. All this is fine until they do it with their own money. But they don’t. They do it by getting the biggest loan from some bank.

Still Sri Lanka is a developing country. Every year it goes to World Bank or IMF for getting loans for running the country. So as Sri Lankans we are in a great debt to the world. Actually not to the whole world but to few powerful countries like USA, Japan etc. So obviously a big portion of every loan a Sri Lankan get from a local bank comes from a loan Sri Lanka took from one of these global organizations.

But the problem lies with the way we spend this money. We spend it for building a house that has no capability of generating revenue. It is like every time we build a house we are burying some of the money we took from some other country. Also to build these houses we get raw material from the same countries that we took the loan itself. So we are doubling our debts.

Situation is worse with Cars. From the car itself to spares parts to fuel we are importing from other countries. So we get loans from other countries, we buy cars from these same countries from the loans we got and then we get fuel from these countries as well. So we are entitled to an eternal debt.

There is another sad side to these loans. Most of these loans are taken by people who don’t do work worth of what they get as their salary. This happens mostly in government sector. Still government sector plays a big role in Sri Lanka. 90 percent of the government workers don’t do work worth of what they get. So ultimately some poor guy has to pay dearly for what these people do.

WSO2 ESB 2.1 Places for putting custom mediators

There are three places for putting a mediator. They are

<esb_carbon_home>\repository\components\mediators
<esb_carbon_home>\repository\components\dropins
<esb_carbon_home>\repository\components\lib

mediators directory

User can put a regular non OSGI mediator jar in to this directory. The system will convert the mediator jar in to an OSGI jar and deploy it in to the server. This way is easy and simple to use. In this way user cannot specifically use the OSGI features for the mediator. For example user cannot make certain packages private or import specific versions of packages. Other than that as I said earlier this is pretty easy. Also user can put mediators that are class mediator as well as mediators that have its own xml configuration.

dropins directory

User need to build an OSGI bundle of the mediator and put it in to the dropins directory. This requires a basic knowledge about the OSGI and maven bundle plug-in. So it can be little bit difficult for an programmer who doesn't aware of the OSGI technologies. Since user is creating the OSGI bundle he can use the OSGI features as he wish. When creating the OSGI bundle a mediator with a XML configuration should be a fragment of the synapse-core. If it is a class mediator it can be a normal bundle.

lib directory

User can only put class mediator jars in to this directory. A regular jar can be put in to this directory and it will be automatically converted to an OSGI bundle by the system.
The recommended way is to put the jar in to the mediators directory.

Note: in all these cases you need to restart the server after putting the mediator..

The WAY I like to see future Carbon architecture

WSo2 Carbon provides a SOA Framework with Configuration + Monitoring. It has the concept of Front end and Back end. Front end and back end communicates through SOAP. Front end is JSP driven. So the actual configuration is done through the browser. Then this configuration is transferred to JSP layer with HTTPS. JSP layer uses SOAP to communicate with the back end. So back end has a series of Services deployed in an Axi2 instance for configuring and monitoring the server.

At the moment users deploy there services to the same Axis2 instance that hosts the Admin services. This has few drawbacks. Axis2 doesn’t have the concept of user. Also a service has access to the whole Axis2 instance. This means a service can virtually do anything in Axis2. So if several user deploy services in carbon they can access services deploy buy others. Also this service has access to all the admin services as well. But at the moment we consider this type of situations as user errors. System doesn’t enforce any restrictions on the user. But if we want to use Carbon to provide services in a multitenant way(As in gmail or Amazon ec2) this model won’t work.

Here is how I would like to see carbon architecture in the future that will solve all the above issues.

Here most important thing is Administrative services run in a separate Axis2 instance and user services run in their own Axis2 instances. This will clearly separate the administrative configuration from the service hosting environment providing better security and reliability. Also by nature this architecture is multitenant.

Different user groups or realms can have their own Axis2 instance as their hosting environment. Mapping the user to their respective Axis2 instance can be done by the management layer. These Axis2 instances should have their own modules, services, and transports.

Although it is simple to describe in a high level, this can be very hard to implement. But writing software is not an easy task anyway. 

Most painful task in Web Services Development

it is Testing!!

I have being writing web services related technologies for almost three years now. Testing is the most boring, time consuming task in Web Service Stack Development. I’m not talking about developing just Services. I’m talking about developing the tools needed for these services. Stuff like web service engines, ESBs etc..

It takes few weeks to write the actual code. Then it takes months to test it properly and get it to a stable enterprise ready application. If you look at the code behind web services tools they are pretty simple and doesn’t have lots of very hard to understand algorithms. But these applications takes years to develop and mature and surprisingly there are not much good web service engines around.

Here are some of the points I’ve noticed

When a bug is found we need to compile the classes, deploy it in the server and then test it. This implies shutting down the server copy the compiled files and then starting it again. Also to go to the actual place where error is found we need to configure the server as well. If you made another mistake you have to repeat the cycle which can lead to a vicious cycle. Normally shutting and starting up the server can take about 1 min.

Web Services are distributed in nature. Typically to test something we need a client + server. If you write a server component you need to write a client as well. Every time a bug is found we need to run the server + client. For products like ESBs we need client + ESB + web services server to test a full scenario.

Since we are writing the client, it can be implemented according to the server implementation we have. This only implies our server and client can work together. It doesn’t imply our implementation is correct.

Web Services invocations are not tangible. They get messages in and produce messages. So if we want to find a bug we need to analyze the messages. This is a hard thing to do as well as automate.

When an UI is involved with the these tools things get much more complicated.

WSO2 ESB – A High Level Architectural Perspective

Enterprises are inherently complex, comprising of hundreds of applications with completely different semantics. Some of these applications are custom built, some are acquired from third parties and some can be a combination of both and they can be operating in different system environments.

Integration among these heterogeneous applications is vital to the enterprise. But conventional integration mechanisms can lead to a maintenance nightmare by coupling different components too tightly.

SOA is today’s integration technology. But SOA alone will not solve all the problems at hand. Service interfaces can change. Different services may be using different data formats and communication protocols. Physical locations of services can change arbitrarily. All these constraints means your applications are still tightly coupled together.

An ESB can be used for loosen up these couplings between different services and service consumers.

WSO2 ESB is a full fledged enterprise ready ESB. WSO2 ESB is built around Apache Synapse project. Apache Synapse is built using the Apache Axis2 Project.

Below is a diagram describing WSO2 ESB architecture from a messaging perspective. There are lot of other areas like Tasks, Events which are not describe in this diagram. This article focus on how messaging is handled in the ESB.

Figure: High Level Architecture of WSO2 ESB

Note: Various components of the pipes doesn’t imply any order in this diagram.

An application sends a message to the ESB.

The message is picked up by the ESB transport.

Transport sends the message through a message pipe. Quality of service aspects like Security and reliable messaging of the message is taken care in this pipe. Internally this pipe is the in-flow and out-flow of Axis2. ESB can operate in two modes. Message mediation or proxy services. In case of message mediation a single pipe is used. In case of proxy services we can think of separate pipes connecting transport to different proxy services.

Message transformation + routing can be seen as a single unit. As the diagram specifies there is no clear separation between message transformation components and routing components. WSO2 ESB call this the mediation framework. Some transformations happens before routing decision has taken. Some transformations happens after the the routing decision has taken. This part is the Synapse implementation.

After this message is injected to the separate pipes depending on the destinations. Here again quality of service aspects of the messages is determined.

At the end there is a transport layer. This transport layer takes care of the transport protocol transformations required by the ESB. 

I have explained how a request propagates to its actual endpoint through ESB using its architecture. Response handling is the reverse of this operation.

All these components cab be managed and monitored through WSO2 ESB management console.

This is a birds eye view of the ESB architecture. Definitely Architecture can be seen in a more detailed view. Possibly in a few more blogs I’ll explain each and every aspect in a more detailed manner.

Writing a WSO2 ESB mediator

Mediators provide a easy way of extending the ESB functionalities. WSO2 ESB is based on WSO2 Carbon platform which uses OSGI as the underlying technology. This implies everything that runs inside the WSO2 ESB to be OSGI bundles. No exception for mediators.

There are two ways of writing  a ESB mediator.

1. Using Class mediator, this doesn’t allow mediator specific XML configurations
2. Writing the mediator with Factory and Serialize methods which allows it to have its own XML configuration

Writing the mediator is straightforward in any of these cases. Easiest way to write the mediator is to extend your mediator class from org.apache.synapse.mediators.AbstractMediator class. I’m not going to go in to details of how to write the mediator. Here are two good articles about how to write a mediator in each of the above cases.

1. Writing a Mediator in WSO2 ESB - Part I | WSO2 Oxygen Tank
2. Writing a Mediator in WSO2 ESB - Part 2 | WSO2 Oxygen Tank

After you write the mediator you need to build it with WSO2 ESB. This is the tricky part. You have to make your mediator an OSGI bundle in order to make it work with ESB.

Easier Way

You just need to create a regular jar which links to the Synpase core jar and put it in to the repository/component/mediators directory. The platform will automatically make it an OSGI bundle and deploy it to the server.

Harder Way

But if you want the full control of how your mediator should be created as an OSGI bundle you have to write the following POM files. I have given two maven pom files that can be used to build the mediator in each of the above cases. This way you can export the packages you want, you can import packages you want etc. This comes handy if your mediator is using some versioned jar files. 

Important

Both pom files are created for the ESB 2.1 release. If you want to use them for another release make sure you change the versions accordingly.    

Here is a POM file if you use class mediator to create the mediator.

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">    

    <modelVersion>4.0.0</modelVersion>
    <groupId>org.test</groupId>
    <artifactId>org.test</artifactId>
    <version>1.0.0</version>
    <packaging>bundle</packaging>
    <name>My Samples - Test mediator</name>
    <url>http://www.test.com</url>

    <repositories>
        <repository>
            <id>wso2-maven2-repository</id>
            <url>http://dist.wso2.org/maven2</url>
        </repository>
        <repository>
            <id>apache-Incubating-repo</id>
            <name>Maven Incubating Repository</name>
            <url>http://people.apache.org/repo/m2-incubating-repository</url>
        </repository>
        <repository>
            <id>apache-maven2-repo</id>
            <name>Apache Maven2 Repository</name>
            <url>http://repo1.maven.org/maven2/</url>
        </repository>
    </repositories>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.0</version>
                <configuration>
                    <source>1.5</source>
                    <target>1.5</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>1.4.0</version>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        <Bundle-SymbolicName>org.test</Bundle-SymbolicName>
                        <Bundle-Name>org.test</Bundle-Name>
                        <Export-Package>
                            org.test.mediator.*,
                        </Export-Package>
                        <Import-Package>                                                                                    
                            *; resolution:=optional
                        </Import-Package>                        
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>        
        <dependency>
            <groupId>org.apache.synapse</groupId>
            <artifactId>synapse-core</artifactId>
            <version>1.3.0.wso2v1</version>
        </dependency>        
    </dependencies>
</project>

You can see we are using the maven bundle plugin for creating the OSGI bundle. Make sure you export the correct package which contains the mediator code. Unless you do this your mediator won’t work.

Here is a POM file if you use Serialize and Factory classes to create the mediator with it’s own XML configuration

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">    

    <modelVersion>4.0.0</modelVersion>
    <groupId>org.test</groupId>
    <artifactId>org.test</artifactId>
    <version>1.0.0</version>
    <packaging>bundle</packaging>
    <name>My Samples - Test mediator</name>
    <url>http://www.test.com</url>

    <repositories>
        <repository>
            <id>wso2-maven2-repository</id>
            <url>http://dist.wso2.org/maven2</url>
        </repository>
        <repository>
            <id>apache-Incubating-repo</id>
            <name>Maven Incubating Repository</name>
            <url>http://people.apache.org/repo/m2-incubating-repository</url>
        </repository>
        <repository>
            <id>apache-maven2-repo</id>
            <name>Apache Maven2 Repository</name>
            <url>http://repo1.maven.org/maven2/</url>
        </repository>
    </repositories>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.0</version>
                <configuration>
                    <source>1.5</source>
                    <target>1.5</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <version>1.4.0</version>
                <extensions>true</extensions>
                <configuration>
                    <instructions>
                        <Bundle-SymbolicName>org.test</Bundle-SymbolicName>
                        <Bundle-Name>org.test</Bundle-Name>
                        <Export-Package>
                            org.test.mediator.*,
                        </Export-Package>
                        <Import-Package>                                                                                    
                            *; resolution:=optional
                        </Import-Package>                        
                        <Fragment-Host>synapse-core</Fragment-Host>
                    </instructions>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <dependencies>        
        <dependency>
            <groupId>org.apache.synapse</groupId>
            <artifactId>synapse-core</artifactId>
            <version>1.3.0.wso2v1</version>
        </dependency>        
    </dependencies>
</project>

In this case we have to make the mediator an OSGI fragment of the synapse-core bundler. To achieve this we are using the <Fragment-Host>synapse-core</Fragment-Host>.

After you create the mediator drop the jar file in to the {ESB HOME}\repository\components\dropins folder.

Why you need WSO2 ESB 2.1 in your SOA?

ESB is a key component in any SOA based solution. WSO2 has released it’s latest version of ESB 2.1.0. Here are some of the key features of WSO2 ESB that you are expecting to see in your ESB.

Functionality	Description
Invocation	Support for synchronous and asynchronous transport protocols like http, jms, mail, vfs, udp, fix and  service mapping (locating and binding) through proxy services
Routing	addressability, static/deterministic routing, content-based routing, rules-based routing
Mediation	protocol transformation, service mapping
Messaging	message-processing, message transformation and message enhancement through mediation framework
Service orchestration	coordination of multiple implementation services exposed as a single, aggregate service
Quality of service	security (encryption and signing), reliable delivery, transaction management, throttling, caching
Management	monitoring, audit, logging, metering, admin console
Component architecture	built on the revolutionary WSO2 carbon architecture which allows you to build your own ESB that suites your enterprise
Clustering	Running in a cluster for better load handling
Load balancing	ESB can load balance the requests to a cluster

You can see WSO2 ESB offers a comprehensive list of functionalities which can be seen only in enterprise grade ESBs.

Hmm quite a lot of features… Now you must be wondering what is the price for all of this? You won’t believe this. It is ZERO. Also the code is available for free download and it is Apache 2.0 license. You know what you can do with Apache 2.0 license. If you are looking for commercial support, WSO2 offers it for may be quarter of what you are paying for other commercial ESBs.  

Bottom line is WSO2 ESB is an enterprise grade ESB, free of charge. I don’t see any reason why you shouldn’t have it!