You are viewing a plain text version of this content. The canonical link for it is here.
Posted to c-dev@axis.apache.org by Dumindu Pallewela <du...@wso2.com> on 2006/10/16 17:34:50 UTC
corrections for om_tutorial
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.
Fw: corrections for om_tutorial
Posted by Dumindu Pallewela <du...@wso2.com>.
Please ignore this patch. I have accidentally deleted some of the text
from the tutorial while editing :(. I will send the correct version soon.
Thank you,
Dumindu.
Dumindu Pallewela wrote:
> 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: axis-c-dev-unsubscribe@ws.apache.org
> For additional commands, e-mail: axis-c-dev-help@ws.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: axis-c-dev-unsubscribe@ws.apache.org
For additional commands, e-mail: axis-c-dev-help@ws.apache.org