Thursday, January 23, 2014

How to write Simple Axis2 Service

Since I have struggled writing an Axis2 service, I thought of preserving and sharing the knowledge I acquired.

Let's begin,

There are so many tutorials explaining how to write an Axis2 services but they seems not adequate for a beginner in Axis2. So I'll take an step by step approach.

Step one
downloading all necessary and required resources. (in this post I'm not going to use axis2 server directly, I'm going to use Apache Tomcat server as the server and use Axis2 as a service inside it and host my service inside Tomcat)

1) so you should need Apache Tomcat, download it from here (since I am using jdk6, I had to use Tomcat 7 or below)
2) Download Axis2 WAR distribution zip and Binary distribution zip from here (download the latest version, in this example I used 1.6.2)

Step two
when you creates an axis2 service you simply have to create the service and define the service in a services.xml then you can package them to a "aar" package using maven "axis2-aar-maven-plugin".

In a web service we invoke a method in a class. So here comes the question, how do we pass parameters to that method and how can we return a result from that, should we only use String format? or can we use objects for that purpose? actually that was the question I faced when creating my first axis2 service.

The answer is you can use any type of objects as your input to the axis2 service and you can return any kind of object from the service. But as I learn there is a exception, we cannot use Collections in those input parameters or return values. Reason for that is Axis2 use its own object processor and it cannot handle collections.

Step three
So lets begin coding :)
first create a folder and file structure as given below

Image 1 - Folder Structure
Don't worry about the contents of files such as pom.xml, service.xml yet, just create the above structure. I think you will understand the above structure. I'll give a simple description

Since I'm creating a maven project there is that pom.xml. The services.xml file I mentioned above is located in resources--> META-INF folder there is a file in case we use log4j for logging purposes and finally there is the class which contains the service methods and a bean class which I'm intend to use as a return value of my service

Step four
using any of your favorite editors, edit the pom.xml file as below



    Axis2 Server App







I think the pom file is also self explanatory. but for the sake of this post I'll give some brief introduction

There is only one dependency for the log4j library. And there are three plugins, maven compiler plugin for the compilation process, maven dependency plugin to copy dependencies to the final package, and finally "axis2-aar-maven-plugin" to create the "aar" bundle. It's straight forward, as you can see I have given the path where my services.xml file reside and given the OrderService as "aar" file a name, thats pretty much it.

Step five
Now let's move on to class, edit it as below

public class OrderService {
    public static Logger logger = Logger.getLogger(OrderService.class);
    public BuyResponse buyProduct(int requestType, String productName, int quantity) {"OrderService::buyProduct --> process invoked, requestType - " + requestType + " productName - " + productName + " quantity - " + quantity);
        //what ever u need to do with the data anc create the return object

        BuyResponse response = new BuyResponse();

        return response;


Little bit about the code. In class there is a method called buyProduct. that's our service method. when ever we invoke our orderservice this method get invoked. So when we are going to invoke this service we have to provide those parameters, requestType, productName, quantity

If you think this parameter declaration is not a correct way, you can create one single object and use that as a parameter as given below

    public BuyResponse buyProduct(BuyProductRequest req) {"OrderService::buyProduct --> process invoked, requestType - " + requestType + " productName - " + productName + " quantity - " + quantity);
        //what ever u need to do with the data anc create the return object

        BuyResponse response = new BuyResponse();

        return response;

Now we have created our web service implementation.

Step six
Then we have to mention about the service in "services.xml" file as given below



There are two xml elements parameter element and operation element. In parameter element we define which is the service class. In operation element we define which are the service methods in the service class.

That's it almost finished, let's build it and deploy it.

Step seven
use maven to build the project (mvn install)

1) Unzip the downloaded Tomcat distribution. 
2) Unzip the downloaded file
3) Copy axis2.war file inside that in to the tomcat distribution's webapps directory.
Next step is to start tomcat server. To do that run the or startup.bat file depending on whether you work in windows or Linux which reside inside tomcat distribution's bin directory.

Then go to this (http://localhost:8080/axis2/axis2-admin/) url and login with username admin and password axis2

Then go to Upload Service link and upload the "OrderService.aar" file which is inside target directory of your project.

It's done :) you have successfully created and deployed an axis2 service
In my next blog post I'll show you how to create a client application to consume this web service. 

(for your convenience I have attached the full source code for above example here)