## 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].

### Contents

- Introduction
- Environment Struct
- Dynamic Loading
- Transport Abstraction
- Stream Abstraction
- Threading Model
- Parser Abstraction

### 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.