SOAP and .net services for Apache HTTP Server

This is an open source contribution for gsoap, to enable Apache HTTP Server to run SOAP and .net services on Linux and other Unices.

Overview

To build and configure the mod_gsoap SOAP service you have to do three main parts:

  1. Build mod_gsoap, which is a SOAP server independent generic module to allow gsoap shared libraries to be plugged into Apache HTTP Server. It contains the infrastructure to dynamically load the required gsoap servers at runtime, and the additional required shared libraries not statically linked into apache server. mod_gsoap passes the SOAP requests received from the clients, and calls into the SOAP server shared libraries and returns the response to the clients.

  2. Build one or more gsoap shared libraries that implement the SOAP services. As a sample a simple calculator was used. Implementing other SOAP servers is straight forward. Please see gsoap for details of how to use soapcpp2 to generate the wsdl , the C++ and the other related code for your own SOAP services.

  3. The configuration instructions for the apache http server in httpd.conf. This specifies which shared libraries are allowed to be loaded into the apache server process and where they reside.

The build process uses Automake . Inside that mod_gsoap.so is built in the standard Apache way using apxs. Please do not be shocked about the long description that follows. It is rather detailled, users acquainted with apache http server will skip most of it.

1. Building the Apache SOAP server

In order to reduce download times you must download and unpack the required standard packages like apache server separately from their original locations. For building I used libtool 1.4 downloaded from http://www.gnu.org/software/libtool, be sure to have it installed. Also be sure that you have apxs, which comes with the apache http server distribution, in your path.

Build instructions

Building a debugging version

The steps above are enough for running the release version. If you want to do debugging for mod_gsoap.c and/or your servers, you must enable debugging code. This is described in this paragraph. Skip it if you do not need debugging.

You can enable debugging for mod_gsoap.c by using --enable-debug
./configure --enable-debug

Debugging is easier when you link mod_gsoap.c statically into httpd, the Apache Server.

For that to the following:
Copy the whole mod_gsoap subdirectory to ~/apache_1.3.26/src/modules/
Next Edit the Configuration file (it is located in ~/apache/src).
Add the following lines:
# goap SOAP extension module.
AddModule modules/mod_gsoap/mod_gsoap.o



2. Implementing your own Servers

In my opinion it is not a good idea to start off with gsoap server programming by using this apache module. Before doing so (and especially before sending questions) please go to the gsoap home page and look at the very good and detailled examples and documentation there. Implement your server as a standalone server and test it. Once that works, you can easily convert it to run with mod_gsoap. How to convert your server to support mod_gsoap is described below in this chapter.

The only additional thing you must do to enable your own gsoap Server to be able to plug into Apache HTTP server is to add the lines below to your source code and build them as shared libraries. Then the required entry points will be exported.

Add the following 2 lines to your SOAP server source code:
#include "apache_gsoap.h"
IMPLEMENT_GSOAP_SERVER()

You also must change Makefile.am accordingly to add your source files and rename and run autoconf, automake, ./configure again of course. apache_gsoap.h came with the gsoap_apache_*.tgz that you downloaded above and will be in the include path of the compiler.

There is also a ConsoleServer subproject, that allows you to build and test your own gsoap server shared libraries indepent of Apache server. It is recommended to test your servers with this soaptest program before you try to use it in Apache Server. Change the search path for the library and the name of the library near the top of the file ConsoleServer.cpp for testing. Another subdirectory foo is there for testing, if you still get file not found errors in the attempt to load a shared library. foo does not depend on other libraries and will load also if your path is not correct. Of course it will not work as a soap server, it is only there to get your directory settings correct.

If you want to have a graphical development environment you can use kdevelop. See below how to use that. But also working with emacs and kdbg is fine. For implementing your own SOAP servers please download the standard gsoap package and follow the instructions there. The servers we use are separated into a shared library of its own, to allow the apache server to load them on demand.

3. Configuration of httpd.conf

Now after the binaries are built, it is necessary to tell Apache server where to find the libraries to answer the soap requests coming in. Locate the httpd.conf file that is in use on your installation (e.g. ~/apache-1.3.26/conf/httpd.conf or /usr/local/apache/conf/httpd.conf) and make your changes.

Programming and Debugging Tips

Lookup the error log file of Apache Server

mod_gsoap logs apache errors in the standard way. So see the apache log file, typically it is located at /usr/local/apache/logs/apache_log.

Be sure you Debug the correct process

Sometimes when you exit the debugger it can happen that the httpd process is still alive. So before you continue, it might be a good idea to run
ps -ef | grep httpd
to see if there is still a server alive, which should be killed before the next debugging session. For killing all active httpd processes I use:
kill `ps -ef | grep httpd | sed -e"s/\ * /:/g" | cut -f2 -d:`

You do not debug the process /usr/local/apache/bin/httpd, but the httpd program that you build in your source code directory ~/apache/src. The key to successful debugging is the -X flag. So in your debugger run httpd from ~/apache/src, but use the same configuration file as your production server will use. Use the following commandline to start debugging:
./httpd -X -f /usr/local/apache/conf/httpd.conf

When the process is started in the debugger, set your breakpoints and use your favourite browser and refresh the page http://127.0.0.1:8080/soap.

 

See also the Frequently asked Questions at the end of  the IIS description.

How to use kdevelop for Programming and Debugging of Apache modules

If you want to use kdevelop to debug Apache then you can change to the directory ~/apache/src and run:
kimport > apache.kdevprj

After that you can open apache.kdevprj as a kdevelop project. Use the appropriate dialogs in your debugging environment to set the commandline arguments for debugging.


I hope you will have fun with this.

Enjoy,

Christian Aberger.