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 di...@apache.org on 2006/05/07 16:50:54 UTC
svn commit: r404774 - /webservices/axis2/site/1_0/OMTutorial.html
Author: dims
Date: Sun May 7 07:50:52 2006
New Revision: 404774
URL: http://svn.apache.org/viewcvs?rev=404774&view=rev
Log:
sync with axiom tutorial update
Modified:
webservices/axis2/site/1_0/OMTutorial.html
Modified: webservices/axis2/site/1_0/OMTutorial.html
URL: http://svn.apache.org/viewcvs/webservices/axis2/site/1_0/OMTutorial.html?rev=404774&r1=404773&r2=404774&view=diff
==============================================================================
--- webservices/axis2/site/1_0/OMTutorial.html (original)
+++ webservices/axis2/site/1_0/OMTutorial.html Sun May 7 07:50:52 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>Axis 2.0 - 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 - Axis 2.0</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/axis2/" id="projectLogo"><img alt="Apache Axis 2.0" src="http://ws.apache.org/axis2/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 05 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="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../">Downloads</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><li class="none"><a href="../modules/index.html">Modules</a></li><li class="none"><a href="../tools/index.html">Tools</a></li></ul></li><li class="expanded"><a href="../">Documentation</a><ul><li class="none"><a href="../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../0_93/index.html">Version 0.93</a></li></ul></li><l
i class="expanded"><a href="../overview.html">Get Involved</a><ul><li class="none"><a href="../svn.html">Checkout the Source</a></li><li class="none"><a href="../siteHowTo.html">Build the Site</a></li><li class="none"><a href="../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../refLib.html">Reference Library</a></li><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../faq.html">FAQ</a></li></ul></li><li class="none"><a href="../thanks.html">Acknowledgements</a></li><li class="none"><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li><li class="expanded"><a href="../">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><a href="http://maven.apache.org/" title="Built by Maven" id="poweredBy"><img alt="Built by M
aven" 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/axis2/" id="projectLogo"><img alt="Apache Axis 2.0" src="http://ws.apache.org/axis2/images/axis.jpg"></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="menuAxis_2_0"><h5>Axis 2.0</h5><ul><li class="none"><a href="../index.html">Home</a></li><li class="expanded"><a href="../">Downloads</a><ul><li class="none"><a href="../download.cgi">Releases</a></li><li class="none"><a href="http://svn.apache.org/viewcvs.cgi/webservices/axis2/trunk/?root=Apache-SVN" class="externalLink" title="External Link">Source Code</a></li><li class="none"><a href="../modules/index.html">Modules</a></li><li class="none"><a href="../tools/index.html">Tools</a></li></ul></li><li class="expanded"><a href="../">Documentation</a><ul><li class="none"><a href="../1_0/index.html">Version 1.0</a></li><li class="none"><a href="../0_95/index.html">Version 0.95</a></li><li class="none"><a href="../0_94/index.html">Version 0.94</a></li><li class="none"><a href="../0_93/index.html">Version 0.93</a></li></ul></li><li class="expand
ed"><a href="../overview.html">Get Involved</a><ul><li class="none"><a href="../svn.html">Checkout the Source</a></li><li class="none"><a href="../siteHowTo.html">Build the Site</a></li><li class="none"><a href="../guidelines.html">Developer Guidelines</a></li><li class="none"><a href="../refLib.html">Reference Library</a></li><li class="none"><a href="../mail-lists.html">Mailing Lists</a></li><li class="none"><a href="../faq.html">FAQ</a></li></ul></li><li class="none"><a href="../thanks.html">Acknowledgements</a></li><li class="none"><a href="http://www.apache.org/licenses/LICENSE-2.0.html" class="externalLink" title="External Link">License</a></li><li class="expanded"><a href="../">Project Information</a><ul><li class="none"><a href="../team-list.html">Project Team</a></li><li class="none"><a href="../issue-tracking.html">Issue Tracking</a></li></ul></li></ul></div><div id="legend"><h5>Legend</h5><ul><li class="externalLink">External Link</li><li class="newWindow">Opens i
n 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="AXIOM_Tutorial"></a><h2>AXIOM Tutorial</h2><p>This document will contain information on the Object Model of Axis2. The
information include an introduction to AXIOM and it's functionalities, data
@@ -108,11 +108,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>
@@ -161,7 +167,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>
@@ -287,11 +293,7 @@
</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>
+ <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><a name="traversing"></a></p></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
list of children. Note however that the child nodes are returned as an
@@ -316,13 +318,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
@@ -360,17 +368,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
@@ -381,7 +383,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);
@@ -431,10 +433,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>
<a name="limitations"></a></p></div><div class="subsection"><a name="Known_Limitations_of_OM"></a><h3>Known Limitations of OM</h3><p><a name="namespace_serialization"></a></p></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
a similar Code Listing to Code Listing 6 is used, but with two elements
@@ -457,20 +465,12 @@
</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>
</pre></div>
<p>Note that the same Namespace is serialized twice. This XML is semantically
@@ -488,7 +488,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 {
@@ -500,7 +500,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();
@@ -527,7 +527,11 @@
to Pull parsing</a></li>
</ul>
</li></ul><p>
-</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