You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ma...@apache.org on 2007/04/25 12:39:58 UTC
svn commit: r532305 [4/4] - in /webservices/axis2/scratch/c/neethi/axis2c:
./ axiom/ axiom/src/soap/ guththila/ ides/ ides/anjuta/
ides/vc/axis2c/axis2_engine/ ides/vc/axis2c/axis2_http_receiver/
ides/vc/axis2c/axis2_http_sender/ ides/vc/axis2c/axis2_h...
Modified: webservices/axis2/scratch/c/neethi/axis2c/xdocs/docs/installationguide.html
URL: http://svn.apache.org/viewvc/webservices/axis2/scratch/c/neethi/axis2c/xdocs/docs/installationguide.html?view=diff&rev=532305&r1=532304&r2=532305
==============================================================================
--- webservices/axis2/scratch/c/neethi/axis2c/xdocs/docs/installationguide.html (original)
+++ webservices/axis2/scratch/c/neethi/axis2c/xdocs/docs/installationguide.html Wed Apr 25 03:39:55 2007
@@ -6,74 +6,73 @@
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>Apache Axis2/C Installation Guide</title>
- <meta name="generator" content="Bluefish 1.0.5"/>
</head>
<body>
<h1>Apache Axis2/C Installation Guide</h1>
-<p>This document will guide you on how to install Axis2/C and run the server
-and client samples on Linux and Microsoft Windows operating systems.</p>
+<p>This document guides you on how to install Axis2/C, and run the server and
+client samples on Linux and Microsoft Windows operating systems.</p>
-<p>This release comes in two forms, source and binary. This document covers both those forms.</p>
+<p>This release comes in two forms, source and binary. This document covers
+both forms.</p>
<p>Please send your feedback to the developer mailing list: <a
-href="mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</a> (please
-remember to prefix the subject with [Axis2]). To subscribe to developer
-mailing list see <a href="http://ws.apache.org/axis2/c/mail-lists.html">here</a>.</p>
+href="mailto:axis-c-dev@ws.apache.org">axis-c-dev@ws.apache.org</a>
+(Subscription details are available on the <a
+href="http://ws.apache.org/axis2/c/mail-lists.html">Axis2 site</a>.) Please
+remember to prefix the subject with [Axis2].</p>
<h2>Contents</h2>
<ul>
<li><a href="#linux">Installing and Running on Linux</a>
<ul>
- <li><a href="#linux_binary">Using Binary Release</a></li>
- <li><a href="#linux_source">Using Source Release</a></li>
+ <li><a href="#linux_binary">Using the Binary Release</a></li>
+ <li><a href="#linux_source">Using the Source Release</a></li>
</ul>
</li>
<li><a href="#win">Installing and Running on Microsoft Windows (win32)</a>
<ul>
- <li><a href="#win_binary">Using Binary Release</a>
- </li>
- <li><a href="#win_source">Using Source Release</a>
- </li>
+ <li><a href="#win_binary">Using the Binary Release</a></li>
+ <li><a href="#win_source">Using the Source Release</a></li>
</ul>
</li>
</ul>
-
<a id="linux"></a>
<h2>1. Installing and Running on Linux</h2>
-<p>This can be done using binary or source distributions.(You can download the two distributions <a href="http://ws.apache.org/axis2/c/download.cgi"> here</a>)</p>
+<p>This can be done using binary or source distributions. (<a
+href="http://ws.apache.org/axis2/c/download.cgi">Download</a> the two
+distributions)</p>
-<p>To get both the binary and source distributions working, you need
-<a href="http://xmlsoft.org/downloads.html">Libxml2</a>.</p>
-
-<p><b>Note :</b> Most Linux systems have Libxml2 installed by default. On MS
-Windows you need to download and install Libxml2.</p>
+<p>To get both the binary and source distributions working, you need <a
+href="http://xmlsoft.org/downloads.html">Libxml2</a>.</p>
+<p><b>Note:</b> Most Linux systems have Libxml2 installed by default. On MS
+Windows, you need to download and install Libxml2.</p>
<a id="linux_binary"></a>
-<h3>1.1. Installing Binary Distribution</h3>
+<h3>1.1. Installing the Binary Distribution</h3>
-<p>The following steps need to be followed to install and run
-Axis2/C binary distribution on Linux : - </p>
+<p>The following steps have to be followed to install and run the Axis2/C
+binary distribution on Linux : </p>
<ol>
- <li>Extract the binary tar package to a folder</li>
- <li>Set AXIS2C_HOME environment variable pointing to the location where you
- have extracted Axis2/C
+ <li>Extract the binary tar package to a folder.</li>
+ <li>Set the AXIS2C_HOME environment variable pointing to the location where
+ you have extracted Axis2/C
<ul>
<li>AXIS2C_HOME='/your_path_to_axis2c'</li>
<li>export AXIS2C_HOME</li>
- <p><strong>Note :</strong> You will need to set AXIS2C_HOME only if you
- need to run Axis2/C samples. The reason is that the samples
- use AXIS2C_HOME to get the path to Axis2/C repository. To write your own
- services or clients this is not a requirement.</p>
+ <p><strong>Note:</strong> You will need to set the AXIS2C_HOME only if
+ you need to run the Axis2/C samples. The reason is that the samples use
+ AXIS2C_HOME to get the path to the Axis2/C repository. This is not
+ required to write your own services or clients. </p>
</ul>
</li>
<li>Run the simple axis server:
<ul>
- <li>To start the simple axis server on default port 9090, run the
+ <li>To start the simple axis server on the default port 9090, run the
following commands.
<ul>
<li>cd /your_path_to_axis2c/bin</li>
@@ -81,8 +80,9 @@
</ul>
</li>
<li>To see the possible command line options run ./axis2_http_server -h
- <p><strong>Note :</strong> If you run into shared library problems, try
- setting the LD_LIBRARY_PATH to include the lib folder containing the Axis2/C libs.</p>
+ <p><strong>Note:</strong> If you run into shared library problems,
+ try setting the LD_LIBRARY_PATH to include the lib folder containing
+ the Axis2/C libs.</p>
<ul>
<li>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
<li>export LD_LIBRARY_PATH</li>
@@ -93,54 +93,54 @@
<li>Run the sample clients in a new shell
<ul>
<li>cd /your_path_to_axis2c/bin/samples</li>
- <li>To run client for echo service
+ <li>To run the client for echo service
<ul>
<li>./echo</li>
</ul>
</li>
- <li>To run client for math service
+ <li>To run the client for math service
<ul>
<li>./math</li>
</ul>
</li>
- <li>To see the possible command line options for sample clients run
- them with '-h' option</li>
- <p><strong>Note :</strong> If you run into shared library problems, try
+ <li>To see the possible command line options for the sample clients,
+ run them with the '-h' option</li>
+ <p><strong>Note:</strong> If you run into shared library problems, try
setting the LD_LIBRARY_PATH</p>
<ul>
- <li>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
- <li>export LD_LIBRARY_PATH</li>
+ <li>LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/your_path_to_axis2c/lib</li>
+ <li>export LD_LIBRARY_PATH</li>
</ul>
</ul>
</li>
</ol>
-
<a id="linux_source"></a>
-<h3>1.2. Installing Source Distribution</h3>
-<p>The following steps need to be followed to install and run Axis2/C using
-source distribution on Linux : - </p>
+<h3>1.2. Installing the Source Distribution</h3>
+
+<p>The following steps have to be followed to install and run Axis2/C using
+the source distribution on Linux :</p>
<ol>
- <li>Extract the source tar package to a folder</li>
- <li>Set AXIS2C_HOME environment variable pointing to the location where you
- want to install Axis2/C
+ <li>Extract the source tar package to a folder.</li>
+ <li>Set the AXIS2C_HOME environment variable pointing to the location where
+ you want to install Axis2/C
<ul>
<li>AXIS2C_HOME='/your_desired_path_to_axis2c_installation'</li>
<li>export AXIS2C_HOME</li>
- <p><strong>Note :</strong> You will need to set AXIS2C_HOME only if you
- need to run Axis2/C samples. The reason is that the samples
- use AXIS2C_HOME to get the path to Axis2/C repository. To write your own
- services or clients this is not a requirement.</p>
+ <p><strong>Note:</strong> You will have to set AXIS2C_HOME only if you
+ want to run the Axis2/C samples. The reason is that the samples use
+ AXIS2C_HOME to get the path to the Axis2/C repository. This is not
+ required to write your own services or clients.</p>
</ul>
</li>
- <li>Then go to the folder where you extracted the source
+ <li>Then go to the folder where you extracted the source.
<ul>
<li>cd /your_path_to_axis2c_source</li>
</ul>
</li>
<li>Build the source
<ul>
- <li>This can be done using the following command sequence in the
+ <li>This can be done using the following command sequence, in the
directory where you have extracted the source:
<ul>
<li>./configure</li>
@@ -149,11 +149,11 @@
</ul>
</li>
<li>Use './configure --help' for possible command line options.</li>
- <li><strong>Note :</strong>If you do not provide a --prefix configure
- option, the default installation would be /usr/local/axis2c
+ <li><strong>Note:</strong> If you do not provide a --prefix configure
+ option, the default installation would be in the /usr/local/axis2c
directory.</li>
- <li>You may need to try Axis2/C with Guththila XML parser. You can do
- that by providing --enable-guththila=yes option when configuring
+ <li>You may have to try Axis2/C with Guththila XML parser. You can do
+ that by providing the --enable-guththila=yes option when configuring.
<ul>
<li>./configure --enable-guththila=yes [other configuration
options]</li>
@@ -161,7 +161,7 @@
<li>make install</li>
</ul>
</li>
- <li>If you need to get the samples working, you also need to build the
+ <li>If you want to get the samples working, you have to build the
samples. <br />
To build the samples:
<ul>
@@ -175,75 +175,77 @@
<li>make install</li>
</ul>
</li>
- <li>Please run "./configure --help" in samples folder for more
- information on configure options.</li>
- <li><strong>Note :</strong> If you do not provide a --prefix configure
- option, samples will by default be installed into
+ <li>Please run "./configure --help" in the samples folder for more
+ information on the configure options.</li>
+ <li><strong>Note:</strong> If you do not provide a --prefix configure
+ option, by default, the samples will be installed into the
"/usr/local/axis2c/bin/samples" directory.</li>
</ul>
</li>
<li>Go to where you installed Axis2/C.</li>
- <li>Start simple axis server
+ <li>Start the simple axis server.
<ul>
- <li>To start the simple axis server on port 9090 run the following
- command lines
+ <li>To start the simple axis server on port 9090, run the following
+ command lines.
<ul>
<li>cd /path_you_installed_axis2c/bin</li>
<li>./axis2_http_server</li>
</ul>
</li>
- <li>To see the possible command line options run ./axis2_http_server -h</li>
- <li><strong>Note :</strong> You may need to be logged in as a superuser to
- run the simple axis server, if you installed Axis2/C as super user.</li>
+ <li>To see the possible command line options, run ./axis2_http_server
+ -h</li>
+ <li><strong>Note:</strong> You may have to be logged in as a superuser
+ to run the simple axis server if you installed Axis2/C as a super
+ user.</li>
</ul>
</li>
- <li>Run the sample clients in a new shell using the following command lines
+ <li>Run the sample clients in a new shell using the following command lines.
<ul>
<li>cd /path_you_installed_axis2c/bin/samples</li>
- <li>to run client for echo service
+ <li>To run the client for the echo service
<ul>
<li>./echo</li>
</ul>
</li>
- <li>to run client for math service
+ <li>To run the client for the math service
<ul>
<li>./math</li>
</ul>
</li>
- <li>To see the possible command line options for sample clients run
- them with '-h' option</li>
+ <li>To see the possible command line options for the sample clients,
+ run them with the '-h' option</li>
</ul>
</li>
</ol>
-
<a id="win"></a>
<h2>2. Installing and Running on Microsoft Windows</h2>
-<p>This too can be done using either binary or source distributions.
-(You can download the two distributions <a href="http://ws.apache.org/axis2/c/download.cgi"> here</a>)</p>
-
-<p>For both the binary and source distributions, you need to
-download <a href="http://xmlsoft.org/downloads.html">Libxml2</a>.</p>
+<p>This too can be done using binary or source distributions. (<a
+href="http://ws.apache.org/axis2/c/download.cgi">Download</a> the two
+distributions.) </p>
+<p>For both binary and source distributions, you have to download <a
+href="http://xmlsoft.org/downloads.html">Libxml2</a>.</p>
<a id="win_binary"></a>
-<h3>2. 1. Installing Binary Distribution</h3>
-<a id="bin_req"></a>
+<h3>2. 1. Installing the Binary Distribution </h3>
<h4>2.1.1. Requirements</h4>
<ul>
- <li>The binaries shipped with this version are compiled with Microsoft
+ <li>The binaries shipped with this version are compiled with the Microsoft
Visual Studio compiler (cl)</li>
- <p>(Note: you can <a href="http://msdn.microsoft.com/vstudio/express/downloads/">download Microsoft VSExpress2005 edition</a>
- from the Microsoft Web site and install it to run these binaries)</p>
+ <p>(<strong>Note</strong>: you can <a
+ href="http://msdn.microsoft.com/vstudio/express/downloads/">download the
+ Microsoft VSExpress2005 edition</a> from the Microsoft Web site and install
+ it to run these binaries.)</p>
<li>You also need the following DLLs:
<ul>
<li>libxml2.dll [http://www.xmlsoft.org - download the version >=
- libxml2-2.6.27.win32]</li>
- <li>iconv.dll [http://www.gnu.org/software/libiconv/ - download the version >=
- iconv-1.9.1.win32]</li>
+ libxml2-2.6.27.win32]</li>
+ <li>iconv.dll [http://www.gnu.org/software/libiconv/ - download the
+ version >= iconv-1.9.1.win32]</li>
<li>zlib1.dll [http://www.gzip.org/zlib/ - download the version >=
zlib-1.2.3.win32]</li>
</ul>
@@ -251,7 +253,7 @@
</ul>
<a id="bin_binaries"></a>
-<h4>2.1.2. Binaries in The Release</h4>
+<h4>2.1.2. Binaries in the Release</h4>
<ul>
<li>Extract the binary distribution to a folder of your choice. (example:
C:\axis2c)</li>
@@ -262,38 +264,39 @@
<p><em>The above folders contain the following files:</em></p>
<ul>
- <li>bin - server and other executable</li>
- <li>bin\samples - client samples go here</li>
+ <li>bin - server and other executables</li>
+ <li>bin\samples - client samples </li>
<li>lib - library modules</li>
<li>services - deployed services</li>
<li>modules - deployed modules</li>
- <li>include - all include files of Axis2/C</li>
+ <li>include - all Include files of Axis2/C</li>
<li>logs - system and client logs are written to this folder</li>
</ul>
- <li>Copy libxml2.dll, iconv.dll and zlib1.dll downloaded to
+ <li>Copy libxml2.dll, iconv.dll, and zlib1.dll downloaded to
C:\axis2c\lib</li>
</ul>
<a id="bin_run"></a>
-<h4>2.1.3. Running The Binaries</h4>
+<h4>2.1.3. Running the Binaries</h4>
<ul>
<li>First, you need to set a couple of environment variables before you can
run the server and samples.
<ul>
<li>Set the variable AXIS2C_HOME to the deploy folder (C:\axis2c)</li>
- <li>Add the path to lib directory to the PATH variable
- (%AXIS2C_HOME%\lib)</li>
+ <li>Add the path to the lib directory to the PATH variable
+ (%AXIS2C_HOME%\lib)</li>
</ul>
</li>
- <li>Now everything is set to run the server<p>
- C:\axis2c\bin\>axis2_http_server.exe</p></li>
- <li>If the server is running successfully you should see the message
+ <li>Now everything is set to run the server.
+ <p>C:\axis2c\bin\>axis2_http_server.exe</p>
+ </li>
+ <li>If the server is running successfully, you will see the message
"Started Simple Axis2 HTTP Server..."</li>
- <li>The log is by default created in %AXIS2C_HOME%\logs folder with the
- name axis2.log.</li>
- <li>(Note: You may provide command line options to change the default
- behavior. Use the command "axis2_http_server.exe -h" to learn about the
- usage)</li>
+ <li>By default, the log is created in the %AXIS2C_HOME%\logs folder with
+ the name axis2.log.</li>
+ <li>(<strong>Note</strong>: You can provide command line options to change
+ the default behavior. Use the command "axis2_http_server.exe -h" to learn
+ about the usage)</li>
<li>Now you can run any sample client located in %AXIS2C_HOME%\bin\samples\
<ul>
<li>Example: C:\axis2c\bin\samples\> echo.exe</li>
@@ -303,22 +306,23 @@
<a id="win_source"></a>
<h3>2. 2. Installing Source Distribution</h3>
-<a id="src_req"></a>
<h4>2.2.1. Requirements</h4>
<ul>
<li>The makefile shipped with this version needs Microsoft Visual Studio
- Compiler (cl) and nmake build tool.</li>
+ Compiler (cl) and the NMake build tool.</li>
- <p>(Note: You can <a href="http://msdn.microsoft.com/vstudio/express/downloads/">download Microsoft VSExpress2005 edition and Platform SDK </a>
- from Microsoft Web site. You will need to add the path to Platform SDK
- Include and Lib folders to makefile)</p>
+ <p>(Note: You can <a
+ href="http://msdn.microsoft.com/vstudio/express/downloads/">download the
+ Microsoft VSExpress2005 edition and Platform SDK</a> from the Microsoft Web
+ site. You will need to add the path to the Platform SDK Include and Lib
+ folders to the makefile)</p>
<li>You also need
<ul>
<li>Libxml2 [http://www.xmlsoft.org - download the version >=
libxml2-2.6.27.win32]</li>
- <li>iconv [http://www.gnu.org/software/libiconv/ - download the version >=
- iconv-1.9.1.win32]</li>
+ <li>iconv [http://www.gnu.org/software/libiconv/ - download the version
+ >= iconv-1.9.1.win32]</li>
<li>zlib [http://www.gzip.org/zlib/ - download the version >=
zlib-1.2.3.win32]</li>
</ul>
@@ -326,52 +330,56 @@
</ul>
<a id="edit"></a>
-<h4>2.2.3. Editing configure.in File</h4>
-<p>Please edit <source_distribution>\build\win32\configure.in file to include following information. </p>
+<h4>2.2.3. Editing the configure.in File</h4>
+
+<p>Please edit the <source_distribution>\build\win32\configure.in file
+to include the following information.</p>
<ul>
<li>The default paths for Libxml2 and iconv are specified in configure.in
<ul>
- <li>Example:If libxml2 is installed into C:\libxml2, edit configure.in file accordingly.</li>
+ <li>Example:If libxml2 is installed into C:\libxml2, edit the
+ configure.in file accordingly.</li>
</ul>
</li>
- <li>You can either extract Libxml2 to this folder, in which case folder
+ <li>You can either extract Libxml2 to this folder, in which case the folder
structure for C:\libxml2 should look like the following:</li>
<p><img alt="Figure: C:\libxml2 Folder Structure"
src="images/folder_structure_libxml2.jpg" /></p>
- <p>Or extract to a location of your choice and edit the configure.in
- accordingly.</p>
+ <p>Else, extract it to a location of your choice and edit the configure.in
+ file accordingly.</p>
<li>You need to have zlib1.dll in a library path. You may copy this DLL to
libxml2/lib.</li>
- <li>If you need the parser to use Guththila XML parser, ENABLE_GUTHTHILA option should be set to 1 in configure.in
+ <li>If you need the parser to use Guththila XML parser, the
+ ENABLE_GUTHTHILA option should be set to 1 in configure.in
<ul>
- <li>Example: ENABLE_GUTHTHILA = 1 </li>
+ <li>Example: ENABLE_GUTHTHILA = 1</li>
</ul>
</li>
</ul>
-
<a id="src_compile"></a>
-<h4>2.2.4. Compiling The Source</h4>
+<h4>2.2.4. Compiling the Source</h4>
-<p>The following steps will take you through the source compilation</p>
+<p>The following steps will take you through the source compilation.</p>
<ul>
<li>Extract the source distribution to a folder of your choice. (Example:
C:\axis2c)</li>
- <li>Edit configure.in file as explained in the section 2.2.3 </li>
+ <li>Edit the configure.in file as explained in the section 2.2.3</li>
<li>Open a DOS shell</li>
<li>cd C:\axis2c\build\win32</li>
<li>to access .Net tools, run
<ul>
<li>C:\axis2c\build\win32> vcvars32.bat</li>
</ul>
- <p>(Note: You may need to set the PATH environment variable to
- vcvars32.bat if Windows complaints that it cannot find this batch file. This file is located in
- <your MS Visual Studio install Directory>\VC\bin directory.)</p>
+ <p>(<strong>Note</strong>: You may have to set the PATH environment
+ variable to vcvars32.bat if MS Windows gives an error indicating that it
+ cannot find this batch file. This file is located in <your MS Visual
+ Studio install Directory>\VC\bin directory.)</p>
</li>
- <li>To build the system and create the binary files in a directory named deploy under build
- directory:
+ <li>To build the system and create the binary files in a directory named
+ deploy under the build directory,
<ul>
<li>C:\axis2c\build\win32>nmake install</li>
</ul>
@@ -394,28 +402,28 @@
</ul>
<a id="src_run"></a>
-<h4>2.2.5. Running The Binaries</h4>
+<h4>2.2.5. Running the Binaries</h4>
<ul>
- <li>You need to set couple of environment variables before you can run the
- server and samples.
+ <li>You need to set a couple of environment variables before you can run
+ the server and samples.
<ul>
<li>Set the variable AXIS2C_HOME to the deploy folder
(C:\axis2c\build\deploy)</li>
- <li>Add the path to lib directory to PATH variable
- (%AXIS2C_HOME%\lib)</li>
+ <li>Add the path to the lib directory to the PATH variable
+ (%AXIS2C_HOME%\lib)</li>
<li>Copy libxml2.dll, iconv.dll and zlib1.dll to Axis2/C lib folder
(%AXIS2C_HOME%\lib)</li>
</ul>
</li>
<li>Now run the server - C:\axis2c\build\deploy\bin>
axis2_http_server.exe</li>
- <li>If server is running successfully you should see the message "Started
- Simple Axis2 HTTP Server..."</li>
- <li>The log is by default created under %AXIS2C_HOME%\logs folder with the
- name axis2.log.</li>
- <li>(Note: you may provide command line options to change the default
- behavior. Use the command "axis2_http_server.exe -h" to learn about the
- usage)</li>
+ <li>If the server is running successfully, you will see the message
+ "Started Simple Axis2 HTTP Server..."</li>
+ <li>By default, the log is created under the %AXIS2C_HOME%\logs folder with
+ the name axis2.log.</li>
+ <li>(<strong>Note</strong>: You can provide command line options to change
+ the default behavior. Use the command "axis2_http_server.exe -h" to learn
+ about the usage)</li>
<li>Now you can run any sample client deployed under
%AXIS2C_HOME%\bin\samples\
<ul>
Modified: webservices/axis2/scratch/c/neethi/axis2c/xdocs/docs/om_tutorial.html
URL: http://svn.apache.org/viewvc/webservices/axis2/scratch/c/neethi/axis2c/xdocs/docs/om_tutorial.html?view=diff&rev=532305&r1=532304&r2=532305
==============================================================================
--- webservices/axis2/scratch/c/neethi/axis2c/xdocs/docs/om_tutorial.html (original)
+++ webservices/axis2/scratch/c/neethi/axis2c/xdocs/docs/om_tutorial.html Wed Apr 25 03:39:55 2007
@@ -3,10 +3,9 @@
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+ <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
<title>Apache Axis2/C AXOM Tutorial</title>
- <meta name="generator" content="Bluefish 1.0.5"/>
</head>
<body>
@@ -16,13 +15,13 @@
<ul>
<li><a href="#Introduction">Introduction</a>
<ul>
- <li><a href="#What_is_OM">What is AXIOM</a></li>
- <li><a href="#For_Whom_is_This_Tutorial">For Whom is This
- Tutorial</a></li>
- <li><a href="#What_is_Pull_Parsing">What is Pull Parsing</a></li>
+ <li><a href="#What_is_OM">What is AXIOM?</a></li>
+ <li><a href="#For_Whom_is_This_Tutorial">For whom is this
+ tutorial?</a></li>
+ <li><a href="#What_is_Pull_Parsing">What is Pull Parsing?</a></li>
<li><a href="#Features_of_OM">Features of AXIOM</a></li>
- <li><a href="#Where_Does_SOAP_Come_into_Play">Where does SOAP come
- into play?</a></li>
+ <li><a href="#Where_Does_SOAP_Come_into_Play">Where does SOAP come into
+ play?</a></li>
</ul>
</li>
<li><a href="#Working_with_OM">Working with AXIOM</a>
@@ -33,8 +32,10 @@
Nodes</a></li>
<li><a href="#Traversing">Traversing</a></li>
<li><a href="#Serialization">Serialization</a></li>
- <li><a href="#Reader_and_Writer">Using axiom_xml_reader and axiom_xml_writer</a></li>
- <li><a href="#Mem_Leaks">How to avoid memory leaks and double frees when using AXIOM</a></li>
+ <li><a href="#Reader_and_Writer">Using axiom_xml_reader and
+ axiom_xml_writer</a></li>
+ <li><a href="#Mem_Leaks">How to avoid memory leaks and double frees
+ when using AXIOM</a></li>
<li><a href="#Complete_Sample">Complete Sample</a></li>
</ul>
</li>
@@ -42,79 +43,78 @@
<a id="Introduction"></a>
<h2>Introduction</h2>
-<a id="What_is_OM"></a>
<h3>What is AXIOM?</h3>
-<p>AXIOM stands for AXis Object Model and refers to
-the XML infoset model that is developed for Axis2. XML infoset refers to the
-information included inside the XML. For programmatical manipulation it is
-convenient to have a representation of this XML infoset in a language
-specific manner. DOM and JDOM are two such XML models. AXIOM is conceptually
-similar to such an XML model by its external behavior but deep down it is
-very much different.</p>
+<p>AXIOM stands for AXis Object Model and refers to the XML infoset model
+that is developed for Apache Axis2. XML infoset refers to the information
+included inside the XML. For programmatical manipulation, it is convenient to
+have a representation of this XML infoset in a language specific manner. DOM
+and JDOM are two such XML models. AXIOM is conceptually similar to such an
+XML model in its external behavior but deep down it is very different.</p>
<p>The objective of this tutorial is to introduce the basics of AXIOM/C and
-explain best practices while using AXIOM.</p>
+explain the best practices while using AXIOM.</p>
-<p>AXIOM/C is a C equivalant of AXIOM/Java. We have done our best to get almost
-the same kind of API in C.</p>
+<p>AXIOM/C is a C equivalant of AXIOM/Java. We have done our best to get
+almost the same kind of API in C.</p>
<a id="For_Whom_is_This_Tutorial"></a>
-<h3>For whom is this Tutorial?</h3>
+<h3>For whom is this tutorial?</h3>
<p>This tutorial can be used by anybody who is interested and wants to go
deeper in to AXIOM/C. Knowledge in similar object models such as DOM will be
-quite helpful in understanding AXIOM but such knowledge is not assumed. Several
-links are listed in the links section that will help understand the
-basics of XML.</p>
+helpful in understanding AXIOM, but such knowledge has not been assumed.
+Several links are listed in the links section that will help you understand
+the basics of XML.</p>
<a id="What_is_Pull_Parsing"></a>
<h3>What is Pull Parsing ?</h3>
Pull parsing is a new trend in XML processing. The previously popular XML
processing frameworks such as DOM were "push-based", which means that the
control of parsing was with the parser itself. This approach is fine and easy
-to use but it is not efficient in handling large XML documents since a
+to use, but it is not efficient in handling large XML documents since a
complete memory model will be generated in the memory. Pull parsing inverts
-the control and hence the parser only proceeds at the user's command. The user
-can decide to store or discard events generated from the parser. AXIOM is based
-on pull parsing. To learn more about XML pull parsing see the <a
+the control and hence the parser only proceeds at the user's command. The
+user can decide to store or discard events generated from the parser. AXIOM
+is based on pull parsing. To learn more about XML pull parsing, see the <a
href="http://www.bearcave.com/software/java/xml/xmlpull.html">XML pull
-parsing introduction</a>.
+parsing introduction</a>. <a id="Features_of_OM"></a>
-<a id="Features_of_OM"></a>
<h3>Features of AXIOM</h3>
<p>AXIOM is a lightweight, differed built XML infoset representation based on
-StAX API derived form (<a
+StAX API derived from <a
href="http://www.jcp.org/aboutJava/communityprocess/first/jsr173/">JSR
-173</a>), which is the standard streaming pull parser API. AXIOM can be
-manipulated as flexibly as any other object model (such as <a
-href="http://www.jdom.org/">JDOM</a>), but underneath the objects will be
+173</a>, which is the standard streaming pull parser API. AXIOM can be
+manipulated as flexibly as any other object model such as <a
+href="http://www.jdom.org/">JDOM</a>, but underneath, the objects will be
created only when they are absolutely required. This leads to much less
-memory intensive programming.</p>
+memory-intensive programming.</p>
-<p>Following is a short feature overview of AXIOM.</p>
+<p>The following is a short feature overview of AXIOM.</p>
<ul>
<li>Lightweight: AXIOM is specifically targeted to be lightweight. This is
- achieved by reducing the depth of the hierarchy, the number of methods
+ achieved by reducing the depth of the hierarchy, the number of methods,
and the attributes enclosed in the objects. This makes the objects less
memory intensive.</li>
- <li>Differed building: By far this is the most important feature of AXIOM. The
- objects are not made unless a need arises for them. This passes the
- control of building to the object model itself rather than an external
+ <li>Differed building: By far, this is the most important feature of AXIOM.
+ The objects are not made unless a need arises for them. This passes the
+ control of building to the object model itself, rather than an external
builder.</li>
- <li>Pull based: For a differed building mechanism a pull based parser is
- required. AXIOM is based on StAX, the standard pull parser API.
+ <li>Pull based: For a differed building mechanism, a pull-based parser is
+ required. AXIOM is based on StAX, which is the standard pull parser API.
<p>Since different XML parsers offer different kinds of pull parser APIs,
we define an API derived from StAX. That API is defined in
- <code>axiom_xml_reader.h</code>. Similarly we define an XML writer API in
- <code>axiom_xml_writer.h</code>. These two APIs work as an abstarction
+ <code>axiom_xml_reader.h</code>. Similarly, we define an XML writer API
+ in <code>axiom_xml_writer.h</code>. These two APIs work as an abstarction
layer between any XML parser and AXIOM. So any parser that is going to be
used for AXIOM should implement the <code>axiom_xml_reader</code> API and
- <code>axiom_xml_writer</code> API using a wrapper layer.</p>
+ the <code>axiom_xml_writer</code> API using a wrapper layer.</p>
<p></p>
- <p>Currenly we use <a href="http://xmlsoft.org/downloads.html">Libxml2</a> as our default XML parser.</p>
+ <p>Currenly we use <a
+ href="http://xmlsoft.org/downloads.html">Libxml2</a> as our default XML
+ parser.</p>
<p></p>
</li>
</ul>
@@ -122,20 +122,19 @@
<p class="img"><img alt="" src="images/archi006.jpg" class="img" width="490"
height="282" /></p>
-<p>AXIOM Builder wraps the raw XML character stream through the
+<p>The AXIOM Builder wraps the raw XML character stream through the
<code>axiom_xml_reader</code> API. Hence the complexities of the pull event
-stream are hidden form the user.</p>
-
+stream are hidden from the user.</p>
<a id="Where_Does_SOAP_Come_into_Play"></a>
+
<h3>Where does SOAP come into play?</h3>
-<p>In a nutshell SOAP is an information exchange protocol based on XML. SOAP
-has a defined set of XML elements that should be used in messages. Since Axis2
-is a "SOAP Engine" and AXIOM is designed for Axis2, a SOAP specific API was
-implemented on top of AXIOM. We have defined a number of structs to represent
-SOAP constructs, which wraps general AXIOM structures. See <a
-href="http://www.w3schools.com/SOAP/soap_intro.asp">here</a> to learn more
-about SOAP.</p>
+<p>In a nutshell, SOAP is an information exchange protocol based on XML. SOAP
+has a defined set of XML elements that should be used in messages. Since
+Axis2 is a "SOAP Engine" and AXIOM is designed for Axis2, a SOAP specific API
+was implemented on top of AXIOM. We have defined a number of structs to
+represent SOAP constructs, which wrap general AXIOM structures. Learn more
+about <a href="http://www.w3schools.com/SOAP/soap_intro.asp">SOAP</a>.</p>
<!--<p>This abstraction provides</p>
<ul>
<li>differed building support</li>
@@ -147,21 +146,18 @@
<h2>Working with AXIOM</h2>
-<p></p>
-
-<a id="Env"></a>
<h3>Axis2/C Environment</h3>
<p>Before starting the discussion on AXIOM, it is necessary to get a good
-understanding of the basics of Axis2/C. Axis2/C is designed to be pluggable to
-any system written in C or C++. Therefor, Axis2/C has abstracted the
+understanding of the basics of Axis2/C. Axis2/C is designed to be pluggable
+to any system written in C or C++. Therefore, Axis2/C has abstracted the
functionalities that differ from system to system into a structure
-<code>axutil_env_t</code>, which we refer to as Axis2 environment . The
-environment holds <code>axutil_allocator_t</code>, used for memory
-allocation and deallocation, <code>axutil_error_t</code>, used for error reporting,
-<code>axuitl_log_t</code>, used for logging mechanisms and
-<code>axutil_thread_t</code> used for threading mechanisms.
-</p>
+<code>axutil_env_t</code>, which we refer to as the Axis2 environment. The
+environment holds <code>axutil_allocator_t</code>, which is used for memory
+allocation and deallocation, <code>axutil_error_t</code>, which is used for
+error reporting, <code>axuitl_log_t</code>, which is used for logging
+mechanisms, and <code>axutil_thread_t</code> which is used for threading
+mechanisms.</p>
<p>When creating the Axis2 environment, the first thing is to create the
allocator.</p>
@@ -170,13 +166,14 @@
<p><code>allocator = axutil_allocator_init(NULL);</code></p>
-<p>We pass <code>NULL</code> to the above function to use the default
-allocator functions. Then the allocator functions would use
-<code>malloc</code>, and <code>free</code> functions for memory management. If
-you have your own allocator structure, with custom malloc and free functions, you may pass it instead.</p>
+<p>We pass <code>NULL</code> to the above function in order to use the
+default allocator functions. Then the allocator functions will use the
+<code>malloc</code>, and <code>free</code> functions for memory management.
+If you have your own allocator structure, with custom malloc and free
+functions, you can pass them instead.</p>
-<p>Convenient macros <code>AXIS2_MALLOC</code> and
-<code>AXIS2_FREE</code> are defined to use allocator functions (please have a look at
+<p>Convenient macros <code>AXIS2_MALLOC</code> and <code>AXIS2_FREE</code>
+are defined to use allocator functions (please have a look at
<code>axutil_allocator.h</code> for more information).</p>
<p>In a similar fashion, you can create the error and log structures.</p>
@@ -199,19 +196,18 @@
<p><code>env = axutil_env_create_with_error_log(allocator, error,
log);</code></p>
-<p>Apart from the above abstraction, all other library functions used are
+<p>Apart from the above abstraction, all the other library functions used are
ANSI C compliant. Further, platform dependent functions are also
abstracted.</p>
-
-<p>As a rule of thumb, all "<code>create</code>" functions take a pointer to
-the environment as its first argument and all other functions take pointer to
-'this' struct as the first argument and a pointer to the environment as the
-second argument. (Please refer to our <a
+<p>As a rule of thumb, all <code>create</code> functions take a pointer to
+the environment as its first argument, and all the other functions take
+pointer to this particular struct as the first argument, and a pointer to the
+environment as the second argument. (Please refer to our <a
href="../coding_conventions.html">coding convention page</a> to learn more
-about this)</p>
+about this.)</p>
-<p>Eg.</p>
+<p>Example,</p>
<p><code>axiom_node_t *node = NULL;</code></p>
@@ -223,31 +219,30 @@
<p>Note that we are passing the node (pointer to <code>axiom_node_t</code> )
as the first argument and the pointer to the environment as the second.</p>
-
-
<a id="Creation"></a>
<h3>Building AXIOM</h3>
-<p>This section explains how AXIOM can be built either from an
-existing document or programmatically. AXIOM provides a notion of a builder to
-create objects. Since AXIOM is tightly bound to StAX, a StAX compliant reader
-should be created first with the desired input stream.</p>
-
-<p>In our AXIOM implementation we define a struct <code>axiom_node_t</code>
-which acts as the container of the other structs. <code>axiom_node_t</code> maintains the links
-that forms the linked list used to hold the AXIOM structure.</p>
+<p>This section explains how AXIOM can be built either from an existing
+document or programmatically. AXIOM provides a notion of a builder to create
+objects. Since AXIOM is tightly bound to StAX, a StAX compliant reader should
+be created first with the desired input stream.</p>
+
+<p>In our AXIOM implementation, we define a struct <code>axiom_node_t</code>
+which acts as the container of the other structs. <code>axiom_node_t</code>
+maintains the links that form the linked list used to hold the AXIOM
+structure.</p>
<p>To traverse this structure, the functions defined in
<code>axiom_node.h</code> must be used. To access XML information, the 'data
element' struct stored in <code>axiom_node_t</code> must be obtained using
the <code>axiom_node_get_data_element</code> function. The type of the struct
-stored in the <code>axiom_node_t</code> struct can be obtained by
+stored in the <code>axiom_node_t</code> struct can be obtained by the
<code>axiom_node_get_node_type</code> function. When we create
-<code>axiom_element_t</code>, <code>axiom_text_t</code> etc., it is
-required to parse a double pointer to the node struct as the last parameter
-of the <code>create</code> function so that the corresponding node struct can
-be referenced using that pointer.</p>
+<code>axiom_element_t</code>, <code>axiom_text_t</code> etc., it is required
+to parse a double pointer to the node struct as the last parameter of the
+<code>create</code> function, so that the corresponding node struct can be
+referenced using that pointer.</p>
<p>Example</p>
@@ -260,34 +255,31 @@
<p></p>
-<p>Now if we call <code>axiom_node_get_node_type</code> function on
-<code>my_node</code> pointer, it will return
-<code>AXIOM_ELEMENT</code>.</p>
+<p>Now if we call the <code>axiom_node_get_node_type</code> function on the
+<code>my_node</code> pointer, it will return <code>AXIOM_ELEMENT</code>.</p>
<p><b>Code Listing 1</b></p>
-
-<pre>axiom_xml_reader_t *xml_reader = NULL;<br />
-axiom_stax_builder_t *om_builder = NULL;<br />
-axiom_soap_builder_t *soap_builder = NULL;<br />
-axiom_soap_envelope_t *soap_envelope = NULL;<br />
-<i>/** create the parser */</i><br />
-xml_reader = axiom_xml_reader_create_for_file(env, "test_soap.xml", NULL);<br />
-<i>/** create the AXIOM builder */</i><br />
-om_builder = axiom_stax_builder_create(env, xml_reader);<br />
-<i>/** create SOAP builder */</i><br />
-soap_builder = axiom_soap_builder_create(env, om_builder , AXIOM_SOAP11_SOAP_ENVELOPE_NAMESPACE_URI);<br />
-<i>/** get soap envelope */</i><br />
-soap_envelope = axiom_soap_builder_get_soap_envelope(soap_builder, env);<br /></pre>
+<pre>axiom_xml_reader_t *xml_reader = NULL;<br />
+axiom_stax_builder_t *om_builder = NULL;<br />
+axiom_soap_builder_t *soap_builder = NULL;<br />
+axiom_soap_envelope_t *soap_envelope = NULL;<br />
+<i>/** create the parser */</i><br />
+xml_reader = axiom_xml_reader_create_for_file(env, "test_soap.xml", NULL);<br />
+<i>/** create the AXIOM builder */</i><br />
+om_builder = axiom_stax_builder_create(env, xml_reader);<br />
+<i>/** create SOAP builder */</i><br />
+soap_builder = axiom_soap_builder_create(env, om_builder , AXIOM_SOAP11_SOAP_ENVELOPE_NAMESPACE_URI);<br />
+<i>/** get soap envelope */</i><br />
+soap_envelope = axiom_soap_builder_get_soap_envelope(soap_builder, env);<br /></pre>
<p>As the example shows, creating an AXIOM from <code>xml_reader</code> is
-pretty straight forward. Elements and nodes can be created
-programmatically to modify the structure as well. Currently AXIOM has two
-builders, namely the <code>axiom_stax_builder_t</code> and the
-<code>axiom_soap_builder_t</code>. These builders provide the necessary
-information to the XML infoset model to build AXIOM tree.</p>
+pretty straight forward. Elements and nodes can be created programmatically
+to modify the structure as well. Currently AXIOM has two builders, namely the
+<code>axiom_stax_builder_t</code> and the <code>axiom_soap_builder_t</code>.
+These builders provide the necessary information to the XML infoset model to
+build the AXIOM tree.</p>
<p><b>Code Listing 2</b></p>
-
<pre class="code">axiom_namespace_t *ns1 = NULL;
axiom_namespace_t *ns2 = NULL;
@@ -306,14 +298,13 @@
<p>Several differences exist between a programmatically created
<code>axiom_node_t</code> and a conventionally built
<code>axiom_node_t</code>. The most important difference is that the latter
-will have a pointer to its builder, where as the former does not have a builder.
-</p>
+will have a pointer to its builder, where as the former does not have a
+builder.</p>
<p>The SOAP struct hierarchy is made in the most natural way for a
-programmer. It acts as a wrapper layer on top of AXIOM implementation. The SOAP
-structs wraps the corresponding <code>axiom_node_t</code> structs to store
-XML information.</p>
-
+programmer. It acts as a wrapper layer on top of the AXIOM implementation.
+The SOAP structs wrap the corresponding <code>axiom_node_t</code> structs to
+store XML information.</p>
<a id="Addition_and_Detaching_of_Nodes"></a>
<h3>Adding and Detaching Nodes</h3>
@@ -334,7 +325,7 @@
axiom_node_detach(axiom_node_t *om_node,
const axutil_env_t *env);</pre>
-<p>The detach operation resets the links and removes a node from AXIOM
+<p>The detach operation resets the links and removes a node from the AXIOM
tree.</p>
<p>This code segment shows how child addition can be done.</p>
@@ -349,12 +340,12 @@
bar_ele = axiom_element_create(env, NULL, "BAR", NULL. &bar_node);
axiom_node_add_child(foo_node, env, bar_node);</pre>
-<p>Alternatively, we can pass the <code>foo_node</code> as the parent node at the time
-of creating to <code>bar_ele</code> as follows.</p>
+<p>Alternatively, we can pass the <code>foo_node</code> as the parent node at
+the time of creating the <code>bar_ele</code> as follows.</p>
<pre> bar_ele = axiom_element_create(env, foo_node, "BAR", NULL, &bar_node);</pre>
-<p>The following are the important methods available in
-<code>axiom_element</code> to can be used to deal with namespaces.</p>
+<p>The following shows important methods available in
+<code>axiom_element</code> to be used to deal with namespaces.</p>
<p><b>Code Listing 5</b></p>
<pre class="code">axiom_namespace_t *
@@ -382,35 +373,34 @@
axiom_namespace_t *ns,
axiom_node_t *element_node);</pre>
-<p>An <code>axiom_element</code> has a namespace list, the declared namespaces, and a pointer to
-its own namespace if one exists.</p>
+<p>An <code>axiom_element</code> has a namespace list, the declared
+namespaces, and a pointer to its own namespace if one exists.</p>
-<p>The <code>axiom_element_declare_namespace</code> function is straight forward. It adds a
-namespace to declared namespace list. Note that a namespace
-that is already declared will not be declared again.</p>
-
-<p><code>axiom_element_find_namespace</code> is a very handy method to locate a namespace
-in the AXIOM tree. It searches for a matching namespace in its own
-declared namespace list and jumps to the parent if it's not found. The search
-progresses up the tree until a matching namespace is found or the root has
-been reached.</p>
-
-<p><code>axiom_element_find_declared_namespace</code> can be used to search for a namespace
-in the current element's declared namespace list.</p>
-
-<p><code>axiom_element_set_namespace</code> sets <code>axiom_element</code>'s own namespace. Note that
-an element's own namespace should be declared in its own namespace
-declaration list or in one of its parent elements. This method first
-searches for a matching namespace using <code>axiom_element_find_namespace</code> and if a
-matching namespace is not found, a namespace is declared to this <code>axiom_element</code>'s
-namespace declarations list before setting the own namespace reference.</p>
+<p>The <code>axiom_element_declare_namespace</code> function is straight
+forward. It adds a namespace to the declared namespace list. Note that a
+namespace that is already declared will not be declared again.</p>
+
+<p><code>axiom_element_find_namespace</code> is a very handy method to locate
+a namespace in the AXIOM tree. It searches for a matching namespace in its
+own declared namespace list and jumps to the parent if it's not found. The
+search progresses up the tree until a matching namespace is found or the root
+has been reached.</p>
+
+<p><code>axiom_element_find_declared_namespace</code> can be used to search
+for a namespace in the current element's declared namespace list.</p>
+
+<p><code>axiom_element_set_namespace</code> sets <code>axiom_element</code>'s
+own namespace. Note that an element's own namespace should be declared in its
+own namespace declaration list or in one of its parent elements. This method
+first searches for a matching namespace using
+<code>axiom_element_find_namespace</code> and if a matching namespace is not
+found, a namespace is declared to this <code>axiom_element</code>'s namespace
+declarations list before setting the own namespace reference.</p>
<p>The following sample code segment shows how the namespaces are dealt with
in AXIOM.</p>
-
<p><b>Code Listing 6</b></p>
-
<pre class="code">axiom_namespace_t *ns1 = NULL;
axiom_namespace_t *ns2 = NULL;
axiom_namespace_t *ns3 = NULL;
@@ -433,7 +423,7 @@
<p></p>
-<p>Serilization of the root element produces the following XML:</p>
+<p>Serialization of the root element produces the following XML:</p>
<pre class="xml"><x:root xmlns:x="bar">
<y:foo xmlns:y="bar1">blah</y:foo>
</x:root></pre>
@@ -441,7 +431,7 @@
<p>If we want to produce</p>
<pre class="xml"><x:foo xmlns:x="bar" xmlns:y="bar1">Test</x:foo></pre>
-<p>we can use set_namespace and declare namespace functions as follows</p>
+<p>we can use set_namespace and declare namespace functions as follows.</p>
<pre class="code">axiom_node_t *foo_node = NULL;
axiom_element_t *foo_ele = NULL;
axiom_namespace_t *ns1 = NULL;
@@ -455,14 +445,14 @@
axiom_element_set_namespace(foo_ele, env, ns1, foo_node);
axiom_element_declare_namespace(foo_ele, env, ns2, foo_node);
axiom_element_set_text(foo_ele, env, "Test", &foo_node);</pre>
-
<a id="Traversing"></a>
+
<h3>Traversing</h3>
-<p>Traversing the AXIOM structure can be done by obtaining an iterator struct.
-You can either call the appropriate function on an AXIOM element or create the
-iterator manually. AXIOM/C offers three iterators to traverse the AXIOM structure.
-They are:</p>
+<p>Traversing the AXIOM structure can be done by obtaining an iterator
+struct. You can either call the appropriate function on an AXIOM element or
+create the iterator manually. AXIOM/C offers three iterators to traverse the
+AXIOM structure. They are:</p>
<ul>
<li>axiom_children_iterator_t</li>
<li>axiom_child_element_iterator_t</li>
@@ -495,7 +485,7 @@
}</pre>
<p>Apart from this, every <code>axiom_node_t</code> struct has links to its
-siblings. If a thorough navigation is needed the
+siblings. If a thorough navigation is needed, the
<code>axiom_node_get_next_sibling()</code> and
<code>axiom_node_get_previous_sibling()</code> functions can be used. A
restrictive set can be chosen by using
@@ -503,18 +493,20 @@
<code>axiom_element_get_first_child_with_qname()</code> method returns the
first child that matches the given <code>axutil_qname_t</code> and
<code>axiom_element_get_children_with_qname()</code> returns
-<code>axiom_children_qname_iterator_t</code> which can be used to traverse all
-the matching children. The advantage of these iterators are that they won't
-build the whole object structure at once; it builds only what is required.</p>
+<code>axiom_children_qname_iterator_t</code> which can be used to traverse
+all the matching children. The advantage of these iterators is that they
+won't build the whole object structure at once; it builds only what is
+required.</p>
<table width="100%">
<tbody>
<tr>
<td><img src="images/OM005.gif" alt="" width="35" height="57" /></td>
- <td class="special-td">All iterator implementations internally stay one
- step ahead of their apparent location to provide the correct value
- for the <code>has_next()</code> function . This hidden advancement
- can build elements that are not intended to be built at all.</td>
+ <td class="special-td">Internally, all iterator implementations stay
+ one step ahead of their apparent location to provide the correct
+ value for the <code>has_next()</code> function . This hidden
+ advancement can build elements that are not intended to be built at
+ all.</td>
<td></td>
</tr>
</tbody>
@@ -522,16 +514,16 @@
<!-- End of special section -->
<p></p>
-
<a id="Serialization"></a>
+
<h3><b>Serialization</b></h3>
-<p>AXIOM can be serialized using <code>axiom_node_serialize</code> function.The
-serialization uses <code>axiom_xml_writer.h</code> and
+<p>AXIOM can be serialized using the <code>axiom_node_serialize</code>
+function. The serialization uses <code>axiom_xml_writer.h</code> and
<code>axiom_output.h</code> APIs.</p>
-<p>Here is an example that shows how to write the output to the console (we have
-serialized the SOAP envelope created in code listing 1).</p>
+<p>Here is an example that shows how to write the output to the console (we
+have serialized the SOAP envelope created in code listing 1).</p>
<p><b>Code Listing 8</b></p>
<pre class="code">axiom_xml_writer_t *xml_writer = NULL;
@@ -567,20 +559,20 @@
printf("%s", xml_output);
AXIS2_FREE(env->allocator, xml_output);</pre>
-<p>Note that freeing the returned buffer is user's responsibility.</p>
-
+<p>Note that freeing the returned buffer is the user's responsibility.</p>
<a id="Reader_and_Writer"></a>
+
<h3><b>Using axiom_xml_reader and axiom_xml_writer</b></h3>
-<p><code>axiom_xml_reader</code> provides three create functions that can
-be used for different xml input sources.</p>
+<p><code>axiom_xml_reader</code> provides three create functions that can be
+used for different XML input sources.</p>
<ul>
- <li><code>axiom_xml_reader_create_for_file</code> function can be used to
- read from a file</li>
+ <li><code>axiom_xml_reader_create_for_file</code> can be used to read from
+ a file</li>
<li><code>axiom_xml_reader_create_for_io</code> uses a user defined
- callback function to pull xml</li>
+ callback function to pull XML</li>
<li><code>axiom_xml_reader_create_for_memory</code> can be used to read
- from an xml string that is in a character buffer</li>
+ from an XML string that is in a character buffer</li>
</ul>
<p>Similarly <code>axiom_xml_writer</code> provides two create functions.</p>
@@ -588,8 +580,8 @@
<li><code>axiom_xml_writer_create_for_file</code> can be used to write to a
file</li>
<li><code>axiom_xml_writer_create_for_memory</code> can be used to write to
- an internal memory buffer and obtain the XML string as a character buffer
- </li>
+ an internal memory buffer and obtain the XML string as a character
+ buffer</li>
</ul>
<p></p>
@@ -598,25 +590,28 @@
<code>axiom_xml_writer.h</code> for more information.</p>
<p></p>
-
<a id="Mem_Leaks"></a>
-<h3><b>How to Avoid Memory Leaks and Double Frees When Using AXIOM</b></h3>
-
-<p>You have to be extremely careful when using AXIOM, in order to avoid memory
-leaks and double free errors. The following guidelines will be extremely useful:</p>
-<p>1. <code>axiom_element</code> struct keeps a list of attributes and a list
-of namespaces, when an <code>axiom_namespace</code> pointer or an <code>axiom_attribute</code> pointer
-is added to these lists, that will be
-freed when the <code>axiom_element</code> is freed. Therefore a pointer to a namespace or
-an attribute should not be freed, once that is used with an <code>axiom_element</code>.</p>
+<h3><b>How to Avoid Memory Leaks and Double Frees When Using AXIOM</b></h3>
-<p>To avoid the inconvenience, clone functions have been implemented for both
-<code>axiom_namespace</code> and <code>axiom_attribute</code> structures.</p>
+<p>You have to be extremely careful when using AXIOM, in order to avoid
+memory leaks and double free errors. The following guidelines will be
+extremely useful:</p>
+
+<p>1. The <code>axiom_element</code> struct keeps a list of attributes and a
+list of namespaces, when an <code>axiom_namespace</code> pointer or an
+<code>axiom_attribute</code> pointer is added to these lists, which will be
+freed when the <code>axiom_element</code> is freed. Therefore a pointer to a
+namespace or an attribute should not be freed, once it is used with an
+<code>axiom_element</code>.</p>
+
+<p>To avoid any inconvenience, clone functions have been implemented for both
+the <code>axiom_namespace</code> and <code>axiom_attribute</code>
+structures.</p>
<p>2. AXIOM returns shallow references to its string values. Therefore, when
-you want deep copies of returned values, <code>axutil_strdup()</code> function should be used to avoid
-double free errors.</p>
+you want deep copies of returned values, the <code>axutil_strdup()</code>
+function should be used to avoid double free errors.</p>
<p>Example</p>
@@ -629,151 +624,158 @@
<p><code>uri = axiom_namespace_get_uri(ns, env);</code></p>
-<p><code>/* now uri points to the same place where namespace struct's uri <br/>
-pointer is pointing. Therefore following will cause a double free */</code></p>
+<p><code>/* now uri points to the same place where namespace struct's uri <br
+/>
+pointer is pointing. Therefore following will cause a double free
+*/</code></p>
<p><code>AXIS2_FREE(env->allocator, uri);</code></p>
<p><code>axiom_namespace_free(ns, env);</code></p>
-<p>3. When creating AXIOM programatically , if you are declaring a namespace with
-an <code>axiom_element</code>, it is advisable to find whether the namespace is already
-available in the elements scope using <code>axiom_element_find_namespace</code> function. If available,
-that pointer can be used instead of creating another namespace struct
-instance to minimize memory usage.</p>
+<p>3. When creating AXIOM programatically, if you are declaring a namespace
+with an <code>axiom_element</code>, it is advisable to find whether the
+namespace is already available in the elements scope using the
+<code>axiom_element_find_namespace</code> function. If available, that
+pointer can be used instead of creating another namespace struct instance to
+minimize memory usage.</p>
+
<p></p>
<a id="Complete_Sample"></a>
+
<h3><b>Complete Code for the AXIOM Based Document Building and
Serialization</b></h3>
-<p>The following code segment shows how to use the AXIOM for completely building
-a document and then serializing it into text pushing the output to the
+
+<p>The following code segment shows how to use AXIOM for building a document
+completely and then serializing it into text, pushing the output to the
console.</p>
+
<p></p>
-<p><b>Code Listing 10</b></p>
-<pre>#include <axiom.h>
-#include <axis2_util.h>
-#include <axutil_env.h>
-#include <axuitl_log_default.h>
-#include <axutil_error_default.h>
-#include <stdio.h>
+<p><b>Code Listing 10</b></p>
+<pre>#include <axiom.h>
+#include <axis2_util.h>
+#include <axutil_env.h>
+#include <axuitl_log_default.h>
+#include <axutil_error_default.h>
+#include <stdio.h>
-FILE *f = NULL;
-int read_input_callback(char *buffer, int size, void* ctx)
+FILE *f = NULL;
+int read_input_callback(char *buffer, int size, void* ctx)
{
- <b>return</b> fread(buffer, <b>sizeof</b>(char), size, f);
+ <b>return</b> fread(buffer, <b>sizeof</b>(char), size, f);
}
-int close_input_callback(void *ctx)
+int close_input_callback(void *ctx)
{
- <b>return</b> fclose(f);
+ <b>return</b> fclose(f);
}
-axutil_env_t * create_environment()
+axutil_env_t * create_environment()
{
- axutil_allocator_t *allocator = NULL;
- axutil_env_t *env = NULL;
- axuitl_log_t *log = NULL;
-
- axutil_error_t *error = NULL;
- allocator = axutil_allocator_init(NULL);
- log = axuitl_log_create(allocator, NULL, NULL);
-
- error = axutil_error_create(allocator);
- env = axutil_env_create_with_error_log(allocator, error, log);
- <b>return</b> env;
+ axutil_allocator_t *allocator = NULL;
+ axutil_env_t *env = NULL;
+ axuitl_log_t *log = NULL;
+
+ axutil_error_t *error = NULL;
+ allocator = axutil_allocator_init(NULL);
+ log = axuitl_log_create(allocator, NULL, NULL);
+
+ error = axutil_error_create(allocator);
+ env = axutil_env_create_with_error_log(allocator, error, log);
+ <b>return</b> env;
}
-build_and_serialize_om(axutil_env_t *env)
+build_and_serialize_om(axutil_env_t *env)
{
- axiom_node_t *root_node = NULL;
+ axiom_node_t *root_node = NULL;
- axiom_element_t *root_ele = NULL;
- axiom_document_t *document = NULL;
- axiom_stax_builder_t *om_builder = NULL;
-
- axiom_xml_reader_t *xml_reader = NULL;
- axiom_xml_writer_t *xml_writer = NULL;
- axiom_output_t *om_output = NULL;
-
- axis2_char_t *buffer = NULL;
-
- f = fopen("test.xml","r");
- xml_reader = axiom_xml_reader_create_for_io(env, read_input_callback,
- close_input_callback, NULL, NULL);
- <b>if</b>(!xml_reader)
- <b>return</b> -1;
-
- om_builder = axiom_stax_builder_create(env, xml_reader);
- <b>if</b>(!om_builder)
- {
- AXIOM_XML_READER_FREE(xml_reader, env);
- <b>return</b> AXIS2_FAILURE;
- }
- document = AXIOM_STAX_BUILDER_GET_DOCUMENT(om_builder, env);
- <b>if</b>(!document)
- {
- AXIOM_STAX_BUILDER_FREE(om_builder, env);
- <b>return</b> AXIS2_FAILURE;
- }
-
- root_node = AXIOM_DOCUMENT_GET_ROOT_ELEMENT(document, env);
- <b>if</b>(!root_node)
- {
- AXIOM_STAX_BUILDER_FREE(om_builder, env);
- <b>return</b> AXIS2_FAILURE;
- }
- <b>if</b>(root_node)
- {
- <b>if</b>(AXIOM_NODE_GET_NODE_TYPE(root_node, env) == AXIOM_ELEMENT)
- {
- root_ele = (axiom_element_t*)AXIOM_NODE_GET_DATA_ELEMENT (root_node, env);
- <b>if</b>(root_ele)
- {
- printf(" %s" , AXIOM_ELEMENT_GET_LOCALNAME(root_ele, env));
- }
- }
- }
- AXIOM_DOCUMENT_BUILD_ALL(document, env);
-
- xml_writer = axiom_xml_writer_create_for_memory(env, NULL, AXIS2_TRUE, 0, AXIS2_XML_PARSER_TYPE_BUFFER);
-
- om_output = axiom_output_create(env, xml_writer);
-
- AXIOM_NODE_SERIALIZE(root_node, env, om_output);
- buffer = (axis2_char_t*)AXIOM_XML_WRITER_GET_XML(xml_writer, env);
-
- printf("The output XML is ->>>>\n %s ", buffer);
-
-
- <i>/** when om_output is freed xml_writer is also freed */</i>
-
- AXIOM_OUTPUT_FREE(om_output, env);
-
- <i>/** when om_builder is freed , the builder, om_document and the entire AXIOM structure is freed */</i>
- AXIOM_STAX_BUILDER_FREE(om_builder, env);
-
- AXIS2_FREE(env->allocator, buffer);
-
- <b>return</b> AXIS2_SUCCESS;
-
+ axiom_element_t *root_ele = NULL;
+ axiom_document_t *document = NULL;
+ axiom_stax_builder_t *om_builder = NULL;
+
+ axiom_xml_reader_t *xml_reader = NULL;
+ axiom_xml_writer_t *xml_writer = NULL;
+ axiom_output_t *om_output = NULL;
+
+ axis2_char_t *buffer = NULL;
+
+ f = fopen("test.xml","r");
+ xml_reader = axiom_xml_reader_create_for_io(env, read_input_callback,
+ close_input_callback, NULL, NULL);
+ <b>if</b>(!xml_reader)
+ <b>return</b> -1;
+
+ om_builder = axiom_stax_builder_create(env, xml_reader);
+ <b>if</b>(!om_builder)
+ {
+ AXIOM_XML_READER_FREE(xml_reader, env);
+ <b>return</b> AXIS2_FAILURE;
+ }
+ document = AXIOM_STAX_BUILDER_GET_DOCUMENT(om_builder, env);
+ <b>if</b>(!document)
+ {
+ AXIOM_STAX_BUILDER_FREE(om_builder, env);
+ <b>return</b> AXIS2_FAILURE;
+ }
+
+ root_node = AXIOM_DOCUMENT_GET_ROOT_ELEMENT(document, env);
+ <b>if</b>(!root_node)
+ {
+ AXIOM_STAX_BUILDER_FREE(om_builder, env);
+ <b>return</b> AXIS2_FAILURE;
+ }
+ <b>if</b>(root_node)
+ {
+ <b>if</b>(AXIOM_NODE_GET_NODE_TYPE(root_node, env) == AXIOM_ELEMENT)
+ {
+ root_ele = (axiom_element_t*)AXIOM_NODE_GET_DATA_ELEMENT (root_node, env);
+ <b>if</b>(root_ele)
+ {
+ printf(" %s" , AXIOM_ELEMENT_GET_LOCALNAME(root_ele, env));
+ }
+ }
+ }
+ AXIOM_DOCUMENT_BUILD_ALL(document, env);
+
+ xml_writer = axiom_xml_writer_create_for_memory(env, NULL, AXIS2_TRUE, 0, AXIS2_XML_PARSER_TYPE_BUFFER);
+
+ om_output = axiom_output_create(env, xml_writer);
+
+ AXIOM_NODE_SERIALIZE(root_node, env, om_output);
+ buffer = (axis2_char_t*)AXIOM_XML_WRITER_GET_XML(xml_writer, env);
+
+ printf("The output XML is ->>>>\n %s ", buffer);
+
+
+ <i>/** when om_output is freed xml_writer is also freed */</i>
+
+ AXIOM_OUTPUT_FREE(om_output, env);
+
+ <i>/** when om_builder is freed , the builder, om_document and the entire AXIOM structure is freed */</i>
+ AXIOM_STAX_BUILDER_FREE(om_builder, env);
+
+ AXIS2_FREE(env->allocator, buffer);
+
+ <b>return</b> AXIS2_SUCCESS;
+
}
-int main()
+int main()
{
- int status = AXIS2_SUCCESS;
-
- axutil_env_t *env = NULL;
- axutil_allocator_t *allocator = NULL;
- env = create_environment();
-<br/>
- status = build_and_serialize_om(env);
-<br/>
- <b>if</b>(status == AXIS2_FAILURE)
- {
- printf(" build AXIOM failed");
- }
-
- axutil_env_free(env);
-
- <b>return</b> 0;
+ int status = AXIS2_SUCCESS;
+
+ axutil_env_t *env = NULL;
+ axutil_allocator_t *allocator = NULL;
+ env = create_environment();
+<br />
+ status = build_and_serialize_om(env);
+<br />
+ <b>if</b>(status == AXIS2_FAILURE)
+ {
+ printf(" build AXIOM failed");
+ }
+
+ axutil_env_free(env);
+
+ <b>return</b> 0;
}</pre>
</body>
</html>
Modified: webservices/axis2/scratch/c/neethi/axis2c/xdocs/navigation.xml
URL: http://svn.apache.org/viewvc/webservices/axis2/scratch/c/neethi/axis2c/xdocs/navigation.xml?view=diff&rev=532305&r1=532304&r2=532305
==============================================================================
--- webservices/axis2/scratch/c/neethi/axis2c/xdocs/navigation.xml (original)
+++ webservices/axis2/scratch/c/neethi/axis2c/xdocs/navigation.xml Wed Apr 25 03:39:55 2007
@@ -6,20 +6,23 @@
<item name="Home" href="index.html"/>
<item name="Download Axis2/C" href="download.cgi">
<item name="Releases" href="download.cgi"/>
- <item name="View Source Code Online"
- href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/"/>
- <item name="Checkout Source Code" href="svn.html"/>
</item>
<item name="Documentation" href="docs/index.html">
<item name="Installation Guide" href="docs/installationguide.html"/>
<item name="Axis2/C manual" href="docs/axis2c_manual.html"/>
</item>
- <item name="Get Involved" href="mail-lists.html">
- <item name="Mailing Lists" href="mail-lists.html"/>
+ <item name="Get Involved" href="list.html">
+ <item name="Mailing Lists" href="list.html"/>
+ <item name="Checkout Source Code" href="svn.html"/>
+ </item>
+ <item name="Developer Guideline">
+ <item name="Coding Convension" href="coding_conventions.html"/>
+ <item name="Versionning" href="version.html"/>
</item>
<item name="Project Information" href="team-list.html">
<item name="Project Team" href="team-list.html"/>
- <item name="Issue Tracking" href="issue-tracking.html"/>
+ <item name="Source Code"
+ href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/"/>
</item>
</menu>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org