Axis C++ Installation Guide

Axis C++ Installation and Configuration Guide

Introduction

This guide will help you to start with Axis C++. This guide will explain the minimum steps needed to install Axis C++ in both a client and a server environment.
Note: Within this document we declare environment variables; You may find that the instructions here need to be altered to your particular operating system.

Contents

Pre-requisites


Client and server

Xerces C++ (2.2.0) XML parser

Axis C++ needs an XML parser to parse SOAP messages and WSDD files. It has a parser abstraction layer that helps users to select/switch between parsers. However only one parser library can be used at a time. Currently Xerces parser is supported by Axis C++.

Server only

Apache web server (2.0.x or 1.3.x)  - If you are going to deploy services to Apache web server (and not simple_axis_server ) then you need to have Apache built with module .so support.

Installing and Configuring Axis C++

Client Installation and Configuration

1. Download Axis C++

Download Axis C++ binary distribution and extract the package into a directory of your choice.

2. Install Xerces C++ (2.2.0)

See the Xerces parser's documentation for installation instructions.

3. Configure environment variables
set AXISCPP_DEPLOY
AXISCPP_DEPLOY="/usr/local/axiscpp_deploy"set LIBRARY_PATHS

The library path needs to have the xml parser libraries and the axis libraries included.


Linux:
LD_LIBRARY_PATH="<xerces installation directory>/lib:$AXISCPP_DEPLOY/lib:$LD_LIBRARY_PATH"

4. Set Engine Wide Settings in Configuration File

The axiscpp.conf file contains all of the user defined setting for the location of specific libraries, definition and log files and can be configured manually or by using the AxisConfiguration executable.
If the user requires a non-standard environment or needs additional information to be supplied (i.e. the location of the client wsdd file) this has to be defined in the axiscpp.conf file.

4.1 Using AxisConfiguration to create the axiscpp.conf file

The AxisConfiguration executable is a simple user interface that allows the user to generate an axiscpp.conf file by first asking a few simple questions about where the package was unzipped to and then allowing the user to pick which file should be associated with configuration tag. Below is an example of a typical conversation between AxisConfiguration and a user (the normal, larger text represents user input).

C:\Axis\axis-c-1.6-Win32-bin\bin>AxisConfiguration Client
Axis Client Configuration
=========================
Type in the Axis fully qualified directory path (e.g. C:\Axis) used when Axis was unzipped (NB: this directory must also contain the axiscpp.conf file). Type '*' to used the existing value of the environment variable (i.e. 'C:\Axis').
AXISCPP_DEPLOY = c:\Axis

Type in the directory where the Axis libraries (e.g. axis_client.dll) can be found. (If you type '*', it will use the default 'axis-c-1.6-Win32-bin\bin').
Axis binaries directory = axis-c-1.6-Win32-bin\bin

Begin to configure the AXISCPP.CONF file.

Select the filename for the HTTP Transport library.
1. c:\Axis\axis-c-1.6-Win32-bin\bin\HTTPTransport.dll
Automatically selected c:\Axis\axis-c-1.6-Win32-bin\bin\HTTPTransport.dll

Select the filename for the HTTP Channel library.
1. C:\Axis\axis-c-1.6-Win32-bin\bin\HTTPChannel.dll
Automatically selected c:\Axis\axis-c-1.6-Win32-bin\bin\HTTPChannel.dll

Select the filename for the HTTP SSL Channel library.
1. C:\Axis\axis-c-1.6-Win32-bin\bin\HTTPSSLChannel.dll
Automatically selected c:\Axis\axis-c-1.6-Win32-bin\bin\HTTPSSLChannel.dll

Select the filename for the Axis XML Parser library.
1. C:\Axis\axis-c-1.6-Win32-bin\bin\AxisXMLParserXerces.dll
Automatically selected C:\Axis\axis-c-1.6-Win32-bin\bin\AxisXMLParserXerces.dll

Select the filename for the SMTP Transport library.
There are no recognised file names for the type of file/library.
You will have to modify the configuration file namually.

Enter name of client trace/log file: client.log

Select the filename for the client WSDD path.
There are no recognised file names for the type of file/library.
You will have to modify the configuration file namually.


Configuration complete.


The configuration file has now been created in %AXISCPP_DEPLOY%\axiscpp.conf. The contents of the file is as follows:-


C:\Axis\axis-c-1.6-Win32-bin\bin>type %AXISCPP_DEPLOY%\axiscpp.conf
# This header file was created by AxisConfiguration on Mon Mar 27 13:50:57 2006
# The comment character is '#'
# Available directives are as follows
#(Some of these directives may not be implemented yet)
#
# Path to server trace log path (only required if you want server trace)
#LogPath:<not set>

# Path to server WSDD path
#WSDDFilePath:<not set>

# Path to client trace log path (only required if you want client trace)
ClientLogPath:c:\Axis\client.log

# Path to client WSDD path
#ClientWSDDFilePath:<not set>

#Node name.
#NodeName: <not set>

#Listening port.
#ListenPort: <not set>

# Path to HTTP Transport library
Transport_http:C:\Axis\axis-c-1.6-Win32-bin\bin\HTTPTransport.dll

# Path to SMTP Transport library
#Transport_smtp:<not set>

# Path to Axis XML Parser library
XMLParser:C:\Axis\axis-c-1.6-Win32-bin\bin\AxisXMLParserXerces.dll

# Path to HTTP Channel library
Channel_HTTP:C:\Axis\axis-c-1.6-Win32-bin\bin\HTTPChannel.dll

# Path to HTTP SSL Channel library
Channel_HTTP_SSL:C:\Axis\axis-c-1.6-Win32-bin\bin\HTTPSSLChannel.dll

# SSL Options
#SecureInfo:<not set>


The AxisConfiguration executable can also be run with a number of command line options to aid automated configuration (an example of this can be found in the ant script axis-c-1.6-Win32-bin\build\executeBuild.xml, target name 'createConfigurationFile'). The available options are listed below.

CommandDescriptionExample
-acdDirectory to write axiscpp.conf once it has been configured. This overrides the '-a' value (which defines where axiscpp.conf would normally reside).-acd c:\Axis\Different
-aRoot directory of Axis download (AXISCPP_HOME).-a c:\Axis
-oDirectory offset from AXISCPP_HOME to object files.-o axis-c-1.6-Win32-bin\bin
-xXerces library name. If -a and -o have both already been defined, then only the filename is required. Otherwise the fully qualified path will be required (NB: You can still override the -a and -o definitions by using a fully qualified path).(with -a and -o defined): -x AxisXMLParserXerces.dll, (without -a and -o defined): -x c:\Axis\axis-c-1.6-Win32-bin\bin\AxisXMLParserXerces.dll
-mMerge with existing configuration file.-m on|off (the default is 'off' meaning 'overwrite')
-piChange the progress information output during the construction of the configuration file.-pi normal|quiet (the default is 'normal' meaning "give full descriptions").
-bBackup the existing configuration file before creating the new one.-b true|false (the default is 'true').
-qmfQuery for missing files. When no parameter for a filename is provided on the command line, the application will list the file options and the user then selects which file to use in the configuration file. This can be turned off using this parameter.-qmf on|off (the default is 'on' meaning "list and then ask for file to include").
-soSSL options. Used to add a string of parameters (if) required by the version SSL.-so "...parameter list..."

Client Specific
---------------

CommandDescriptionExample
-thTransport library name. If -a and -o have both already been defined, then only the filename is required. Otherwise the fully qualified path will be required (NB: You can still override the -a and -o definitions by using a fully qualified path).(with -a and -o defined): -th HTTPTransport.dll, (without -a and -o defined): -th c:\Axis\axis-c-1.6-Win32-bin\bin\HTTPTransport.dll
-cChannel library name. If -a and -o have both already been defined, then only the filename is required. Otherwise the fully qualified path will be required (NB: You can still override the -a and -o definitions by using a fully qualified path).(with -a and -o defined): -c HTTPChannel.dll, (without -a and -o defined): -c c:\Axis\axis-c-1.6-Win32-bin\bin\HTTPChannel.dll
-csSSL channel library name. If -a and -o have both already been defined, then only the filename is required. Otherwise the fully qualified path will be required (NB: You can still override the -a and -o definitions by using a fully qualified path).(with -a and -o defined): -cs HTTPSSLChannel.dll, (without -a and -o defined): -cs c:\Axis\axis-c-1.6-Win32-bin\bin\HTTPSSLChannel.dll
-clClient log filename. If -a has been defined, then only the filename is required. Otherwise the fully qualified path will be required. (NB: You can still override the -a and -o definitions by using a fully qulified path). To ignore the client log, using 'ignore' instead of a filename.(without -a defined): -cl c:\Axis\client.log.
-cwClient WSDD filename. If -a and -o have both already been defined, then only the filename is required. Otherwise the fully qualified path will be required (NB: You can still override the -a and -o definitions by using a fully qulified path).(with -a and -o defined): -cw client.wsdd, (without -a and -o defined): -cw c:\Axis\WSDD\client.wsdd

Server Specific
---------------

CommandDescriptionExample
-slServer log filename. If -a has been defined, then only the filename is required. Otherwise the fully qualified path will be required. (NB: You can still override the -a and -o definitions by using a fully qulified path).(with -a defined): -sl server.log, (without -a defined): -sl c:\Axis\server.log
-swServer WSDD filename. If -a and -o have both already been defined, then only the filename is required. Otherwise the fully qualified path will be required (NB: You can still override the -a and -o definitions by using a fully qulified path).(with -a and -o defined): -sw server.wsdd, (without -a and -o defined): -sw c:\Axis\WSDD\server.wsdd


4.2 Manually create the axiscpp.conf file

A sample configuration file is installed in $AXISCPP_DEPLOY/etc on linux or %AXISCPP_DEPLOY% on windows systems. Edit this file to match your systems settings and copy it to axiscpp.conf

Configuration file has the following syntax on the client-side:

The comment character is '#'
Transport_http - HTTP transport library: Required
Channel_HTTP - Channel transport library: Required
Channel_HTTP_SSL - SSL channel transport library: Optional - only required is you are going to use ssl
XMLParser - The Axis XML parser library that comes with your configuration: Required
SecureInfo: SSL configuration information: Optional - only required if you are going to use ssl
ClientWSDDFilePath - Path to the client wsdd: Optional - only required if you are using client-side handlers
ClientLogPath - Path to the Axis C++ client log: Optional - only required if you want engine trace for debugging purposes

A sample axiscpp.conf file for a client (linux)

Transport_http:/usr/local/axiscpp_deploy/lib/libhttp_transport.so
Channel_HTTP:/usr/local/axiscpp_deploy/lib/libhttp_channel.so
XMLParser:/usr/local/axiscpp_deploy/lib/libaxis_xerces.so
ClientWSDDFilePath:/usr/local/axiscpp_deploy/etc/client.wsdd
ClientLogPath:/usr/local/axiscpp_deploy/log/AxisClientLog


Once you have completed the above steps you should be ready to create and run your client application using AXIS C++ !

Server Installation and Configuration

1. Download Axis C++

Download Axis C++ binary distribution and extract the package into a directory of your choice.

2. Install Apache Web Server

If you are going to deploy services to Apache and not use the simple_axis_server then you need to install apache webserver. In case you have already installed Apache , make sure that 'so modules' are enabled.
This is because Axis C++ server engine is implemented as a 'so module'. (For Apache 1.3.x use --enable-module=so; for Apache 2.0.x use --enable-so when configuring. See Apache web server documentation for more details)

3. Install Xerces C++ (2.2.0)

See the Xerces parser's documentation for installation instructions.

4. Configure environment variables

The Axis server runtime requires the same variables to be set as the Axis client engine does.

set AXISCPP_DEPLOYAXISCPP_DEPLOY="Path to the folder where you installed Axis C++"
e.g. AXISCPP_DEPLOY="/usr/local/axiscpp_deploy"set LIBRARY_PATHS

The library path needs to have the xml parser libraries and the axis libraries included.

Windows:PATH=<xerces installation path>/bin;%AXISCPP_DEPLOY/bin%;%PATH%

Linux:LD_LIBRARY_PATH="<xerces installation path>/lib:$AXISCPP_DEPLOY/lib:$LD_LIBRARY_PATH"

5. Configure Engine Wide Settings in Configuration File

As with the client-side the Axis C++ server-side engine uses a configuration file to let the user specify preferences such as log file locations, transport and parser libs to be used and location of deployment descriptor files.
A sample configuration file is installed in $AXISCPP_DEPLOY/etc folder (or in %AXISCPP_DEPLOY% on windows). Edit this file to match your systems settings and copy or rename it to "axiscpp.conf"

Configuration file has the following Syntax:


The comment character is '#'
WSDDFilePath - Path to the server wsdd file: Required - so that Axis knows what services and handlers you have deployed
Transport_http - Axis HTTP transport library: Required
Channel_HTTP - Axis Channel transport library: Required
XMLParser - Axis XML parser library: Required
LogPath: Path to the Axis C++ server log: Optional - only required if you want to see trace from the Axis Engine for debugging purposes

A sample server axiscpp.conf file (Linux):

WSDDFilePath:/usr/local/axiscpp_deploy/etc/server.wsdd
LogPath:/usr/local/axiscpp_deploy/log/AxisLog
XMLParser:/usr/local/axiscpp_deploy/lib/libaxis_xercesc.so
Transport_http:/usr/local/axiscpp_deploy/lib/libaxis3_transport.so
Channel_HTTP:/usr/local/axiscpp_deploy/lib/libaxis3_transport_channel.so
6. Setting Axis files to be executable

On non-windows platforms you need to ensure global access rights to the Axis C++ deploy folder to make sure that Axis C++ works properly.

chmod -R 777 $AXISCPP_DEPLOY

7. Configure Apache Module

Note: to execute the following steps, you may need to have administrator rights on your machine.

Now you need to edit httpd.conf file in <path to Apache web server installation>/conf and add the following lines at the bottom of that file (assuming you are using Apache 2.0.x):
(Linux)

LoadModule axis_module modules/libaxiscpp_mod2.so
<Location /axis>
SetHandler axis
</Location>

For Apache1.3.x LoadModule line should read as:
LoadModule axis_module libexec/libaxiscpp_mod.so

8. Deploying Axis Module to Apache Web Server

Now we need to copy Apache module (libaxiscpp_mod2.so - linux names- for Apache 2.0.x and libaxiscpp_mod.so for Apache 1.3.x) to the correct places and start Apache web server. The steps to follow are:

  1. Copy libaxiscpp_mod2.so to /<your Apache 2.0.x home>/modules (or copy libaxiscpp_mod.so to /<your Apache 1.3.x home>/libexec)
  2. Start Apache /<path to Apache installation>/bin/apachectl start

9. See Axis C++ in action

Now the installation is complete. You can verify that the server side is working by accessing the URL http://localhost/axis using your web browser. You should get the Axis C++ welcome page and this page will show you a list of deployed services as specified by the <Axis Installation directory>/conf/server.wsdd file. Although at this stage you won't have any services deployed yet.

Now you can run a client sample and see if it works.

Simple Axis Server installation and configuration

1. Make sure that you have set the AXISCPP_DEPLOY environment variable to point to your deployment folder as mentioned above

2. Create your axiscpp.conf file as above for the Apache server-side making sure that the contents of that file match your system settings

3. Run simple axis server in $AXISCPP_DEPLOY/bin
Synopsis: simple_axis_server server-port Where server-port is the port on which you would like the server to listen for client requests.

For Example (linux):

cd $AXISCPP_DEPLOY/bin

./simple_axis_server 9090

5. Run clients in $AXISCPP_DEPLOY/bin

On a different shell:

cd $AXISCPP_DEPLOY/bin

./base http://localhost:9090/axis/base

Similarly you could run the other samples.