Author: dims
Date: Sat May 6 14:28:22 2006
New Revision: 400373
URL: http://svn.apache.org/viewcvs?rev=400373&view=rev
Log:
don't prettify output even for illustration, use FileInputStream to prevent
problems loading xml files that are not utf-8
Modified:
webservices/commons/site/axiom/OMTutorial.html
Modified: webservices/commons/site/axiom/OMTutorial.html
URL:
http://svn.apache.org/viewcvs/webservices/commons/site/axiom/OMTutorial.html?rev=400373&r1=400372&r2=400373&view=diff
==============================================================================
--- webservices/commons/site/axiom/OMTutorial.html (original)
+++ webservices/commons/site/axiom/OMTutorial.html Sat May 6 14:28:22 2006
@@ -1,9 +1,9 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html><head><title>Web
Services Commons : AXIOM Implemenation - OM Tutorial</title><style
type="text/css" media="all">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html><head><title>OM
Tutorial - Web Services Commons : AXIOM Implemenation</title><style
type="text/css" media="all">
@import url("./style/maven-base.css");
- @import
url("./style/maven-theme.css");</style><link rel="stylesheet"
href="./style/print.css" type="text/css" media="print"></link><meta
http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a
href="http://www.apache.org/"; id="organizationLogo"><img alt="Apache Software
Foundation" src="http://www.apache.org/images/asf-logo.gif";></img></a><a
href="http://ws.apache.org/commons/axiom"; id="projectLogo"><img alt="Apache
AXIOM" src="http://www.apache.org/images/asf-logo.gif";></img></a><div
class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 03 May 2006
- | Doc for 1.0</div><div class="xright"></div><div
class="clear"><hr></hr></div></div><div id="leftColumn"><div
id="navcolumn"><div id="menuAXIOM"><h5>AXIOM</h5><ul><li class="none"><a
href="index.html">Home</a></li><li class="expanded"><a href=""></a><ul><li
class="none"><a href="download.cgi">Releases</a></li><li class="none"><a
href="http://svn.apache.org/repos/asf/webservices/commons/trunk/modules/axiom/";
class="externalLink" title="External Link">Source Code</a></li></ul></li><li
class="expanded"><a href="">Documentation</a><ul><li class="none"><a
href="OMTutorial.html">OM Tutorial</a></li><li class="none"><a
href="apidocs/index.html">Javadocs</a></li><li class="none"><a
href="svn.html">Checkout Source</a></li></ul></li><li class="expanded"><a
href="">Project Information</a><ul><li class="none"><a
href="mail-lists.html">Mailing Lists</a></li><li class="none"><a
href="team-list.html">Project Team</a></li><li class="none"><a
href="http://issues.apache.org
/jira/browse/WSCOMMONS" class="externalLink" title="External Link">Issue
Tracking</a></li><li class="none"><a
href="dependencies.html">Dependencies</a></li></ul></li><li class="none"><a
href="http://www.apache.org/licenses/LICENSE-2.0.html"; class="externalLink"
title="External Link">License</a></li></ul></div><a
href="http://maven.apache.org/"; title="Built by Maven" id="poweredBy"><img
alt="Built by Maven"
src="./images/logos/maven-button-1.png"></img></a></div></div><div
id="bodyColumn"><div class="contentBox"><div class="section"><p>
+ @import url("./style/maven-theme.css");</style><link
rel="stylesheet" href="./style/print.css" type="text/css"
media="print"></link><meta http-equiv="Content-Type" content="text/html;
charset=ISO-8859-1"></meta></head><body class="composite"><div id="banner"><a
href="http://www.apache.org/"; id="organizationLogo"><img alt="Apache Software
Foundation" src="http://www.apache.org/images/asf-logo.gif";></img></a><a
href="http://ws.apache.org/commons/axiom"; id="projectLogo"><img alt="Apache
AXIOM" src="http://www.apache.org/images/asf-logo.gif";></img></a><div
class="clear"><hr></hr></div></div><div id="breadcrumbs"><div
class="xleft">Last published: 06 May 2006
+ <span class="separator">|</span> Doc for SNAPSHOT
+ </div><div class="xright"></div><div
class="clear"><hr></hr></div></div><div id="leftColumn"><div
id="navcolumn"><div id="menuAXIOM"><h5>AXIOM</h5><ul><li class="none"><a
href="index.html">Home</a></li><li class="expanded"><a href=""></a><ul><li
class="none"><a href="download.cgi">Releases</a></li><li class="none"><a
href="http://svn.apache.org/repos/asf/webservices/commons/trunk/modules/axiom/";
class="externalLink" title="External Link">Source Code</a></li></ul></li><li
class="expanded"><a href="">Documentation</a><ul><li class="none"><a
href="OMTutorial.html">OM Tutorial</a></li><li class="none"><a
href="apidocs/index.html">Javadocs</a></li><li class="none"><a
href="svn.html">Checkout Source</a></li></ul></li><li class="expanded"><a
href="">Project Information</a><ul><li class="none"><a
href="mail-lists.html">Mailing Lists</a></li><li class="none"><a
href="team-list.html">Project Team</a></li><li class="none"><a
href="http://issues.apache.org/jira/browse/WS
COMMONS" class="externalLink" title="External Link">Issue Tracking</a></li><li
class="none"><a href="dependencies.html">Dependencies</a></li></ul></li><li
class="none"><a href="http://www.apache.org/licenses/LICENSE-2.0.html";
class="externalLink" title="External Link">License</a></li></ul></div><div
id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li
class="newWindow">Opens in a new window</li></ul></div><a
href="http://maven.apache.org/"; title="Built by Maven" id="poweredBy"><img
alt="Built by Maven"
src="./images/logos/maven-button-1.png"></img></a></div></div><div
id="bodyColumn"><div class="contentBox"><div class="section"><p>
</p></div><div class="section"><a name="OM_Tutorial"></a><h2>OM
Tutorial</h2><div class="subsection"><a
name="Introduction"></a><h3>Introduction</h3></div><div class="subsection"><a
name="What_is_OM_"></a><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 initialy developed for Apache Axis2.
XML infoset
@@ -66,11 +66,17 @@
required. OM is based on StAX, the standard pull parser API.</li>
</ul><p>
-</p><p class="special"></p><table class="bodyTable"><tbody>
- <tr class="b"><td><img src="images/OM005.gif" alt="Remember this"
width="35" height="57"></img></td><td class="special-td">OM is tightly bound to
StAX API. To work with OM
+</p><p class="special"></p><table class="bodyTable">
+ <tbody>
+ <tr class="a">
+ <td><img src="images/OM005.gif" alt="Remember this" width="35"
height="57"></img></td>
+ <td class="special-td">OM is tightly bound to StAX API. To work with OM
a StAX compliant parser and the API <i>must</i> be present in the
- classpath.</td><td></td></tr>
- </tbody></table><p>
+ classpath.</td>
+ <td></td>
+ </tr>
+ </tbody>
+</table><p>
</p><p>The Following image shows how OM API is viewed by the user</p><p>
@@ -118,7 +124,7 @@
<p><b>Code Listing 1</b></p>
</div>
<div class="source"><pre><pre>//create the parser<br></br>
-XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
+XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileInputStream(file));
<br></br>//create the builder<br></br>
StAXOMBuilder builder = new StAXOMBuilder(parser);
//get the root element (in this case the envelope)<br></br>
@@ -245,12 +251,8 @@
root.addChild(elt1);
</pre></div>
- <p>Serilization of the root element produces the following XML</p>
- <div class="source"><pre><x:root xmlns:x="bar" xmlns:y="bar1">
- <x:foo>
- <y:yuck>blah</y:yuck>
- </x:foo>
-</x:root>
+ <p>Serialization of the root element produces the following XML</p>
+ <div class="source"><pre><x:root xmlns:x="bar"
xmlns:y="bar1"><x:foo><y:yuck>blah</y:yuck></x:foo></x:root>
</pre></div>
</div><div class="subsection"><a
name="Traversing"></a><h3>Traversing</h3><p>Traversing the object structure can
be done in the usual way by using the
@@ -276,13 +278,19 @@
children. The advantage of these iterators is that they won't build the whole
object structure at once, until its required.</p><p>
-</p><p class="special"></p><table class="bodyTable"><tbody>
- <tr class="a"><td><img src="images/OM005.gif" alt="Remember this"
width="35" height="57"></img></td><td class="special-td">All iterator
implementations internally stay one
+</p><p class="special"></p><table class="bodyTable">
+ <tbody>
+ <tr class="b">
+ <td><img src="images/OM005.gif" alt="Remember this" width="35"
height="57"></img></td>
+ <td class="special-td">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
that are not intended to be built at all. Hence these iterators are
- recommended only when caching is not a concern.</td><td></td></tr>
- </tbody></table><p>
+ recommended only when caching is not a concern.</td>
+ <td></td>
+ </tr>
+ </tbody>
+</table><p>
</p><p>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
@@ -322,17 +330,11 @@
accurately figure out the namespaces. The example is from Code Listing 6
which creates a small OM programmatically. Serialization of the root element
produces the following,</p>
- <div class="source"><pre><x:root xmlns:x="bar" xmlns:y="bar1">
- <x:foo>
- <y:yuck>blah</y:yuck>
- </x:foo>
-</x:root>
+ <div class="source"><pre><x:root xmlns:x="bar"
xmlns:y="bar1"><x:foo><y:yuck>blah</y:yuck></x:foo></x:root>
</pre></div>
<p>However serialization of only the foo element produces the following</p>
- <div class="source"><pre><x:foo xmlns:x="bar">
-<y:yuck xmlns:y="bar1">blah</y:yuck>
-</x:foo>
+ <div class="source"><pre><x:foo xmlns:x="bar"><y:yuck
xmlns:y="bar1">blah</y:yuck></x:foo>
</pre></div>
<p>Note how the serializer puts the relevant namespace declarations in
@@ -343,7 +345,7 @@
<p><b>Code Listing 9</b></p>
</div>
<div class="source"><pre>//create the parser
-XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
+XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileInputStream(file));
//create the builder
StAXOMBuilder builder = new StAXOMBuilder(parser);
@@ -395,10 +397,16 @@
events need to be handled in a pull based manner without any intermediate
models. This makes such operations faster and efficient.</p><p>
-</p><p class="special"></p><table class="bodyTable"><tbody>
- <tr class="b"><td><img src="images/OM005.gif" alt="Remember this"
width="35" height="57"></img></td><td class="special-td">For consistency
reasons once the cache is
- switched off it cannot be switched on again.</td><td></td></tr>
- </tbody></table><p>
+</p><p class="special"></p><table class="bodyTable">
+ <tbody>
+ <tr class="a">
+ <td><img src="images/OM005.gif" alt="Remember this" width="35"
height="57"></img></td>
+ <td class="special-td">For consistency reasons once the cache is
+ switched off it cannot be switched on again.</td>
+ <td></td>
+ </tr>
+ </tbody>
+</table><p>
</p></div><div class="subsection"><a
name="Known_Limitations_of_OM"></a><h3>Known Limitations of OM</h3></div><div
class="subsection"><a
name="Inefficient_Namespace_serialization"></a><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
@@ -422,22 +430,14 @@
</pre></div>
<p>Serialization of the root element provides the following XML</p>
- <div class="source"><pre><x:root xmlns:x="bar" xmlns:y="bar1">
-<x:foo>
- <y:yuck>blahblah</y:yuck>
- <y:yuck>blah</y:yuck>
-</x:foo>
-</x:root>
+ <div class="source"><pre><x:root xmlns:x="bar"
xmlns:y="bar1"><x:foo><y:yuck>blahblah</y:yuck><y:yuck>blah</y:yuck></x:foo></x:root>
</pre></div>
<p>However if the serialization is carried on the foo element then the
following XML is produced</p>
- <div class="source"><pre><x:foo xmlns:x="bar" >
- <y:yuck " xmlns:y="bar1">blahblah</y:yuck>
- <y:yuck " xmlns:y="bar1">blah</y:yuck>
-</x:foo>
+ <div class="source"><pre><x:foo xmlns:x="bar" ><y:yuck
xmlns:y="bar1">blahblah</y:yuck><y:yuck
xmlns:y="bar1">blah</y:yuck></x:foo>
@@ -457,7 +457,7 @@
import org.apache.axis2.impl.llom.factory.OMXMLBuilderFactory;
import javax.xml.stream.*;
-import java.io.FileReader;
+import java.io.FileInputStream;
import java.io.FileNotFoundException;
public class TestOMBuilder {
@@ -469,7 +469,7 @@
public static void main(String[] args) {
try {
//create the parser
- XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(args[0]));
+ XMLStreamReader parser =
XMLInputFactory.newInstance().createXMLStreamReader(new
FileInputStream(args[0]));
//get the root element (in this case the envelope)
OMElement documentElement = builder.getDocumentElement();
@@ -495,7 +495,11 @@
<li><a href="http://www.bearcave.com/software/java/xml/xmlpull.html";
class="externalLink" title="External Link">Introduction
to Pull parsing</a></li>
</ul>
-</p></div></div><div class="section"><table class="bodyTable"><tbody>
- <tr class="a"><td align="center">All rights reserved by Apache Software
- Foundation</td></tr>
- </tbody></table></div></div></div><div class="clear"><hr></hr></div><div
id="footer"><div class="xright">© 2004-2006, Apache Software
Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
+</p></div></div><div class="section"><table class="bodyTable">
+ <tbody>
+ <tr class="b">
+ <td align="center">All rights reserved by Apache Software
+ Foundation</td>
+ </tr>
+ </tbody>
+</table></div></div></div><div class="clear"><hr></hr></div><div
id="footer"><div class="xright">© 2004-2006, Apache Software
Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
![http://www.apache.org/images/asf-logo.gif"](http://www.apache.org/images/asf-logo.gif"){kind=link}