Creating a Web Service Using Apache Axis2

Prerequisites

We need Apache Axis2 running and a suitable container. You could also run Axis2 as a standalone server but for this let’s use Tomcat as a container. So in the following order

1. Download and install Oracle JDK7
2. Download and install Tomcat 7 (even 8 would do, but it seems as of now Tomcat 8 isn’t being supported by Eclipse, so let’s go with version 7)
3. Download and install Axis2 on Tomcat

Oracle JDK7

Download and extract the JDK tarball.

Add and modify the following lines in ~/.profile or /etc/profile (for system wide application) to add JAVA_HOME environment variable and it’s bin folder to $PATH.

Refresh the terminal session and check if Java is working.

Tomcat 7

You could install tomcat through apt-get or manually.

Or download and set paths manually.

Add the $CATALINA_HOME environment var to the bash profile.

Prefix the following line before exporting the $PATH.

Server start/stop can be done by the scripts in the $CATALINA_HOME/bin folder.

Deploying Axis2

Download Axis2 WAR distribution and copy the web archive file to the tomcat webapps root.

In the browser go to http://localhost:8080/axis2. Axis2 welcome page should appear.

The Service

An Axis2 archive (of .aar extension) has a certain directory structure not so different from a Web Archive.

META-INF folder contains the services descriptor file. The other is the binary which implements the service.

The service class itself is a plain old Java class which exposes the services it offers through public methods. My simple service would be the following.

SimpleService offers just one service named add which accepts two Integer parameters and returns the sum of them as an Integer.

Now this service needs a service descriptor which exposes the service class to Axis2 when asked.

A parameter named ServiceClass is defined with value com.chamiladealwis.ws.service.SimpleService which the FQN of the Java class we just wrote.

Now compile sources, create the Axis2 archive and deploy it in the Axis Server.

Browse to http://localhost:8080/axis2/services/listServices in your browser and you will see SimpleService being listed as an available service with add as an operation.

Click on the link to SimpleService to view the WSDL file which will describe the service and it’s operation in an abstracted XML interpretation that can be used to create clients in any language to consume the service.

The Client

The client code has to make use of a “Stub” of the service which will act as a proxy and a communication agent. Axis2 binary distribution includes tools which can generate the Java stub using the WSDL file as the source.

Download the Axis2 binary distribution, extract it and set AXIS2_HOME environment variable to its root. Add $AXIS2_HOME to $PATH.

Add the $AXIS2_HOME variable before export PATH line and modify $PATH to include $AXIS2_HOME/bin.

Now refresh terminal by sourcing the .profile file.

Copy the WSDL path of the SimpleService, go to the directory you’re going to create your client code and execute the following.

The WSDL path would be something similar to http://localhost:8080/axis2/services/SimpleService?wsdl.

This will create the Java stub and the CallbackHandler classes. The CallbackHandler class can be extended to implement custom success and error callback executions. The Stub is the class of main importance here. It contains the Request and Response types of the operations available from the Service it was generated from and the skeletal methods that call to the target endpoint once invoked. We will use these members to call our simple service.

Let’s go through the client code.

Consuming an operation available through a Web Service consists of following steps.

• Create an object of the stub. All method calls will be invoked through this object.

SimpleServiceStub serviceStub = new SimpleServiceStub();

• Create the request object. This will have methods to add input parameters to the request.

Add addReq = new Add(); 
addReq.setNum1(4); 
addReq.setNum2(8);

• Invoke and the operation method. The operation method will be invoked through the stub object and the invocation accepts a parameter of type of request object.

serviceStub.add(addReq);

• Catch the response object. The invocation will return the response object mainly containing the value returned by the operation.

AddResponse response = serviceStub.add(addReq);

• Extract the return value. By calling get_return() of the response object the return value can be extracted.

int sum = response.get_return();

As you see it’s pretty straightforward, although there are couple of things to keep in mind.

1. You have to regenerate the client stubs everytime you change most of the server code (obviously).
2. It’s good to check if the service has been properly deployed by going to the services page and checking the WSDL generation.
3. This was a simple client with simple input and output types. When complex types are involved there are some standards to be practiced. Be mindful that Web Services operate on a language and platform agnostic environment.
4. You will not be writing web services and clients this way most of the time! But that’s a topic for another post :)

Originally published at chamilad.github.io on July 1, 2014.