C Specific Architectural Notes on Apache Axis2/C

Please send your feedback to: axis-c-dev@ws.apache.org (Subscription details are available on the Axis2 site.) Prefix the subject with [Axis2].

Introduction

Some of the main design goals of Apache Axis2/C are the usability of the library, the ability to be plugged into different platforms, and the ability to be embedded in other software systems to provide Web services support. There are many features that allow Axis2/C to be pluggable into different platforms as well as to enable the extension of the functionality of Axis2/C.

Environment Struct

Apache Axis2/C defines an environment struct to hold platform specific entities such as the memory allocator, the threading mechanism, etc. The environment is initialized at the point of starting Axis2/C and will last for the lifetime of the Axis2/C run-time. Different sub environments can also be created to suit particular needs, for example, each thread can create its own environment. The Axis2 environment holds the following entities in order to abstract the platform specific implementations.

Allocator

Allocator is the wrapper for memory management mechanisms. It defines the following primitives:

  1. malloc - method to allocate a memory block of a given size.
  2. free - method to free a memory block.

Based on the platform, or the software system into which Axis2/C is embedded, these primitives could be provided with concrete implementations.

Error

Error defines error reporting mechanisms for Axis2/C. All the Axis2/C internal functions use the axutil_error struct instance in the environment to report errors.

Log

The log defines the common logging mechanisms required for the Axis2/C library. All internal Axis2/C code use the functions associated with the axutil_log struct available in the environment for logging.

Thread Pool

The thread pool defines the thread management functions. It hides the complex thread pooling functions as well as the platform specific implementations of threads. The Axis2/C internal library uses this interface to manipulate threads and deal with a common thread type which is defined as axutil_thread.

The environment struct is the starting point for platform abstraction supported by Axis2/C. It can be used to plug platform specific memory management, error reporting, logging, and thread pooling mechanisms.

Dynamic Loading

Axis2/C is designed in an extensible manner, so that the users can add functionality by implementing new modules. These modules should be compiled as Dynamic Shared Objects (DSOs). Services are also loaded dynamically at server start up by reading the contents of the services folder and service configuration files.

The DSO support for loading Axis2/C services and modules is based on the struct named axutil_class_loader. To abstract the axutil_class_loader from the DSO loading functionality of the underlying operating system, a set of platform independent macros such as AXIS2_PLATFORM_LOADLIB and AXIS2_PLATFORM_UNLOADLIB are used. These macros will be mapped to platform specific system calls in platform specific header files (e.g. axutil_unix.h and axutil_windows.h). The file axutil_platform_auto_sense.h will include the correct platform specific header file, based on the compiler directives available at compile time.

Transport Abstraction

One of the key advantages of Axis2/C is the fact that the engine and the SOAP processing is independent of the transport aspects. Users can develop their own transports and the interface will be defined in: axis2_transport_sender.h and axis2_transport_receiver.h.

Currently, Axis2/C supports HTTP transport. Axis2/C Apache2 module (mod_axis2) is an example of the implementation of the axis2_transport_receiver.h interface. libcurl based client transport is an example of the implementation of the axis2_transport_sender.h interface.

Stream Abstraction

Stream is a representation of a sequence of bytes. Since Axis2/C heavily uses streaming mechanisms to read/write XML, an implementation independent stream abstraction is required in order to integrate Axis2/C into other environments seamlessly. The core components of Axis2/C deal with this abstracted stream and does not worry about the implementation specific details. axutil_stream.h defines the stream interface.

Threading Model

The Axis2/C core functions such as asynchronous invocation and concurrent request processing in simple axis2 server make use of threads. The use of threads should be platform independent inside the Axis2/C core components.

An implementation independent interface for threads is provided in the axutil_thread.h header file. Platform specific implementations of this interface are provided for Windows and Linux.

Parser Abstraction

The Axis2/C architecture depends on the XML pull model when dealing with XML payloads. In Java there is StAX API, but in C there is no such standard API. Therefore, an XML pull API, that is similar to StAX API, is defined in the axiom_xml_reader.h and axiom_xml_writer.h. Any implementation of this API can be plugged into the Axis2/C core. If an external XML parser needs to be plugged into Axis2/C, a wrapper that maps the reading/writing functions to the Axis2/C XML reader/writer API should be written.