Using JSR181 annotations with Axis2

I've been meaning to try the annotation support in Axis2 ever since I knew it was there, but I've been a bit busy. I'm running a course on Axis2 for SkillsMatter this week so it seemed like a good time to figure it out and see how well it works.

JSR181 is the standard for doing this, and it defines a simple way to add some annotations to your Java class and interface so that you no longer need a services.xml. You can read the JSR181 specification but they 44 pages to formally specify what could be put in about a single piece of A4 or Letter size paper!

Basically you start by adding the following lines to your class or interface definition:

import javax.jws.WebService;

@WebService
public class PaulsService {

@WebMethod
public String myMethod() {
...
}
}

That's a nice easy start. So what now??! Well you need to make sure you have the following in your classpath when you compile:
axis2-jaxws-api-1.3.jar

[I could write a whole blog post about whether Java with annotations are really POJOs! After all, to compile a normal Axis2 POJO service I don't need anything Axis2-related in my classpath - I fix all that up later with XML descriptors. In this case, although the annotations are standard, I still need to have WebService specific JARs in my classpath to compile these "POJOs".]

Then you need to deploy it. This turns out to be a tiny weeny bit tricky. Did I mention that there is no documentation of this feature in Axis2!? Ah.

Well, basically there is a line in your default Axis2-1.3 configuration:

<deployer extension=".class" directory="pojo" class="org.apache.axis2.deployment.POJODeployer"/>

Well the directory element is relative to your Axis2 repository. So go and create a directory repository\pojo. Now place your class in there. As far as I can tell there is no hot deployment for these yet, so place your .class file there and restart Axis2.

If all is well you will now have a new service called JSR181ServiceService.JSR181ServicePort. Don't be worried if there is no log info to say the new service has been deployed, because as yet there is no logging in the POJODeployer class either.

Now this is a pretty ugly name for a Service, but we can easily fix that.

@WebService(name="Hello", serviceName="PaulsService")

Now the service is listed by Axis2 as PaulsService.HelloPort. But there are some other cool things we can do to the service, like giving it a nice namespace:

@WebService(name="Hello",
targetNamespace="http://fremantle.org/ns",
serviceName="PaulsService")

The other thing JSR181 let's you do is to separate the interface and implementation classes, though I didn't try this with Axis2 yet.

We can also modify the method/operation details:

@WebMethod(action="http://fremantle.org/actions/doit");

In theory you can also set operationName="doit" as a parameter, but it doesn't work yet.

The other things you can do with JSR181 include setting the names of parameters and responses, setting namespaces, and changing the default binding from doc/lit/wrapped.

However, I think that the @WebService and @WebMethod annotations are probably enough for most users.

Although the Axis2 implementation still needs a little polishing, I think its fair to say its a very useful addition to Axis2's capabilities. It certainly makes it simple to create Web services without needing to learn to write services.xml. I recommend you have a go. Its really pretty simple - just add the right JAR to your build path, create the repo/pojo directory, and copy the class file in. Bingo!

I'll post an update here as soon as we have managed to get the bugs fixed and the documentation written!