| Table of Contents | |
| ================= | |
| 1. Getting Axis2/C Working on Linux | |
| 1.1 Setting up Prerequisites | |
| 1.1.1 Mandatory | |
| 1.1.2 Optional | |
| 1.2 Using Binary Release | |
| 1.3 Using Source Release | |
| 1.3.1 Basic Build | |
| 1.3.2 Build with Options | |
| (a) With Guththila | |
| (b) With libxml2 | |
| (c) With AMQP Transport | |
| 1.3.3 Building Samples | |
| 1.4 Configuration | |
| 1.4.1 AMQP Transport | |
| 1.5 Running Samples | |
| 1.5.1 HTTP Transport | |
| (a) Server | |
| (b) Clients | |
| 1.5.2 AMQP Transport | |
| (a) Server | |
| (b) Client | |
| 2. Getting Axis2/C Working on Windows (Win32) | |
| 2.1 Setting up Prerequisites | |
| 2.1.1 Mandatory | |
| 2.1.2 Optional | |
| 2.2 Using Binary Release | |
| 2.3 Using Source Release | |
| 2.3.1 Setting Build Options | |
| (a) Enable Guththila | |
| (b) Enable libxml2 | |
| (c) Enable SSL Support | |
| (d) Enable libcurl | |
| (e) Setting zlib Location | |
| 2.3.2 Compiling the Source | |
| 2.4 Running Samples | |
| 2.4.1 HTTP transport | |
| (a) Server | |
| (b) Clients | |
| 3. Installing Apache2 Web Server Integration Module (mod_axis2) | |
| 3.1 Building mod_axis2 from Source | |
| 3.1.1 On Linux | |
| 3.1.2 On Windows (Win32) | |
| 3.2 Deploying in Apache2 Web Server | |
| 3.3 HTTP/2 Support (Optional) | |
| 4. Installing IIS (Internet Information Server) Integration Module | |
| (mod_axis2_IIS) | |
| 4.1 Building mod_axis2_IIS from Source | |
| 4.2 Deploying in the IIS | |
| 5. Using Axis2/C with CGI | |
| 5.1 Deploying in Apache2 | |
| 5.2 Deploying in IIS | |
| 6. FAQ | |
| 1. Getting Axis2/C Working on Linux | |
| =================================== | |
| 1.1 Setting up Prerequisites | |
| ---------------------------- | |
| 1.1.1 Mandatory | |
| -------------- | |
| By default Axis2/C is not dependent on any other software libraries. | |
| 1.1.2 Optional | |
| -------------- | |
| (a) libxml2 - http://www.xmlsoft.org/ | |
| (b) zlib - http://www.zlib.net/ | |
| (c) libiconv - http://www.gnu.org/software/libiconv/ | |
| (d) openssl - http://www.openssl.org/ | |
| (e) Apache Qpid - You need to have Qpid libraries installed on your machine | |
| if you are going to use AMQP transport. It is recommended | |
| that you compile and install Qpid from Git source. | |
| You can checkout Qpid Git source from | |
| https://github.com/apache/qpid-cpp. | |
| (f) HTTP/2 Transport Support (New in 2.0.0) - To enable HTTP/2 transport: | |
| libnghttp2 >= 1.0.0 - HTTP/2 C library for protocol implementation | |
| openssl >= 1.0.0 - Required for HTTPS and HTTP/2 ALPN negotiation | |
| Ubuntu/Debian installation: | |
| $ sudo apt install libnghttp2-dev libnghttp2-14 libssl-dev libcurl4-openssl-dev | |
| RedHat/CentOS installation: | |
| $ sudo yum install libnghttp2-devel openssl-devel libcurl-devel | |
| # OR for newer systems: | |
| $ sudo dnf install libnghttp2-devel openssl-devel libcurl-devel | |
| Build with HTTP/2 support: | |
| $ ./configure \ | |
| --prefix=$(pwd)/deploy \ | |
| --enable-http2 \ | |
| --enable-json=yes \ | |
| --enable-tests \ | |
| --enable-ssl \ | |
| --enable-libcurl \ | |
| --with-apache2=/usr/include/apache2 \ | |
| --with-apr=/usr/include/apr-1.0 \ | |
| PKG_CONFIG_PATH=/usr/lib/pkgconfig:/usr/lib/x86_64-linux-gnu/pkgconfig \ | |
| APACHE2_HOME=/usr \ | |
| CFLAGS="$CFLAGS -DAXIS2_H2_JSON_ONLY_BUILD -DAXIS2_JSON_ENABLED -O2" \ | |
| CPPFLAGS="$CPPFLAGS -DAXIS2_H2_JSON_ONLY_BUILD -DAXIS2_JSON_ENABLED" \ | |
| LDFLAGS="$LDFLAGS -L/usr/lib/x86_64-linux-gnu" | |
| Note: HTTP/2 transport provides: | |
| - Enterprise-grade stream multiplexing (100 concurrent streams) | |
| - Memory-efficient large payload processing (50MB+) | |
| - Automatic protocol negotiation (HTTP/2 with HTTP/1.1 fallback) | |
| - Integration with Apache mod_http2 for production deployment | |
| 1.1.3 For WSDL2C Code Generator (New in 2.0.0) | |
| ----------------------------------------------- | |
| To build and use the WSDL2C code generator, you need: | |
| (a) libxml2-dev - Development headers for libxml2 | |
| Ubuntu/Debian: sudo apt install libxml2-dev | |
| RedHat/CentOS: sudo yum install libxml2-devel | |
| (b) pkgconf - pkg-config implementation for dependency detection | |
| Ubuntu/Debian: sudo apt install pkgconf | |
| RedHat/CentOS: sudo yum install pkgconfig | |
| The native C generator provides fast, reliable WSDL to C code generation | |
| for SOAP-based web services with minimal dependencies (libxml2 only). | |
| Complete development package installation for Ubuntu/Debian: | |
| $ sudo apt update | |
| $ sudo apt install libxml2-dev pkgconf autoconf \ | |
| automake libtool make gcc g++ libssl-dev zlib1g-dev | |
| For testing and development (optional): | |
| $ sudo apt install libgtest-dev valgrind | |
| Note: On modern Ubuntu/Debian systems, libgtest-dev provides pre-built | |
| libraries that are automatically detected by the build system. | |
| Note: Apache httpd web server is NOT required for unit tests or basic | |
| development. Axis2/C includes a built-in simple HTTP server for testing. | |
| Apache httpd is only needed for production deployment via mod_axis2 module | |
| (see section 3 for Apache2 Web Server Integration). | |
| For production mod_axis2 development (optional): | |
| $ sudo apt install apache2-dev libapr1-dev libaprutil1-dev | |
| 1.2 Using Binary Release | |
| ------------------------ | |
| (a) Extract the binary tar package to a directory. | |
| (b) Set AXIS2C_HOME environment variable pointing to the location where you | |
| have extracted Axis2/C. | |
| $ AXIS2C_HOME='/your_path_to_axis2c' | |
| $ export AXIS2C_HOME | |
| NOTE : You will need to set AXIS2C_HOME only if you need to run Axis2/C | |
| samples or tests. The reason is that the samples and test codes | |
| use AXIS2C_HOME to get the path to Axis2/C. To write your own | |
| services or clients this is not a requirement. | |
| 1.3 Using Source Release | |
| ------------------------ | |
| 1.3.1 Basic Build | |
| ----------------- | |
| (a) Extract the source tar package to a directory | |
| (b) Set AXIS2C_HOME environment variable pointing to the location where you | |
| want to install Axis2/C. | |
| $ AXIS2C_HOME='/your_desired_path_to_axis2c_installation' | |
| $ export AXIS2C_HOME | |
| NOTE : You will need to set AXIS2C_HOME only if you need to run Axis2/C | |
| samples or tests. The reason is that the samples and test codes | |
| use AXIS2C_HOME to get the path to Axis2/C. To write your own | |
| services or clients this is not a requirement. | |
| (c) Go to the directory where you extracted the source | |
| $ cd /your_path_to_axis2c_source | |
| (d) Build the source | |
| This can be done by running the following command sequence in the | |
| directory where you have extracted the source. | |
| $ ./configure --prefix=${AXIS2C_HOME} | |
| $ make | |
| $ make install | |
| Please run './configure --help' in respective sub directories for more | |
| information on these configure options. | |
| NOTE : If you don't provide the --prefix configure option, it will by | |
| default be installed into '/usr/local/axis2c' directory. | |
| You could run 'make check' to test if everything is working fine. However, | |
| note that the test/core/clientapi/test_clientapi program would fail unless | |
| AXIS2C_HOME points to the installed location. (It's looking for Axis2/C | |
| repository) This means you really should run 'make && make install', | |
| then set 'AXIS2C_HOME=/path/to/install', and then 'make check'. | |
| That's a little different than the usual 'make && make check && make | |
| install' process. | |
| 1.3.1.1 Convenience Build Scripts | |
| --------------------------------- | |
| For developers familiar with C project conventions, Axis2/C provides | |
| convenience scripts that automate the typical autotools build process: | |
| $ ./build_for_tests.sh # Build with testing enabled, http/2 omitted - see section 3.3 | |
| $ ./run_tests.sh # Run the full test suite (make check) | |
| $ ./run_native_codegen_tests.sh # Run only native WSDL2C generator tests | |
| These scripts handle the complete configure-make-install-test cycle with | |
| appropriate options for development and testing. They are equivalent to | |
| the traditional C development workflow of running autogen.sh, configure | |
| with various flags, make, make install, and running tests. | |
| For quick one-liners equivalent to the convenience scripts: | |
| Build and install with testing enabled (equivalent to build_for_tests.sh): | |
| $ ./autogen.sh && ./configure --prefix=$(pwd)/deploy --enable-tests --enable-json=yes && make -j4 && make install && export AXIS2C_HOME=$(pwd)/deploy | |
| Run full test suite (equivalent to run_tests.sh): | |
| $ export AXIS2C_HOME=$(pwd)/deploy && export ASAN_OPTIONS=detect_odr_violation=1 && make check | |
| Run only native WSDL2C generator tests (equivalent to run_native_codegen_tests.sh): | |
| $ cd tools/codegen/native/test && make clean && make check | |
| Build and basic install (no unit tests): | |
| $ make clean; ./autogen.sh && ./configure --prefix=$(pwd)/deploy --enable-json=yes && make -j4 && make install && export AXIS2C_HOME=$(pwd)/deploy | |
| These commands demonstrate the standard C autotools workflow that the | |
| convenience scripts automate for you. Note: --enable-json=yes is optional | |
| and only needed for REST API support (requires libjson-c-dev package). | |
| The build with testing requires proper Google Test setup for full coverage. | |
| 1.3.1.2 Development Workflow - Making Code Changes | |
| ------------------------------------------------- | |
| When modifying Axis2/C source code during development, you MUST rebuild | |
| AND reinstall before running tests, because tests use installed libraries | |
| from the ./deploy directory: | |
| After making source changes: | |
| $ make && make install # Rebuild and install updated libraries | |
| $ bash run_tests.sh # Run tests with updated code | |
| Or as one-liner: | |
| $ make && make install && bash run_tests.sh | |
| IMPORTANT: Simply running 'make' is not sufficient - tests will use old | |
| installed libraries in ./deploy/ until 'make install' copies the updated | |
| libraries there. This is different from most C projects where 'make check' | |
| tests the build tree directly. | |
| Role of build_for_tests.sh: | |
| ---------------------------- | |
| The build_for_tests.sh convenience script is designed for INITIAL setup | |
| and FULL rebuilds from scratch. It runs the complete configure-make-install | |
| cycle with proper testing options. For incremental development after making | |
| code changes, you only need 'make && make install' since configuration is | |
| already done. | |
| Use build_for_tests.sh when: | |
| - Setting up a fresh checkout | |
| - Changing build configuration options | |
| - Doing a complete clean rebuild | |
| Use 'make && make install' when: | |
| - Making incremental source code changes | |
| - Continuing development after initial setup | |
| - You want to test your modifications quickly | |
| 1.3.1.3 Build System Maintenance Commands | |
| --------------------------------------- | |
| During development and troubleshooting, you may need to use additional | |
| build system maintenance commands to resolve build issues or start with | |
| a completely clean environment: | |
| make distclean: | |
| -------------- | |
| This command removes ALL generated files and returns the source tree to | |
| its pristine state as if freshly extracted from a tar archive. Use this | |
| when you need to completely reset your build environment. | |
| What 'make distclean' removes: | |
| - All compiled object files (*.o, *.lo) | |
| - All generated libraries (*.a, *.la, *.so) | |
| - All generated executables and test programs | |
| - All Makefiles generated by configure | |
| - All autotools cache files (autom4te.cache/) | |
| - All configuration headers (config.h, stamp-h1) | |
| - All libtool files (libtool, .deps/, .libs/) | |
| - The deploy/ directory and all installed files | |
| Example usage: | |
| $ make distclean | |
| $ ./autogen.sh | |
| $ ./configure --prefix=$(pwd)/deploy --enable-tests --enable-json=yes | |
| $ make && make install | |
| autoreconf -fiv: | |
| --------------- | |
| This command regenerates the autotools build system files (configure script, | |
| Makefiles, etc.) from their source templates. The flags mean: | |
| -f: Force regeneration even if files seem up-to-date | |
| -i: Install missing auxiliary files | |
| -v: Verbose output showing what's being regenerated | |
| What 'autoreconf -fiv' regenerates: | |
| - configure script from configure.ac | |
| - Makefile.in files from Makefile.am templates | |
| - aclocal.m4 from macro definitions | |
| - config.h.in from autoheader | |
| - Missing auxiliary files (install-sh, missing, etc.) | |
| WHEN TO USE THESE COMMANDS: | |
| Use 'make distclean' followed by 'autoreconf -fiv' when: | |
| - Build system files appear corrupted or inconsistent | |
| - You've modified configure.ac or Makefile.am files | |
| - You're getting strange autotools-related errors | |
| - You want to completely start over with a clean slate | |
| - Switching between different development branches | |
| - Build fails with "file not found" errors for generated files | |
| Use 'make distclean' alone when: | |
| - You want to clean up disk space (removes deploy/ directory) | |
| - Preparing to create a clean source distribution | |
| - Build artifacts are causing issues but autotools files are OK | |
| Use 'autoreconf -fiv' alone when: | |
| - You've modified build system files (configure.ac, Makefile.am) | |
| - autotools files seem out of sync but you want to keep build artifacts | |
| - You get warnings about outdated autotools files | |
| Complete Clean Rebuild Sequence: | |
| ------------------------------- | |
| For the most thorough reset when troubleshooting build issues: | |
| $ make distclean # Remove all generated files | |
| $ autoreconf -fiv # Regenerate build system | |
| $ ./configure --prefix=$(pwd)/deploy --enable-tests --enable-json=yes | |
| $ make && make install # Build and install | |
| This sequence is equivalent to starting with a fresh source extraction | |
| but preserves any local source code modifications you've made. | |
| 1.3.2 Build with Options | |
| ------------------------ | |
| (a) With Guththila | |
| ------------------ | |
| - Now Guththila is the default parser. Unless you enable libxml2 Guththila will be built. | |
| (b) With libxml2 | |
| ---------------- | |
| You may need to try Axis2/C with libxml2 XML parser. You can do it by | |
| giving '--enable-libxml2=yes' as a configure option. | |
| $ ./configure --enable-libxml2=yes [other configuration options] | |
| $ make | |
| $ make install | |
| (c) With AMQP Transport | |
| ----------------------- | |
| You may need to try Axis2/C with the AMQP transport. You can do it by | |
| giving '--with-qpid=/path/to/qpid/home' as a configure option. | |
| $ ./configure --with-qpid=/path/to/qpid/home [other configuration options] | |
| $ make | |
| $ make install | |
| (d) With openssl | |
| ---------------- | |
| You may need to try Axis2/C with openssl. You can do it by | |
| giving '--with-openssl=[Path to openssl directory]' as a configure option. Path will contain | |
| openssl include directory and lib directory. If path is not given, include files will be | |
| taken from /usr/include/openssl and lib will be taken from /usr/lib (or /usr/lib64). | |
| $ ./configure --with-openssl=/opt/openssl [other configuration options] | |
| $ make | |
| $ make install | |
| (e) With JSON Support (REST API Alternative) | |
| -------------------------------------------- | |
| If you need REST API support as an alternative to SOAP-based web services, | |
| you can enable JSON processing support. This requires the JSON-C library | |
| and can be enabled with '--enable-json=yes' as a configure option. | |
| Prerequisites for JSON support: | |
| Ubuntu/Debian: sudo apt install libjson-c-dev | |
| RedHat/CentOS: sudo yum install json-c-devel | |
| $ ./configure --enable-json=yes [other configuration options] | |
| $ make | |
| $ make install | |
| Note: JSON support is NOT required for SOAP-based web services or the | |
| WSDL2C code generator. It provides REST API capabilities as an alternative | |
| to traditional SOAP messaging. | |
| (f) With Google Test (C++ Unit Testing Support) - ADVANCED | |
| ----------------------------------------------------------- | |
| IMPORTANT: Google Test C++ unit tests are optional. The basic build and | |
| functionality testing works without Google Test (recommended for most users). | |
| WHY BUILD GOOGLE TEST FROM SOURCE? | |
| ---------------------------------- | |
| Axis2/C's build system (dating from ~2015) expects to compile Google Test | |
| source files directly (gtest-all.cc, gtest_main.cc) rather than using | |
| modern pre-built libraries. This is because: | |
| 1. Ubuntu's libgtest-dev provides CMake integration and pre-built libraries | |
| 2. Axis2/C's autotools build expects source compilation for direct control | |
| 3. Axis2/C Makefile.am files reference $(GTEST_DIR)/src/gtest-all.cc explicitly | |
| 4. Converting to modern Google Test would require significant build system changes | |
| This approach ensures compatibility with the existing test infrastructure | |
| while avoiding the complexity of modernizing the entire build system. | |
| Method 1A - Use existing system Google Test (if available): | |
| # First, check if Google Test source files are already installed | |
| $ ls /usr/src/googletest/googletest/src/gtest-all.cc | |
| # If the file exists, configure directly with existing installation: | |
| $ ./configure --enable-tests --with-gtest=/usr/src/googletest/googletest [other options] | |
| Note: Many Ubuntu systems have Google Test source pre-installed in /usr/src/ | |
| This method avoids downloading and recompiling Google Test unnecessarily. | |
| Method 1B - Build Google Test from source (if system version unavailable): | |
| $ sudo apt install cmake git | |
| $ cd /tmp | |
| $ git clone https://github.com/google/googletest.git -b v1.17.0 | |
| $ cd googletest | |
| $ mkdir build && cd build | |
| $ cmake .. && make | |
| $ sudo make install | |
| Then configure Axis2/C with: | |
| $ ./configure --enable-tests --with-gtest=/tmp/googletest/googletest [other options] | |
| Method 2 - Skip unit tests entirely (recommended for most users): | |
| $ ./configure [other configuration options] | |
| $ make && make install | |
| Method 3 - Manual functionality verification (after Method 2): | |
| # Test WSDL2C native generator | |
| $ cd tools/codegen/native/build | |
| $ ./wsdl2c-native --help | |
| # Test code generation and compilation | |
| $ mkdir /tmp/axis2c_test && cd /tmp/axis2c_test | |
| $ echo '<?xml version="1.0"?><definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:tns="http://test/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" targetNamespace="http://test/"><types><xsd:schema targetNamespace="http://test/"><xsd:element name="TestRequest" type="xsd:string"/><xsd:element name="TestResponse" type="xsd:string"/></xsd:schema></types><message name="TestMessage"><part name="body" element="tns:TestRequest"/></message><message name="TestResponseMessage"><part name="body" element="tns:TestResponse"/></message><portType name="TestPortType"><operation name="TestOperation"><input message="tns:TestMessage"/><output message="tns:TestResponseMessage"/></operation></portType><binding name="TestBinding" type="tns:TestPortType"><soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/><operation name="TestOperation"><soap:operation soapAction="urn:TestOperation"/><input><soap:body use="literal"/></input><output><soap:body use="literal"/></output></operation></binding><service name="TestService"><port name="TestPort" binding="tns:TestBinding"><soap:address location="http://localhost:8080/axis2/services/TestService"/></port></service></definitions>' > test.wsdl | |
| $ ${AXIS2C_HOME}/../tools/codegen/native/build/wsdl2c-native -uri test.wsdl -o output -d adb -u | |
| $ cd output/src && gcc -c adb_*.c -I. -I${AXIS2C_HOME}/include/axis2-2.0.0 -I/usr/include/libxml2 -Wall -Wno-unused-parameter | |
| Note: Methods 2 and 3 avoid the C++ Google Test compilation issues and | |
| are sufficient for most development and testing purposes. If all commands | |
| above succeed, your Axis2/C installation is working correctly. | |
| RECOMMENDATION: For comprehensive regression testing of HTTP/2 JSON processing | |
| and the revolutionary interface pattern, use Method 1A (if available) or 1B. | |
| FUTURE IMPROVEMENT OPPORTUNITY: | |
| ------------------------------ | |
| The Axis2/C build system could be modernized to use system Google Test | |
| packages (libgtest-dev) with CMake integration, which would eliminate | |
| the need for source compilation. This would involve: | |
| - Updating util/test/util/Makefile.am to use pkg-config or CMake | |
| - Converting from direct source compilation to library linking | |
| - Testing compatibility across different Linux distributions | |
| 1.3.3 Building Samples | |
| ---------------------- | |
| If you need to get the samples working, you also need to build the samples. | |
| To build the samples: | |
| $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${AXIS2C_HOME}/lib/ | |
| $ cd samples | |
| $ ./configure --prefix=${AXIS2C_HOME} | |
| --with-axis2=${AXIS2C_HOME}/include/axis2-2.0.0 | |
| $ make | |
| $ make install | |
| Please run './configure --help' in samples folder for more information on | |
| configure options. | |
| NOTE : If you don't provide a --prefix configure option, samples will by | |
| default be installed into '/usr/local/axis2c/samples' directory. | |
| 1.4 Configuration | |
| ----------------- | |
| 1.4.1 AMQP Transport | |
| -------------------- | |
| You need to add the following entries into the axis2.xml. | |
| <transportReceiver name="amqp" class="axis2_amqp_receiver"> | |
| <parameter name="qpid_broker_ip" locked="false">127.0.0.1</parameter> | |
| <parameter name="qpid_broker_port" locked="false">5672</parameter> | |
| </transportReceiver> | |
| <transportSender name="amqp" class="axis2_amqp_sender"/> | |
| 1.5 Running Samples | |
| ------------------- | |
| 1.5.1 HTTP Transport | |
| -------------------- | |
| (a) Server | |
| ---------- | |
| You have to first start the axis2_http_server as follows. | |
| $ cd ${AXIS2C_HOME}/bin | |
| $ ./axis2_http_server | |
| You should see the message | |
| Started Simple Axis2 HTTP Server... | |
| This will start the simple axis server on port 9090. To see the possible | |
| command line options run | |
| $ ./axis2_http_server -h | |
| NOTE 1 : You may need to login as superuser to run the axis2_http_server. | |
| NOTE 2 : If you run into shared lib problems, set the LD_LIBRARY_PATH as | |
| follows. | |
| $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${AXIS2C_HOME}/lib | |
| (b) Clients | |
| ----------- | |
| When the axis2_http_server is up and running, you can run the sample | |
| clients in a new shell as follows. | |
| $ cd ${AXIS2C_HOME}/samples/bin | |
| $ ./echo | |
| This will invoke the echo service. | |
| $ ./math | |
| This will invoke the math service. | |
| To see the possible command line options for sample clients run them | |
| with '-h' option | |
| NOTE : If you run into shared lib problems, set the LD_LIBRARY_PATH as | |
| follows. | |
| $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${AXIS2C_HOME}/lib | |
| 1.5.2 AMQP Transport | |
| -------------------- | |
| (a) Server | |
| ---------- | |
| Start the Qpid broker as follows. | |
| $ cd ${QPID_HOME}/sbin | |
| $ ./qpidd --data-dir ./ | |
| Start the axis2_amqp_server as follows. | |
| $ cd ${AXIS2C_HOME}/bin | |
| $ ./axis2_amqp_server | |
| You should see the message | |
| Started Simple Axis2 AMQP Server... | |
| This will connect to the Qpid broker listening on 127.0.0.1:5672. | |
| To see the possible command line options run | |
| $ ./axis2_amqp_server -h | |
| NOTE 1 : You have the flexibility of starting the Qpid broker first and | |
| then axis2_amqp_server or vice-versa. | |
| NOTE 2 : You may need to login as superuser to run the axis2_amqp_server. | |
| NOTE 3 : If you run into shared lib problems, set the LD_LIBRARY_PATH as | |
| follows. | |
| $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${AXIS2C_HOME}/lib | |
| (b) Clients | |
| ----------- | |
| When the axis2_amqp_server is up and running, you can run the sample | |
| clients in a new shell as follows. | |
| $ cd ${AXIS2C_HOME}/samples/bin/amqp | |
| $ ./echo_blocking | |
| This will invoke the echo service. | |
| To see the possible command line options for sample clients run them | |
| with '-h' option | |
| NOTE : If you run into shared lib problems, set the LD_LIBRARY_PATH as | |
| follows. | |
| $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${AXIS2C_HOME}/lib | |
| 2. Getting Axis2/C Working on Windows (Win32) | |
| ============================================= | |
| 2.1 Setting up Prerequisites | |
| ---------------------------- | |
| 2.1.1 Mandatory | |
| --------------- | |
| (a) The binaries shipped with this version are compiled with | |
| Microsoft Visual Studio compiler (cl). And also the makefile that is | |
| shipped with this version needs Microsoft Visual Studio compiler (cl) | |
| and nmake build tool. | |
| NOTE : You can download Microsoft VS Express2005 Edition and | |
| Platform SDK from Microsoft website. You need to add the path to | |
| Platform SDK Include and Lib folders to the makefile in order | |
| for you to compile the source. | |
| 2.1.2 Optional | |
| -------------- | |
| (a) libxml2 [http://www.zlatkovic.com/pub/libxml | |
| version >= libxml2-2.6.20.win32] | |
| (b) zlib [http://www.zlatkovic.com/pub/libxml | |
| version >= zlib-1.2.3.win32] | |
| (c) iconv [http://www.zlatkovic.com/pub/libxml | |
| version >= iconv-1.9.1.win32] | |
| (d) openssl [http://www.slproweb.com/products/Win32OpenSSL.html | |
| version >= openssl 0.9.8e] | |
| 2.2 Using Binary Release | |
| ------------------------ | |
| Extract the binary distribution to a folder of your choice. | |
| (example: C:\axis2c) | |
| The c:\axis2c folder structure is as follows. | |
| axis2c | |
| | | |
| +- bin - server | |
| | | |
| +- samples - samples go here | |
| | | | |
| | +- bin - sample client executables | |
| | | | |
| | +- lib - sample libraries | |
| | | | |
| | +- src - source files of the sampels in bin and lib folders | |
| | | |
| | | |
| +- docs - documentation | |
| | | |
| +- include - all include files of axis2 | |
| | | |
| +- lib - library modules | |
| | | |
| +- logs - system and client logs are written to this folder | |
| | | |
| +- modules - deployed modules | |
| | | |
| +- services - deployed services | |
| You might optionally require to copy zlib1.dll ,iconv.dll and libxml2.dll. Copy | |
| them to C:\axis2c\lib . | |
| (Or you can have these dll's in some other place and add that | |
| location to PATH environment variable) | |
| 2.3 Using Source Release | |
| ------------------------ | |
| 2.3.1 Setting Build Options | |
| --------------------------- | |
| Please edit the <source_distribution>\build\win32\configure.in file | |
| to set the following build options. | |
| (a) Enable Guththila | |
| -------------------- | |
| - Now Guththila is the default parser. Unless you enable libxml2 Guththila will be built. | |
| (b) Enable libxml2 | |
| ------------------ | |
| - Set the ENABLE_LIBXML2 option to 1 | |
| - Set the LIBXML2_BIN_DIR to the location where libxml2 is installed to | |
| - Set the ICONV_BIN_DIR to the location where iconv is installed to | |
| (c) Enable SSL Support | |
| ---------------------- | |
| - Set ENABLE_SSL option to 1 | |
| - Set OPENSSL_BIN_DIR to the location where OpenSSL is installed to | |
| (d) Enable libcurl | |
| ------------------ | |
| - Set ENABLE_LIBCURL to 1 | |
| - Set LIBCURL_BIN_DIR to the location where libcurl is installed to | |
| (e) Setting zlib Location | |
| ------------------------- | |
| Set the ZLIB_BIN_DIR to the location where zlib is installed to | |
| Default location for zlib is E:\zlib-1.2.3.win32 and the folder | |
| structure should look like the following | |
| E:\zlib-1.2.3.win32 | |
| | | |
| +- include | |
| | | |
| +- bin | |
| | | |
| +- lib | |
| You can either extract zlib to this folder or extract it to a location | |
| of your choice and edit the configure.in file accordingly. | |
| NOTE : You need to have zlib1.dll in the library path. | |
| 2.3.2 Compiling the Source | |
| -------------------------- | |
| Extract the source distribution to a folder of your choice. | |
| Example: | |
| C:\axis2c | |
| Open a DOS shell and type: | |
| > cd %AXIS2C_HOME%\build\win32 | |
| > vcvars32.bat | |
| > nmake install | |
| NOTE : You may need to set the PATH environment variable to vcvars32.bat | |
| if Windows complains that it cannot find this batch file. This file | |
| is located in <Your MS Visual Studio Install Directory>\VC\bin | |
| directory. | |
| That's it! This will build the system and create a directory named 'deploy' | |
| under the build directory. | |
| The deploy folder structure is as follows. | |
| deploy | |
| | | |
| +- bin - server and other executables | |
| | | |
| +- samples - samples go here | |
| | | | |
| | +- bin - sample client executables | |
| | | | |
| | +- lib - sample libraries | |
| | | | |
| | +- src - sources of the samples in bin and lib folders | |
| | | |
| | | |
| +- lib - library modules | |
| | | |
| +- services - deployed services | |
| | | |
| +- modules - deployed modules | |
| | | |
| +- include - all include files of axis2 | |
| | | |
| +- logs - system and client logs are written to this folder | |
| 2.4 Running Samples | |
| ------------------- | |
| You need to set a couple of environment variables before you can run the | |
| server and samples. | |
| Set the variable AXIS2C_HOME to the deploy folder (C:\axis2c) | |
| Add the path to lib directory to the PATH variable (%AXIS2C_HOME%\lib) | |
| You might optionally require to copy the iconv.dll, zlib1.dll, libxml2.dll to | |
| the %AXIS2C_HOME%\lib folder. | |
| 2.4.1 HTTP transport | |
| -------------------- | |
| (a) Server | |
| ---------- | |
| > cd %AXIS2C_HOME%\bin | |
| > axis2_http_server.exe | |
| You should see the message | |
| Started Simple Axis2 HTTP Server... | |
| By default the log is created under %AXIS2C_HOME%\logs folder with the | |
| name axis2.log. | |
| NOTE : You may provide command line options to change the default behaviour. | |
| Type 'axis2_http_server.exe -h' to learn about the usage | |
| (b) Clients | |
| ----------- | |
| Now you can run any sample client deployed under %AXIS2C_HOME%\samples\bin | |
| Example: | |
| > cd %AXIS2C_HOME%\samples\bin | |
| > echo.exe | |
| 3. Installing Apache2 Web Server Integration Module (mod_axis2) | |
| =============================================================== | |
| 3.1 Building mod_axis2 from Source | |
| ---------------------------------- | |
| 3.1.1 On Linux | |
| -------------- | |
| First, install Apache2 development packages: | |
| Ubuntu/Debian: | |
| $ sudo apt install apache2-dev libapr1-dev libaprutil1-dev | |
| RedHat/CentOS: | |
| $ sudo yum install httpd-devel apr-devel apr-util-devel | |
| Then provide the Apache2 include file location as a configure option: | |
| $ ./configure --with-apache2="<apache2 httpd include files location>" | |
| [other configure options] | |
| Common locations: | |
| Ubuntu/Debian: --with-apache2="/usr/include/apache2" | |
| RedHat/CentOS: --with-apache2="/usr/include/httpd" | |
| NOTE : Some apache2 distributions install APR (Apache Portable Runtime) | |
| include files in a separate location which is required to build | |
| mod_axis2. | |
| In that case use: | |
| $ ./configure --with-apache2="<apache2 include files location>" | |
| --with-apr="<apr include files location>" | |
| [other configure options] | |
| Common APR locations: | |
| Ubuntu/Debian: --with-apr="/usr/include/apr-1.0" | |
| RedHat/CentOS: --with-apr="/usr/include/apr-1" | |
| Then build the source tree | |
| $ make | |
| $ make install | |
| This will install mod_axis2.so into your "<your_path_to_axis2c>/lib" | |
| 3.1.2 On Windows (Win32) | |
| ------------------------ | |
| Provide the apache2 location in configure.in file in APACHE_BIN_DIR | |
| Example: | |
| APACHE_BIN_DIR = E:\Apache22 | |
| After compiling the sources (as described in section 2.3) build the | |
| mod_axis2.dll by issuing the command 'nmake axis2_apache_module'. | |
| This will build mod_axis2.dll and copy it to %AXIS2C_HOME%\lib directory. | |
| Example: | |
| C:\axis2c\build\deploy\lib | |
| 3.2 Deploying in Apache2 Web Server | |
| ----------------------------------- | |
| NOTE : To do the following tasks, you might need super user privileges | |
| on your machine. | |
| Copy the mod_axis2 (libmod_axis2.so.0.7.0 on Linux and mod_axis2.dll | |
| on Windows) to "<apache2 modules directory>" as mod_axis2.so | |
| NOTE: The 0.7.0 version in the library filename reflects libtool's shared library versioning for ABI compatibility tracking and differs from the project release version (2.0.0). | |
| Example: | |
| cp $AXIS2C_HOME/lib/libmod_axis2.so.0.7.0 | |
| /usr/lib/apache2/modules/mod_axis2.so (on Linux) | |
| copy C:\axis2c\build\deploy\lib\mod_axis2.dll | |
| C:\Apache2\modules\mod_axis2.so (on Windows) | |
| Edit the Apache2's configuration file (generally httpd.conf) and add the | |
| following directives | |
| LoadModule axis2_module <apache2 modules directory>/mod_axis2.so | |
| Axis2RepoPath <axis2 repository path> | |
| Axis2LogFile <axis2 log file path> | |
| Axis2MaxLogFileSize <maximum size of log file> | |
| Axis2LogLevel LOG_LEVEL | |
| <Location /axis2> | |
| SetHandler axis2_module | |
| </Location> | |
| NOTE: Axis2 log file path should have write access to all users because by | |
| default Apache Web Server runs as nobody. | |
| If you want to use a Shared Global Pool with Apache you have to give | |
| another entry called Axis2GlobalPoolSize. You have to give the size of | |
| the shared global pool in MB. If you don't set the value or if you | |
| set a negative value Apache module doesn't create shared global pool. | |
| Axis2GlobalPoolSize <global pool size in MB> | |
| LOG_LEVEL can be one of the followings | |
| crit - Log critical errors only | |
| error - Log errors critical errors | |
| warn - Log warnings and above | |
| info - Log info and above | |
| debug - Log debug and above (default) | |
| trace - Log trace messages | |
| NOTE: Use forward slashes "/" for path separators in | |
| <apache2 modules directory>, <axis2 repository path> and | |
| <axis2 log file path> | |
| Make sure that the apache2 user has the correct permissions to above paths | |
| - Read permission to the repository | |
| - Write permission to the log file | |
| Restart apache2 and test whether mod_axis2 module is loaded by typing the | |
| URL http://localhost/axis2/services in your Web browser | |
| 3.3 HTTP/2 Support (Optional) | |
| ----------------------------- | |
| Axis2/C supports HTTP/2 when deployed with Apache httpd 2.4.17+ and properly configured. | |
| HTTP/2 provides performance improvements for web services, with benefits varying by payload type: | |
| **JSON/REST Services (with --enable-json)**: | |
| - 30-50% performance improvement due to better compression ratios | |
| - Significant header compression benefits (JSON APIs use more varied HTTP headers) | |
| - Excellent streaming performance for large JSON payloads (50MB+) | |
| - HPACK compression is highly effective with JSON content-type headers | |
| - Better multiplexing efficiency with RESTful API patterns | |
| **Key HTTP/2 Benefits**: | |
| - Single persistent connection replaces multiple HTTP/1.1 connections | |
| - Header compression (HPACK) reduces overhead, especially beneficial for JSON APIs | |
| - Stream multiplexing eliminates head-of-line blocking | |
| - Server push disabled by default (optimized for API responses, not web assets) | |
| Prerequisites for HTTP/2: | |
| - Apache httpd 2.4.17 or later | |
| - mod_axis2 properly installed (see section 3.1-3.2 above) | |
| - mod_http2 module enabled: `sudo a2enmod http2` | |
| - mod_ssl module enabled: `sudo a2enmod ssl` | |
| - OpenSSL 1.0.2+ with ALPN support | |
| - SSL certificates (can use self-signed for development) | |
| Ubuntu/Debian HTTP/2 setup: | |
| $ sudo a2enmod http2 | |
| $ sudo a2enmod ssl | |
| $ sudo systemctl restart apache2 | |
| RedHat/CentOS HTTP/2 setup: | |
| $ sudo yum install mod_http2 # or dnf install for newer versions | |
| $ sudo systemctl restart httpd | |
| Complete HTTP/2 configuration instructions are provided in docs/*HTTP2* and | |
| docs/userguide/json-httpd-h2-userguide.md . | |
| Note: HTTP/2 is entirely optional. Axis2/C works perfectly with HTTP/1.1. | |
| HTTP/2 is recommended for JSON based production deployments handling high traffic | |
| or large payloads where performance improvements are valuable. SOAP and XML | |
| are not supported in HTTP/2 due to high effort and few benefits. | |
| 4. Installing IIS (Interner Information Server) Integration Module | |
| (mod_axis2_IIS) | |
| ================================================================== | |
| 4.1 Building mod_axis2_IIS from Source | |
| -------------------------------------- | |
| After compiling the source (as described in section 2.3) build the | |
| mod_axis2.dll by issuing the command 'nmake axis2_IIS_module'. | |
| This will build the mod_axis2_IIS.dll and copy it to %AXIS2C_HOME%\lib | |
| directory. | |
| Example: | |
| C:\axis2c\build\deploy\lib | |
| 4.2 Deploying in the IIS | |
| ------------------------ | |
| Add the following key to the registery. | |
| HKEY_LOCAL_MACHINE\SOFTWARE\Apache Axis2c\IIS ISAPI Redirector | |
| Under this registry key add the following entries. | |
| A String value with the name "axis2c_home". The value is the AXIS2C_HOME. | |
| Example : c:\axis2c | |
| A String value with the name "log_file". The value is the absolute path of | |
| the log file. | |
| Example: c:\axis2c\logs\axis2.log | |
| A String value with the name "log_level". The value can be one of the | |
| followings. | |
| trace - Log trace messages | |
| error - Log errors critical errors | |
| info - Log info and above | |
| critical - Log critical errors only | |
| debug - Log debug and above (default) | |
| warning - Log warnings | |
| You can add a string value with the name services_url_prefix. This is optional and defaults | |
| to "/services". As an example, if you have "/web_services" as the prefix, then all the | |
| services hosted would have the endpoint prefix of : http://localhost/axis2/web_services. | |
| Note: don't forget the / at the begining. | |
| If you wish, you can also change the location as well by adding a string value with the name | |
| axis2_location. This is also optional and defaults to /axis2. If you have /myserser as the | |
| value you can access your web services with a url like http://localhost/myserver/services. | |
| Note: Don't forget the / at the beginning. | |
| Now you can do all the registry editing using the JScript file axis2_iis_regedit.js | |
| provided with the distribution. When you build axis2/C with the IIS module the file | |
| is copied to the root directory of the binary distribution. Just double click it and | |
| everything will be set to the defaults. The axis2c_home is taken as the current directory, | |
| so make sure you run the file in the Axis2/C repository location (or root of the binary | |
| distribution). If you want to change the values you can manually edit the the .js file or | |
| give it as command line arguments to the script when running the script. To run the jscript | |
| from the command line use the command :\cscript axis2_iis_regedit.js optional arguments. | |
| We recomend the manual editing as it is the easiest way to specify the values | |
| IIS 5.1 or Below | |
| ----------------- | |
| Using the IIS management console, add a new virtual directory to the | |
| IIS/PWS web site called "axis2". The physical path of this virtual | |
| directory should be the axis2\lib directory (Where the mod_axis2_IIS.dll | |
| is in) | |
| Assign excecute permissions to this virtual directory. | |
| Using the IIS management console, add mod_axis2_IIS.dll as a filter to the | |
| IIS/PWS web site. The name of the filter can be any meaningful name. | |
| Restart IIS and test whether mod_axis2_IIS module is loaded by typing the | |
| URL http://localhost/axis2 in your Web browser. | |
| IIS 6 & 7 | |
| --------- | |
| Using the IIS management console, add the mod_axis2_IIS.dll as a Wildcard Script Map. | |
| Executable should be the complete path to the mod_axis2_IIS.dll | |
| You can put any name as the name of the Wildcard Script Map | |
| Please don't add the mod_axis2_IIS.dll as a filter to IIS as in the IIS 5.1 case. | |
| Note: If the Axis2/C failed to load, verify that Axis2/C and its dependent DLLs are in the | |
| System Path (not the user path). | |
| 5. Using Axis2/C with CGI | |
| 5.1 Deploying in Apache2 | |
| If you haven't already done so you need to configure and set up an cgi-bin/ directory | |
| that holds your CGI scripts,where we will put Axis2/C cgi executable axis2.cgi. | |
| (Note: most of recent Apache web servers already have an cgi-bin dir set up, usually | |
| /usr/lib/cgi-bin/. ) | |
| Add following to your Apache2 configuration (httpd.conf) file. | |
| ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/ (Or some other directory of your choice) | |
| OR you can use | |
| <Directory /usr/local/apache/cgi-bin/> | |
| Options +ExecCGI | |
| </Directory> | |
| AddHandler cgi-script .cgi | |
| { It's recomended to restrict all your cgi scripts to single ScriptAlias directory for security reasons.} | |
| Now we have to set up configuration parameters via environment variables for the cgi | |
| deployment using the SetEnv directive. | |
| { You need to have mod_env enabled for this to work ) | |
| Add the following to your apache2 configuration file (httpd.conf) | |
| SetEnv AXIS2C_HOME <your path to axis2c home dir> | |
| ( i.e. SetEnv AXIS2C_HOME /usr/local/axis2c/ ) | |
| If you have chosen another alias for you cgi-bin you can also set up an AXIS2C_URL_PREFIX | |
| environment variable, but it's not needed if you have chosen /cgi-bin/. | |
| AXIS2C_URL_PREFIX defines your web services deployment url prefix. Lets say you have chosen URL | |
| /private/scripts/ for your cgi-bin URL and named your cgi exec as 'axis2.cgi', | |
| Then you need to set AXIS2_URL_PREFIX environment variable as follows: | |
| SetEnv AXIS2C_URL_PREFIX /private/scripts/axis2.cgi/ | |
| Now we have configured apache such that all requests with URL http://<domain-name>/cgi-bin/ requests | |
| are located at your configured cgi folder. We have granted Apache server to execute CGI from that directory | |
| and treat files with .cgi extensions as CGI executables. | |
| Now you need to copy the Axis2/C cgi executable "axis2.cgi" located in <AXIS2C_HOME>\bin directory. | |
| 5.2 Deploying in IIS | |
| IIS 5.1 | |
| 1. Open your 'Internet services manager' | |
| 2. Under your computer name and 'Default Web Site' you must create an virtual | |
| directory called 'cgi-bin' (if you haven't done so by now) so right click | |
| 'Default Web Site' -> New -> Virtual Directory. | |
| 3. In wizard enter 'cgi-bin' as Alias. | |
| 4. Choose a directory of your choice for cgi scripts placement. (like C:\www\cgi-bin\) | |
| 5. In access permissions select Read and Execute. | |
| 6. Finish the wizard so that Virtual Directory is created. | |
| 7. Open your selected folder (i.e. C:\www\cgi-bin\) and copy axis2.cgi there. | |
| NOTE: | |
| Your Axis2 endpoints now looks like this when deployed under cgi. | |
| http://domain-name.com/cgi-bin/axis2.cgi/<services directory>/<service name> | |
| For the echo service found under /services/ directory of Axis2, the endpoint will become | |
| http://domain-name.com/cgi-bin/axis2.cgi/services/echo | |
| 6. FAQ | |
| ====== | |
| 1. Although I was able to get simple axis server up, unable to run samples. | |
| This could happen because the AXIS2C_HOME environment variable is not | |
| set to the correct axis2 installation path. | |
| 2. What are the other dependencies Axis2/C has? | |
| Basically if you are willing to use libxml2 as your parser, you need to | |
| have it installed in your system. | |
| You can get libxml2 from http://xmlsoft.org/downloads.html. | |
| 3. I have libxml2 installed in my system, but ./configure fails saying | |
| "libxml2 not found" | |
| Yes, you need to install libxml2-dev packages. | |
| 1. If you are using a Debian based system run | |
| $ apt-get install libxml2-dev | |
| 2. If you are using a RedHat/Fedora based system run | |
| $ yum install libxml2-dev | |
| 3. If you install libxml2 from source you will not get this error | |
| 4. Is there any recommended packages, that I need to install in my system? | |
| 1. automake, autoconf, libtool, aclocal | |
| 2. libxml2 and libxml2-dev | |
| 3. pkg-config | |
| 5. I tried several methods, browse through axis-c-dev and axis-c-user mail | |
| archives but I was not able to solve my problem. | |
| Then you can ask from Axis2/C users or Axis2/C developers about it by | |
| sending your question to | |
| user = c-user@axis.apache.org | |
| developer = c-dev@axis.apache.org | |
| You can subscribe to | |
| c-user list by sending a request to | |
| <c-user-subscribe@axis.apache.org> with the subject "subscribe" | |
| c-dev list by sending request to | |
| <c-dev-subscribe@axis.apache.org> with the subject "subscribe" | |
| 6. This FAQ is not enough... | |
| You can help us by reporting your suggestions, complaints, problems and bugs | |
| Thank you for using Axis2/C ... |