Debugging Axis2/C Services and Clients

In this tutorial, Supun Kamburugamuva illustrates debugging Apache Axis2/C services and clients in both Windows and Linux platforms under different deployment scenarios.

Applies To

Project/Lan	Apache Axis2/C any version
Tools Required	gdb, Visual Studio 2005
Environment	Linux or Windows

Introduction
Debugging Services
Debugging Axis2/C clients
Summary

Introduction

As an Apache Axis2/C Web services developer, at one point or the other during the development cycle the need will arise for you to debug Axis2/C services and clients.

I assume you have a basic knowledge on debugging programs in Linux or Windows. You will also need to have a source distribution of Axis2/C available as I will be using a sample service and a client shipped with Axis2/C for llustrating the debugging procedure. If you have a source distribution, you can build it by following the guidelines given in the Axis2/C manual and installation guide. Building Axis2/C on any supported platform is a very easy task.

I have used an echo service and a client for demonstrating the debugging procedure. Source code for the client and server can be found in <AXIS2C_SRC_DIR>/sample/clients/echo and <AXIS2C_SRC_DIR>/sample/server/echo locations, respectively.

If you do not want to build Axis2/C from the scratch, you can use your own service and client with a binary distribution of Axis2/C. Obviously, both the service and client must be built with debugging enabled.

Debugging Services

Axis2/C Web services are shared object files (in Linux) or dynamic link library files (in Windows) that exports two functions and instantiate the axis2_svc_skeleton_t structure. Services are deployed in the <AXIS2C_BIN_HOME>/services directory. A service has a .so (Linux) or .dll (Windows) file and a configuration file called services.xml. Services should be hosted within a folder with the name as the service.

You need to build Axis2/C and its samples as specified in the Axis2/C manual. Client binaries are copied into the directory {AXIS2C_BIN_DIR}/bin/samples. Services binaries are copied into the {AXIS2C_BIN_DIR}/services directory.

If you are using your own service deploy it to Axis2/C.

Start Axis2/C and type the http://<yourserver>/axis2/services in your Web browser to verify whether the service is actually deployed or not. If the service is deployed correctly, your service name should be in the list of services that are displayed in the browser.

Note: Axis2/C Windows source distribution has a Visual Studio 2005 solution. The solution can be found in <AXIS2C_SRC_DIR>/ides/vc/axis2c directory.

Axis2 http server

Axis2 HTTP server is a simple HTTP server capable of hosting Axis2/C Web services only. It is part of the Axis2/C distribution. Axis2 HTTP server binary can be found in the <AXIS2C_BIN_HOME>/bin directory.

Windows

Starting the axis2_http_server from the Axis2/C VC solution

Obviously the first thing you need to do is to start the axis2_http_server. If you start the axis2_http_server from the Axis2/C VC solution, you can then go ahead and directly start debugging the services. All you have to do is to put a few break points in to the service files within the Axis2/C solution. Following are the steps required:

Start the axis2_http_server.
- First, make it the startup project by clicking the right mouse button on axis2_http_server project and choose “set as StartUp project”
- Make sure that axis2_http_server project’s working directory is set correctly. This should be <AXIS2C_SRC_DIR>\ides\vc\axis2c\deploy\bin
Open the service's source files from Axis2/C VC solution
Put a few break points into service's source files
Send a request to Axis2/C

Starting the axis2_http_server from command prompt

If you didn’t start axis2_http_server from the Axis2/C VC solution, then you need to use the service's VC solution or Axis2/C solution for debugging the service. If you are using a binary version of Axis2/C, then the only option you have is the service’s VC solution.

In the VC solution go to debug menu and choose attach to process.
In “attach to process” dialog box choose the axis2_http_serve.exe.
Put some break points in the service's source files
Send a request to the service

If the service is properly loaded by Axis2/C, you must be able to debug the service. Axis2/C loads the services when it receives the first request for that service. So when you specify debug points for a service without sending a request to that service, breakpoints appear as yellow circles ( and not red circles). This indicates that no symbols are loaded for the break points. This is perfectly normal since Axis2/C does not load a service until the first request for that service is received.

Linux

Start the axis2_http_server using gdb.
Put a few break points in the service's source files.
- When you put a break point within a service, gdb will complain that it cannot find that break point. Then it will ask you to make that break point pending for future shared library loads. Here, you expected to say yes by typing ‘y’. This happens because Axis2/C loads services dynamically, during run time. So when the as the server starts, it does not know about the services it is to load in the future.
Run the program (by typing "run" in the gdb prompt)

$ gdb axis2_http_server
(gdb) br <break points>
(gdb) r

Send a request to the service

In the figure above I have shown a debug session of the echo sample service.

The above process is similar in Axis2/c tcp server as well.

Apache Server

Follow instructions given in the Axis2/C manual to install Axis2/C with the Apache server.

Windows

Start Apache server from the command line by giving the –X option. This will force Apache not to create threads and it will ease the debugging process.
From Axis2/C VC solution or the service’s VC solution, go to debug menu and choose 'attach to process'. Choose httpd.exe from attach to process dialog box.
Put a few break points in the service's source files.
Send a request to the service

Linux

Start the Apache server using gdb.
- gdb httpd
Put some break points in your service's source files.
- (gdb) br <break points>
Run the apache server specifying the -X option.
- (gdb) r -X
Send a request to the service

$ gdb httpd
(gdb) br  <break point>
(gdb) run -X

You may want to run the gdb command as super user. When you try to set break points, gdb will complain saying that it cannot find break points. Then it will ask you to make the break points pending similar to the case with the axis2 http server. Specify yes to and run the server.

If everything goes well, the break points should hit. The figure below illustrates a debugging session for Axis2/C with httpd.

Microsoft Internet Information Services (IIS) Server

With IIS server, the process is almost same as with the Apache server. Deploy Axis2/C in the IIS, by following guidelines given in the Axis2/C manual. Then start the IIS server. If you are using IIS 6 or 7, you first need to send a request to the IIS server before start debugging. In IIS 6 and 7, Axis2/C is initialized when IIS receives the first request for Axis2/C.

Start the IIS Server
If you are using IIS 6 or 7 send a request to the IIS server.
From the VC solution (Service or Axis2/C) go to debug menu and choose 'attach to process'.
- If you are using IIS 5.1, choose the process inetinfo.exe.
- If you are using IIS 6 or 7, choose the process W3wp.exe.
Put a few break points in the service's source files
Send a request to the service.

Debugging Axis2/C clients

Axis2/C clients are executable files. So you can start debugging clients rightaway, as you would do with any other executable. In Linux, start the client using gdb. For Windows, start debugging the client from its VC project.

Summary

In this tutorial I’ve focused on illustrating how to debug Axis2/C services in different deployment scenarios. If you follow the tutorial carefully, you will clearly see that it is very easy to setup and debug Axis2/C services.