You are viewing a plain text version of this content. The canonical link for it is here.
Posted to axis-cvs@ws.apache.org by ch...@apache.org on 2006/01/05 05:53:11 UTC
svn commit: r366083 - /webservices/axis2/trunk/java/xdocs/OMTutorial.html
Author: chinthaka
Date: Wed Jan 4 20:53:07 2006
New Revision: 366083
URL: http://svn.apache.org/viewcvs?rev=366083&view=rev
Log:
some changes to OM tutorial. Thanks Chatra.
Modified:
webservices/axis2/trunk/java/xdocs/OMTutorial.html
Modified: webservices/axis2/trunk/java/xdocs/OMTutorial.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/trunk/java/xdocs/OMTutorial.html?rev=366083&r1=366082&r2=366083&view=diff
==============================================================================
--- webservices/axis2/trunk/java/xdocs/OMTutorial.html (original)
+++ webservices/axis2/trunk/java/xdocs/OMTutorial.html Wed Jan 4 20:53:07 2006
@@ -1,6 +1,6 @@
<html>
<head>
- <meta http-equiv="Content-Type" content="">
+ <meta http-equiv="content-type" content="">
<title>OM Tutorial</title>
<link href="css/axis-docs.css" type="text/css" rel="stylesheet">
</head>
@@ -17,7 +17,7 @@
<h1>OM Tutorial</h1>
-<h2>Section 1-Introduction</h2>
+<h2>Introduction</h2>
<h3>What is OM?</h3>
@@ -30,20 +30,20 @@
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
-using OM. However before entering the deep ends of OM it is better to skim
-the surface and see what it is all about!</p>
+using OM. However before entering the deep end of OM it is better to skim the
+surface and see what it is all about!</p>
<h3>For whom is this Tutorial?</h3>
-<p>This tutorial can be used by anybody who is interested in OM and needs to
+<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
-DOM will be quite helpful in understanding but such knowledge is not assumed.
-Several Links are listed in the appendix/ links section that will help
-anybody who lacks the basic understanding of XML.</p>
+knowledge of tools such as Ant. 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>
-<h3>What is pull parsing ?</h3>
+<h3>What is Pull Parsing ?</h3>
Pull parsing is a recent trend in XML processing. The previously popular XML
processing frameworks such as SAX and DOM were "push-based" which means the
control of the parsing was with the parser itself. This approach is fine and
@@ -58,22 +58,22 @@
<h3>A Bit of History</h3>
<p>The original OM was proposed as a store for the pull parser events for
-later processing, at the Axis summit held at Colombo in September 2004.
-However this approach was soon improved and OM was pursued as a complete info
-set model due to its flexibility. Several implementation techniques were
-attempted during the initial phases. The two most promising techniques were
-the table based technique and the link list based technique. During the
-intermediate performance tests the link list based technique proved to be
-much more memory efficient for smaller and mid sized XML documents (the
-advantage of the table based OM was only visible for the large and very large
-XML documents) and hence the link list based technique was chosen as the most
-suitable. Initial efforts were focused on implementing the XML info set items
-which are relevant to the SOAP specification (DTD support, Processing
-Instruction support, etc were not considered). The advantage of having a
-tight integration was evident at this stage and this resulted in having SOAP
-specific interfaces as part of OM rather than a layer on top of it. OM was
-deliberately made API centric. It allows the implementations to take place
-independently and swapped without affecting the program later.</p>
+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
+complete info set model due to its flexibility. Several implementation
+techniques were attempted during the initial phases. The two most promising
+techniques were the table based technique and the link list based technique.
+During the intermediate performance tests the link list based technique
+proved to be much more memory efficient for smaller and mid sized XML
+documents (the advantage of the table based OM was only visible for the large
+and very large XML documents) and hence the link list based technique was
+chosen as the most suitable. Initial efforts were focused on implementing the
+XML info set items which are relevant to the SOAP specification (DTD support,
+Processing Instruction support, etc were not considered). The advantage of
+having a tight integration was evident at this stage and this resulted in
+having SOAP specific interfaces as part of OM rather than a layer on top of
+it. OM was deliberately made API centric. It allows the implementations to
+take place independently and swapped without affecting the program later.</p>
<h3>Features of OM</h3>
@@ -86,15 +86,15 @@
created only when they are absolutely required. This leads to much less
memory intensive programming. Following is a short feature overview of OM.</p>
<ul>
- <li>Lightweight , OM is specifically targeted to be lightweight. This is
+ <li>Lightweigt: OM 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.</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
+ <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 over to the object model itself rather than an
external builder.</li>
- <li>Pull based , For a differed building mechanism a pull based parser is
+ <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>
</ul>
<!-- Special section -->
@@ -127,7 +127,7 @@
<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>
-<h3>A bit about caching</h3>
+<h3>A Bit About Caching</h3>
<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
@@ -138,14 +138,15 @@
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>
+<h3>Where Does SOAP Come into Play?</h3>
<p>In a nutshell SOAP is a 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
-general OM objects. To <a
-href="http://www.w3schools.com/SOAP/soap_intro.asp">learn more on SOAP</a></p>
+general OM objects. See <a
+href="http://www.w3schools.com/SOAP/soap_intro.asp"> here </a> to learn more
+about SOAP.</p>
<!--<p>This abstraction provides</p>
<ul>
<li>differed building support</li>
@@ -154,36 +155,40 @@
<p>AXIOM has the flexibility to plug in any builder which implements the given builders interface. The upcoming sections of this tutorial deal with the creation and usage of OM for manipulating SOAP (and to some extent nonSOAP) based XML documents.</p>
-->
-<h2>Section 2 - Working with OM</h2>
+<h2>Working with OM</h2>
<h3>Obtaining the OM binary</h3>
<p>OM is not a separate product but part of Axis2. However since Axis2 has a
-modular build structure It is possible to obtain an "OM only" jar.</p>
+modular build structure, it is possible to obtain an "OM only" jar.</p>
<p>The easiest way to obtain the OM binary is to download the Axis2 binary
-distribution. The lib directory will contain the axis2-xml-0.93.jar. However
-more adventurous users can build the OM from source. The next section
-describes how to build OM from source.</p>
+distribution. <em><font> </font></em><font color="red"
+style="color: #000000">The lib directory will contain the <span
+style="color: #FF0000">axis2-xml-0.94.jar</span></font><span
+style="color: #000000">. However more adventurous users can build the OM from
+source, which is described in the next section.</span></p>
<p>Detailed information on getting source from Axis2 SVN repository can be
found <a href="svn.html" target="_blank">here</a>.</p>
-<p>After the source download OM-binary can be built. For both Windows and
-Linux move to the project directory and execute the command "maven jar". All
-other necessary jars will be automatically downloaded. When the build
-finishes successfully, the axis2-xml-0.93.jar can be found in the newly
-created "targets" directory in the XML module.</p>
-
-<p>Once the OM-binary is obtained by any of the mentioned means , it should
-be included in the class path for any of the OM based programs to work. The
-subsequent parts of this tutorial assume that this build step is complete and
-the Axis-0.93.jar is correctly in the classpath along with the StAX API jar
-file and a StAX implementation.</p>
+<p>After the source download, OM-binary can be built. For both Windows and
+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: #FF0000">axis2-xml-0.94.jar</span> can
+be found in the newly created "targets" directory in the XML
+module.</span></font></p>
+
+<p>Once the OM-binary is obtained by any of the above ways , it should be
+included in the class path 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">Axis-0.94.jar </font> is correct in the classpath
+along with the StAX API jar file and a StAX implementation.</p>
<h3>Creation</h3>
-<p>Creation is the first and foremost action in using an Object
+<p>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 just programmatically. OM provides a notion of a factory and a
builder to create objects. The factory helps to keep the code at the
@@ -191,13 +196,17 @@
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.
+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
(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>
+
+<div align="left">
+<p><b>Code Listing 1</b></p>
+</div>
<source><pre>//create the parser<br>
XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
<br>//create the builder<br>
@@ -205,9 +214,6 @@
//get the root element (in this case the envelope)<br>
SOAPEnvelope envelope = (SOAPEnvelope) builder.getDocumentElement();</pre>
</source>
-<div align="left">
-<b>Code listing 2.1</b></div>
-
<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
@@ -225,6 +231,10 @@
<!-- End of Image -->
<p>A simple example is shown below.</p>
+
+<div align="left">
+<p><b>Code Listing 2</b></p>
+</div>
<pre class="code">//create a factory
OMFactory factory = OMAbstractFactory.getOMFactory();
//use the factory to create two namespace objects
@@ -235,15 +245,12 @@
OMElement elt11 = factory.createOMElement("foo1",ns1);
OMElement elt12 = factory.createOMElement("foo2",ns1);</pre>
-<div align="left">
-<b>Code listing 2.2</b></div>
-
<p>The reason to have a set of factory.createXXX methods is to cater for
different implementations but keep the programmers code intact. Its highly
recommend 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
-important difference is that the former will have no builder object enclosed
+important difference is that the former will have no builder object enclosed,
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
@@ -277,42 +284,49 @@
<p>Addition and removal methods are primarily defined in the OMElement
interface. The following are the most important in adding nodes.</p>
-<pre class="code">public void addChild(OMNode omNode);
-public void addAttribute(OMAttribute attr);</pre>
<div align="left">
-<b>Code listing 2.3</b></div>
+<p><b>Code Listing 3</b></p>
+</div>
+<pre class="code">public void addChild(OMNode omNode);
+public void addAttribute(OMAttribute attr);</pre>
<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 align="left">
+<p><b>Code Listing 4</b></p>
+</div>
<pre class="code">//set the children
elt11.addChild(elt21);
elt12.addChild(elt22);
root.addChild(elt11);
root.addChild(elt12);</pre>
+<ul>
+ <li>AddChild method 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 detach()
+ 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.</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.
+ OMNamespace is the class that represents a namespace with intentionally
+ removed setter methods. This makes the OMNamespace immutable and allows
+ the underlying implementation to share the objects without any
+ difficulty.</li>
+</ul>
-<div align="left">
-<b>Code listing 2.4</b></div>
+<p>Following are the important methods available in OMElement to handle
+namespaces.</p>
-<p>Note that AddChild method will always add the child as the first child of
-the parent. Removal of Nodes 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 method of the returned iterator which will also call the
-detach method of the particular node internally. Handling namespaces
-Namespaces are a tricky part of any XML object model and is the same in OM.
-However care has been taken to make the interface to the namespace very
-simple. OMNamespace is the class that represents a namespace with
-intentionally removed setter methods. This makes the OMNamespace immutable
-and allows the underlying implementation to share the objects without any
-difficulty. Following are the important methods available in OMElement to
-handle namespaces.</p>
+<div align="left">
+<b><p>Code Listing 5</p></b></div>
<pre class="code">public OMNamespace declareNamespace(String uri, String prefix);
public OMNamespace declareNamespace(OMNamespace namespace);
public OMNamespace findNamespace(String uri, String prefix) throws OMException;</pre>
-<div align="left">
-<b>Code listing 2.5</b></div>
-
<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.
@@ -328,6 +342,10 @@
<p>The following simple code segment shows how the namespaces are dealt with
in OM</p>
+
+<div align="left">
+<p><b>Code Listing 6</b></p>
+</div>
<pre class="code">OMFactory factory = OMAbstractFactory.getOMFactory();
OMNamespace ns1 = factory.createOMNamespace("bar","x");
OMElement root = factory.createOMElement("root",ns1);
@@ -339,9 +357,6 @@
elt1.addChild(elt2);
root.addChild(elt1);</pre>
-<div align="left">
-<b>Code listing 2.6</b></div>
-
<p>Serilization of the root element produces the following XML</p>
<pre class="xml"><x:root xmlns:x="bar" xmlns:y="bar1">
<x:foo>
@@ -357,15 +372,15 @@
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.</p>
+
+<div align="left">
+<b><p>Code Listing 7</p></b></div>
<pre class="code">Iterator children = root.getChildren();
While(children.hasNext()){
OMNode node = (OMNode)children.next();
}</pre>
-<div align="left">
-<b>Code listing 2.7</b></div>
-
-<p>Apart from this every OMNode has links to its siblings. If more thorough
+<p>Apart from this, every OMNode has links to its siblings. If more thorough
navigation is needed the nextSibling() and PreviousSibling() methods can be
used. A more selective set can be chosen by using the
getChildrenWithName(QName) methods. The getChildWithName(Qname) method
@@ -399,7 +414,7 @@
different types of outputs (such as text, binary, etc.,).</p>
<p>A caching flag is provided by OM to control the building of the in-memory
-OM. The OMNode has two methods, serializeWithCache and serialize When
+OM. The OMNode has two methods, serializeWithCache and serialize When
serialize 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.</p>
@@ -407,7 +422,7 @@
<p>The serializer serializes namespaces in the following way.</p>
<ol>
<li>When a namespace that is in the scope but not yet declared is
- encountered, then it will be declared.</li>
+ encountered, it will then be declared.</li>
<li>When a namespace that is in scope and already declared is encountered,
the existing declarations prefix is used.</li>
<li>When the namespaces are declared explicitly using the elements
@@ -420,43 +435,46 @@
declarations.</p>
<p>Here is an example that shows how to write the output to the console, with
-reference to the earlier code sample (Code listing 2.1 ) that created a SOAP
+reference to the earlier code sample (Code listing 1 ) that created a SOAP
envelope.</p>
-<p></p>
+<div align="left">
+<b><p>Code Listing 8</p></b></div>
<pre class="code">XMLStreamWriter writer = XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);
//dump the output to console with caching
envelope.serializeWithCache(writer);
writer.flush();</pre>
-<pre class="code"> </pre>
-
-<div align="left">
-<b>Code listing 2.8</b></div>
+<pre class="code"> </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
serializations show how the serialization mechanism takes the trouble to
-accurately figure out the namespaces. The example is from code listing 2.6
+accurately figure out the namespaces. The example is from Code Listing 6
which creates a small OM programmatically. Serialization of the root element
-produces</p>
+produces the following,</p>
<pre class="xml"><x:root xmlns:x="bar" xmlns:y="bar1">
<x:foo>
<y:yuck>blah</y:yuck>
</x:foo>
</x:root></pre>
-<p>However serialization of only the foo element produces</p>
+<p>However serialization of only the foo element produces the following</p>
<pre class="xml"><x:foo xmlns:x="bar">
<y:yuck xmlns:y="bar1">blah</y:yuck>
-</x:foo>
-</pre>
+</x:foo></pre>
-<p>Note how the serializer puts the relevant namespace declarations in place.
-Complete code for the OM based document building and serialization 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.
-Only the important sections are shown here and the complete program listing
-can be found in the appendix.</p>
+<p>Note how the serializer puts the relevant namespace declarations in
+place.</p>
+<b>Complete code for the OM based document building and serialization </b>
+
+<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. Only the important sections are shown here. The complete program
+listing can be found in the appendix.</p>
+
+<div align="left">
+<p><b>Code Listing 9</b></p>
+</div>
<pre class="code">//create the parser
XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
//create the builder
@@ -469,10 +487,7 @@
envelope.serialize(writer);
writer.flush();</pre>
-<div align="left">
-<b>Code listing 2.9</b></div>
-
-<h2>Section 3 - Advanced Operations with OM</h2>
+<h2>Advanced Operations with OM</h2>
<h3>Use of the OMNavigator for Traversal</h3>
@@ -482,8 +497,7 @@
Since the navigator provides the navigation starting from an OMElement, 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
-anymore.</p>
+reached the complete status its navigation is done and it cannot proceed.</p>
<p>It is possible that the OM tree does not get built completely when it is
navigated. The navigable status shows whether the tree structure is
@@ -491,6 +505,9 @@
However it is possible for a navigator to become non-navigable without being
complete. The following code sample shows how the navigator should be used
and handled using its states.</p>
+
+<div align="left">
+<b><p>Code Listing 10</p></b></div>
<pre class="code">//Create a navigator
OMNavigator navigator = new OMNavigator(envelope);
OMNode node = null;
@@ -498,9 +515,6 @@
node = navigator.next();
}</pre>
-<div align="left">
-<b>Code listing 3.1</b></div>
-
<h3>Accessing the Pull Parser</h3>
<p>OM is tightly integrated with StAX and the
@@ -511,18 +525,18 @@
completely transparent to the user. This is further explained in the
following paragraphs.</p>
-<p> OM has the concept of caching, and OM 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 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
+<p>OM has the concept of caching, and OM 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
+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/partially
built. The getXMLStreamReaderWithoutCaching() 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. </p>
+models. This makes such operations faster and efficient.</p>
<!-- Special section -->
<p class="special"></p>
@@ -540,16 +554,17 @@
</table>
<!-- End of special section -->
-<h3> </h3>
-
-<h2>Section 4 - Known Limitations of OM</h2>
+<h3> Known Limitations of OM</h3>
<h3>Inefficient Namespace serialization</h3>
<p>Although the serializer acts correctly in every situation, the code that
it produces may not be efficient all the time. Take the following case where
-a similar code listing to 1.6 is used but with two elements having the same
-namespace. Note that the newly added items are in bold.</p>
+a similar Code Listing to Code Listing 6 is used, but with two elements
+having the same namespace. Note that the newly added items are in bold.</p>
+
+<div align="left">
+<b><p>Code Listing 11</p></b></div>
<pre class="code">OMFactory factory = OMAbstractFactory.getOMFactory();
OMNamespace ns1 = factory.createOMNamespace("bar","x");
OMElement root = factory.createOMElement("root",ns1);
@@ -565,15 +580,12 @@
<b>elt1.addChild(elt3);</b>
root.addChild(elt1);</pre>
-<div align="left">
-<b>Code listing 4.1</b></div>
-
<p>Serialization of the root element provides the following XML</p>
<pre class="xml"><x:root xmlns:x="bar" xmlns:y="bar1">
<x:foo>
- <y:yuck>blahblah</y:yuck>
+ <y:yuck>blahblah</y:yuck>
<y:yuck>blah</y:yuck>
- </x:foo>
+ </x:foo>
</x:root>
</pre>
@@ -581,9 +593,9 @@
<p>However if the serialization is carried on the foo element then the
following XML is produced</p>
<pre class="xml"><x:foo xmlns:x="bar" >
- <y:yuck " xmlns:y="bar1">blahblah</y:yuck>
- <y:yuck " xmlns:y="bar1">blah</y:yuck>
- </x:foo>
+ <y:yuck " xmlns:y="bar1">blahblah</y:yuck>
+ <y:yuck " xmlns:y="bar1">blah</y:yuck>
+ </x:foo>
</pre>
@@ -603,7 +615,7 @@
<h2>Appendix</h2>
-<h3>Program listing for complete OM - build and serialize</h3>
+<h3>Program Listing for complete OM - build and serialize</h3>
<pre class="code">import org.apache.axis2.om.SOAPEnvelope;
import org.apache.axis2.om.OMFactory;
import org.apache.axis2.om.OMXMLParserWrapper;