Author: chinthaka
Date: Thu Apr 20 00:39:55 2006
New Revision: 395523
URL: http://svn.apache.org/viewcvs?rev=395523&view=rev
Log:
Improved the AXIOM tutorial.
Modified:
webservices/commons/trunk/modules/axiom/xdocs/OMTutorial.html
Modified: webservices/commons/trunk/modules/axiom/xdocs/OMTutorial.html
URL:
http://svn.apache.org/viewcvs/webservices/commons/trunk/modules/axiom/xdocs/OMTutorial.html?rev=395523&r1=395522&r2=395523&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/xdocs/OMTutorial.html (original)
+++ webservices/commons/trunk/modules/axiom/xdocs/OMTutorial.html Thu Apr 20
00:39:55 2006
@@ -22,11 +22,11 @@
<h3>What is OM?</h3>
<p>OM stands for Object Model (also known as AXIOM - AXis Object Model) and
-refers to the XML infoset model that is developed for Axis 2. XML infoset
+refers to the XML infoset model that is initialy developed for Apache Axis2.
XML infoset
refers to the information included inside the XML and for programmatical
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. DOM and JDOM are two such XML models.
+choice is a model made up of objects. DOM and <a
href="http://www.jdom.org/";>JDOM</a> 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 follow while
@@ -37,8 +37,8 @@
<p>This tutorial can be used by anybody who is interested in OM and need to
go deeper in it. However it is assumed that the reader has a basic
-understanding of the concepts of XML (such as Namespaces) and a working
-knowledge of tools such as Ant. Knowledge in similar object models such as
+understanding of the concepts of XML (such as <a
href="http://www.w3.org/TR/REC-xml-names/";>Namespaces</a>) and a working
+knowledge of tools such as <a href="http://ant.apache.org/";>Ant</a>. 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>
@@ -79,7 +79,7 @@
<p>OM is a lightweight, differed built XML info set representation based on
StAX (<a
-href="http://www.jcp.org/aboutJava/communityprocess/first/jsr173/";>JSR
+href="http://www.jcp.org/en/jsr/detail?id=173";>JSR
173</a>), which is the standard streaming pull parser API. The object model
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
@@ -125,22 +125,22 @@
<!-- End of Image -->
<p>OM Builder wraps the raw xml character stream through the StAX reader API.
-Hence the complexities of the pull event stream is covered</p>
+Hence the complexities of the pull event stream is transparent to the user.</p>
<h3>A Bit About Caching</h3>
-<p>Since OM is a differed built Object model, It incorporates the concept of
+<p>Since OM is a differed 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
+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 and in this case it is sometimes beneficial to switch off
+instead of the OM. In this case it is sometimes beneficial to switch off
caching. The advanced operations section explains more on accessing the raw
pull stream and switching the caching on and off.</p>
<h3>Where Does SOAP Come into Play?</h3>
-<p>In a nutshell SOAP is a information exchange protocol based on XML. SOAP
+<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 set of SOAP specific objects
were also defined along with OM. These SOAP Objects are extensions of the
@@ -159,20 +159,11 @@
<h3>Obtaining the OM binary</h3>
-<p>OM is not a separate product but part of Axis2. But Axis2 provides a
-minimal jar which contains the run time of Axis2. This axis2-core-0.95.jar
-contains the compiled version of OM module.</p>
-
-<p>The easiest way to obtain the OM binary is to download the Axis2 minimal
-binary distribution. <font color="red" style="color: #000000">The lib
-directory will contain the <span
-style="color: #000000">axis2-</span></font><font style="color: #000000"><span
-style="color: #000000">core</span></font><font color="red"
-style="color: #000000"><span
-style="color: #000000">-0.95.jar</span></font><span style="color: #000000">.
+<p></p>
+
+<p>The easiest way to obtain the OM binary is to download the latest release
from <a href="http://ws.apache.org/commons/axiom/download.cgi";>here</a>
However more adventurous users can build the OM from source, which is
-described in the next section. In this way one get only the "OM
-jar".</span></p>
+described in the next section. </p>
<p>Detailed information on getting source from Axis2 SVN repository can be
found <a href="../svn.html" target="_blank">here</a>.</p>
@@ -181,16 +172,15 @@
Linux move it to the project directory and execute the command "maven jar".
All other necessary jars will be automatically downloaded. <em> </em><font
color="red"><span style="color: #000000">When the build finishes
-successfully, the <span style="color: #000000">axis2-xml-0.95.jar</span> can
-be found in the newly created "targets" directory in the XML
-module.</span></font></p>
+successfully, the <span style="color: #000000">axiom-api-<version>.jar</span>
and <span style="color: #000000">axiom-impl-<version>.jar</span> can
+be found in the newly created "targets" directory.</span></font></p>
<p>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.
Subsequent sections of this tutorial assume that this build step is complete
-and the <font color="red"><span style="color: #000000">axis2-core-0.95.jar
-or</span> <span style="color: #000000">axis2-xml-0.95.jar </span></font>is
-correct in the classpath along with the StAX API jar file and a StAX
+and <font color="red"><span style="color: #000000">axiom-api-<version>.jar
+</span> and <span style="color:
#000000">axiom-impl-<version>.jar</span></font> are
+present in the classpath along with the StAX API jar file and a StAX
implementation.</p>
<h3>Creation</h3>
@@ -201,15 +191,11 @@
builder to create objects. The factory helps to keep the code at the
interface level and the implementations separately (Figure 2). Since OM is
tightly bound to StAX, a StAX compliant reader should be created first with
-the desired input stream. Then the reader should be fed into the
-OMXMLBuilderFactory to instantiate a suitable builder. The interface provided
-by the builder is identical, though the internal implementations vary.
-However, the types of the returned objects depend on the implementation of
-the builder. For example the SOAPModelBuilder returns SOAP specific objects
+the desired input stream. Then one can select one of the different builders
available.
+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 from an input stream. Note that the SOAP builder is
-used in this example.</p>
+its builder methods and . The following piece of code shows the correct method
of
+creating an OM document from an input stream. </p>
<div align="left">
<p><b>Code Listing 1</b></p>
@@ -217,17 +203,18 @@
<source><pre>//create the parser<br/>
XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
<br/>//create the builder<br/>
-OMXMLParserWrapper builder =
OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMAbstractFactory.getSOAP11Factory(),
parser);
+StAXOMBuilder builder = new StAXOMBuilder(parser);
//get the root element (in this case the envelope)<br/>
- SOAPEnvelope envelope = (SOAPEnvelope)
builder.getDocumentElement();</pre>
+OMElement documentElement = builder.getDocumentElement();
+</pre>
</source>
<p>As the example shows, creating an OM 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
return the proper factory and the creator methods for each type should be
-called. Currently OM has two builders, namely the OM builder and the SOAP
-model builder. These builders provide the necessary information to the XML
+called. Currently OM has two builders, namely the OM builder (StAXOMBuilder)
and the SOAP
+model builder (StAXSOAPModelBuilder). These builders provide the necessary
information to the XML
info set model to build itself.</p>
<!-- Image -->
@@ -261,7 +248,7 @@
where as the latter always carries a reference to its builder. 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. If
-this information is not available, it is due to the Object being created
+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
detail in the advanced operations section.</p>
@@ -278,10 +265,10 @@
mixing up programmatically made OMNode objects with OMNode objects built from
builders.</p>
-<p>The SOAP Object hierarchy is made in the most natural way for a
+<p>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 element) hence one can access a SOAP
+extend basic OM classes (such as the OMElement) 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.</p>
<!-- The following illustration of the actual class diagram will be helpful
in understanding this.
@@ -310,7 +297,7 @@
root.addChild(elt11);
root.addChild(elt12);</pre>
<ul>
- <li>AddChild method will always add the child as the first child of the
+ <li>AddChild method will always add the child as the last child of the
parent.</li>
<li><p>A given node can be removed from the tree by calling the detach()
method. A node can also be removed from the tree by calling the remove
@@ -338,7 +325,7 @@
<p>The declareNamespaceXX methods are fairly straightforward. They 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 method to locate a namespace object higher up
+findNamespace 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 namespace is found or the root has been reached.</p>
@@ -385,7 +372,7 @@
<p><b>Code Listing 7</b></p>
</div>
<pre class="code">Iterator children = root.getChildren();
-While(children.hasNext()){
+while(children.hasNext()){
OMNode node = (OMNode)children.next();
}</pre>
@@ -454,7 +441,10 @@
//dump the output to console with caching
envelope.serialize(writer);
writer.flush();</pre>
-<pre class="code"></pre>
+
+or simply
+
+<pre class="code"> System.out.println(root.toStringWithConsume()); </pre>
<p>The above mentioned features of the serializer forces a correct
serialization even if only a part of the OM tree is serialized. The following
@@ -488,14 +478,13 @@
<pre class="code">//create the parser
XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
//create the builder
-OMXMLParserWrapper builder =
OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMAbstractFactory.getOMFactory(),parser);
+StAXOMBuilder builder = new StAXOMBuilder(parser);
+
//get the root element (in this case the envelope)
-SOAPEnvelope envelope = (SOAPEnvelope)builder.getDocumentElement();
-//get the writer
-XMLStreamWriter writer =
XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);
+OMElement documentElement = builder.getDocumentElement();
+
//dump the out put to console with caching
-envelope.serialize(writer);
-writer.flush();</pre>
+System.out.println(documentElement.toStringWithConsume()); </pre>
<h2>Advanced Operations with OM</h2>
@@ -584,8 +573,8 @@
OMElement elt1 = factory.createOMElement("foo",ns1);
OMElement elt2 = factory.createOMElement("yuck",ns2);
<b>OMElement elt3 = factory.createOMElement("yuck",ns2);</b>
-OMText txt1 = factory.createOMText(elt2,"blah");
-<b>OMText txt2 = factory.createOMText(elt3,"blahblah");
+OMText txt1 = factory.createText(elt2,"blah");
+<b>OMText txt2 = factory.createText(elt3,"blahblah");
elt3.addchild(txt2);</b>
elt2.addChild(txt1);
elt1.addChild(elt2);
@@ -647,15 +636,11 @@
try {
//create the parser
XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(args[0]));
- //create the builder
- OMXMLParserWrapper builder =
OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMAbstractFactory.getOMFactory(),
parser);
//get the root element (in this case the envelope)
- SOAPEnvelope envelope = (SOAPEnvelope)
builder.getDocumentElement();
- //get the writer
- XMLStreamWriter writer =
XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);
+ OMElement documentElement = builder.getDocumentElement();
+
//dump the out put to console with caching
- envelope.serialize(writer);
-writer.flush();
+ System.out.println(documentElement.toStringWithConsume());
} catch (XMLStreamException e) {
e.printStackTrace();
