Introduction

According to most tutorials writing Web services is fun and easy. However, reality is different and often something goes wrong in between the seemingly easy and straight forward steps. How can the fault be traced down? A Web service makes things slightly harder and often these services are deployed inside a container such as Apache Tomcat bringing in extra parameters to the equation. This tutorial shows how to Debug a Web service implementation written in Axis2 and shows how the remote debugging feature of the Java Virtual Machine (VM) can be effectively utilized to debug Web services.

Know your Tools First

Like every good mechanic, a Web service developer needs to know his tools before attempting to debug the Web service. The first obvious requirement is a debugger itself. In today's world of productive Integrated Development Environments (IDEs) a java developer can select between two of equally good IDEs.

• IntelliJ IDEA

  Even when it is not free, IntelliJ IDEA is one of the very best IDEs. With a large number of developer friendly features, IDEA supports a fantastic number of configurations and comes built in with a very nice debugger.

• Eclipse

  Just as good as IDEA, Eclipse is a free IDE that supports multiple languages and features a nice plugin architecture. Eclipse also comes with a debugger.

In this tutorial both these IDE's will be used to demonstrate the debug configurations.

However, since we are talking about a Web service, a debugger is not just enough. A tool to monitor messages is needed. The obvious choice for this is the TCPMon from Apache WS Commons. Resources section contains the link to the Web site and TCPMon bundle comes with documentation of how to use it. This tutorial however focuses towards utilizing the remote debug capability of the Java debugger.

Remote Debugging With IntelliJ IDEA

Although with Apache Axis2 there can be a large number of possibilities. Let us consider one of the most frequent scenarios and form the picture

• Tomcat is installed as the servlet container.
• Axis2 Webapp is installed in the container.
• The code for the Web service is configured as an IntelliJ IDEA project.
• The service archive (.aar file) is uploaded to the Axis2 Webapp repository.

For more information on installing Axis2 in a servlet container and the Axis2 deployment mechanism, Official Axis2 documentation is an excellent source.

Let us go through the configuration, one step at a time. The feature that is being used here is the remote debugging capability of the Java VM (from JDK 1.4 upwards). A VM can be started in the debug mode and a debugger can attach itself to the VM through a socket remotely!

1. Set up the Tomcat VM to run in the debug mode. This can be done in several ways but the easiest and the most flexible way is to set up the CATALINA_OPTS environment variable. To force Tomcat to startup in the debug mode add the following options as the CATALINA_OPTS environment variable.

   -Xdebug -Xnoagent -Djava.compiler=NONE
   -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005

   This instructs the VM to start in the debug mode, use a socket transport, to suspend the VM while debugging and open up port 5005 for the debugger to connect. If you want the Tomcat instance to begin running immediately and then want to connect from the IDE then use suspend=n

2. Create an IDEA remote debug configuration. This is very simple and straightforward-

   Select 'Edit configuration' from the run configurations drop down

   

   
   

   Select the 'Remote' tab

   

   
   

   Add a configuration by clicking the '+' icon

   

   
   

   If the configuration is exactly the same as mentioned in step 1 then just the defaults will suffice. However, one may want to change the parameters a bit, most probably use a different port which can be adjusted by altering the option.s

   

   
   

   Click Ok.

3. Start Tomcat

   Note that if Tomcat is installed as an MS Windows service, starting the service might not work. Setting up the environment variables come into play only when using the scripts.

4. Start the debugger

   Just click the debug button.

   

   
   
   
5. When the debugger starts successfully, a message should appear in the IDEA debug window indicating a successful connection.

   

   
   

Now the Web service is ready to be debugged. Put break points inside the code in the usual way and invoke the Web service. As soon as the execution hits a line with a break point the debugger becomes active. It allows stepping, variable inspections, thread inspection and all the usual debugger functionality.

Remote Debugging with Eclipse

Consider the scenario in case 1 with a slight variation:

• Tomcat is installed as the servlet container.
• Axis2 Webapp is installed in the container.
• The code for the web service is configured as an Eclipse project.
• The service archive (.aar file) is uploaded to the Axis2 Webapp repository.

Let us go through the configuration, one step at a time.

1. Set up the Tomcat VM to run in the debug mode. This is exactly the same way as case 1 and can be done by setting up the CATALINA_OPTS environment variable.

   -Xdebug -Xnoagent -Djava.compiler=NONE
    -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000

   Note that the port is now changed to 8000 from the previous example.

2. Start Tomcat. Tomcat needs to be started before configuring Eclipse.
3. Create an Eclipse remote debug configuration. This is similar to the IDEA one but the menus and screens are different.

   Select 'Debug' from the drop down which pops up when the small arrow near the bug icon is clicked.

   

   
   

   Select 'Remote java application' from the left select pane.

   

   
   

   Add a configuration by clicking the 'New' button.

   

   
   

   If the configuration is exactly the same as mentioned in step 1 then just the defaults will suffice. However, one may want to change the parameters a bit, most probably use a different port which can be adjusted by altering the option.

   

   
   
4. Start the debugger

   Just click the 'debug' button.

Now the Web service is ready to be debugged. Put break points inside the code in the usual way and invoke the Web service. It is similar to IDEA and all the features of the debugger will be available through Eclipse as usual.

Conclusion

Although debugging Web services is seemingly a pain, one can utilize the remote debugging feature of the Java VM and a full featured IDE to make it much easier.

Resources

1. Apache TCPMon
2. Apache Axis2

Author

Ajith Ranabahu, Senior Software Engineer, WSO2. ajith AT wso2 DOT com