This is an open source contribution by Christian Aberger for IdooXoap, an open source SOAP implementation that enables Apache Server to be a SOAP server.
The IdooXoap SOAP service consists of two main parts:
mod_isoap, which is a SOAP server independent generic module to allow IdooXoap servers to be plugged into Apache Server. It contains the infrastructure to dynamically load the required IdooXoap servers at runtime, and the support libraries they need. It reads the SOAP requests from the clients, calls into the SOAP server shared libraries and returns the response to the clients.
One or more IdooXoap server shared libraries that implement the SOAP services. As a sample the structures sample from the IdooXoap distribution was used. Implementing other SOAP servers is straight forward. Please see IdooXoap for details of how to use ServiceCompilerC to generate the C++ code for other servers.
The build process also reflects this separation into 2 pieces. The mod_isoap is built in the standard Apache way, while the SOAP servers use Automake in order to be portable. Please do not be shocked about the long description that follows. What follows is a very detailled description, also for users not very much acquainted with apache server.
In order to reduce download times you have to download and unpack standard packages like xerces and apache server separately from their original locations. The following description assumes that you unpack the apache source directly into your home directory, which will be abbreviated with ~. Any other directory will also be OK, but it is important that you keep the relative location of the directories below apache intact. For building I used libtool 1.4 downloaded from http://www.gnu.org/software/libtool, be sure to install it with ./configure then make and make install. I am afraid you will not be able to compile it with older versions of libtool.
download apache_1.3.19.tar.gz from http://www.apache.org/httpd
download the binaries of xerces (e.g. xerces-c1_4_0-linux.tar.gz for linux) from http://xml.apache.org/dist/xerces-c/stable/
download the current isoap.tar.gz from http://www.webware.at/SOAP
download the fix for dom.cpp from http://www.webware.at/SOAP and replace the file ./src/dom.cpp from the original isoap.tar.gz,it contains a hotfix for DOM_xcode() function
unpack apache_1.3.19.tar.gz to your home directory ~.
rename ~/apache_1.3.19 to ~/apache
you must unpack isoap.tar.gz to the apache subdirectory ~/apache/src/modules. Make sure after unpack of isoap.tar.gz that you have the directory ~/apache/src/modules/isoap/SOAP
unpack xerces so that it is a direct
subdirectory of ~/apache/src/modules/isoap/SOAP and rename
xerces-c1_4_0-linux to xerces.
or if you have installed xerces
already somewhere else, make as an alternative a symbolic link to
the xerces 1.4 directory that you have already on your disk, e.g.
cd
~/apache/src/modules/isoap/SOAP
ln
-s /usr/local/xerces-c1_4_0-linux xerces
Verify now that ~/apache/src/modules/isoap/SOAP has a subdirectory named xerces that contains the xerces distribution, and other subdirectories like client, server, src
For generating the servers you can download the original soap.tar.gz from http://www.webware.at/SOAP. It contains the java classes to generate your soap servers (this is not available any more from the IDOOX site currently, later the code should be upgraded to use WASP C++ Lite, any contributions are welcome, please let me know. The sources I used are from an older package IdooXoap-C-0.95.tgz).
The build consists of two main parts: building the SOAP server shared libaries that implement your personal SOAP servers, independent of Apache server. The second step is to build mod_isoap, which is an apache module that will load any of your SOAP servers into Apache server and execute it if requests for it come in.
In a command shell change to the directory ~/apache/src/modules/isoap/SOAP. Then run:
./configure
make
This will build the libraries and shared objects required.
Note:
If you build for a production environment, you should remove the
debugging code. You can set other compiler options in the
configure.in file. Search for the line containing [CXXFLAGS="-g
-D_NDEBUG"], then run automake, autoconf, configure, make clean,
make.
There is also a ConsoleServer subproject, that allows you to build and test your own IdooXoap servers 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 LD_LIBRARY_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 package IdooXoap 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.
The only additional thing you must do to run your IdooXoap Server under Apache server is to add the file ServerFactory.cpp to your project and change the name of the include file and the name of your server. Here is the file as it is used for the structures sample:
#define
DYNAMIC_SOAP_SERVER_IMPLEMENTATION
#include
"DynamicSOAPServer.h"
#include "serviceIA.h"
// just as a demo. Add here whatever include files you need for your
IdooXoap SOAP
server.
BEGIN_SOAP_SERVER_ENTRY_TABLE
SOAP_SERVER_ENTRY("structures",
serviceIA)
END_SOAP_SERVER_ENTRY_TABLE
Rename everywhere „structures“ with the name of your server. If you use additional files to implement your server, you have to add these to Makefile.am and rename structures to whatever name your SOAP server has. After that run automake, autoconf, configure, make clean, make from the~/apache/src/modules/isoap/SOAP directory.
For testing the Soap servers with ConsoleServer.cpp your need the
libxerces-c1_4.so shared library. Make sure that your LD_LIBRARY_PATH
contains this. For example, add to your ~/.bashrc file the following
line:
export
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:~/apache/src/modules/isoap/SOAP/xerces/lib
or copy the libxerces-c1_4.so to an appropriate place in your LD_LIBRARY_PATH
Note: Due to security reasons the loader in mod_isoap does not use the LD_LIBRARY_PATH, you have to explicitly configure the location of your SOAP server shared libraries in the file httpd.conf (see later for mod_isoap).
mod_isoap is responible to call your SOAP server dynamic library when a SOAPAction request comes in. It is independent of your SOAP servers and a general interface to Apache Server. It is built in the standard way as Apache Server 3rd party libraries are built. Follow the following steps:
Edit the Configuration file (it is located in
~/apache/src).
Add the following lines:
#
IdooXoap SOAP extension module.
AddModule
modules/isoap/mod_isoap.o
Iin
the same file locate in the section Makefile configuration the line
containing EXTRA_LIBS and add -ldl (for the dlopen function) and the
-lpthread:
EXTRA_LIBS=-ldl
-lpthread
This
links the libtool library to httpd for portable loading of shared
dlls. If you want to debug, also add -g to the line containing
EXTRA_CFLAGS:
EXTRA_CFLAGS=-g
Remove
the -g again for release builds. Do not remove the libpthread! This
library must be linked with httpd, or it will block the server when
multiple requests come in.
There is also a ConfigurationSamples directory below isoap, which contains sample files edited in the way described here, where you can compare your changes.
Run
the src/Configure script:
cd
~/apache/src
./Configure
This
will build the Makefile for the server itself.
Note:
do not run ./apache/configure after it, this will overwrite the
Makefiles generated above. For other platforms than linux there
might be a minor problem. If so, please have a look at
.../isoap/Makefile.tmpl in that case. The standard Apache
distribution does not use C++,
only C. So your operating systems C - compiler commandline might not
accept .cpp files, if so change the compiler $(CC) compiler
directive in Makefile.tmpl appropriatly (e.g. to c++) and run
Configure again.
Build the Apache Server, together
with the mod_isoap by running in the current ~/apache/src
directory:
make
The
previous step should have produced the file httpd
Check that the
mod_isoap has really been linked correctly by running:
httpd
-l
This should list as a module among
others also mod_isoap.cpp
In
the next step we install apache to a directory of its own by running
the standard apache install command from the ~/apache directory.
Before doing so, read the README.configure file in the apache
distribution. After you know what you are doing, run the following
command from ~/apache:
make install
This
will generate the apache server in the directory you specified (or
usually /usr/local/apache if you did not do so). This step will also
generate the httpd.conf file that we need for debugging. You can of
course omit this step, if was only done to easily get a working
apache distribution on your machine, and a httpd.conf file that we
must change in the next steps. If you already have a working
installation, you can use that.
In the next step it is necessary to
tell Apache to use your module for soap requests. For that the
httpd.conf file must be edited.
This file will also be used to
explicitly start debugging of the apache server process httpd and
step into mod_isoap with e.g. kdbg
debugger. The same file is used when you run apache as a daemon.
This procedure is identical to what is described in the example
module README in the standard Apache distribution, only with
different names. Add the following lines to httpd.conf, near the
other <Location> sections:
#
SOAP handler (see http://www.w3c.org/TR/SOAP)
<Location
/soap>
SetHandler isoap-handler
SupportLibrary
/home/myusername/src/apache/src/modules/isoap/SOAP/xerces/lib/libxerces-c1_4.so
SupportLibrary
/home/myusername/src/apache/src/modules/isoap/SOAP/src/soap/.libs/libsoap.so
SOAPLibrary
/home/myusername/src/apache/src/modules/isoap/SOAP/server/example/structures/.libs/libstructures.so
</Location>
You can paste the lines
above from the sample file in ConfigurationSamples subdirectory. Of
course you must change „myusername“ to your login name, so
that the string /home/myusername above corresponds to your home
directory. Do not use ~ for your home directory here. This will not
be resolved by dlopen()! The isoap-handler knows 2 configuration
directives:
SOAPLibrary is the full path to the
library that contains your SOAP server shared library, with
mandatory exported function handleRequest as defined in the include
file „SoapServerInterface.h“. It tells the extension what
shared object library to load to serve the SOAP requests for this
location at runtime. You must change the path of course to the full
path of your server. It is better to specifiy the full path, and not
to use the LD_LIBRARY_PATH due to security reasons.
SupportLibrary
are all libraries needed by your Soap server shared library. They
are dynamically loaded into the apache server process httpd.
Otherwise it would be necessary to statically link these libraries
and rebuild httpd and mod_isoap every time you change something.
This was not the desired goal.
Now test if the Apache Server
itself is correctly configured, run the following from your
~/apache/src directory:
./httpd
-X -f /usr/local/apache/conf/httpd.conf
This will launch the server in
console mode (does not return until you cancel it). Then open your
favourite Web Browser and browse to:
http://127.0.0.1:8080
This
should give a standard apache response, has nothing to do with your
mod_isoap yet. The port 8080 was also set in httpd.conf, if you
don't get a response, check the port and see the error_log file. For
the production server it maybe will be port 80, which you do not
need to specify explicitly in the browser then. But for debugging I
recommend to stay with port 8080, because for port 80 you would need
root priviledges for debugging, which is not wise.
As a next step let us test if your
mod_isoap responds. The request must contain the location you gave
in the <Location> directive, and separated with a question
mark the name of your SOAP server as defined in the
ServerFactory.cpp file in the BEGIN_SOAP_SERVER_ENTRY_TABLE (see
above).
Enter as address in your
browser:
http://127.0.0.1:8080/soap?structures
This
should give a response from mod_isoap, an error message, because
your browser will propably not send the required SOAPAction header.
Note: the soap virtual directory was defined by yourself in the
<Location> instruction above, structures is the identification
string for the SoapServerFactory.
Well, now it is time to check if
Apache Server can answer your SOAP requests. Run the structues
client demo program. Enter the following:
cd
~/apache/src/isoap/SOAP/client/structures
structuresclient
http://127.0.0.1:8080/soap?structures
This should answer
the SOAP requests in the same way as the ConsoleServer does, but of
course with all the quality, speed, scalability, stability etc. of
the world's most popular http server.
mod_isoap logs apache errors in the standard way. So see the apache log file, typically it is located at /usr/local/apache/logs/apache_log.
For debugging it is necessary to compile with the -g compiler
option. There are two places where you must adjust this. In the
~/apache/src/Configuration file search for the line where
EXTRA_CFLAGS is and add a -g to it:
EXTRA_CFLAGS=-g
In
the file ~/apache/src/modules/isoap/SOAP/configure.in you should
remove the dnl from the line that sets the CXXFLAGS if there is any,
so that it reads:
[CXXFLAGS="-g -D_NDEBUG"]
Then
run:
automake
autoconf
configure
make
clean
make
in that directory.
Make clean in the ~/apache and in the ~/apache/src/modules/isoap/SOAP
directories and rebuild all. Don't forget to remove these settings
for the release build again.
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.
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. A
SOAP.kdevprj is included in the source, you can generate it in a
similar way if you have a newer version of kdevelop. Use the
appropriate dialogs in your debugging environment to set the
commandline arguments for debugging.
I hope you will have fun with this.
Enjoy,