summaryrefslogtreecommitdiffstats
path: root/xdocs/docs/architecture_notes.html
blob: f050aed16dabdc1825849dbd87b939e4b21b2060 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You 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.
-->
<html><head><title>Apache Axis2/C - Architecture Notes</title><h2>C Specific Architectural Notes on Apache Axis2/C</h2><p>Please send your feedback to: <a href="mailto:c-dev@axis.apache.org?subject=[Axis2]">c-dev@axis.apache.org</a>
(Subscription details are available on the <a href="http://axis.apache.org/axis2/c/core/mail-lists.html" class="externalLink" title="External Link">Axis2 site</a>.) Prefix
the subject with [Axis2].</p><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
  <li><a href="#Introduction">Introduction</a></li>
  <li><a href="#Axis2_Environment">Environment Struct</a></li>
  <li><a href="#Dynamic_Loading">Dynamic Loading</a></li>
  <li><a href="#Transport_Abstraction">Transport Abstraction</a></li>
  <li><a href="#Stream_Abstraction">Stream Abstraction</a></li>
  <li><a href="#Threading_Model">Threading Model</a></li>
  <li><a href="#Parser_Abstraction">Parser Abstraction</a></li>
</ul><p><a name="Introduction"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p>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.</p><p><a name="Axis2_Environment"></a></p></div><div class="subsection"><a name="Environment_Struct"></a><h3>Environment Struct</h3><p>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.</p></div><div class="subsection"><a name="Allocator"></a><h3>Allocator</h3><p>Allocator is the wrapper for memory management mechanisms. It defines the
following primitives:</p><ol>
  <li><code>malloc</code> - method to allocate a memory block of a given
  size.</li>
  <li><code>free</code> - method to free a memory block.</li>
</ol><p>Based on the platform, or the software system into which Axis2/C is
embedded, these primitives could be provided with concrete
implementations.</p></div><div class="subsection"><a name="Error"></a><h3>Error</h3><p>Error defines error reporting mechanisms for Axis2/C. All the Axis2/C
internal functions use the <code>axutil_error</code> struct instance in the
environment to report errors.</p></div><div class="subsection"><a name="Log"></a><h3>Log</h3><p>The log defines the common logging mechanisms required for the Axis2/C
library. All internal Axis2/C code use the functions associated with the
<code>axutil_log</code> struct available in the environment for logging.</p></div><div class="subsection"><a name="Thread_Pool"></a><h3>Thread Pool</h3><p>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
<code>axutil_thread.</code></p><p>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.</p><p><a name="Dynamic_Loading"></a></p></div><div class="subsection"><a name="Dynamic_Loading"></a><h3>Dynamic Loading</h3><p>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.</p><p>The DSO support for loading Axis2/C services and modules is based on the
struct named <code>axutil_class_loader</code>. To abstract the
<code>axutil_class_loader</code> from the DSO loading functionality of the
underlying operating system, a set of platform independent macros such as
<code>AXIS2_PLATFORM_LOADLIB</code> and <code>AXIS2_PLATFORM_UNLOADLIB</code>
are used. These macros will be mapped to platform specific system calls in
platform specific header files (e.g. <code>axutil_unix.h</code> and
<code>axutil_windows.h</code>). The file
<code>axutil_platform_auto_sense.h</code> will include the correct platform
specific header file, based on the compiler directives available at compile
time.</p><p><a name="Transport_Abstraction"></a></p></div><div class="subsection"><a name="Transport_Abstraction"></a><h3>Transport Abstraction</h3><p>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:
<code>axis2_transport_sender.h</code> and
<code>axis2_transport_receiver.h</code>.</p><p>Currently, Axis2/C supports HTTP transport. Axis2/C Apache2 module (<a href="installationguide.html#installing-apache2">mod_axis2</a>) is an example
of the implementation of the <code>axis2_transport_receiver.h</code>
interface. libcurl based client transport is an example of the implementation
of the <code>axis2_transport_sender.h</code> interface.</p><p><a name="Stream_Abstraction"></a></p></div><div class="subsection"><a name="Stream_Abstraction"></a><h3>Stream Abstraction</h3><p>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. <code>axutil_stream.h</code> defines the stream interface.</p><p><a name="Threading_Model"></a></p></div><div class="subsection"><a name="Threading_Model"></a><h3>Threading Model</h3><p>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.</p><p>An implementation independent interface for threads is provided in the
<code>axutil_thread.h</code> header file. Platform specific implementations
of this interface are provided for Windows and Linux.</p><p><a name="Parser_Abstraction"></a></p></div><div class="subsection"><a name="Parser_Abstraction"></a><h3>Parser Abstraction</h3><p>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 <code>axiom_xml_reader.h</code> and <code>axiom_xml_writer.h</code>. 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.</p></div></div></div></div><div class="clear"><hr></hr></div></body></html>