Hierarchical Service Support for Axis2

Until Axis2 1.5, service deployment in Axis2 has been flat and global. All services must be deployed in AXIS2_HOME/repository/services directory and it was really hard to manage services separately. Think about a situation where a large organization uses Axis2 to deploy a large number of services from different departments. They all have to agree on service names before deploying to avoid conflicts. And also supporting multiple versions of the same service was not possible without changing the service name in the services.xml file.

So how can we overcome this issue? Supporting hierarchical service deployment is the ideal solution to this problem. In other words, the ability to deploy services inside any prefered directory structure inside “services” folder.

Ex : repository/services/foo/bar/version.aar

In this case, the EPR for the service will be ../axis2/services/foo/bar/Version. This makes it extremely easy to manage services and it is the natural way of managing things separately. And also If you want to deploy two different versions of the same service without changing anything other than your business logic, it can be easily done as follows.


I’ve already implemented this feature in Axis2 trunk and you can try this by just building the trunk. And also, this will be there from the next Axis2 release which will be 1.6. Hierarchical support is there for AAR services and all other types of services like JAXWS, POJO etc.

Limitations :

[1] Maximum supported hierarchical depth is 10. In other words, you can deploy services only up to 10 directory levels starting from /services directory. This limitation was introduced to avoid possible performance issues.

[2] You can’t have a service and a sub directory from the same name within your service hierarchy.

Ex : If you have a service with the name “foo” (defined in the services.xml of foo.aar), you can’t have a sub directory “foo” inside the same directory.


In this case, “foo” service and “foo” sub directory are inside the “mark” directory. In this case, requests coming into version service will be dispatched to “foo” services. Therefore, this kind of situations should be avoided.

Uses of different “lib” folders in WSO2 Carbon

WSO2 Carbon is the OSGi based platform for all WSO2 java products. In Carbon, there are four different “lib” folders. If you have ever tried any of the Carbon based products, you may have thought “why are there four different libs?”. If so, this post will provide you the answer for that question.

These are the “lib” folders that you can find in Carbon.

[1] CARBON_HOME/webapps/ROOT/WEB-INF/lib

Carbon is a web app which is deployed in an embedded tomcat instance. This is the lib folder which is specific to Carbon web app just like any other web app has in WEB-INF/lib folder. Bridge servlet is the one who forwards each and every incoming request into the OSGi environment of Carbon. We have used this lib to place our Bridge Servlet. Tomcat pics it up from there and hands over the incoming requests to it.

[2] CARBON_HOME/repository/components/lib

This is the place to put your normal jars if you want them to become pure bundles in the OSGi environment. All packages in these bundles are exported into the OSGi environment. As you may know, Carbon can be extended as you wish. You can add your own bundles into it. So If you have dependent jars for those bundles, you can place those in this lib.

[3] CARBON_HOME/repository/lib

This is the place where all client libraries exist. When you run ‘ant’ from CARBON_HOME/bin, all needed jars are put into this folder. If you want to write a client (or you can generate it using the WSDL2Java tool in WSAS) and test it, the set of all jars you need in the classpath can be found in this lib. For example, WSAS samples are run by adding all these libs into client classpath.


This is the place where we put all jars which are needed by tomcat to start and some others for specific reasons. This is same as the Tomcat root lib. These libraries can be seen from all webapps deployed. And also, if you place the same jar in this lib and also inside Carbon web app, it will be picked up from this root lib as Tomcat uses parent first class loading.