Web Services Example Using Axis 2 and Tomcat

Aim
The aim of this Java Axis tutorial is to write a simple 'Hello World' web service and client in Java, using the Axis2 framework. Once created, the web-service will be deployed in Axis2, running on Tomcat. The client will be a remote Java client. Leave any questions or problems as comments and I will endeavour to answer them. See Web Services Using JWSDP and Tomcat for a Sun alternative.

Assumptions
This article assumes that you have Axis 2 installed and configured on Tomcat and you have a working version of the Java JDK. Please see Setting up Axis2 on Tomcat for more details. For purposes of this example Tomcat is running on port 8080 and the project directory is Axis2TomcatHelloWorld. Also for tcpmon you have the axis.jar file from Axis1 installed. Again see Setting up Axis2 on Tomcat for more details.

Versions used in this example

Sofware/Component	Image
Windows XP SP2	N/A
Axis 2 (bin)	Axis2-1.4-bin.zip
tomcat 6	apache-tomcat-6.0.18.zip
Java JDK 1.5.0	N/A
Axis 1 (for tcpmon)	axis-bin-1_4.tar.gz

jav Links to these files can be found here.

Although this is a quick 'helloworld' tutorial we will not sacrifice neatness for speed - so all the source files, class files etc will be kept in separate directories and as clean as possible. You will thank me for this later.

Create this directory structure in your working directory- similar to something you would get from eclipse. The structure used in this example is given below. Axis2TomcatHelloworld will be referred to as your project or working directory. Create this structure.

Axis2TomcatHelloworld
_|_client_bin
_|_client_src
_|__|_Axis2TomcatHelloWorldClient.java
_|_web_bin
_|__|_META-INF
_|__.__|_services.xml
_|_web_src
_.__|_HelloWorldServiceImplementation.java
_.__|_HelloWorldServiceInterfacejava

You can download the zipped example here.


The axis 2 binaries are unzipped in D:\downloads\axis2\axis2-1.4.1 directory for this tutorial.


Compiling the webservice code

1. Write the code. We don't really need an interface for this example, but I have added one for completeness, because we will use these exact same files for the JWSDP example. The  HelloCallEcho function will be exposed in this tutorial.
   

   1. package helloworld; 2. 3. import java.rmi.RemoteException; 4. 5. public interface HelloWorldServiceInterface extends java.rmi.Remote{ 6. public String HelloCallEcho(String hellostring)throws java.rmi.RemoteException; 7. public int HelloCallAdd(int helloNumber1, int helloNumber2)throws java.rmi.RemoteException; 8. } Hide line numbers

   Save this as HellowWorldServiceInterface.java in your web_src directory.
   next create the implementation.
   

   1. package helloworld; 2. 3. public class HelloWorldServiceImplementation implements HelloWorldServiceInterface{ 4. 5. public String HelloCallEcho(String hellostring) { 6. return "Web service echoing back - "+hellostring; 7. } 8. 9. public int HelloCallAdd(int helloNumber1, int helloNumber2) { 10. return helloNumber1 + helloNumber2; 11. } 12. } Hide line numbers

   Save this as HelloWorldServiceImplementation.java under in your web_src directory.
2. Open a command prompt and cd into your project directory (Axis2TomcateHelloWorld in this example).
3. Compile the code using,
   

   ..workspace\Axis2TomcatHelloWorld>javac -d web_bin web_src\*.java

   
   
4. Your web_bin directory should have some class file in there.
5. Create the services.xml file in the web_bin\META-INF directory.
   

   1. <service> 2. <description> 3. This is my first service, which says hello 4. </description> 5. <parameter name="ServiceClass">helloworld.HelloWorldServiceImplementation</parameter> 6. <operation name="HelloCallEcho"> 7. <messageReceiver 8. class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/> 9. </operation> 10. <operation name="HelloCallAdd"> 11. <messageReceiver 12. class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/> 13. </operation> 14. </service> Hide line numbers

   
   
6. Cd into web_bin directory and jar it all up using,
   

   ..workspace\Axis2TomcatHelloWorld\web_bin>jar -cvf HelloWorldServices.aar *

   
   

Deploying the Service

1. go to http://127.0.0.1:8080/axis2 - select Administration. The default username is 'admin' and the password is 'axis2.'
2. Select upload service and navigate to the HelloWorldServices.aar and upload.
3. Now navigate to 'available services' on the navigation pane on the left.
4. You should be able to see your service. Click on it and it should open up yout WSDL file.

Generating the stub code - required for the client.

1. Open a promt and cd to your working directory.
2. Generate the client stub by running wsdl2java.bat. Wsdl2java should be in your Axis2 directory under bin. The -S specifies the output directory.
   

   ..workspace\Axis2TomcatHelloWorld>D:\downloads\axis2-1.4.1-bin\axis2-1.4.1\bin\wsdl2java.bat -uri http://127.0.0.1:8080/axis2/services/axis2tomcathelloworld?wsdl -S client_src

   You can now go to the client_src/helloworld directory to see the generated files.

Compiling the client

1. Write the actual client code. All we are doing is setting up the stub and the request and then calling the function which returns a response. Save this file in the client_src directory.
   

   1. import helloworld.*; 2. import org.apache.log4j.*; 3. 4. public class Axis2TomcatHelloWorldClient { 5. static Logger logger = Logger.getLogger("Axis2TomcatHelloWorldClient.class"); 6. 7. public static void main(String[] args) throws Exception { 8. 9. Axis2TomcathelloworldStub stub = new Axis2TomcathelloworldStub(); 10. Axis2TomcathelloworldStub.HelloCallEcho helloReqEcho = 11. new Axis2TomcathelloworldStub.HelloCallEcho(); 12. helloReqEcho.setHellostring("client says hello Axis2"); 13. Axis2TomcathelloworldStub.HelloCallEchoResponse helloRespEcho = 14. stub.HelloCallEcho(helloReqEcho); 15. System.out.println(helloRespEcho.get_return()); 16. } 17. } Hide line numbers

   You can ignore the log4j stuff, it's just here for completetion.
2. Now go to the client_src directory and compile it.
   

   ..workspace\Axis2TomcatHelloWorld\client_src>javac -d ..\client_bin -extdirs D:\downloads\axis2-1.4.1-bin\axis2-1.4.1\lib Axis2TomcatHelloWorldClient.java

   
   

Running the application

1. CD into client_bin and run the client using the command below. Replace D:\downloads\axis2-1.4.1-bin\axis2-1.4.1\lib with the path to your Axis 2 lib directory,
   

   ...workspace\Axis2TomcatHelloWorld\client_bin>java -Djava.ext.dirs=D:\downloads\axis2-1.4.1-bin\axis2-1.4.1\lib Axis2TomcatHelloWorldClient

   You should see a printout saying 'hello back' from the web service.

Looking at the soap messages using tcpmon The way the monitor works is like a proxy. Your client connects to the monitor and the monitor connects to the web-service. Remember that tomcat is already running on 8080

1. Go back and edit the Axis2TomcatHelloworldClient.java. Add the URL as the parameter to the constructor,
   

   original	Axis2TomcathelloworldStub stub = new Axis2TomcathelloworldStub();
   modified	Axis2TomcathelloworldStub stub = new Axis2TomcathelloworldStub("http://127.0.0.1:8081/axis2/services/axis2tomcathelloworld.axis2tomcathelloworldHttpSoap12Endpoint/");

   
   
2. Compile the code as explained previously.
3. Open up another seprate command prompt and start up tcpmon,
   

   ...\anywhere>java -cp D:\downloads\axis-bin-1_4\axis-1_4\lib\axis.jar org.apache.axis.utils.tcpmon

   Please refer to the final section in the Setting up Axis2 on Tomcat for more details on this step and why we are using the axis.jar core from Axis 1. This should startup tcpmon.
4. In the tcpmon gui, in the listen port type in 8081 and press add.
5. Go to the 8081 tab at the top.
6. Now open up a command prompt and run the recompiled client as explained in the previous section- You should see SOAP messages send back and forth.