Java SOAP Web Service With Apache Axis2 in Eclipse

Today we are going to build a SOAP based Java web service. We are using AXIS2 which serves as a SOAP implementation. I assume that you have already installed Java JDK in to your machine.

Requirements :

1) Eclipse EE – Download
2) Apache Tomcat - Download
3) Apache Axis2 Binary Distribution - Download
4) Apache Axis2 WAR Distribution - Download

While installing these programs, consider about default ports. There may be port conflicts if you neglect this fact. This becomes an issue only if you are allocating ports which are already used by previously installed programs. For an instance, there may be a port conflict when attempting to install Tomcat server using port 8080 in a machine where Oracle 10g is installed. Both of these use port 8080 by default. So you may change the ports as necessary during or after the installation.

Please note that there may be various compatibility issues when using Eclipse and Apache Tomcat with Axis2 to build our web service. Most of the problems can be minimized with Netbeans. GlassFish server supports out of the box in many occasions with Netbeans.
Let's deal with Netbeans at a later time.

I'm using Eclipse Indigo, Apache Tomcat 6 and Axis2 for this tutorial.

Extract Apache Axis2 Binary Distribution. Create an Environment Variable as AXIS2_HOME. Get the path to Axis2 installation directory and use it as the value of AXIS2_HOME Environment Variable. (something like C:\Program Files\axis2-1.6.2)

Extract Axis2 WAR Distribution and copy axis2.war file to Tomcat server webapps directory.

Now you are ready to go ahead with this tutorial. First check our road map.
1. Setup Development Environment in Eclipse.
2. Create Web Service.
3. Deploy web service.
4. Create a client who consumes Web Service.

1. Setup Development Environment in Eclipse.

Now you need to configure Eclipse for Tomcat server and Axis2.
Open Eclipse IDE and go to Window >> Preferences
Add new server runtime environment.



Select your Tomcat server version and click Next. Browse your Tomcat installation directory in next window.



Now configure Axis2 in Axis2 preferences under Web Services category. Browse your Axis2 installation directory. You should see this message if this is fine.
"Axis2 runtime loaded successfully"



Select Server and Runtime. Make sure your server runtime is selected. Web service runtime should be Apache Axis2.



 

2. Create Web Service.

First create a new Dynamic Web Project (File >> New >> Other) and choose Web >> Dynamic Web Project. Enter project settings in the first window.
Select the target runtime that we configured earlier.
You should modify the configuration so that Axis2 is included into the project.



Remeber to put a tick on Axis2 web services



Click Next>>Next and Finish. Now Eclipse will load the project.
Now it's time to create web service class. This class can contain some methods which are exposed to outside. The clients are going to consume this web service class. First we create a Plain Old Java Class and convert it into a web service. Right click on project and select New>> Class



Add a public method to this class.

[sourcecode language="java"]
package com.codezone4;

public class MyService
{
public String testMethod(String param)
{
return "Read " + param;
}
}
[/sourcecode]

To expose this file as a web service right click on the Java file and select Web Services >> Create Web Service
or
select File >> New >> Other and choose Web Service.
You can can add web service using one of above methods.

We use bottom-up approach as web service type. Select the class which acts as the web service(that we just created). Make sure your configurations are correct.



Click Next. Make sure Generate a default service.xml file is selected and click Next. Now you are asked to Start Server. Do it!
Then Click Next and Finish the dialog.
Now you should be able to reach your web service through your browser. Tomcat server is started and you gonna run your web service in Tomcat.
Right click on your project and select Run as >> Run on server.

You may see the below screen through your Eclipse web browser. Alternatively you can copy the following URL into your web browser bar.
http://localhost:8440/HelloWorldWebService/
This port number 8888 depends on your Tomcat configuarations.



Go to Services. Under Available Services you will find your own service. Click on MyService link (You will find your web service class name here).
Can you see bunch of beautiful xml? This is your WSDL(Web Service Description Language). The clients who consume your service communicate with this WSDL to access the functionality of the web service.
Copy the URL for WSDL file.
You can validate this file at a later time when you create the client. To do that enable WSDL validation for all files in Eclipse preferences. This option can be found under web service category.

Obviously you can play with your web service without a real client using Web Service Explorer tool in Eclipse. Click that icon



This will launch a screen similar to the following.



Click WSDL page icon. On the next screen, click WSDL Main under navigation section.
Enter your WSDL URL into the box and click Go. On the left you will see a hierarchical representation of your web service. Play around with this for a while and test your web service with different inputs....

3. Deploy web service.

In current situation, the web service can only be run within Eclipse. So we are going to deploy it to Tomcat server. First create .aar (Axis Archive)
Got to your web service directory using command prompt.
Eg. C:\Users\AAA\Documents\Eclipse\HelloWorldWebService\WebContent\WEB-INF\services\MyService

Enter following command to create .aar file.
jar cvf HelloWorldWebService.aar com META-INF
This will generate .aar file in your web service directory. Now wanna upload this file using the Administration panel in Axis2. You can enter this area using Axis home page Administration link.
username : admin
password : axis2

Or else you can simply copy the .aar file and paste into Tomcat webapps\axis2\WEB-INF\services directory.

To verify your deployment first stop Tomcat server in Eclipse. Click on red, small rectangular button on Servers panel to stop Tomcat.
Next go to Tomcat bin directory and find startup.bat file. Run this file to start Tomcat. If you are using Mac run startup.sh file.
Then go to your web service URL.
http://localhost:8440/HelloWorldWebService/

 

4. Create a Web service client

Select File >> New >> Other and choose Web Service Client.
Enter WSDL URL into the box. Here you can browse for WSDL and validate if needed.



This will generate two new classes called MyServiceStub.java and MyServiceCallbackHandler.java. Now we can create client. Create new class called TestClient.java and paste following code.

[sourcecode language="java"]
package com.codezone4;

import java.rmi.RemoteException;
import com.codezone4.MyServiceStub.TestMethod;
import com.codezone4.MyServiceStub.TestMethodResponse;

public class TestClient {

public static void main(String[] args) throws RemoteException {
MyServiceStub stub = new MyServiceStub();
TestMethod method = new TestMethod();
method.setParam(" Cheers!");
TestMethodResponse response = stub.testMethod(method);
System.out.println(response.get_return());

}

}

[/sourcecode]

Run this client as a Java application. Observe the output in console. You should see the message that resulted from remote method call if everything worked fine.

I think you enjoy this web service tut. Please leave a comment.
Happy coding!