/*
 *   Copyright 2003-2004 The Apache Software Foundation.
 *
 *   Licensed under the Apache License, Version 2.0 (the "License");
 *   you may not use this file except in compliance with the License.
 *   You may obtain a copy of the License at
 *
 *       http://www.apache.org/licenses/LICENSE-2.0
 *
 *   Unless required by applicable law or agreed to in writing, software
 *   distributed under the License is distributed on an "AS IS" BASIS,
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *   See the License for the specific language governing permissions and
 *   limitations under the License.
 *
 *
 *   @author Damitha Kumarage (damitha@opensource.lk, damitha@jkcsworld.com)
 *
 */


Introduction
============

This guide will help you to start with Axis C++. I'll explain the minimum
steps needed to build and run Axis C++, and warn you about the common 
pitfalls.

What you need
=============
RedHat 9(2.4.20-8)
expat-1.95.7(source)
xerces-c-src2_2_0(I build xerces from source)
httpd-2.0.48(source)
apache_1.3.27(source)

Note: In my environment I have
autoconf 2.57, automake 1.6.3, libtool 1.4.3,  gcc 3.2.2 

You can download the Axis C++ source or binary from one of the apache mirror sites 
    http://ws.apache.org/axis/cpp/download.html

You can get expat from the uri http://sourceforge.net/projects/expat/

You can get xercesc from the uri http://www.xml.apache.org/xerces-c/download.cgi

You must define some environment variables in order to build.
AXISCPP_HOME is where you checkout Axis C++

------------------------------------------------------------
AXISCPP_HOME="/home/damitha/projects/axiscpp"
AXIS_HOME="/usr/local/Axis"
EXPAT_HOME="/usr/local/expat1957"
XERCESC_HOME="/usr/local/xerces-c"
LD_LIBRARY_PATH="$XERCESC_HOME/lib:$EXPAT_HOME/lib:$AXISCPP_HOME/bin:$AXIS_HOME/libs:$LD_LIBRARY_PATH"
export AXISCPP_HOME AXIS_HOME XERCESC_HOME EXPAT_HOME LD_LIBRARY_PATH
------------------------------------------------------------

A note about AXIS_HOME
Copy $AXISCPP_HOME/deploy folder to a place of your choice and define AXIS_HOME pointing to it.
cp -rf $AXISCPP_HOME/deploy /usr/local/
mv /usr/local/deploy /usr/local/Axis
Give read write permissions to /usr/local/Axis

EXPAT_HOME points to where you installed expat
XERCESC_HOME points to where you installed xereces-c

Axis C++ core is independant of the parser layer and transport layer.
You can write your own transport or parser library according to the APIs provided. Currently Axis C++
provides API implementations for Xerces-c and Expat. It also provides it's own client side transport
library implementation. In the server side deployment, Axis C++ provides two modules that can be loaded
into apache1.3 and apache 2 as shared libraries.
So this sums upto two posibilities.
You can deploy Axis C++ server 
    on Apache2 with xercesc parser or expat parser(Only one parser at a time)
    on Apache1.3 with xercesc parer or expat parser

So if you use only Expat no need to define XERCESC_HOME vice versa.

When you build Axis C++ you can give options
1) Build for Apache2
   with Expat parser support only
   with Xerces paresr support only
   with both parser support
2) Build for Apache1.3
   with Expat parser support only
   with Xerces parser support only
   with both parser support

You can choose these selections on $AXISCPP_HOME/configure.ac

------------------------------------------------------------
#{apache2 block starts
#if you use apache2
#if you need to build both axis_expat and axis_xerces libraries
                                                                                                                             
AC_OUTPUT(Makefile src/Makefile src/common/Makefile src/soap/Makefile src/wsdd/Makefile src/xml/Makefile src/transport/Makefile src/transport/axis/Makefile src/engine/Makefile src/engine/server/Makefile src/engine/client/Makefile  src/server/Makefile src/server/apache2/Makefile src/server/simple_axis_server/Makefile src/server/adminservice/Makefile src/client/Makefile src/client/adminclient/Makefile src/xml/expat/Makefile src/xml/xerces/Makefile)
                                                                                                                             
#if you need to build only axis_expat
                                                                                                                             
#AC_OUTPUT(Makefile src/Makefile src/common/Makefile src/soap/Makefile src/wsdd/Makefile src/xml/Makefile src/transport/Makefile src/transport/axis/Makefile src/engine/Makefile src/engine/server/Makefile src/engine/client/Makefile  src/server/Makefile src/server/apache2/Makefile src/server/simple_axis_server/Makefile src/server/adminservice/Makefile src/client/Makefile src/client/adminclient/Makefile src/xml/expat/Makefile)

#if you need to build only axis_xerces
                                                                                                                             
#AC_OUTPUT(Makefile src/Makefile src/common/Makefile src/soap/Makefile src/wsdd/Makefile src/xml/Makefile src/transport/Makefile src/transport/axis/Makefile src/engine/Makefile src/engine/server/Makefile src/engine/client/Makefile  src/server/Makefile src/server/apache2/Makefile src/server/simple_axis_server/Makefile src/server/adminservice/Makefile src/client/Makefile src/client/adminclient/Makefile src/xml/xerces/Makefile)
                                                                                                                             
#}apache2 block ends
                                                                                                                             
#{apache1.3 block starts
#if you use apache1.3
                                                                                                                             
#if you need to build both axis_expat and axis_xerces libraries
                                                                                                                             
#AC_OUTPUT(Makefile src/Makefile src/common/Makefile src/soap/Makefile src/wsdd/Makefile src/xml/Makefile src/transport/Makefile src/transport/axis/Makefile src/engine/Makefile src/engine/server/Makefile src/engine/client/Makefile  src/server/Makefile src/server/apache/Makefile src/server/simple_axis_server/Makefile src/server/adminservice/Makefile src/client/Makefile src/client/adminclient/Makefile src/xml/expat/Makefile src/xml/xerces/Makefile)
                                                                                                                             
#if you need to build only axis_expat
#AC_OUTPUT(Makefile src/Makefile src/common/Makefile src/soap/Makefile src/wsdd/Makefile src/xml/Makefile src/transport/Makefile src/transport/axis/Makefile src/engine/Makefile src/engine/server/Makefile src/engine/client/Makefile  src/server/Makefile src/server/apache/Makefile src/server/simple_axis_server/Makefile src/server/adminservice/Makefile src/client/Makefile src/client/adminclient/Makefile src/xml/expat/Makefile)
                                                                                                                             
#if you need to build only axis_xerces
                                                                                                                             
#AC_OUTPUT(Makefile src/Makefile src/common/Makefile src/soap/Makefile src/wsdd/Makefile src/xml/Makefile src/transport/Makefile src/transport/axis/Makefile src/engine/Makefile src/engine/server/Makefile src/engine/client/Makefile  src/server/Makefile src/server/apache/Makefile src/server/simple_axis_server/Makefile src/server/adminservice/Makefile src/client/Makefile src/client/adminclient/Makefile src/xml/xerces/Makefile)
                                                                                                                             
#}apache1.3 block ends
------------------------------------------------------------

You need also do a selection at $AXISCPP_HOME/src/xml/Makefile.am

-----------------------------------------------------------
SUBDIRS = expat xerces #Here I build both expat and xerces libraries
#SUBDIRS = expat
#SUBDIRS = xerces
---------------------------------------------------------

And again in $AXISCPP_HOME/src/server/Makefile.am

---------------------------------------------------------
#if you use apache2
SUBDIRS = apache2 adminservice #Here I build for Apache2
                                                                                                                             
#if you use apache1.3
#SUBDIRS = apache adminservice
---------------------------------------------------------

Now you need to copy header files from apache and parser you use
I have installed xercesc at /usr/local/xerces-c and
expat at /usr/local/expat1957 and
apache2 at /usr/local/apache2 and
apache1.3 at /usr/local/apache

I'm going to build Axis C++ for apache2 and for both xercesc and expat(But I'm going to
use only one parser. But anyway I can give instructions to build both as you've seen earlier)

cp -rf /usr/local/xerces-c/include/xercesc/* $AXISCPP_HOME/include/xercesc/
cp -f /usr/local/expat1957/include/expat.h $AXISCPP_HOME/include/expat/
cp -f /usr/local/apache2/include/* $AXISCPP_HOME/include/apache2_0/

Then I can build Axis C++ server, client,parser libraries, transport library and server/client samples
by,
cd $AXISCPP_HOME
sh build.sh

Once you finished, have a look at $AXISCPP_HOME/build_errors, 
$AXISCPP_HOME/samples/server/sample_server_build_errors and 
$AXISCPP_HOME/samples/client/sample_client_build_errors to identify
any warnings and errors. Most probably you will see many warnings.
Just ignore them. But if you see any errors it means that build was 
not successful and check whether you followed the instructions 
carefully. Note that if you see errors on build_errors file then
client samples will also fail since it depends on libaxiscpp_client.so.

You can see the folder $AXISCPP_HOME/bin to see what are created

libaxiscpp_mod.so is apache module which is loaded when apache loads
libaxiscpp_mod2.so is apache2 module which is loaded when apache2 loads
libserver_engine.so is the Axis C++ server engine which is loaded by libaxis_mod(2).so module
libaxiscpp_client.so is Axis C++ client library
libaxis_transport.so is the Axis C++ client transport library
libaxis_expat.so is the expat parser library implementation for Axis C++
libaxis_xercesc.so is the xercesc parser library implmentation for Axis C++

Also $AXISCPP_HOME/sampels/server samples are built and installed in
$AXIS_HOME/web_services

$AXISCPP_HOME/samples/client samples are built and executable are in $AXISCPP_HOME/samples/client

Now you need to add to $<apache install directory>/conf/httpd.conf
$ vi <apache install directory>/conf/httpd.conf

At the bottom of the file you have to include following lines and save it.
-------------------------------------------------
LoadModule axis_module modules/libaxiscpp_mod2.so (in apache1.3 replace modules with libexec and libaxiscpp_mod2.so with libaxiscpp_mod.so)

<Location /axis>

SetHandler axis

</Location> 
---------------------------------------------------

Now you need the deployment descripter to deploy server samples you built

cd $AXIS_HOME/conf
mv server.wsdd_linux server.wsdd
cd ..
mv axiscpp.conf_linux axiscpp.conf

In $AXIS_HOME/axiscpp.conf file you can give paths to
your log files, configuration files libraries etc.
------------------------------------------------------------------------------------------
# The comment character is '#'
#Available directives are as follows
#(Some of these directives may not be implemented yet)
#
#WSDDFilePath:The path to the server wsdd
#LogPath:The path to the axis log
#ClientLogPath:The path to the axis client log
#ClientWSDDFilePath:The path to the client wsdd
#Transport_http:The HTTP transport library
#Transport_smtp:The SMTP transport library
#XMLParser:The xml parser library

LogPath:/usr/local/Axis/logs/AxisLog
WSDDFilePath:/usr/local/Axis/conf/server.wsdd
ClientLogPath:/usr/local/Axis/logs/AxisClientLog
XMLParser:/usr/local/Axis/libs/libaxis_xmlparser.so
Transport_http:/usr/local/Axis/libs/libaxis_transport.so

-----------------------------------------------------------------------------------------
Now we need to copy neccessary libraries to the correct places and start apache. To
do that you can find scripts written in $AXIS_HOME.
cd $AXIS_HOME

To deploy on apache2
sh deploy_apache2.sh

To deploy on apache
sh deploy_apache.sh

When you run the above script all the libraries are copied into corresponding places.
libaxiscpp_mod2.so is copied to <your apache home>/modules folder.
libserver_engine.so and libaxis_expat.so is copied to $AXIS_HOME/libs folder(and renamed
libaxis_xmlparser.so). Also apache is started and libaxiscpp_mod2.so is loaded into apache.
libaxiscpp_mod2.so is the apache module for Axis C++. This will in term load Axis C++ server engine
(libserver_engine.so).
Note that libaxis_xmlparser.so is loaded by the engine dynamically as parsing is required from the
engine.

Note that in the line no. 12 of the script above we change
the name libaxis_expat.so to libaxis_xmlparser.so.
If we use xerces we need to change
libaxis_xercesc.so to libaxis_xmlparser.so.

If you have done installation successfully it will display the Axis C++ welcome page when you point to URI http://localhost/axis .
Note: In the axis welcome page all the services in $AXIS_HOME/conf/server.wsdd are listed. This does not mean
that the libraries corresponding to these services are deployed yet. It merely list whatever in the server.wsdd.

To run interop samples
cd $AXISCPP_HOME/samples/client
sh run_interoptests.sh
By default this script assumes that apache is running in the localhost at port 80
if you want other
sh run_interoptests.sh <server> <port>
eg: sh run_interoptests.sh -u localhost -p 80

Note for people who downloaded Axis C++ binary.
In this case all the libraries are already generated for you in $AXISCPP_HOME/bin.
You need just build samples.
