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.


About isurues
Age : 24 Date of Birth : 05.11.1984 Country : Sri Lanka

8 Responses to Hierarchical Service Support for Axis2

  1. Hi Isuru,
    Good move. Very helpful to manage services.
    I’d like to know apart from the endpoint what other changes/compromises that would make? E.g. In the context hierarchy, Dispatching messages based on the RequestURI. (RequestURIBasedDispatcher )
    Also, have you looked into this work? Might be helpful.



  2. isurues says:

    Hi Kau Ayya,

    I didn’t have to do any major changes in the context hierarchy. Actually I’ve treated the hierarchical part as a part of the service name. After reading the services.xml, hierarchical part is attached to the service name to get the actual service name.
    I had to do some changes in the deployment engine and in the dispatchers. I’ve added recursion into the Repository listener to find services inside folders. Deployers make sure they compute the service name by looking at the absolute path of the service artifact.
    When it comes to dispatchers, URI based service dispatcher finds the service by adding hierarchical parts one by one.
    For example, if the incoming URI is ../axis2/services/foo/bar/1.0.0/Version/getVersion, if checks for services as follows.
    foo/bar/1.0.0/Version -> finds the service

    This is why there are 2 limitations as mentioned in my original post.
    URI based operation dispatcher finds the operation by using the service name which is already found.
    HTTP location based dispatcher is also improved to handle RESTful behaviour correctly.


  3. Fair enough.
    But as per the second limitation I think it is better to give a warning at deployment time rather than giving the priority for the foo service over the folder. Just like getting a warning while attempting to create two virtual services with the same name in the Axis2 config. 🙂 Because in practice there is a chance of getting into such situations.

  4. isurues says:

    Yes exactly. Ideally it’s nice to give a deployment time warning. I just thought of doing it. There are two cases.

    [1] When there is a “foo” service inside “mark” folder, warn if the user tries to create a folder “foo” inside “mark”.

    [2] When there is a “foo” folder inside “mark” folder, warn if the user tries to create a service “foo” inside “mark”.

    Out of above two situations, #2 is easy to detect and can be warned. But #1 is bit difficult to implement according to the current architecture of the deployment engine. It’s not aware of the AxisConfiguration. 🙂


  5. Kelli Garner says:

    Great site, how do I subscribe?

  6. isurues says:

    Hi Kelli,

    You can subscribe through Google Reader. Just click on the “Posts” link on the top right side of this page and select “Google”. That’s it..


  7. Savannah says:

    Awesome blog!

    I thought about starting my own blog too but I’m just too lazy so, I guess Ill just have to keep checking yours out.

  8. Wally Dennis says:


    Is this functionality included with Axis2 1.5.3? I am getting deployment errors when I attempt to put .aar files in subdirectories under services.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: