Creating a Web service using Apache Axis2
by Laura Zavala

Apache Axis2 is an engine for Web services. The purpose of this guide is to get you started on creating services and clients using Axis2. Axis2 makes these tasks very easy, as it comes with code generator tools that simplify the work for you.
Basically, you can use the code generator to:
  • Generate code to access an existing service as a client.
  • Generate, from a class containing the functionality (public methods) you want to expose in a service, the WSDL file that describes the service functionality.
  • Generate, from a WSDL file describing the service functionality, the skeletal code to implement the service on the server side.
Getting started

Follow these steps to get get your environment ready for working with Axis2:
  1. Download and install a Java Development Kit (JDK) release (version 1.4 or  later)
  2. Set an environment variable JAVA_HOME to the pathname of the directory into which you installed the JDK release.
  3. Download Apache Axis2 and extract it to a target directory.
  4. Set the AXIS2_HOME environment variable to point to the target directory in the previous step.
  5. Add the AXIS2_HOME\bin directory to your PATH environment variable.
  6. Download Apache Ant and extract it to a target directory.
  7. Set the ANT_HOME environment variable to point to the target directory in the previous step.
  8. Add the ANT_HOME\bin directory to your PATH environment variable.
Generating a WSDL file from a Java class

We will create a simple WeightConverter service. Save the cfollowing code into a WeightConverter.java file and compile it:
public class WeightConverter {
   
    public double kgtopounds (double kg){
        return kg/2.20462262;
    }
    public double poundstokg (double pounds){
        return pounds*2.20462262;
    }

}

Use the following command to generates the appropriate WSDL file for our WeightConverter java class:

java2wsdl -cp . -tn weightconverter -stn weightconverter -cn WeightConverter
Generating the client code and the skeletal code to implement the service

The wsdl2java script generates Java code according to a given WSDL file to handle Web service invocations (Client side Stubs). This script also has the ability to generate service skeletons according to the given wsdl. Basically there are 3 different sets of files that you can generate by using wsdl2java:
  1. Only client stubs  (not using -ss, neither -g)
  2. Only server side files (using -ss, but not -g)
  3. Both, client stubs and server side files (using -ss and -g)

So, we will use the 3rd option to generate both, client stubs and server side files. Use the following command:

wsdl2java -ss -sd -g -uri WeightConverter.wsdl

A src directory is created with the source code for our server side files, as well as our client. Also, a resources directory is create with the WSDL file for the service and a service descriptor (services.xml) file. Finally a build.xml file is created in the current directory, which will be used to create the ws deployment file.

Filling the server skeletal code 

Now you need to fill WeightConverterSkeleton.java with the necessary business logic. You can copy the functionality from your original java file, though you need to change it a little to match the new datatypes. The new kgtopounds method in the WeightConverterSkeleton code looks like:

        public weightconverter.KgtopoundsResponse kgtopounds (weightconverter.Kgtopounds param0)
        {
                //Todo fill this with the necessary business logic
                throw new  java.lang.UnsupportedOperationException("Please implement " + this.getClass().getName() + "#kgtopounds");
        }

So you need to replace the  throw instruction (which is the default functionality for the case in which not implementation is provided befor edeploying the service) by your original functionality, which was:
    public double kgtopounds (double kg){
        return kg/2.20462262;
    }

But as you can see, the input and output parameters are different than in our original WeightConverter class.
The original kgtopounds method takes a double and returns a double. The new kgtopounds method takes a weightconverter.Kgtopounds object and returns a weightconverter.KgtopoundsResponse object. If you dive into these latest files you will find the methods public double getParam0() and public void set_return(double param) in them. You can use those methods to get the double value of the input parameter, then perform your original operations, and finally set the double value of the output. The result is as follows:

        public weightconverter.KgtopoundsResponse kgtopounds (weightconverter.Kgtopounds param0)
        {
                double kg = param0.getParam0();
                weightconverter.KgtopoundsResponse result = new weightconverter.KgtopoundsResponse();
                result.set_return(kg/2.20462262);
                return result;
        }

You need to modify the poundstokg method similarly.
Compiling the code

Download the compile.bat script into the src directory (to compile the source code files). This script calls the "javac" command after adding the classpath for Axis2 dependent libraries (*.jar files present in your AXIS2_HOME/lib).
Go to the src directory and compile with: compile wstest\*.java 
Deploying and running the service

Once you compiled the server files, use the ant command (run it where the build.xml file is) to generate the deployment files for the service. Go to the directory where the build.xml file is and run:

ant jar.server

A build directory will be created. Copy the lib\WeightConverter.aar file to the AXIS2_HOME/repository/services directory.

Then, run axis server with: axis2server. This will start an standalone Axis2 server using the AXIS2_HOME/repository directory as the Axis2 repository and the AXIS2_HOME/conf/axis2.xml as the Axis2 configuration file.

The client

You must have a file called WeightConverterStub. You can use this file to create a client for your ws. You still have to create a new java file (eg. WSClient.java) with a main method. This is what the main method should look like:
 
try {
  //Creates the client stub
  WeightConverterStub stub = new WeightConverterStub();
 
  //Sets the input parameter to the argument received in the command line
  weightconverter.Kgtopounds param = new weightconverter.Kgtopounds();
  param.setParam0(args[0]);

   //invokes the WS through the client stub
  weightconverter.KgtopoundsResponse result = stub.kgtopounds(param);
 
  //prints result
  System.out.println("\n\nThe Web service returned the following result: " + result.get_return() + "\n\n");
}
catch (Exception e) {System.out.println(e);}

Use the compile.bat script to compile the source code files. Use the axis2 command  to run the client.