You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by sa...@apache.org on 2007/04/30 07:43:24 UTC
svn commit: r533595 [4/6] - in /webservices/axis2/site/c: ./ docs/
docs/hello/client/ docs/mod_log/
Added: webservices/axis2/site/c/docs/mod_log/mod_log.c.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/c/docs/mod_log/mod_log.c.html?view=auto&rev=533595
==============================================================================
--- webservices/axis2/site/c/docs/mod_log/mod_log.c.html (added)
+++ webservices/axis2/site/c/docs/mod_log/mod_log.c.html Sun Apr 29 22:43:23 2007
@@ -0,0 +1,148 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - modules/mod_log/mod_log.c</title><style type="text/css" media="all">
+ @import url("../../style/maven-base.css");
+
+ @import url("../../style/maven-classic.css");</style><link rel="stylesheet" href="../../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2/C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 30 April 2007
+ | Doc for 1.0.0</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../../index.html">Home</a></li><li class="expanded"><a href="../../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../../download.cgi">Releases</a></li></ul></li><li class="expanded"><a href="../../docs/index.html">Documentation</a><ul><li class="none"><a href="../../docs/installationguide.html">Installation Guide</a></li><li class="none"><a href="../../docs/axis2c_manual.html">Axis2/C manual</a></li></ul></li><li class="expanded"><a href="../../list.html">Get Involved</a><ul><li class="none"><a href="../../list.html">Mailing Lists</a></li><li class="none"><a href="../../svn.html">Checkout Source Code</a></li></ul></li><li class="expanded"><a href="../../">Developer Guideline</a><ul><li class="none"><a href="../../coding_conventions.html">Coding Con
vension</a></li><li class="none"><a href="../../version.html">Versionning</a></li></ul></li><li class="expanded"><a href="../../team-list.html">Project Information</a><ul><li class="none"><a href="../../team-list.html">Project Team</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><font face="Monospace">
+<font color="#808080"><i>/*<br></br>
+ * Licensed to the Apache Software Foundation (ASF) under one or more<br></br>
+ * contributor license agreements. See the NOTICE file distributed with<br></br>
+ * this work for additional information regarding copyright ownership.<br></br>
+ * The ASF licenses this file to You under the Apache License, Version 2.0<br></br>
+ * (the "License"); you may not use this file except in compliance with<br></br>
+ * the License. You may obtain a copy of the License at<br></br>
+ *<br></br>
+ * http://www.apache.org/licenses/LICENSE-2.0<br></br>
+ *<br></br>
+ * Unless required by applicable law or agreed to in writing, software<br></br>
+ * distributed under the License is distributed on an "AS IS" BASIS,<br></br>
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.<br></br>
+ * See the License for the specific language governing permissions and<br></br>
+ * limitations under the License.<br></br>
+ */</i></font><br></br>
+<font color="#008000">#include <axis2_module.h><br></br></font>
+<font color="#008000">#include <axis2_conf_ctx.h><br></br></font>
+<br></br>
+<font color="#008000">#include "mod_log.h"<br></br></font>
+<br></br>
+<font color="#000000">axis2_status_t</font> <font color="#000000">AXIS2_CALL</font><br></br>
+<font color="#000000">axis2_mod_log_shutdown</font>(<font color="#000000">axis2_module_t</font> *<font color="#000000">module</font>,<br></br>
+ <font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>);<br></br>
+<br></br>
+<font color="#000000">axis2_status_t</font> <font color="#000000">AXIS2_CALL</font><br></br>
+<font color="#000000">axis2_mod_log_init</font>(<br></br>
+ <font color="#000000">axis2_module_t</font> *<font color="#000000">module</font>,<br></br>
+ <font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>,<br></br>
+ <font color="#000000">axis2_conf_ctx_t</font> *<font color="#000000">conf_ctx</font>,<br></br>
+ <font color="#000000">axis2_module_desc_t</font> *<font color="#000000">module_desc</font>);<br></br>
+<br></br>
+<font color="#000000">axis2_status_t</font> <font color="#000000">AXIS2_CALL</font><br></br>
+<font color="#000000">axis2_mod_log_fill_handler_create_func_map</font>(<font color="#000000">axis2_module_t</font> *<font color="#000000">module</font>,<br></br>
+ <font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>);<br></br>
+<br></br>
+<font color="#808080"><i>/**<br></br>
+ * Module operations struct variable with functions assigned to members<br></br>
+ */</i></font><br></br>
+<font color="#800000">static</font> <font color="#800000">const</font> <font color="#000000">axis2_module_ops_t</font> <font color="#000000">log_module_ops_var</font> = {<br></br>
+ <font color="#000000">axis2_mod_log_init</font>,<br></br>
+ <font color="#000000">axis2_mod_log_shutdown</font>,<br></br>
+ <font color="#000000">axis2_mod_log_fill_handler_create_func_map</font><br></br>
+};<br></br>
+<br></br>
+<font color="#000000">axis2_module_t</font> *<br></br>
+<font color="#000000">axis2_mod_log_create</font>(<font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>)<br></br>
+{<br></br>
+ <font color="#000000">axis2_module_t</font> *<font color="#000000">module</font> = <font color="#000000">NULL</font>;<br></br>
+ <font color="#000000">module</font> = <font color="#000000">AXIS2_MALLOC</font>(<font color="#000000">env</font>-><font color="#000000">allocator</font>, <br></br>
+ <font color="#000000"><b>sizeof</b></font>(<font color="#000000">axis2_module_t</font>));<br></br>
+<br></br>
+ <font color="#808080"><i>/* initialize operations */</i></font><br></br>
+ <font color="#000000">module</font>-><font color="#000000">ops</font> = &<font color="#000000">log_module_ops_var</font>;<br></br>
+<br></br>
+ <font color="#000000"><b>return</b></font> <font color="#000000">module</font>;<br></br>
+}<br></br>
+<br></br>
+<font color="#000000">axis2_status_t</font> <font color="#000000">AXIS2_CALL</font><br></br>
+<font color="#000000">axis2_mod_log_init</font>(<br></br>
+ <font color="#000000">axis2_module_t</font> *<font color="#000000">module</font>,<br></br>
+ <font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>,<br></br>
+ <font color="#000000">axis2_conf_ctx_t</font> *<font color="#000000">conf_ctx</font>,<br></br>
+ <font color="#000000">axis2_module_desc_t</font> *<font color="#000000">module_desc</font>)<br></br>
+{<br></br>
+ <font color="#808080"><i>/* Any initialization stuff related to this module can be here */</i></font><br></br>
+ <font color="#000000"><b>return</b></font> <font color="#000000">AXIS2_SUCCESS</font>;<br></br>
+}<br></br>
+<br></br>
+<font color="#000000">axis2_status_t</font> <font color="#000000">AXIS2_CALL</font><br></br>
+<font color="#000000">axis2_mod_log_shutdown</font>(<font color="#000000">axis2_module_t</font> *<font color="#000000">module</font>,<br></br>
+ <font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>)<br></br>
+{<br></br>
+ <font color="#000000"><b>if</b></font>(<font color="#000000">module</font>-><font color="#000000">handler_create_func_map</font>)<br></br>
+ {<br></br>
+ <font color="#000000">axutil_hash_free</font>(<font color="#000000">module</font>-><font color="#000000">handler_create_func_map</font>, <font color="#000000">env</font>);<br></br>
+ }<br></br>
+ <br></br>
+ <font color="#000000"><b>if</b></font>(<font color="#000000">module</font>)<br></br>
+ {<br></br>
+ <font color="#000000">AXIS2_FREE</font>(<font color="#000000">env</font>-><font color="#000000">allocator</font>, <font color="#000000">module</font>);<br></br>
+ }<br></br>
+ <font color="#000000"><b>return</b></font> <font color="#000000">AXIS2_SUCCESS</font>; <br></br>
+}<br></br>
+<br></br>
+<font color="#000000">axis2_status_t</font> <font color="#000000">AXIS2_CALL</font><br></br>
+<font color="#000000">axis2_mod_log_fill_handler_create_func_map</font>(<font color="#000000">axis2_module_t</font> *<font color="#000000">module</font>,<br></br>
+ <font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>)<br></br>
+{<br></br>
+ <font color="#000000">AXIS2_ENV_CHECK</font>(<font color="#000000">env</font>, <font color="#000000">AXIS2_FAILURE</font>);<br></br>
+ <br></br>
+ <font color="#000000">module</font>-><font color="#000000">handler_create_func_map</font> = <font color="#000000">axutil_hash_make</font>(<font color="#000000">env</font>);<br></br>
+ <font color="#000000"><b>if</b></font>(!<font color="#000000">module</font>-><font color="#000000">handler_create_func_map</font>)<br></br>
+ {<br></br>
+ <font color="#000000">AXIS2_ERROR_SET</font>(<font color="#000000">env</font>-><font color="#000000">error</font>, <font color="#000000">AXIS2_ERROR_NO_MEMORY</font>, <br></br>
+ <font color="#000000">AXIS2_FAILURE</font>);<br></br>
+ <font color="#000000"><b>return</b></font> <font color="#000000">AXIS2_FAILURE</font>;<br></br>
+ }<br></br>
+<br></br>
+ <font color="#808080"><i>/* add in handler */</i></font><br></br>
+ <font color="#000000">axutil_hash_set</font>(<font color="#000000">module</font>-><font color="#000000">handler_create_func_map</font>, <font color="#FF0000">"LoggingInHandler"</font>, <br></br>
+ <font color="#000000">AXIS2_HASH_KEY_STRING</font>, <font color="#000000">axutil_log_in_handler_create</font>);<br></br>
+<br></br>
+ <font color="#808080"><i>/* add out handler */</i></font><br></br>
+ <font color="#000000">axutil_hash_set</font>(<font color="#000000">module</font>-><font color="#000000">handler_create_func_map</font>, <font color="#FF0000">"LoggingOutHandler"</font>, <br></br>
+ <font color="#000000">AXIS2_HASH_KEY_STRING</font>, <font color="#000000">axutil_log_out_handler_create</font>);<br></br>
+ <br></br>
+ <font color="#000000"><b>return</b></font> <font color="#000000">AXIS2_SUCCESS</font>;<br></br>
+}<br></br>
+<br></br>
+<font color="#808080"><i>/**<br></br>
+ * Following functions are expected to be there in the module lib <br></br>
+ * that helps to create and remove module instances <br></br>
+ */</i></font><br></br>
+<br></br>
+<font color="#000000">AXIS2_EXPORT</font> <font color="#800000">int</font> <br></br>
+<font color="#000000">axis2_get_instance</font>(<font color="#000000">axis2_module_t</font> **<font color="#000000">inst</font>,<br></br>
+ <font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>)<br></br>
+{<br></br>
+ *<font color="#000000">inst</font> = <font color="#000000">axis2_mod_log_create</font>(<font color="#000000">env</font>);<br></br>
+ <font color="#000000"><b>if</b></font>(!(*<font color="#000000">inst</font>))<br></br>
+ {<br></br>
+ <font color="#000000"><b>return</b></font> <font color="#000000">AXIS2_FAILURE</font>;<br></br>
+ }<br></br>
+<br></br>
+ <font color="#000000"><b>return</b></font> <font color="#000000">AXIS2_SUCCESS</font>;<br></br>
+}<br></br>
+<br></br>
+<font color="#000000">AXIS2_EXPORT</font> <font color="#800000">int</font> <br></br>
+<font color="#000000">axis2_remove_instance</font>(<font color="#000000">axis2_module_t</font> *<font color="#000000">inst</font>,<br></br>
+ <font color="#800000">const</font> <font color="#000000">axutil_env_t</font> *<font color="#000000">env</font>)<br></br>
+{<br></br>
+ <font color="#000000">axis2_status_t</font> <font color="#000000">status</font> = <font color="#000000">AXIS2_FAILURE</font>;<br></br>
+ <font color="#000000"><b>if</b></font> (<font color="#000000">inst</font>)<br></br>
+ {<br></br>
+ <font color="#000000">status</font> = <font color="#000000">axis2_mod_log_shutdown</font>(<font color="#000000">inst</font>, <font color="#000000">env</font>);<br></br>
+ }<br></br>
+ <font color="#000000"><b>return</b></font> <font color="#000000">status</font>;<br></br>
+}<br></br>
+<br></br>
+<br></br>
+ </font></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Added: webservices/axis2/site/c/docs/mod_log/module.xml
URL: http://svn.apache.org/viewvc/webservices/axis2/site/c/docs/mod_log/module.xml?view=auto&rev=533595
==============================================================================
--- webservices/axis2/site/c/docs/mod_log/module.xml (added)
+++ webservices/axis2/site/c/docs/mod_log/module.xml Sun Apr 29 22:43:23 2007
@@ -0,0 +1,19 @@
+<module name="logging" class="axis2_mod_log">
+ <inflow>
+ <handler name="LoggingInHandler" class="axis2_mod_log">
+ <order phase="PreDispatch"/>
+ </handler>
+ </inflow>
+
+ <outflow>
+ <handler name="LoggingOutHandler" class="axis2_mod_log">
+ <order phase="MessageOut"/>
+ </handler>
+ </outflow>
+
+ <Outfaultflow>
+ <handler name="LoggingOutHandler" class="axis2_mod_log">
+ <order phase="MessageOut"/>
+ </handler>
+ </Outfaultflow>
+</module>
Modified: webservices/axis2/site/c/docs/om_tutorial.html
URL: http://svn.apache.org/viewvc/webservices/axis2/site/c/docs/om_tutorial.html?view=diff&rev=533595&r1=533594&r2=533595
==============================================================================
--- webservices/axis2/site/c/docs/om_tutorial.html (original)
+++ webservices/axis2/site/c/docs/om_tutorial.html Sun Apr 29 22:43:23 2007
@@ -1,173 +1,154 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Axis2/C OM Tutorial</title><style type="text/css" media="all">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html><head><title>Axis2/C - Apache Axis2/C AXOM Tutorial</title><style type="text/css" media="all">
@import url("../style/maven-base.css");
- @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2 C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 22 December 2006
- | Doc for 0.96</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">View Source Code Online</a></li><li class="none"><a href="../svn.html">Checkout Source Code</a></li></ul></li><li class="expanded"><a href="../docs/index.html">Documentation</a><ul><li class="none"><a href="../docs/installationguide.html">Installation Guide</a></li><li class="none"><a href="../docs/developerguide.html">Developer Guide</a></li><li class="none"><a href="../docs/userguide.html">User Guide</a></li><li class="none"><a href="../docs/axis2c_manual.html">Axis2/C manual</a>
</li></ul></li><li class="expanded"><a href="../mail-lists.html">Get Involved</a><ul><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Axis2_C_OM_Tutorial"></a><h2>Axis2/C OM Tutorial</h2><div class="subsection"><a name="Content"></a><h3>Content</h3><ul>
+ @import url("../style/maven-classic.css");</style><link rel="stylesheet" href="../style/print.css" type="text/css" media="print"></link><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a href="http://www.apache.org/" id="organizationLogo"><img alt="Apache Software Foundation" src="http://www.apache.org/images/asf-logo.gif"></img></a><a href="http://ws.apache.org/axis2/c" id="projectLogo"><img alt="Apache Axis2/C" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
+ Last published: 30 April 2007
+ | Doc for 1.0.0</div><div class="xright"></div><div class="clear"><hr></hr></div></div><div id="leftColumn"><div id="navcolumn"><div id="menuAxis2_C"><h5>Axis2/C</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../download.cgi">Download Axis2/C</a><ul><li class="none"><a href="../download.cgi">Releases</a></li></ul></li><li class="expanded"><a href="../docs/index.html">Documentation</a><ul><li class="none"><a href="../docs/installationguide.html">Installation Guide</a></li><li class="none"><a href="../docs/axis2c_manual.html">Axis2/C manual</a></li></ul></li><li class="expanded"><a href="../list.html">Get Involved</a><ul><li class="none"><a href="../list.html">Mailing Lists</a></li><li class="none"><a href="../svn.html">Checkout Source Code</a></li></ul></li><li class="expanded"><a href="../">Developer Guideline</a><ul><li class="none"><a href="../coding_conventions.html">Coding Convension</a></li><li class="none">
<a href="../version.html">Versionning</a></li></ul></li><li class="expanded"><a href="../team-list.html">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/c/" class="externalLink" title="External Link">Source Code</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by Maven" src="../images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Apache_Axis2_C_AXIOM_Tutorial"></a><h2>Apache Axis2/C AXIOM Tutorial</h2><div class="subsection"><a name="Contents"></a><h3>Contents</h3><ul>
<li><a href="#Introduction">Introduction</a>
<ul>
- <li><a href="#What_is_OM">What is OM</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 OM</a></li>
- <li><a href="#Where_Does_SOAP_Come_into_Play_">Where does SOAP come
- into play?</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>
</ul>
</li>
- <li><a href="#Working_with_OM">Working with OM</a>
+ <li><a href="#Working_with_OM">Working with AXIOM</a>
<ul>
<li><a href="#Env">Axis2/C Environment</a></li>
- <li><a href="#Creation">Creation</a></li>
+ <li><a href="#Creation">Building AXIOM</a></li>
<li><a href="#Addition_and_Detaching_of_Nodes">Adding and Detaching
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 OM</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>
-</ul><p><a id="Introduction"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p><a id="What_is_OM"></a></p></div><div class="subsection"><a name="What_is_OM_"></a><h3>What is OM?</h3><p>OM stands for Object Model (a.k.a AXIOM - AXis Object Model) and refers to
-the XML infoset model that is developed for Axis 2. 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. OM is conceptually
-similar to such an XML model by its external behavior but deep down it is
-very much different.</p><p>The objective of this tutorial is to introduce the basics of OM C and
-explain best practices while using OM.</p><p>AXIOM C is a C implementation of AXIOM Java. We have tried to get almost
-the same kind of API in C.</p><p><a id="For_Whom_is_This_Tutorial"></a></p></div><div class="subsection"><a name="For_whom_is_this_Tutorial_"></a><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 OM C. Knowledge in similar object models such as DOM will be
-quite helpful in understanding OM but such knowledge is not assumed. Several
-links are listed in the appendix/ links section that will help understand the
-basics of XML.</p><p><a id="What_is_Pull_Parsing"></a></p></div><div class="subsection"><a name="What_is_Pull_Parsing__"></a><h3>What is Pull Parsing ?</h3><p>
+</ul><p><a id="Introduction"></a></p></div><div class="subsection"><a name="Introduction"></a><h3>Introduction</h3><p><a id="What_is_OM"></a></p></div><div class="subsection"><a name="What_is_AXIOM_"></a><h3>What is AXIOM?</h3><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 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><a id="For_Whom_is_This_Tutorial"></a></p></div><div class="subsection"><a name="For_whom_is_this_tutorial_"></a><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
+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><p><a id="What_is_Pull_Parsing"></a></p></div><div class="subsection"><a name="What_is_Pull_Parsing__"></a><h3>What is Pull Parsing ?</h3><p>
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 users command. The user
-can decide to store or discard events generated from the parser. OM 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" class="externalLink" title="External Link">XML pull
-parsing introduction</a>.
-
-<a id="Features_of_OM"></a></p></div><div class="subsection"><a name="Features_of_OM"></a><h3>Features of OM</h3><p>OM is a lightweight, differed built XML infoset representation based on
-StAX API derived form (<a href="http://www.jcp.org/aboutJava/communityprocess/first/jsr173/" class="externalLink" title="External Link">JSR
-173</a>), which is the standard streaming pull parser API. OM can be
-manipulated as flexibly as any other object model (such as <a href="http://www.jdom.org/" class="externalLink" title="External Link">JDOM</a>), but underneath the objects will be
+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" class="externalLink" title="External Link">XML pull
+parsing introduction</a>. <a id="Features_of_OM"></a></p></div><div class="subsection"><a name="Features_of_AXIOM"></a><h3>Features of AXIOM</h3><p>AXIOM is a lightweight, differed built XML infoset representation based on
+StAX API derived from <a href="http://www.jcp.org/aboutJava/communityprocess/first/jsr173/" class="externalLink" title="External Link">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/" class="externalLink" title="External Link">JDOM</a>, but underneath, the objects will be
created only when they are absolutely required. This leads to much less
-memory intensive programming.</p><p>Following is a short feature overview of OM.</p><ul>
- <li>Lightweight: OM is specifically targeted to be lightweight. This is
- achieved by reducing the depth of the hierarchy, the number of methods
+memory-intensive programming.</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,
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 OM. 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. OM 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
- layer between any XML parser and OM. So any parser that is going to be
- used for OM should implement the <code>axiom_xml_reader</code> API and
- <code>axiom_xml_writer</code> API using a wrapper layer.</p>
+ <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
+ the <code>axiom_xml_writer</code> API using a wrapper layer.</p>
<p></p>
- <p>Currenly we use <code>libxml2</code> as our default XML parser.</p>
+ <p>Currenly we use <a href="http://xmlsoft.org/downloads.html" class="externalLink" title="External Link">Libxml2</a> as our default XML
+ parser.</p>
<p></p>
</li>
-</ul><p>
-
-
-</p><p class="img"><img alt="" src="images/archi006.jpg" class="img" width="490" height="282"></img></p><p>
-
-</p><p>OM Builder wraps the raw xml character stream through the
+</ul><p class="img"><img alt="" src="images/archi006.jpg" class="img" width="490" height="282"></img></p><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 covered.</p><p><a id="Where_Does_SOAP_Come_into_Play?"></a></p></div><div class="subsection"><a name="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 Axis
-is a "SOAP Engine" and OM is built for Axis, a SOAP specific API was
-implemented on top of OM. We have defined a number of structs to represent
-SOAP constructs like Envelope etc., which wraps general OM structures. See <a href="http://www.w3schools.com/SOAP/soap_intro.asp" class="externalLink" title="External Link">here</a> to learn more
-about SOAP.</p><p>
-<a id="Working_with_OM"></a></p></div><div class="subsection"><a name="Working_with_OM"></a><h3>Working with OM</h3><p></p><p><a id="Env"></a></p></div><div class="subsection"><a name="Axis2_C_Environment"></a><h3>Axis2/C Environment</h3><p>Before starting the discussion on OM, 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++ as such, Axis2 has abstracted the
+stream are hidden from the user.</p><p><a id="Where_Does_SOAP_Come_into_Play"></a></p></div><div class="subsection"><a name="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 wrap general AXIOM structures. Learn more
+about <a href="http://www.w3schools.com/SOAP/soap_intro.asp" class="externalLink" title="External Link">SOAP</a>.</p><p>
+<a id="Working_with_OM"></a></p></div><div class="subsection"><a name="Working_with_AXIOM"></a><h3>Working with AXIOM</h3><p><a id="Env"></a></p></div><div class="subsection"><a name="Axis2_C_Environment"></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++. Therefore, Axis2/C has abstracted the
functionalities that differ from system to system into a structure
-<code>axis2_env_t</code>, which we refer to as axis2 environment . The
-environment holds <code>axis2_allocator_t</code> [ used for memory
-allocation/deallocation ] , <code>axis2_error_t</code> [ error reporting
-mechanism ], <code>axis2_log_t</code> [ logging mechanism ] and
-<code>axis2_thread_t</code> [ threading mechanism ].
-<code>axis2_allocator_t</code> has function pointers to <code>malloc</code>,
-<code>realloc</code> and <code>free</code> functions and all memory
-allocation and deallocation is done using the allocator. Therefore, by
-pluging in a different allocator, a user can make the entire Axis2 system to
-use different memory management functions.</p><p></p><p>When creating the axis2 environment, the first thing is to create the
-allocator.</p><p><code>axis2_allocator_t *allocator = NULL;</code></p><p><code>allocator = axis2_allocator_init(NULL);</code></p><p></p><p>We pass <code>NULL</code> to the above function to use the default
-allocator. Then the allocators function pointers point to
-<code>malloc</code>, <code>realloc</code> and <code>free</code> functions. If
-you have your own allocator structure, you may pass it instead.</p><p></p><p>Convenient macros <code>AXIS2_MALLOC</code>, <code>AXIS2_REALLOC</code> and
-<code>AXIS2_FREE</code> are defined to use allocator functions (refer to
-<code>axis2_allocator.h</code> for more information).</p><p></p><p>In a similar fashion, you can create the error and log structures.</p><p><code>axis2_log_t *log = NULL;</code></p><p><code>axis2_error_t *error = NULL;</code></p><p><code>log = axis2_log_create(allocator, NULL, NULL);</code></p><p><code>log = axis2_log_create(allocator, NULL, "mylog.log");</code></p><p></p><p>Now we can create the environment by parsing the allocator, error and log
-to <code>axis2_env_create_with_error_log()</code> function.</p><p><code>axis2_env_t *env = NULL;</code></p><p><code>env = axis2_env_create_with_error_log(allocator, error,
-log);</code></p><p></p><p>Apart from the above abstraction, all other library functions used are
+<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><p><code>axutil_allocator_t *allocator = NULL;</code></p><p><code>allocator = axutil_allocator_init(NULL);</code></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
+<code>axutil_allocator.h</code> for more information).</p><p>In a similar fashion, you can create the error and log structures.</p><p><code>axuitl_log_t *log = NULL;</code></p><p><code>axutil_error_t *error = NULL;</code></p><p><code>log = axuitl_log_create(allocator, NULL, NULL);</code></p><p><code>log = axuitl_log_create(allocator, NULL, "mylog.log");</code></p><p></p><p>Now we can create the environment by parsing the allocator, error and log
+to <code>axutil_env_create_with_error_log()</code> function.</p><p><code>axutil_env_t *env = NULL;</code></p><p><code>env = axutil_env_create_with_error_log(allocator, error,
+log);</code></p><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></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 href="../coding_conventions.html">coding convention page</a> to learn more
-about this)</p><p>Eg.</p><p><code>axiom_node_t *node = NULL;</code></p><p><code>axiom_node_t *child = NULL;</code></p><p><code>node = axiom_node_create(env);</code></p><p><code>child = AXIOM_NODE_GET_FIRST_CHILD(node, env);</code></p><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><p></p><p>All functions return a pointer to a struct or a status code [
-<code>AXIS2_SUCCESS</code> , <code>AXIS2_FAILURE</code>]. So if
-<code>NULL</code> is returned by a function it is either because there is
-nothing to return or an error has occurred.</p><p></p><p><a id="Creation"></a></p></div><div class="subsection"><a name="Creation"></a><h3>Creation</h3><p>Creation is the first and foremost action when using an Object
-representation. This part explains how OM can be built either from an
-existing document or programmatically. OM provides a notion of a builder to
-create objects. Since OM is tightly bound to StAX, a StAX compliant reader
-should be created first with the desired input stream.</p><p>In our OM implementation we define a struct '<code>axiom_node_t</code>'
-which acts as the container of the other structs and it maintains the links
-that form the Link List OM in C.</p><p>To traverse this structure, the functions defined in
-<code>axiom_node.h</code> must be used. To access xml information, the 'data
+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 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><p>Example,</p><p><code>axiom_node_t *node = NULL;</code></p><p><code>axiom_node_t *child = NULL;</code></p><p><code>node = axiom_node_create(env);</code></p><p><code>child = axiom_node_get_first_child(node, env);</code></p><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><p><a id="Creation"></a></p></div><div class="subsection"><a name="Building_AXIOM"></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 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> macro. The type of the struct
-stored in the '<code>axiom_node_t'</code> struct can be obtained by
-<code>AXIOM_NODE_GET_NODE_TYPE</code> macro. 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><p>Example</p><p><code>axiom_node_t *my_node = NULL;</code></p><p><code>axiom_element_t *my_ele = NULL;</code></p><p><code>my_ele = axiom_element_create(env, NULL, "MY_ELEMENT", NULL,
-&my_node);</code></p><p></p><p>Now if we call <code>AXIOM_NODE_GET_NODE_TYPE</code> macro on
-'<code>my_node</code>' pointer we will get the value as
-<code>AXIOM_ELEMENT</code>.</p><div>
-<p></p>
-
-<p><b>Code Listing 1</b></p>
-</div>
+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 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><p>Example</p><p><code>axiom_node_t *my_node = NULL;</code></p><p><code>axiom_element_t *my_ele = NULL;</code></p><p><code>my_ele = axiom_element_create(env, NULL, "MY_ELEMENT", NULL,
+&my_node);</code></p><p></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>
<div class="source"><pre>axiom_xml_reader_t *xml_reader = NULL;
axiom_stax_builder_t *om_builder = NULL;
axiom_soap_builder_t *soap_builder = NULL;
axiom_soap_envelope_t *soap_envelope = NULL;
-xml_reader = axiom_xml_reader_create_for_file(env, "test_soap.xml",NULL);
+xml_reader = axiom_xml_reader_create_for_file(env, "test_soap.xml", NULL);
om_builder = axiom_stax_builder_create(env, xml_reader);
soap_builder = axiom_soap_builder_create(env, om_builder , AXIOM_SOAP11_SOAP_ENVELOPE_NAMESPACE_URI);
-soap_envelope = AXIOM_SOAP_BUILDER_GET_SOAP_ENVELOPE(soap_builder, env);
-</pre></div>
- <br></br><p>As the example shows, creating an OM from <code>xml_reader</code> is
-pretty straight forward. However, elements and nodes can be created
-programmatically to modify the structure as well. Currently OM 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 itself.</p><div>
-<p></p>
+soap_envelope = axiom_soap_builder_get_soap_envelope(soap_builder, env);
-<p><b>Code Listing 2</b></p>
-</div>
+</pre></div>
+ <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 the AXIOM tree.</p><p><b>Code Listing 2</b></p>
<div class="source"><pre>axiom_namespace_t *ns1 = NULL;
axiom_namespace_t *ns2 = NULL;
@@ -184,38 +165,29 @@
ele1 = axiom_element_create(env, root_node, "foo1", ns2, &ele1_node);
</pre></div>
- <p></p><p>Several differences exist between a programmatically created
+ <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 that
-information. As stated earlier in this tutorial, since the OM is built as and
-when required, each and every <code>axiom_node_t</code> struct should have a
-reference to its builder. If this information is not available, it is due to
-the struct being created without a builder.</p><p></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 OM implementation. The SOAP
-structs wraps the corresponding <code>axiom_node_t</code> structs to store
-information in xml.</p><p>
-<a id="Addition_and_Detaching_of_Nodes"></a></p></div><div class="subsection"><a name="Adding_and_Detaching_Nodes"></a><h3>Adding and Detaching Nodes</h3><p>Addition and removal methods are defined in the <code>axiom_node.h</code>
-header. The following are the most important in adding nodes.</p><div>
-<p><b>Code Listing 3</b></p>
-</div><p>Add child operation</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 the AXIOM implementation.
+The SOAP structs wrap the corresponding <code>axiom_node_t</code> structs to
+store XML information.</p><p><a id="Addition_and_Detaching_of_Nodes"></a></p></div><div class="subsection"><a name="Adding_and_Detaching_Nodes"></a><h3>Adding and Detaching Nodes</h3><p>Addition and removal methods are defined in the <code>axiom_node.h</code>
+header file.</p><p><b>Code Listing 3</b></p><p>Add child operation</p>
<div class="source"><pre>axis2_status_t
-axiom_node_add_child( axiom_node_t *om_node,
- const axis2_env_t *env,
- axiom_node_t *child_node);
+axiom_node_add_child(axiom_node_t *om_node,
+ const axutil_env_t *env,
+ axiom_node_t *child_node);
</pre></div>
<p>Detach operation</p>
- <div class="source"><pre>axiom_node_t*
-axiom_node_detach (axiom_node_t *om_node,
- const axis2_env_t *env);
+ <div class="source"><pre>axiom_node_t *
+axiom_node_detach(axiom_node_t *om_node,
+ const axutil_env_t *env);
</pre></div>
- <p>The detach operation resets the links and removes a node from OM
-structure.</p><p></p><p>This code segment shows how the addition takes place. Note,that it is
-related to the code segment shown in the creation section.</p><div>
-<p><b>Code Listing 4</b></p>
-</div>
+ <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><p><b>Code Listing 4</b></p>
<div class="source"><pre>axiom_node_t *foo_node = NULL;
axiom_element_t *foo_ele = NULL;
axiom_node_t *bar_node = NULL;
@@ -223,78 +195,58 @@
foo_ele = axiom_element_create(env, NULL, "FOO", NULL, &foo_node);
bar_ele = axiom_element_create(env, NULL, "BAR", NULL. &bar_node);
+axiom_node_add_child(foo_node, env, bar_node);
</pre></div>
- <p></p><p>Now if we want to make 'BAR' element, a child of 'FOO' element we can use
-add child macro.</p>
- <div class="source"><pre> AXIOM_NODE_ADD_CHILD(foo_node, env, bar_node);
-
-</pre></div>
- <p></p><p>Or we can parse 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>
<div class="source"><pre> bar_ele = axiom_element_create(env, foo_node, "BAR", NULL, &bar_node);
+
</pre></div>
- <ul>
- <li><code>add_child</code> function will always add the child as the first
- child of the parent.</li>
- <li><p>A given node can be removed from the tree by calling the
- <code>detach()</code> method. A node can also be removed from the tree by
- calling the <code>remove</code> method of the returned iterator which
- will also call the <code>detach</code> method of the particular node
- internally.</p>
- </li>
- <li>Namespaces are a tricky part of any XML object model and is the same in
- OM. However the interface to the namespace have been made very simple.
- <code>axiom_namespace_t</code> is the struct that represents a namespace
- and we do not have setter functions. This makes the axiom namespace
- immutable.</li>
-</ul><p></p><p>The following are the important methods available in
-<code>axiom_element</code> to handle namespaces.</p><div>
-<p><b>Code Listing 5</b></p>
-</div>
- <div class="source"><pre>axiom_namespace_t*
+ <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>
+ <div class="source"><pre>axiom_namespace_t *
axiom_element_declare_namespace(axiom_element_t *om_ele,
- const axis2_env_t *env,
- axiom_node_t *om_node,
- axiom_namespace_t *om_ns);
+ const axutil_env_t *env,
+ axiom_node_t *om_node,
+ axiom_namespace_t *om_ns);
-axiom_namespace_t*
+axiom_namespace_t *
axiom_element_find_namespace(axiom_element_t *om_ele,
- const axis2_env_t *env,
- axiom_node_t *om_node,
- axis2_char_t *uri,
- axis2_char_t *prefix);
+ const axutil_env_t *env,
+ axiom_node_t *om_node,
+ axis2_char_t *uri,
+ axis2_char_t *prefix);
-axiom_namespace_t*
+axiom_namespace_t *
axiom_element_find_declared_namespace(axiom_element_t *om_element,
- const axis2_env_t *env,
- axis2_char_t *uri,
- axis2_char_t *prefix);
+ const axutil_env_t *env,
+ axis2_char_t *uri,
+ axis2_char_t *prefix);
axis2_status_t
axiom_element_set_namespace(axiom_element_t *om_element,
- const axis2_env_t *env,
- axiom_namespace_t *ns,
- axiom_node_t *element_node);
-
-</pre></div>
- <p></p><p>An <code>om_element</code> has a namespace list [declared namespaces] and a pointer to
-its own namespace if one exists.</p><p>The <code>declare_namespace</code> function is straight forward. It adds a
-namespace to namespace declarations section. Note that a namespace
-declaration that is already added will not be added twice.</p><p><code>find_namespace</code> is a very handy method to locate a namespace
-higher up the tree. It searches for a matching namespace in its own
-declarations section 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>find_declared_namespace</code> can be used to search for a namespace
-in the current element's namespace declarations section.</p><p><code>set_namespace</code> sets an <code>om_elements</code> own namespace. [ Note that
-an element's own namespace should be declared in its own namespace
-declarations section or in one of its parent elements. ] This method first
-searches for a matching namespace using <code>find_namespace</code> and if a
-matching namespace is not found, a namespace is declared to this om_element's
-namespace declarations section before setting the own namespace reference.</p><p>The following sample code segment shows how the namespaces are dealt with
-in OM.</p><div>
-<p><b>Code Listing 6</b></p>
-</div>
+ const axutil_env_t *env,
+ axiom_namespace_t *ns,
+ axiom_node_t *element_node);
+
+</pre></div>
+ <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 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>
<div class="source"><pre>axiom_namespace_t *ns1 = NULL;
axiom_namespace_t *ns2 = NULL;
axiom_namespace_t *ns3 = NULL;
@@ -316,11 +268,9 @@
om_text = axiom_text_create(env, ele1_node, "blah", &text_node);
</pre></div>
- <p></p><p>Serilization of the root element produces the following XML:</p>
+ <p></p><p>Serialization of the root element produces the following XML:</p>
<div class="source"><pre><x:root xmlns:x="bar">
- <y:foo xmlns:y="bar1">
- blah
- </y:foo>
+ <y:foo xmlns:y="bar1">blah</y:foo>
</x:root>
</pre></div>
@@ -328,7 +278,7 @@
<div class="source"><pre><x:foo xmlns:x="bar" xmlns:y="bar1">Test</x:foo>
</pre></div>
- <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>
<div class="source"><pre>axiom_node_t *foo_node = NULL;
axiom_element_t *foo_ele = NULL;
axiom_namespace_t *ns1 = NULL;
@@ -337,42 +287,36 @@
foo_ele = axiom_element_create(env, NULL,"foo" ,NULL, &foo_node);
ns1 = axiom_namespace_create(env, "bar", "x");
-
ns2 = axiom_namespace_create(env, "bar1","y");
-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></div>
- <p></p><p><a id="Traversing"></a></p></div><div class="subsection"><a name="Traversing"></a><h3>Traversing</h3><p>Traversing the OM structure can be done by obtaining an iterator struct.
-You can either call the appropriate function on an OM element or create the
-iterator manually. OM C offers three iterators to traverse the OM structure.
-They are:</p><ul>
+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></div>
+ <p><a id="Traversing"></a></p></div><div class="subsection"><a name="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><ul>
<li>axiom_children_iterator_t</li>
<li>axiom_child_element_iterator_t</li>
<li>axiom_children_qname_iterator_t</li>
-</ul><p></p><p>The iterator supports the 'OM way' of accessing elements and is more
+</ul><p>The iterator supports the 'AXIOM way' of accessing elements and is more
convenient than a list for sequential access. The following code sample shows
how the children can be accessed. The children can be of type
-<code>AXIOM_TEXT</code> or <code>AXIOM_ELEMENT</code>.</p><div>
-<p><b>Code Listing 7</b></p>
-</div>
+<code>AXIOM_TEXT</code> or <code>AXIOM_ELEMENT</code>.</p><p><b>Code Listing 7</b></p>
<div class="source"><pre>axiom_children_iterator_t *children_iter = NULL;
-children_iter = AXIOM_ELEMENT_GET_CHILDREN(om_ele, env, om_node);
+children_iter = axiom_element_get_children(om_ele, env, om_node);
if(NULL != children_iter )
{
- while(AXIOM_CHILDREN_ITERATOR_HAS_NEXT(children_iter, env))
+ while(axiom_children_iterator_has_next(children_iter, env))
{
axiom_node_t *node = NULL;
- node = AXIOM_CHILDREN_ITERATOR_NEXT(children_iter, env);
+ node = axiom_children_iterator_next(children_iter, env);
if(NULL != node)
{
- if(AXIOM_NODE_GET_NODE_TYPE(node, env) == AXIOM_ELEMENT)
+ if(axiom_node_get_node_type(node, env) == AXIOM_ELEMENT)
{
- /** any processing */
+ /* processing logic goes here */
}
}
@@ -380,32 +324,30 @@
}
</pre></div>
- <p></p><p>Apart from this, every <code>axiom_node_t</code> struct has links to its
-siblings. If a thorough navigation is needed the
-<code>AXIOM_NODE_GET_NEXT_SIBLING()</code> and
-<code>AXIOM_NODE_GET_PREVIOUS_SIBLING()</code> macros can be used. A
+ <p>Apart from this, every <code>axiom_node_t</code> struct has links to its
+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
-<code>AXIOM_ELEMENT_XXX_WITH_QNAME()</code> methods. The
-<code>AXIOM_ELEMENT_GET_FIRST_CHILD_WITH_QNAME()</code> method returns the
-first child that matches the given <code>axis2_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><p></p><p>
-
-<table class="bodyTable"><tbody>
- <tr class="b"><td><img src="images/OM005.gif" alt="" width="35" height="57"></img></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></td></tr>
- </tbody></table>
-
-</p><p></p><p><a id="Serialization"></a></p></div><div class="subsection"><a name="Serialization"></a><h3>Serialization</h3><p>OM can be serialized using <code>AXIOM_NODE_SERIALIZE</code> macro .The
-serialization uses <code>axiom_xml_writer.h</code> and
-<code>axiom_output.h</code> APIs.</p><p></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><div>
-<p><b>Code Listing 8</b></p>
-</div>
+<code>axiom_element_xxx_with_qname()</code> methods. The
+<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 is that they
+won't build the whole object structure at once; it builds only what is
+required.</p><table class="bodyTable"><tbody>
+ <tr class="b"><td><img src="images/OM005.gif" alt="" width="35" height="57"></img></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></table><p>
+
+</p><p></p><p><a id="Serialization"></a></p></div><div class="subsection"><a name="Serialization"></a><h3>Serialization</h3><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><b>Code Listing 8</b></p>
<div class="source"><pre>axiom_xml_writer_t *xml_writer = NULL;
axiom_output_t *om_output = NULL;
axis2_char_t *buffer = NULL;
@@ -415,71 +357,72 @@
xml_writer = axiom_xml_writer_create(env, NULL, 0, 0);
om_output = axiom_output_create(env, xml_writer);
-AXIOM_SOAP_ENVELOPE_SERIALIZE(envelope, env, om_output);
-buffer = (axis2_char_t*)AXIS2_XML_WRITER_GET_XML(xml_writer, env);
+axiom_soap_envelope_serialize(envelope, env, om_output);
+buffer = (axis2_char_t*)axis2_xml_writer_get_xml(xml_writer, env);
printf("%s ", buffer);
</pre></div>
- <p></p><p>An easy way to serialize is to use the <code>to_string</code> function in
-<code>om_element</code></p><p></p><p><b>Code Listing 9</b></p>
+ <p>An easy way to serialize is to use the <code>to_string</code> function in
+<code>om_element</code></p><p><b>Code Listing 9</b></p>
<div class="source"><pre>axis2_char_t *xml_output = NULL;
axiom_node_t *foo_node = NULL;
axiom_element_t *foo_ele = NULL;
axiom_namespace_t* ns = NULL;
-ns = axiom_namespace_create(env, "bar","x");
+ns = axiom_namespace_create(env, "bar", "x");
foo_ele = axiom_element_create(env, NULL, "foo", ns, &foo_node);
-AXIOM_ELEMENT_SET_TEXT(foo_ele, env, "EASY SERAILIZATION", foo_node);
+axiom_element_set_text(foo_ele, env, "EASY SERAILIZATION", foo_node);
-xml_output = AXIOM_ELEMENT_TO_STRING(foo_ele, env, foo_node);
+xml_output = axiom_element_to_string(foo_ele, env, foo_node);
printf("%s", xml_output);
AXIS2_FREE(env->allocator, xml_output);
</pre></div>
- <p></p><p>Note that freeing the returned buffer is user's responsibility.</p><p></p><p><a id="Reader_and_Writer"></a></p></div><div class="subsection"><a name="Using_axiom_xml_reader_and_axiom_xml_writer"></a><h3>Using axiom_xml_reader and axiom_xml_writer</h3><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>
+ <p>Note that freeing the returned buffer is the user's responsibility.</p><p><a id="Reader_and_Writer"></a></p></div><div class="subsection"><a name="Using_axiom_xml_reader_and_axiom_xml_writer"></a><h3>Using axiom_xml_reader and axiom_xml_writer</h3><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> 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>
-</ul><p></p><p>Similarly <code>axiom_xml_writer</code> provides two create functions.</p><ul>
+ from an XML string that is in a character buffer</li>
+</ul><p>Similarly <code>axiom_xml_writer</code> provides two create functions.</p><ul>
<li><code>axiom_xml_writer_create_for_file</code> can be used to write to a
- file.</li>
+ 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 to a character buffer
- as the output.</li>
+ an internal memory buffer and obtain the XML string as a character
+ buffer</li>
</ul><p></p><p>Please refer to <code>axiom_xml_reader.h</code> and
-<code>axiom_xml_writer.h</code> for more information.</p><p></p><p><a id="Mem_Leaks"></a></p></div><div class="subsection"><a name="How_to_Avoid_Memory_Leaks_and_Double_Frees_When_Using_OM"></a><h3>How to Avoid Memory Leaks and Double Frees When Using OM</h3><p>You have to be extremely careful when using OM, in order to avoid memory
-leaks and double free errors. The following guidelines will be extremely useful:</p><p>1. <code>om_element_t</code> struct keeps a list of attributes and a list
-of namespaces, when a namespace pointer is added to this list , it will be
-freed when this <code>om_element</code> is freed, Therefore same pointer to a namespace or
-an attribute should not be passed twice to a <code>create</code> , add or
-<code>set</code> function.</p><p>To avoid the inconvenience, clone functions have been implemented for both
-<code>axiom_namespace</code> and <code>axiom_attribute</code> structures.</p><p></p><p>2. OM returns shallow references to its string values. Therefore, when
-using the returned values, <code>AXIS2_STRDUP ()</code> function should be used to avoid
-double free errors, if the returned value is going to be set to another
-struct.</p><p>Example</p><p><code>axiom_namespace_t *ns = NULL;</code></p><p><code>axis2_char_t *uri = NULL;</code></p><p><code>ns = axiom_namespace_create(env, "http://ws.apache.org",
-"om");</code></p><p><code>uri = AXIOM_NAMESPACE_GET_URI(ns, env);</code></p><p><code>/** now uri points to the same place where namespace structs uri
-pointer is pointing */</code></p><p><code>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></p><p>3. When creating OM programatically , if you are declaring a namespace to
-an OM element, it is advisable to find whether the namespace is already
-available in the elements scope using <code>find_namespace</code> function. If available,
-that pointer can be used instead of creating another namespace struct
-instance to prevent memory leaks.</p><p></p><p><a id="Complete_Sample"></a></p></div><div class="subsection"><a name="Complete_Code_for_the_OM_Based_Document_Building_and_Serialization"></a><h3>Complete Code for the OM Based Document Building and Serialization</h3><p>The following code segment shows how to use the OM for completely building
-a document and then serializing it into text pushing the output to the
-console.</p><div>
-<p></p>
-<p><b>Code Listing 10</b></p>
-</div>
+<code>axiom_xml_writer.h</code> for more information.</p><p></p><p><a id="Mem_Leaks"></a></p></div><div class="subsection"><a name="How_to_Avoid_Memory_Leaks_and_Double_Frees_When_Using_AXIOM"></a><h3>How to Avoid Memory Leaks and Double Frees When Using AXIOM</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. 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, the <code>axutil_strdup()</code>
+function should be used to avoid double free errors.</p><p>Example</p><p><code>axiom_namespace_t *ns = NULL;</code></p><p><code>axis2_char_t *uri = NULL;</code></p><p><code>ns = axiom_namespace_create(env, "http://ws.apache.org",
+"AXIOM");</code></p><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></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 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><p><a id="Complete_Sample"></a></p></div><div class="subsection"><a name="Complete_Code_for_the_AXIOM_Based_Document_Building_and_Serialization"></a><h3>Complete Code for the AXIOM Based Document Building and Serialization</h3><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>
<div class="source"><pre>#include <axiom.h>
#include <axis2_util.h>
-#include <axis2_env.h>
-#include <axis2_log_default.h>
-#include <axis2_error_default.h>
+#include <axutil_env.h>
+#include <axuitl_log_default.h>
+#include <axutil_error_default.h>
#include <stdio.h>
FILE *f = NULL;
@@ -491,22 +434,22 @@
{
fclose(f);
}
-axis2_env_t * create_environment()
+axutil_env_t * create_environment()
{
- axis2_allocator_t *allocator = NULL;
- axis2_env_t *env = NULL;
- axis2_log_t *log = NULL;
-
- axis2_error_t *error = NULL;
- allocator = axis2_allocator_init(NULL);
- log = axis2_log_create(allocator, NULL, NULL);
+ 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 = axis2_error_create(allocator);
- env = axis2_env_create_with_error_log(allocator, error, log);
+ error = axutil_error_create(allocator);
+ env = axutil_env_create_with_error_log(allocator, error, log);
env;
}
-build_and_serialize_om(axis2_env_t *env)
+build_and_serialize_om(axutil_env_t *env)
{
axiom_node_t *root_node = NULL;
@@ -584,22 +527,22 @@
{
int status = AXIS2_SUCCESS;
- axis2_env_t *env = NULL;
- axis2_allocator_t *allocator = NULL;
+ axutil_env_t *env = NULL;
+ axutil_allocator_t *allocator = NULL;
env = create_environment();
status = build_and_serialize_om(env);
(status == AXIS2_FAILURE)
{
- printf(" build om failed");
+ printf(" build AXIOM failed");
}
- axis2_env_free(env);
+ axutil_env_free(env);
0;
}
</pre></div>
- </div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2006, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
+ </div></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2005-2007, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-cvs-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-cvs-help@ws.apache.org