I've attached corrections for errors found in om tutorial while i was
going through it.
please review and apply the patch.
thank you,
dumindu.
Index: om_tutorial.html
===================================================================
--- om_tutorial.html (revision 464503)
+++ om_tutorial.html (working copy)
@@ -33,88 +33,17 @@
Nodes</a></li>
<li><a href="#Traversing">Traversing</a></li>
<li><a href="#Serialization">Serialization</a></li>
- <li><a href="#Reader_and_Writer">Using axis2_xml_reader and
axis2_xml_writer</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="#Complete_Sample">Complete Sample</a></li>
</ul>
- </li>
-</ul>
-<a id="Introduction"></a>
-
-<h2>Introduction</h2>
-<a id="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>
-<a id="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>
-<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
-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";>XML pull
-parsing introduction</a>.
-
-<a id="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/";>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/";>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
- 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
- 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.
- <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>axis2_xml_reader.h</code>. Similarly we define an xml writer API in
- <code>axis2_xml_writer.h</code>. These two APIs work as an abstarction
+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 abstraction
layer between any XML parser and OM. So any parser that is going to be
- used for OM should implement the <code>axis2_xml_reader</code> API and
- <code>axis2_xml_writer</code> API using a wrapper layer.</p>
+ used for OM should implement the <code>axiom_xml_reader</code> API and
+ <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>Currently we use <code>libxml2</code> as our default XML parser.</p>
<p></p>
</li>
</ul>
@@ -126,7 +55,7 @@
<!-- End of Image -->
<p>OM Builder wraps the raw xml character stream through the
-<code>axis2_xml_reader</code> API. Hence the complexities of the pull event
+<code>axiom_xml_reader</code> API. Hence the complexities of the pull event
stream are covered.</p>
<a id="Where_Does_SOAP_Come_into_Play?"></a>
@@ -135,7 +64,7 @@
<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
+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";>here</a> to learn more
about SOAP.</p>
@@ -156,14 +85,14 @@
<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 plugble to
+understanding of the basics of Axis2/C. Axis2/C is designed to be pluggable to
any system written in C or C++ and therefore Axis2 has abstracted the
functionalities that differ from system to system in to a structure
<code>axis2_env_t</code>, which we refer to as axis2 environment . The
-environment holds <code>axis2_allocater_t</code> [ used for memory
+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 mechnism ].
+<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
@@ -181,14 +110,14 @@
<p></p>
-<p>We parse <code>NULL</code> to the above function to use the default
+<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> functons. If
+<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>Convinent macros <code>AXIS2_MALLOC</code>, <code>AXIS2_REALLOC</code> and
+<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>
@@ -216,8 +145,8 @@
<p></p>
-<p>Apart from the above abstraction , all other library functions used are
-ANSI C complient. Further, platform dependent funtions are also
+<p>Apart from the above abstraction, all other library functions used are
+ANSI C compliant. Further, platform dependent functions are also
abstracted.</p>
<p></p>
@@ -247,7 +176,7 @@
<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 occured.</p>
+nothing to return or an error has occurred.</p>
<p></p>
@@ -273,7 +202,7 @@
<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 correponding node struct can
+of the <code>create</code> function so that the corresponding node struct can
be referenced using that pointer.</p>
<p>Eg.</p>
@@ -305,7 +234,7 @@
<i>/** create the OM 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_SOAP_ENVELOPE_NAMESPACE_URI);<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>
<br />
@@ -353,7 +282,7 @@
<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 correspoding <code>axiom_node_t</code> structs to store
+structs wraps the corresponding <code>axiom_node_t</code> structs to store
information in xml.</p>
<!-- The following illustration of the actual class diagram will be helpful
in understanding this.
Need an image here -->
@@ -455,7 +384,7 @@
axis2_status_t
axiom_element_set_namespace(axiom_element_t *om_element,
const axis2_env_t *env,
- axis2_namespace_t *ns,
+ axiom_namespace_t *ns,
axiom_node_t *element_node);</pre>
<p></p>
@@ -480,8 +409,8 @@
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 anamespace is declared to this om_element's
-namespace declarations section before seting the own namespace reference.</p>
+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>
@@ -594,7 +523,7 @@
<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 travese all
+<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>
@@ -621,7 +550,7 @@
<h3><b>Serialization</b></h3>
<p>OM can be serialized using <code>AXIOM_NODE_SERIALIZE</code> macro .The
-serialization uses <code>axis2_xml_writer.h</code> and
+serialization uses <code>axiom_xml_writer.h</code> and
<code>axiom_output.h</code> APIs.</p>
<p></p>
@@ -632,13 +561,13 @@
<div>
<p><b>Code Listing 8</b></p>
</div>
-<pre class="code">axis2_xml_writer_t *xml_writer = NULL;
+<pre class="code">axiom_xml_writer_t *xml_writer = NULL;
axiom_output_t *om_output = NULL;
axis2_char_t *buffer = NULL;
..............
-xml_writer = axis2_xml_writer_create(env, NULL, 0, 0);
+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);
@@ -676,41 +605,41 @@
<p></p>
<a id="Reader_and_Writer"></a>
-<h3><b>Using axis2_xml_reader and axis2_xml_writer</b></h3>
+<h3><b>Using axiom_xml_reader and axiom_xml_writer</b></h3>
-<p><code>axis2_xml_reader</code> provides three create functions that and can
+<p><code>axiom_xml_reader</code> provides three create functions that and can
be used for different xml input sources.</p>
<ul>
- <li><code>axis2_xml_reader_create_for_file</code> functon can be used to
+ <li><code>axiom_xml_reader_create_for_file</code> function can be used to
read from a file.</li>
- <li><code>axis2_xml_reader_create_for_io</code> uses a user defined
+ <li><code>axiom_xml_reader_create_for_io</code> uses a user defined
callback function to pull xml.</li>
- <li><code>axis2_xml_reader_create_for_memory</code> can be used to read
+ <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>axis2_xml_writer</code> provides two create functions.</p>
+<p>Similarly <code>axiom_xml_writer</code> provides two create functions.</p>
<ul>
- <li><code>axis2_xml_writer_create_for_file</code> can be used to write to a
+ <li><code>axiom_xml_writer_create_for_file</code> can be used to write to a
file.</li>
- <li><code>axis2_xml_writer_create_for_memory</code> can be used to write to
- an internal memory buffer and obtain the xml string to a charcater buffer
+ <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>
</ul>
<p></p>
-<p>Please refer to <code>axis2_xml_reader.h</code> and
-<code>axis2_xml_writer.h</code> for more information.</p>
+<p>Please refer to <code>axiom_xml_reader.h</code> and
+<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 OM</b></h3>
-<p>You have to be extremely carefull when using om in order to avoid memory
+<p>You have to be extremely careful when using om in order to avoid memory
leaks and double free errors. Following guidelines will be very useful.</p>
<p>1. <code>om_element_t</code> struct keeps a list of attributes and a list
@@ -752,8 +681,8 @@
<p></p>
<p>3. when creating om programatically , if you are declaring a namespace to
-an om elment, it is advisible to find whether the namespace is already
-availble in the elements scope using find_namespace function. If available,
+an om element, it is advisable to find whether the namespace is already
+available in the elements scope using find_namespace function. If available,
that pointer can be used instead of creating another namespace struct
instance to prevent memory leaks.</p>
@@ -778,10 +707,10 @@
#include <axiom_element.h>
#include <axiom_document.h>
#include <axiom_stax_builder.h>
-#include <axis2_xml_reader.h>
+#include <axiom_xml_reader.h>
#include <axis2_log_default.h>
#include <axis2_error_default.h>
-#include <axis2_xml_writer.h>
+#include <axiom_xml_writer.h>
#include <axiom_output.h>
#include <stdio.h>
@@ -821,14 +750,14 @@
axiom_document_t *document = NULL;
axiom_stax_builder_t *om_builder = NULL;
- axis2_xml_reader_t *xml_reader = NULL;
- axis2_xml_writer_t *xml_writer = 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 = axis2_xml_reader_create_for_io(env, read_input_callback,
+ 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;
@@ -865,7 +794,7 @@
}
AXIOM_DOCUMENT_BUILD_ALL(document, env);
- xml_writer = axis2_xml_writer_create_for_memory(env, NULL, AXIS2_TRUE, 0,
AXIS2_XML_PARSER_TYPE_BUFFER);
+ 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);
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
