ws-commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From veit...@apache.org
Subject svn commit: r795330 - /webservices/commons/trunk/modules/axiom/src/docbkx/tutorial.xml
Date Sat, 18 Jul 2009 09:30:41 GMT
Author: veithen
Date: Sat Jul 18 09:30:41 2009
New Revision: 795330

URL: http://svn.apache.org/viewvc?rev=795330&view=rev
Log:
Tutorial: s/OM/Axiom/ and formatting.

Modified:
    webservices/commons/trunk/modules/axiom/src/docbkx/tutorial.xml

Modified: webservices/commons/trunk/modules/axiom/src/docbkx/tutorial.xml
URL: http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/src/docbkx/tutorial.xml?rev=795330&r1=795329&r2=795330&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/docbkx/tutorial.xml (original)
+++ webservices/commons/trunk/modules/axiom/src/docbkx/tutorial.xml Sat Jul 18 09:30:41 2009
@@ -48,29 +48,29 @@
     <chapter>
         <title>Introduction</title>
         <section>
-            <title>What is OM?</title>
+            <title>What is Axiom?</title>
             <para>
-                OM stands for Object Model (also known as AXIOM - AXis Object Model) and
refers to the XML infoset model
+                Axiom stands for <firstterm>Axis Object Model</firstterm> and
refers to the XML infoset model
                 that is initially developed for Apache Axis2. XML infoset refers to the information
included inside the
                 XML, and for programmatic manipulation it is convenient to have a representation
of this XML infoset in
                 a language specific manner. For an object oriented language the obvious choice
is a model made up of
                 objects. <ulink url="http://www.w3.org/DOM/">DOM</ulink> and
<ulink url="http://www.jdom.org/">JDOM</ulink>
-                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. The objective of this tutorial is to
introduce the basics of OM and
-                explain the best practices to be followed while using OM. However, before
diving in to the deep end of
-                OM it is better to skim the surface and see what it is all about!
+                are two such XML models. Axiom is conceptually similar to such an XML model
by its external behavior but
+                deep down it is very much different. The objective of this tutorial is to
introduce the basics of Axiom and
+                explain the best practices to be followed while using Axiom. However, before
diving in to the deep end of
+                Axiom it is better to skim the surface and see what it is all about!
             </para>
         </section>
         <section>
             <title>For whom is this Tutorial?</title>
             <para>
-                This tutorial can be used by anyone who is interested in OM and needs to
+                This tutorial can be used by anyone who is interested in Axiom and needs
to
                 gain a deeper knowledge about the model. However, it is assumed that the
                 reader has a basic understanding of the concepts of XML (such as
                 <ulink src="http://www.w3.org/TR/REC-xml-names/">Namespaces</ulink>)
and a working
                 knowledge of tools such as <ulink href="http://ant.apache.org/">Ant</ulink>.
                 Knowledge in similar object models such as DOM will be quite helpful in
-                understanding OM, mainly to highlight the differences and similarities
+                understanding Axiom, mainly to highlight the differences and similarities
                 between the two, but such knowledge is not assumed. Several links are listed
                 in <xref linkend="links"/> that will help understand the basics of
                 XML.
@@ -88,7 +88,7 @@
                 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
+                discard events generated from the parser. Axiom is based on pull parsing.
To
                 learn more about XML pull parsing see the
                 <ulink url="http://www.bearcave.com/software/java/xml/xmlpull.html">XML
pull
                 parsing introduction</ulink>.
@@ -97,6 +97,8 @@
         <section>
             <title>A Bit of History</title>
             <para>
+                As mentioned earlier, Axiom was initially developed as part of Axis and simply
+                called <firstterm>OM</firstterm>.
                 The original OM was proposed as a store for the pull parser events for
                 later processing, at the Axis summit held in Colombo, Sri Lanka, in September
                 2004. However, this approach was soon improved and OM was pursued as a
@@ -120,9 +122,9 @@
             </para>
         </section>
         <section>
-            <title>Features of OM</title>
+            <title>Features of Axiom</title>
             <para>
-                OM is a lightweight, deferred built XML infoset representation based on
+                Axiom is a lightweight, deferred built XML infoset representation based on
                 StAX (<ulink url="http://www.jcp.org/en/jsr/detail?id=173">JSR 173</ulink>),
which
                 is the standard streaming pull parser API. The object model can be
                 manipulated as flexibly as any other object model (Such as
@@ -133,7 +135,7 @@
             <itemizedlist>
                 <listitem>
                     <para>
-                        <emphasis role="bold">Lightweight</emphasis>: OM is specifically
targeted to be
+                        <emphasis role="bold">Lightweight</emphasis>: Axiom is
specifically targeted to be
                         lightweight. This is achieved by reducing the depth of the hierarchy,
                         number of methods and the attributes enclosed in the objects. This
makes
                         the objects less memory intensive.
@@ -142,7 +144,7 @@
                 <listitem>
                     <para>
                         <emphasis role="bold">Deferred building</emphasis>: By
far this is the most important
-                        feature of OM. The objects are not made unless a need arises for
them.
+                        feature of Axiom. The objects are not made unless a need arises for
them.
                         This passes the control of building over to the object model itself
                         rather than an external builder.
                     </para>
@@ -150,7 +152,7 @@
                 <listitem>
                     <para>
                         <emphasis role="bold">Pull based</emphasis>: For a deferred
building mechanism a pull
-                        based parser is required. OM is based on
+                        based parser is required. Axiom is based on
                         <ulink url="http://today.java.net/pub/a/today/2006/07/20/introduction-to-stax.html">StAX</ulink>,
                         the standard pull parser API.
                     </para>
@@ -158,13 +160,13 @@
             </itemizedlist>
             <important>
                 <para>
-                    OM is tightly bound to StAX API. To work with OM
+                    Axiom is tightly bound to StAX API. To work with Axiom
                     a StAX compliant parser and the API <emphasis>must</emphasis>
be present in the
                     classpath.
                 </para>
             </important>
             <para>
-                The Following image shows how OM API is viewed by the user
+                The Following image shows how Axiom API is viewed by the user
             </para>
             <figure>
                 <title>Architecture overview</title>
@@ -183,12 +185,12 @@
         <section>
             <title>A Bit About Caching</title>
             <para>
-                Since OM is a deferred built object model, It incorporates the concept of
+                Since Axiom is a deferred built object model, It incorporates the concept
of
                 caching. Caching refers to the creation of the objects while parsing the
pull
                 stream. The reason why this is so important is because caching can be turned
                 off in certain situations. If so the  parser proceeds without building the
-                object structure. User can extract the raw pull stream from OM and use that
-                instead of the OM. In this case it is sometimes beneficial to switch off
+                object structure. User can extract the raw pull stream from Axiom and use
that
+                instead of the object model. In this case it is sometimes beneficial to switch
off
                 caching. <xref linkend="advanced"/> explains
                 more on accessing the raw pull stream and switching on and off the
                 caching.
@@ -200,45 +202,45 @@
                 In a nutshell <ulink url="http://www.w3schools.com/SOAP/soap_intro.asp">SOAP</ulink>
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
-                OM is built for Axis2, a set of SOAP specific objects were also defined along
-                with OM. These SOAP Objects are extensions of the general OM objects.
+                Axiom is built for Axis2, a set of SOAP specific objects were also defined
along
+                with Axiom. These SOAP Objects are extensions of the general object model
classes.
             </para>
         </section>
     </chapter>
 
     <chapter>
-        <title>Working with OM</title>
+        <title>Working with Axiom</title>
         <section>
-            <title>Obtaining the OM Binary</title>
+            <title>Obtaining the Axiom Binary</title>
             <para>
-                There are two methods through which the OM-binary can be obtained:
+                There are two methods through which the Axiom binary can be obtained:
             </para>
             <orderedlist>
                 <listitem>
                     <para>
-                        The easiest way to obtain the OM binary is to
+                        The easiest way to obtain the Axiom binary is to
                         <ulink url="http://ws.apache.org/commons/axiom/download.cgi">download</ulink>
the
-                        latest release. After the source download, OM-binary can be built.
For
+                        latest release. After the source download, the binary can be built.
For
                         both MS Windows and Linux, move it to the project directory and execute
-                        the command "maven jar". All other necessary jars will be automatically
+                        the command <command>maven jar</command>. All other necessary
jars will be automatically
                         downloaded. When the build is completed successfully, the
-                        axiom-api-&version;.jar and axiom-impl-&version;.jar can
be
+                        <filename>axiom-api-&version;.jar</filename> and
<filename>axiom-impl-&version;.jar</filename> can be
                         found in the newly created "targets" directory.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
-                        However, more adventurous users can build the OM from source, which
is
+                        However, more adventurous users can build Axiom from source, which
is
                         described in the next section. Detailed information on getting source
                         from SVN repository is found <ulink url="svn.html">here</ulink>.
                     </para>
                 </listitem>
             </orderedlist>
             <para>
-                Once the OM-binary is obtained by any of the above ways, it should be
-                included in the classpath for any of the OM based programs to work.
+                Once the Axiom binary is obtained by any of the above ways, it should be
+                included in the classpath for any of the Axiom based programs to work.
                 Subsequent sections of this tutorial assume that this build step is complete
-                and axiom-api-&version;.jar, and axiom-impl-&version;.jar are
+                and <filename>axiom-api-&version;.jar</filename> and <filename>axiom-impl-&version;.jar</filename>
are
                 present in the classpath along with the StAX API jar file and a StAX
                 implementation.
             </para>
@@ -247,23 +249,23 @@
             <title>Creation</title>
             <para>
                 Creation is the first and foremost action when using an Object
-                representation. This part explains how OM can be built from an existing
-                document or simply programmatically. OM provides a notion of a factory and
a
+                representation. This part explains how the object model can be built from
an existing
+                document or simply programmatically. Axiom provides a notion of a factory
and a
                 builder to create objects. The factory helps to keep the code at the
                 interface level and the implementations separately as shown in
-                <xref linkend="fig_api"/>. Since OM is tightly bound to StAX, a StAX
+                <xref linkend="fig_api"/>. Since Axiom is tightly bound to StAX, a
StAX
                 compliant reader should be created first with the desired input stream. Then
                 one can select one of the different builders available.
             </para>
             <para>
-                StAXOMBuilder will build pure XML infoset compliant object model whilst
-                the SOAPModelBuilder returns SOAP specific objects (such as the SOAPEnvelope,
-                which are sub classes of the OMElement) through its builder methods. The
-                following piece of code shows the correct method of creating an OM document
+                <classname>StAXOMBuilder</classname> will build pure XML infoset
compliant object model whilst
+                the <classname>SOAPModelBuilder</classname> returns SOAP specific
objects (such as the <classname>SOAPEnvelope</classname>,
+                which are sub classes of the <classname>OMElement</classname>)
through its builder methods. The
+                following piece of code shows the correct method of creating an object model
                 from an input stream.
             </para>
             <example id="list1">
-                <title>Creating an OM document from an input stream</title>
+                <title>Creating an object model from an input stream</title>
 <programlisting>//create the parser
 XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileInputStream(file));
 
@@ -274,13 +276,13 @@
 OMElement documentElement =  builder.getDocumentElement();</programlisting>
             </example>
             <para>
-                As the example shows, creating an OM from an input stream is pretty
+                As the example shows, creating an object model from an input stream is pretty
                 straightforward. However, elements and nodes can be created programmatically
-                to modify the structure as well. The recommended way to create OM objects
-                programmatically is to use the factory. OMAbstractFactory.getOMFactory()
will
+                to modify the structure as well. The recommended way to create Axiom objects
+                programmatically is to use the factory. <methodname>OMAbstractFactory.getOMFactory()</methodname>
will
                 return the proper factory and the creator methods for each type that should
-                be called. Currently OM has two builders, namely the OM builder
-                (StAXOMBuilder) and the SOAP model builder (StAXSOAPModelBuilder). These
+                be called. Currently Axiom has two builders, namely the OM builder
+                (<classname>StAXOMBuilder</classname>) and the SOAP model builder
(<classname>StAXSOAPModelBuilder</classname>). These
                 builders provide the necessary information to the XML infoset model to build
                 itself.
             </para>
@@ -296,7 +298,7 @@
                 A simple example is shown below:
             </para>
             <example id="list2">
-                <title>Creating an OM document programmatically</title>
+                <title>Creating an object model programmatically</title>
 <programlisting>//create a factory
 OMFactory factory = OMAbstractFactory.getOMFactory();
 //use the factory to create two namespace objects
@@ -308,40 +310,40 @@
 OMElement elt12 = factory.createOMElement("foo2",ns1);</programlisting>
             </example>
             <para>
-                The reason as to have a set of factory.createXXX methods is to cater for
+                The reason as to have a set of <code>factory.createXXX</code>
methods is to cater for
                 different implementations, but keep the programmers code intact. Its highly
-                recommended to use the factory for creating OM objects as this will ease
the
-                switching of different OM implementations. Several differences exist between
-                a programmatically created OMNode and a conventionally built OMNode. The
most
+                recommended to use the factory for creating Axiom objects as this will ease
the
+                switching of different Axiom implementations. Several differences exist between
+                a programmatically created <classname>OMNode</classname> and
a conventionally built <classname>OMNode</classname>. The most
                 important difference is that the former will have no builder object enclosed,
                 where as the latter always carries a reference to its builder.
             </para>
             <para>
                 As stated earlier in this tutorial, since the object model is built as and
-                when required, each and every OMNode should have a reference to its builder.
+                when required, each and every <classname>OMNode</classname> should
have a reference to its builder.
                 If this information is not available, it is due to the object being created
                 without a builder. This difference becomes evident when the user tries to
get
-                a non caching pull parser from the OMElement. This will be discussed in more
+                a non caching pull parser from the <classname>OMElement</classname>.
This will be discussed in more
                 detail in <xref linkend="advanced"/>.
             </para>
             <para>
                 In order to understand the requirement of the builder reference in each
-                and every OMNode, consider the following scenario. Assume that the parent
+                and every <classname>OMNode</classname>, consider the following
scenario. Assume that the parent
                 element is built but the children elements are not. If the parent is asked
to
                 iterate through its children, this information is not readily available to
                 the parent element and it should build its children first before attempting
                 to iterate them. In order to provide a reference of the builder, each and
-                every node of an OM structure should carry the reference to its builder.
Each
-                and every OMNode carries a flag that states its build status. Apart from
this
+                every node of the object model should carry the reference to its builder.
Each
+                and every <classname>OMNode</classname> carries a flag that states
its build status. Apart from this
                 restriction there are no other constraints that keep the programmer away
from
-                mixing up programmatically made OMNode objects with OMNode objects built
from
+                mixing up programmatically made <classname>OMNode</classname>
objects with <classname>OMNode</classname> objects built from
                 builders.
             </para>
             <para>
                 The SOAP object hierarchy is made in the most natural way for a
                 programmer. An inspection of the API will show that it is quite close to
the
                 SAAJ API but with no bindings to DOM or any other model. The SOAP classes
-                extend basic OM classes (such as the OMElement) hence, one can access a SOAP
+                extend basic Axiom classes (such as the <classname>OMElement</classname>)
hence, one can access a SOAP
                 document either with the abstraction of SOAP or drill down to the underlying
                 XML Object model with a simple casting.
             </para>
@@ -349,7 +351,7 @@
         <section>
             <title>Addition of Nodes</title>
             <para>
-                Addition and removal methods are primarily defined in the OMElement
+                Addition and removal methods are primarily defined in the <classname>OMElement</classname>
                 interface. The following are the most important in adding nodes.
             </para>
 <programlisting>public void addChild(OMNode omNode);
@@ -366,12 +368,12 @@
             <itemizedlist>
                 <listitem>
                     <para>
-                        AddChild method will always add the child as the last child of the
parent.
+                        <methodname>addChild</methodname> will always add the
child as the last child of the parent.
                     </para>
                 </listitem>
                 <listitem>
                     <para>
-                        A given node can be removed from the tree by calling the detach()
+                        A given node can be removed from the tree by calling the <methodname>detach()</methodname>
                         method. A node can also be removed from the tree by calling the remove
                         method of the returned iterator which will also call the detach method
of
                         the particular node internally.
@@ -380,25 +382,25 @@
                 <listitem>
                     <para>
                         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.
-                        OMNamespace is the class that represents a namespace with intentionally
-                        removed setter methods. This makes the OMNamespace immutable and
allows
+                        Axiom. However, the interface to the namespace have been made very
simple.
+                        <classname>OMNamespace</classname> is the class that
represents a namespace with intentionally
+                        removed setter methods. This makes the <classname>OMNamespace</classname>
immutable and allows
                         the underlying implementation to share the objects without any
                         difficulty.
                     </para>
                 </listitem>
             </itemizedlist>
             <para>
-                Following are the important methods available in OMElement to handle
+                Following are the important methods available in <classname>OMElement</classname>
to handle
                 namespaces.
             </para>
 <programlisting>public OMNamespace declareNamespace(String uri, String prefix);
 public OMNamespace declareNamespace(OMNamespace namespace);
 public OMNamespace findNamespace(String uri, String prefix) throws OMException;</programlisting>
             <para>
-                The declareNamespaceXX methods are fairly straightforward. Add a namespace
+                The <methodname>declareNamespaceXX</methodname> methods are fairly
straightforward. Add a namespace
                 to namespace declarations section. Note that a namespace declaration that
has
-                already being added will not be added twice. findNamespace is a very handy
+                already being added will not be added twice. <methodname>findNamespace</methodname>
is a very handy
                 method to locate a namespace object higher up the object 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
@@ -436,22 +438,24 @@
             <para>
                 Traversing the object structure can be done in the usual way by using the
                 list of children. Note however, that the child nodes are returned as an
-                iterator. The Iterator supports the 'OM way' of accessing elements and is
+                iterator. 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 are of the type OMNode
-                that can either be OMText or OMElement.
+                shows how the children can be accessed. The children are of the type <classname>OMNode</classname>
+                that can either be <classname>OMText</classname> or <classname>OMElement</classname>.
             </para>
 <programlisting>Iterator children = root.getChildren();
 while(children.hasNext()){
         OMNode node = (OMNode)children.next();
 }</programlisting>
             <para>
-                Apart from this, every OMNode has links to its siblings. If more thorough
-                navigation is needed the nextSibling() and PreviousSibling() methods can
be
+                Apart from this, every <classname>OMNode</classname> has links
to its siblings. If more thorough
+                navigation is needed the <methodname>getNextOMSibling()</methodname>
+                and <methodname>getPreviousOMSibling()</methodname> methods can
be
                 used. A more selective set can be chosen by using the
-                getChildrenWithName(QName) methods. The getChildWithName(Qname) method
-                returns the first child that matches the given QName and
-                getChildrenWithName(QName) returns a collection containing all the matching
+                <methodname>getChildrenWithName(QName)</methodname> methods.
+                The <methodname>getChildWithName(Qname)</methodname> method
+                returns the first child that matches the given <classname>QName</classname>
and
+                <methodname>getChildrenWithName(QName)</methodname> returns a
collection containing all the matching
                 children. The advantage of these iterators is that they won't build the whole
                 object structure at once, until its required.
             </para>
@@ -459,7 +463,7 @@
                 <para>
                     All iterator implementations internally stay one
                     step ahead of their apparent location to provide the correct value
-                    for the hasNext() method. This hidden advancement can build elements
+                    for the <methodname>hasNext()</methodname> method. This hidden
advancement can build elements
                     that are not intended to be built at all. Hence these iterators are
                     recommended only when caching is not a concern.
                 </para>
@@ -468,15 +472,16 @@
         <section id="serializer">
             <title>Serializer</title>
             <para>
-                OM can be serialized either as the pure object model or the pull event
-                stream. The serialization uses a XMLStreamWriter object to write out the
+                An Axiom tree can be serialized either as the pure object model or the pull
event
+                stream. The serialization uses a <classname>XMLStreamWriter</classname>
object to write out the
                 output and hence, the same serialization mechanism can be used to write
                 different types of outputs (such as text, binary, etc.).
             </para>
             <para>
-                A caching flag is provided by OM to control the building of the in-memory
-                OM. The OMNode has two methods, serializeAndConsume and serialize. When
-                serializeAndConsume is called the cache flag is reset and the serializer
does
+                A caching flag is provided by Axiom to control the building of the in-memory
+                object model. The <classname>OMNode</classname> has two methods,
+                <methodname>serializeAndConsume</methodname> and <methodname>serialize</methodname>.
When
+                <methodname>serializeAndConsume</methodname> is called the cache
flag is reset and the serializer does
                 not cache the stream. Hence, the object model will not be built if the cache
                 flag is not set.
             </para>
@@ -499,7 +504,7 @@
                 <listitem>
                     <para>
                         When the namespaces are declared explicitly using the elements
-                        declareNamespace() method, they will be serialized even if those
+                        <methodname>declareNamespace()</methodname> method, they
will be serialized even if those
                         namespaces are not used in that scope.
                     </para>
                 </listitem>
@@ -524,10 +529,10 @@
 <programlisting>System.out.println(root.toStringWithConsume());</programlisting>
             <para>
                 The above mentioned features of the serializer forces a correct
-                serialization even if only a part of the OM tree is serialized. The following
+                serialization even if only a part of the Axiom tree is serialized. The following
                 serializations show how the serialization mechanism takes the trouble to
                 accurately figure out the namespaces. The example is from <xref linkend="list6"/>
-                which creates a small OM programmatically.
+                which creates a small object model programmatically.
                 Serialization of the root element produces the following:
             </para>
 <screen>&lt;x:root xmlns:x="bar" xmlns:y="bar1"&gt;&lt;x:foo&gt;&lt;y:yuck&gt;blah&lt;/y:yuck&gt;&lt;/x:foo&gt;&lt;/x:root&gt;</screen>
@@ -540,9 +545,9 @@
             </para>
         </section>
         <section>
-            <title>Complete Code for the OM based Document Building and Serialization</title>
+            <title>Complete Code for the Axiom based Document Building and Serialization</title>
             <para>
-                The following code segment shows how to use the OM for completely building
+                The following code segment shows how to use Axiom for completely building
                 a document and then serializing it into text pushing the output to the
                 console. Only the important sections are shown here. The complete program
                 listing can be found in <xref linkend="appendix"/>.
@@ -561,20 +566,20 @@
     </chapter>
 
     <chapter id="advanced">
-        <title>Advanced Operations with OM</title>
+        <title>Advanced Operations with Axiom</title>
         <section>
-            <title>Use of the OMNavigator for Traversal</title>
+            <title>Use of the <classname>OMNavigator</classname> for Traversal</title>
             <para>
-                OM provides a utility class to navigate the OM structure. The navigator
-                provides an in-order traversal of the OM tree up to the last-built node.
The
+                Axiom provides a utility class to navigate the object model structure. The
navigator
+                provides an in-order traversal of the Axiom tree up to the last-built node.
The
                 Navigator has two states called the navigable state and the completion state.
-                Since the navigator provides the navigation starting from an OMElement, it
is
+                Since the navigator provides the navigation starting from an <classname>OMElement</classname>,
it is
                 deemed to have completed the navigation when the starting node is reached
                 again. This state is known as the completion state. Once the navigator has
                 reached the complete status its navigation is done and it cannot proceed.
             </para>
             <para>
-                It is possible that the OM tree does not get built completely when it is
+                It is possible that the Axiom tree does not get built completely when it
is
                 navigated. The navigable status shows whether the tree structure is
                 navigable. When the navigator is complete it is not navigable anymore.
                 However, it is possible for a navigator to become non-navigable without being
@@ -591,25 +596,26 @@
         <section>
             <title>Accessing the Pull Parser</title>
             <para>
-                OM is tightly integrated with StAX and the
-                getXMLStreamReader()/getXMLStreamReaderWithoutCaching() methods in the
-                OMElement provides a XMLStreamReader object. This XMLStreamReader instance
+                Axiom is tightly integrated with StAX and the
+                <methodname>getXMLStreamReader()</methodname> and <methodname>getXMLStreamReaderWithoutCaching()</methodname>
methods in the
+                <classname>OMElement</classname> provides a <classname>XMLStreamReader</classname>
+                object. This <classname>XMLStreamReader</classname> instance
                 has a special capability of switching between the underlying stream and the
-                OM object tree if the cache setting is off. However, this functionality is
+                Axiom object tree if the cache setting is off. However, this functionality
is
                 completely transparent to the user. This is further explained in the
                 following paragraphs.
             </para>
             <para>
-                OM has the concept of caching, and OM is the actual cache of the events
+                Axiom has the concept of caching, and the Axiom tree is the actual cache
of the events
                 fired. However, the requester can choose to get the pull events from the
-                underlying stream rather than the OM tree. This can be achieved by getting
+                underlying stream rather than the Axiom tree. This can be achieved by getting
                 the pull parser with the cache off. If the pull parser was obtained without
                 switching off cache, the new events fired will be cached and the tree
                 updated. This returned pull parser will switch between the object structure
                 and the stream underneath, and the users need not worry about the differences
                 caused by the switching. The exact pull stream the original document would
-                have provided would be produced even if the OM tree was fully or partially
-                built. The getXMLStreamReaderWithoutCaching() method is very useful when
the
+                have provided would be produced even if the Axiom tree was fully or partially
+                built. The <methodname>getXMLStreamReaderWithoutCaching()</methodname>
method is very useful when the
                 events need to be handled in a pull based manner without any intermediate
                 models. This makes such operations faster and efficient.
             </para>
@@ -625,9 +631,9 @@
     <chapter>
         <title>Summary</title>
         <para>
-            This is meant to be a small yet comprehensive introduction to AXIOM. AXIOM
+            This is meant to be a small yet comprehensive introduction to Axiom. Axiom
             however, is a lot more than what is described in this tutorial. Readers are
-            welcome to explore AXIOM, especially it's capabilities to handle binary
+            welcome to explore Axiom, especially it's capabilities to handle binary
             content.
         </para>
     </chapter>
@@ -635,7 +641,7 @@
     <chapter id="appendix">
         <title>Appendix</title>
         <section>
-            <title>Program Listing for Complete OM - Build and Serialize</title>
+            <title>Program Listing for Build and Serialize</title>
 <programlisting>import org.apache.axiom.om.OMElement;
 import org.apache.axiom.om.impl.builder.StAXOMBuilder;
 



Mime
View raw message