Web Services have gained tremendous popularity and widespread adoption. Since there is a lot of mystic surrounding the Web Services development and deployment, it is important to use the right tools that improve the developer productivity and hide the complexity of development and deployment details, allowing the developers to focus on the implementation logic. There are several SOAP frameworks that help build Web Services. In this discussion the focus will be on the Apache AXIS2 soap stack. AXIS2 is the next generation of soap engine from the Apache stable after Apache Soap and Apache AXIS1.

AXIS2 is a complete overhaul of its predecessors and has several improvements in terms of performance and scalability.  AXIS2 when used in conjunction with Eclipse development tools provides excellent design time and run time platforms that aid rapid development of Web Services. This article discusses these tools and how they are used to quickly develop Web Services. This article is a step by step illustration to developing and deploying web services using AXIS2 and Eclipse IDE and related plugins.

We use the following tools and runtimes to build our Web Services in this exercise.

• Java 1.6
• AXIS2 Version 1.4
• Eclipse 3.2.x
• Tomcat 4.1
• Apache AXIS2 Service Archiver Wizard Plugin
• Apache AXIS2 Code Generator Wizard Plugin

To install AXIS2 place the axis2.war file from the AXIS2 distribution in the ‘webapps’ folder of the tomcat distribution. If you have installed tomcat on ‘C:’ drive, place axis2.war under ‘c:\tomcat\webapps’. Restart tomcat. To verify if the AXIS2 installation went through fine, try loading the ‘HappyAxis’ page: http://localhost:8080/axis2/axis2-web/HappyAxis.jsp

Also, unzip the AXIS2 distribution to the ‘C:’ drive.

Eclipse Plugin installation

After downloading the binary distribution of Service Archiver, Code Generator, unzip both in the ‘plugins’ directory of eclipse installation. If you have installed eclipse on the ‘C:’ drive, the unzipped contents would be placed under c:\eclipse\plugins.

Now that runtime and design time platforms are set up, we can start the Web Services development. Web Services development can be using two ways.

• Top Down Development
• Bottom Up Development

In this article I will explain the ‘Top Down Development’. In the ’Top Down’ method we start with a WSDL document as a starting point. I will use the following WSDL for the purpose of my exercise.

<definitions targetNamespace="http://example.org/math/"
   xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" 
   xmlns="http://schemas.xmlsoap.org/wsdl/" 
   xmlns:ns="http://example.org/math/types/" 
   xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" 
   xmlns:xs="http://www.w3.org/2001/XMLSchema"
   xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
   xmlns:mime="http://schemas.xmlsoap.org/wsdl/mime/" 
   xmlns:y="http://example.org/math/">
   
  <types>
    <xs:schema attributeFormDefault="unqualified" 
  	elementFormDefault="unqualified" 
  	targetNamespace="http://example.org/math/types/" 
  	xmlns="http://example.org/math/types/">
        <xs:complexType name="MathInput">
          <xs:sequence>
                <xs:element name="x" type="xs:double" /> 
                <xs:element name="y" type="xs:double" /> 
            </xs:sequence>
        </xs:complexType>
        <xs:complexType name="MathOutput">
            <xs:sequence>
                <xs:element name="result" type="xs:double" /> 
            </xs:sequence>
        </xs:complexType>
        <xs:element name="Add" type="MathInput" /> 
        <xs:element name="AddResponse" type="MathOutput" /> 
    </xs:schema>
  </types>
  
  <message name="AddMessage">
    <part name="parameters" element="ns:Add" /> 
  </message>

  <message name="AddResponseMessage">
    <part name="parameters" element="ns:AddResponse" /> 
  </message>
  
  <portType name="MathInterface">
     <operation name="Add">
         <input message="y:AddMessage" /> 
         <output message="y:AddResponseMessage" /> 
    </operation>
  </portType>
<binding name="MathSoapHttpBinding" type="y:MathInterface">
	<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/> 
		<operation name="Add">
	<soap:operation soapAction="http://example.org/math/Add"/> 
	   <input>
		<soap:body use="literal"/> 
	   </input>
	   <output>
		<soap:body use="literal" /> 
	   </output>
	</operation>
</binding>
<service name="MathService">
    <port name="MathEndpoint" binding="y:MathSoapHttpBinding">
         <soap:address location="http://localhost:8080/axis2/services/MathService" /> 
    </port>
</service>
</definitions>

Place the MathService.wsdl under the ‘WSDL’ folder.

Next step is to generate the server side code. Press Ctrl+N. We get the following screen.

Choose the Axis2 Code Generator. It will pop up the following window.

Choose the first option. Click Next.

Give the exact location of the WSDL file. Click Next. 

Choose the ‘Custom’ option and ‘Generate Server Side Code’, and default Services.xml. Click Next to get the following window. 

Choose the ‘Browse and select a project on current Eclipse workspace’. Choose the MathService project from the resulting window. Click Ok and Choose ‘Add Axis2 libraries’. Click Finish.

Refresh the project folders. You will find the ‘lib’ folder and the ‘resources’ folder.
Add the jars in the ‘lib’ folder to the build path and compile the generated code.

Now modify the skeleton code [in our case, org.example.math.MathServiceSkeleton.java] to include the implementation logic as below:

public org.example.math.types.AddResponse Add(org.example.math.types.Add add) {
  AddResponse response = new AddResponse();
  MathOutput output = new MathOutput();

  double x = add.getAdd().getX();
  double y = add.getAdd().getY();

  output.setResult(x+y);
  response.setAddResponse(output);

  return response;
}

Rebuild the project again [Project->Clean].

Once the source code is generated and services.xml [in the resources folder] is generated, it is time to archive the service. This is done using the Service Archiver wizard. On the eclipse project, click Ctrl+N. After choosing the Service Archiver wizard, provide the exact class file location in the next window. Select the option ‘Include .class files only’. 

Click Next We get the following window. Choose the ‘Select WSDL’ option.  And click Next.

On the next window click Next.

On the resulting window, provide the reference to the ‘services.xml’ as below. Click Next.

On the resulting window, provide the output location for the archive generated. Click Finish.

This results in the following window.

In the build folder, you can see that the MathService.jar file has been generated. Rename it to MathService.aar. Drop the archive in <TOMCAT_HOME>\webapps\axis2\WEB-INF\services folder. To verify the service has been deployed properly, restart the Tomcat server.

Access the URL http://localhost:8080/axis/services/listServices to see the deployed service. This page should show the service status as ‘Active’.

Now that the service has been deployed, we need to generate the client that accesses the service. This is generated by the Code Generator wizard. On the project click ‘Ctrl+N’. Choose the ‘Axis2 Code Generator’.  From the resulting window choose the first option.

Click Next.

On the resulting window, provide the exact location of the ‘wsdl’ file.

Click Next.

On the resulting window retain the default options and click Next.  After clicking Next, the following window will be shown. Specify the location where the client code will be placed as shown below.

Note: Do not choose the ‘Add AXIS2 codegen jars’ option this time.

On clicking Finish, the following window appears.

On refreshing the ‘src’ folder, you can see the client side code in the form of MathServiceStub.java and MathServiceCallbackHandler.java.

Write the client code around the stubs generated in the previous step as shown below. There are two types of clients. Synchronous/blocking client. Asynchronous/non-blocking client. We will discuss the synchronous client first.
>> code 2

Execute the client. On successful execution you will see the following output in the Eclipse console.

If you recall, while generating client stubs, we chose to generate synchronous and asynchronous clients. To write an asynchronous client, we need to write a CallBack class and register the client with this class. Let’s write the callback class.

package org.example.math;

import org.example.math.MathServiceStub.AddResponse;

public class CallBack extends MathServiceCallbackHandler {
  private boolean complete = false;
  
  public void receiveResultAdd(AddResponse result) {
    System.out.println("Result in Callback " + result.getAddResponse().getResult());
    complete = true;
  }

  public boolean isComplete() {
    return complete
  }
}

Let’s write the client which makes use of the above callback class.

public static void main(String[] args)

  MathServiceStub stub
  
  try {
    stub = new MathServiceStub("http://localhost:8080/axis2/services/mathService");
    MathServiceStub.Add add = MathServiceStub.Add();
    MathServiceStub.MathInput input = new MathServiceStub.MathInput();
    input.setX(3);
    input.setY(5)
    add.setAdd(input);
    CallBack cb = new CallBack();
    stub.startAdd(add, cb);

    while(!cb.isComplete()) {
      System.out.println("Do Something");
    }
  } catch (AxisFault e) {
    e.printStackTrace();
  } catch (RemoteException e) {
    e.printStackTrace();
  }
}

On executing the above client you should see the following output. The output “Do Something” indicates that the client was not waiting for the response from the server.

Web Services are a key technology on our journey to Service Oriented Architectures. They also play vital role in the Web 3.0 computing paradigm. Apache AXIS2 is an excellent SOAP framework and when used along with Eclipse IDE, AXIS2 Code Generator, and Service Archiver plug-ins, it greatly simplifies the development and deployment process of Web Services. It improves developer productivity by automating tasks and hiding some of the complexity related to the development and deployment.

1. Tomcat Installable [http://tomcat.apache.org]
2. AXIS 2 Framework [http://ws.apache.org/axis2]
3. Eclipse IDE [http://www.eclipse.org/downloads]
4. AXIS2 Code Generator Eclipse plug-in
5. AXIS2 Service Archiver Eclipse plug-in [http://ws.apache.org/axis2/tools/index.html]

Prasad Katti has over 10 years of experience in software development using Java, J2EE, messaging based integration technologies. He is also a Sun Certified Enterprise Architect and Java Developer.