You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-dev@axis.apache.org by ch...@apache.org on 2005/02/16 11:02:47 UTC
svn commit: r154012 [4/4] - in
webservices/axis/trunk/java/dev/scratch/prototype2/xdocs: ./ Axis 2 OM
Tutorial_files/ Axis2 Archteture Guide_files/
Added: webservices/axis/trunk/java/dev/scratch/prototype2/xdocs/OM Tutorial.html
URL: http://svn.apache.org/viewcvs/webservices/axis/trunk/java/dev/scratch/prototype2/xdocs/OM%20Tutorial.html?view=auto&rev=154012
==============================================================================
--- webservices/axis/trunk/java/dev/scratch/prototype2/xdocs/OM Tutorial.html (added)
+++ webservices/axis/trunk/java/dev/scratch/prototype2/xdocs/OM Tutorial.html Wed Feb 16 02:02:43 2005
@@ -0,0 +1,1416 @@
+<html>
+
+<head>
+<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
+<meta name=Generator content="Microsoft Word 11 (filtered)">
+<title>OM tutorial</title>
+
+<style>
+<!--
+ /* Font Definitions */
+ @font-face
+ {font-family:Wingdings;
+ panose-1:5 0 0 0 0 0 0 0 0 0;}
+@font-face
+ {font-family:Tahoma;
+ panose-1:2 11 6 4 3 5 4 4 2 4;}
+@font-face
+ {font-family:"Lucida Console";
+ panose-1:2 11 6 9 4 5 4 2 2 4;}
+ /* Style Definitions */
+ p.MsoNormal, li.MsoNormal, div.MsoNormal
+ {margin:0in;
+ margin-bottom:.0001pt;
+ font-size:12.0pt;
+ font-family:"Times New Roman";}
+h1
+ {margin-top:12.0pt;
+ margin-right:0in;
+ margin-bottom:3.0pt;
+ margin-left:0in;
+ page-break-after:avoid;
+ font-size:14.0pt;
+ font-family:Tahoma;}
+h2
+ {margin-top:12.0pt;
+ margin-right:0in;
+ margin-bottom:3.0pt;
+ margin-left:0in;
+ page-break-after:avoid;
+ font-size:11.0pt;
+ font-family:Tahoma;}
+h3
+ {margin-top:12.0pt;
+ margin-right:0in;
+ margin-bottom:3.0pt;
+ margin-left:0in;
+ page-break-after:avoid;
+ font-size:13.0pt;
+ font-family:Arial;}
+p.MsoToc1, li.MsoToc1, div.MsoToc1
+ {margin:0in;
+ margin-bottom:.0001pt;
+ font-size:9.0pt;
+ font-family:Tahoma;}
+p.MsoToc2, li.MsoToc2, div.MsoToc2
+ {margin-top:0in;
+ margin-right:0in;
+ margin-bottom:0in;
+ margin-left:12.0pt;
+ margin-bottom:.0001pt;
+ font-size:9.0pt;
+ font-family:Tahoma;}
+p.MsoToc3, li.MsoToc3, div.MsoToc3
+ {margin-top:0in;
+ margin-right:0in;
+ margin-bottom:0in;
+ margin-left:24.0pt;
+ margin-bottom:.0001pt;
+ font-size:9.0pt;
+ font-family:Tahoma;}
+p.MsoHeader, li.MsoHeader, div.MsoHeader
+ {margin:0in;
+ margin-bottom:.0001pt;
+ font-size:12.0pt;
+ font-family:"Times New Roman";}
+p.MsoFooter, li.MsoFooter, div.MsoFooter
+ {margin:0in;
+ margin-bottom:.0001pt;
+ font-size:12.0pt;
+ font-family:"Times New Roman";}
+a:link, span.MsoHyperlink
+ {color:blue;
+ text-decoration:underline;}
+a:visited, span.MsoHyperlinkFollowed
+ {color:purple;
+ text-decoration:underline;}
+p.MsoDocumentMap, li.MsoDocumentMap, div.MsoDocumentMap
+ {margin:0in;
+ margin-bottom:.0001pt;
+ background:navy;
+ font-size:10.0pt;
+ font-family:Tahoma;}
+span.q1
+ {color:#550055;}
+ /* Page Definitions */
+ @page Section1
+ {size:8.5in 11.0in;
+ margin:1.0in 63.0pt 1.0in 63.0pt;}
+div.Section1
+ {page:Section1;}
+ /* List Definitions */
+ ol
+ {margin-bottom:0in;}
+ul
+ {margin-bottom:0in;}
+-->
+</style>
+
+</head>
+
+<body lang=EN-US link=blue vlink=purple>
+
+<div class=Section1>
+
+<h1 align=center style='text-align:center'><a name="_Toc92017313"></a>OM Tutorial</h1>
+
+<h1>Table of Contents</h1>
+
+<p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc95752358">Section 1
+Introduction<span style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>3</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752359">What is OM?<span
+style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>3</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752360">A Bit of
+History<span style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>3</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752361">Features of
+OM<span style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>3</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752362">High Level
+Architecture<span style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>4</span></a></span></p>
+
+<p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc95752363">Section 2
+Working with OM<span style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>4</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752364">Obtaining the
+OM binary<span style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>4</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752365">Creation<span
+style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>4</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752366">Addition of
+Nodes<span style='color:windowtext;display:none;text-decoration:none'> </span><span
+style='color:windowtext;display:none;text-decoration:none'>6</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752367">Removal of
+Nodes<span style='color:windowtext;display:none;text-decoration:none'> </span><span
+style='color:windowtext;display:none;text-decoration:none'>7</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752368">Handling
+namespaces<span style='color:windowtext;display:none;text-decoration:none'> </span><span
+style='color:windowtext;display:none;text-decoration:none'>7</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752369">Traversing<span
+style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>8</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752370">Serializing<span
+style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>8</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752371">Complete code
+for OM based document building and serialization<span style='color:windowtext;
+display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>9</span></a></span></p>
+
+<p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc95752372">Section 3
+Advanced Operations with OM<span style='color:windowtext;display:none;
+text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>9</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752373">Use of the
+OMNavigator for Traversal<span style='color:windowtext;display:none;text-decoration:
+none'> </span><span
+style='color:windowtext;display:none;text-decoration:none'>9</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752374">Accessing the
+Pull Parser<span style='color:windowtext;display:none;text-decoration:none'> </span><span
+style='color:windowtext;display:none;text-decoration:none'>10</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752375">Building OM
+from Objects - Use of ObjectToOMBuilder<span style='color:windowtext;
+display:none;text-decoration:none'> </span><span
+style='color:windowtext;display:none;text-decoration:none'>10</span></a></span></p>
+
+<p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc95752376">Section 4
+Known Limitations of OM<span style='color:windowtext;display:none;text-decoration:
+none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>11</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752377">Incomplete
+XML Info set support<span style='color:windowtext;display:none;text-decoration:
+none'> </span><span
+style='color:windowtext;display:none;text-decoration:none'>11</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752378">Inefficient
+Namespace serialization<span style='color:windowtext;display:none;text-decoration:
+none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>11</span></a></span></p>
+
+<p class=MsoToc1><span class=MsoHyperlink><a href="#_Toc95752379">Appendix<span
+style='color:windowtext;display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>11</span></a></span></p>
+
+<p class=MsoToc2><span class=MsoHyperlink><a href="#_Toc95752380">Program
+listing for complete OM build and serialize<span style='color:windowtext;
+display:none;text-decoration:none'>. </span><span
+style='color:windowtext;display:none;text-decoration:none'>11</span></a></span></p>
+
+<p class=MsoNormal> </p>
+
+<h1><a name="_Toc92017314"></a><a name="_Toc95752358">Section 1 Introduction</a></h1>
+
+<h2><a name="_Toc95752359">What is </a>OM?</h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+ font-family:Tahoma'>OM</span><span style='font-size:9.0pt;font-family:Tahoma'>
+stands for <b>O</b>bject <b>M</b>odel (also known as AXIOM <b>AX</b>is <b>O</b>bject
+<b>M</b>odel) and refers to the XML info set model that is developed for Axis
+2. 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!</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<h2><a name="_Toc95752360">A Bit of History</a></h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The original OM was proposed as a store for the pull parser
+events for later processing, at the Axis summit held at Colombo during
+September 2004. However this approach was soon improved and OM was pursued as a
+complete info set model due to its flexibility.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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. </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+ font-family:Tahoma'>OM</span><span style='font-size:9.0pt;font-family:Tahoma'>
+was deliberately made API centric. It allows the implementations to take place
+independently and swapped without affecting the program later.</span></p>
+
+<h2><a name="_Toc95752361"></a><a name="_Toc92017315">Features of </a>OM</h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+ font-family:Tahoma'>OM</span><span style='font-size:9.0pt;font-family:Tahoma'>
+is a <b><u>lightweight</u></b>, <b><u>differed built</u></b> XML info set
+representation based on <a href="http://www.jcp.org/en/jsr/detail?id=173">StAX
+(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 jdom),
+but underneath the objects will be created only when they are absolutely
+required. This leads to much less memory intensive programming.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Following is a short feature overview of OM.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='margin-left:.75in;text-align:justify;text-indent:
+-.25in'><span style='font-size:9.0pt;font-family:Symbol'>·<span
+style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>Lightweight </span></p>
+
+<p class=MsoNormal style='margin-left:1.25in;text-align:justify;text-indent:
+-.25in'><span style='font-size:9.0pt;font-family:"Courier New"'>o<span
+style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>OM</span><span
+style='font-size:9.0pt;font-family:Tahoma'> 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.</span></p>
+
+<p class=MsoNormal style='margin-left:.75in;text-align:justify;text-indent:
+-.25in'><span style='font-size:9.0pt;font-family:Symbol'>·<span
+style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>Differed
+building</span></p>
+
+<p class=MsoNormal style='margin-left:1.25in;text-align:justify;text-indent:
+-.25in'><span style='font-size:9.0pt;font-family:"Courier New"'>o<span
+style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>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. </span></p>
+
+<p class=MsoNormal style='margin-left:.75in;text-align:justify;text-indent:
+-.25in'><span style='font-size:9.0pt;font-family:Symbol'>·<span
+style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>Pull based</span></p>
+
+<p class=MsoNormal style='margin-left:1.25in;text-align:justify;text-indent:
+-.25in'><span style='font-size:9.0pt;font-family:"Courier New"'>o<span
+style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>For a differed
+building mechanism a pull based parser is required. OM is based on StAX, the
+standard pull parser API.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'><img width=654 height=71
+src="Axis%202%20OM%20Tutorial_files/image001.gif"
+alt="Text Box: OM is tightly bound to StAX API. To work with OM a StAX compliant parser and the API must be present in the classpath. "></span></p>
+
+<h2><a name="_Toc95752362"> </a></h2>
+
+<h2>High Level Architecture</h2>
+
+<p class=MsoNormal align=center style='text-align:center'>
+
+<table cellpadding=0 cellspacing=0>
+ <tr>
+ <td width=54 height=0></td>
+ </tr>
+ <tr>
+ <td></td>
+ <td><img width=540 height=311
+ src="Axis%202%20OM%20Tutorial_files/image002.jpg"></td>
+ </tr>
+</table>
+
+<br clear=ALL>
+<span style='font-size:9.0pt;font-family:Tahoma'>Figure 1</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>OM Builder wraps
+the raw xml character stream through the StAX reader API. This abstraction
+provides</span></p>
+
+<ul style='margin-top:0in' type=disc>
+ <li class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>differed
+ building support</span></li>
+ <li class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>Caching</span></li>
+</ul>
+
+<p class=MsoNormal style='margin-left:.25in'> </p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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 non-SOAP) based XML documents.</span></p>
+
+<h1><a name="_Toc95752363"></a><a name="_Toc92017316">Section 2 Working with </a>OM </h1>
+
+<h2><a name="_Toc92017317"></a><a name="_Toc95752364">Obtaining the </a>OM binary</h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+ font-family:Tahoma'>OM</span><span style='font-size:9.0pt;font-family:Tahoma'>
+is not a separate product but part of Axis2. Hence the easiest way to obtain
+the OM binary is to build the axis 2 jar file. </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Axis build is based on Maven. For further information on
+Maven (and the binary download) please visit </span><a
+href="http://maven.apache.org/"><span style='font-size:9.0pt;font-family:Tahoma'>http://maven.apache.org</span></a><span
+style='font-size:9.0pt;font-family:Tahoma'>.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Once Maven is properly installed the source should be
+downloaded from the SVN repository. For further information on SVN and client
+programs for both windows and Linux please visit </span><a
+href="http://svn.tigris.org/"><span style='font-size:9.0pt;font-family:Tahoma'>http://svn.tigris.org</span></a><span
+style='font-size:9.0pt;font-family:Tahoma'>.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>After the source download it is the simple maven command
+to build the Axis-M1.jar. All other necessary jars will be automatically
+downloaded.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Once the Axis-M1.jar is created (which can be found in the
+newly created targets directory) 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-M1.jar is correctly in the
+classpath along with the StAX API jar file and a StAX implementation.</span></p>
+
+<h2><a name="_Toc95752365">Creation</a></h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Creation is the first and foremost action in using an
+Object representation. This part explains how OM can be built from an existing
+document or just programmatically.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+ font-family:Tahoma'>OM</span><span style='font-size:9.0pt;font-family:Tahoma'>
+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 (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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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 (such as the SOAPEnvelope, which are sub classes
+of the OMElement) through its builder methods.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal><span style='font-size:10.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>//create the parser</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>XMLStreamReader parser =
+XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>//create the builder</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>OMXMLParserWrapper builder =
+OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMFactory.newInstance(),parser);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>//get the root element (in this case the envelope)</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>SOAPEnvelope envelope =
+(SOAPEnvelope)builder.getDocumentElement();</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'> </span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.1</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console"'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>The
+recommended way to create OM objects programmatically is to use the factory.
+OMFactory.newInstance() will return the proper factory and the creator methods
+for each type should be called. </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Currently OM has two builders, namely the OM builder and
+the SOAP model builder. These builders provide the necessary information to the
+XML info set model to build itself.</span> </p>
+
+<p class=MsoNormal align=center style='text-align:center'><img border=0
+width=420 height=246 src="Axis%202%20OM%20Tutorial_files/image003.jpg"></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:10.0pt;font-family:Tahoma'>Figure 2</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>A simple
+example is shown below.</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:10.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:#993300'>//create a factory</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:maroon'>OMFactory factory =
+OMFactory.newInstance();</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:maroon'>//use the factory to create two
+namespace objects</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:maroon'>OMNamespace ns1 =
+factory.createOMNamespace("bar","x");</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:maroon'>OMNamespace ns2 =
+factory.createOMNamespace("bar1","y");</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:maroon'>//use the factory to create three
+elements</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:maroon'>OMElement root =
+factory.createOMElement("root",ns1);</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:maroon'>OMElement elt11 =
+factory.createOMElement("foo1",ns1);</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:"Lucida Console";color:maroon'>OMElement elt12 =
+factory.createOMElement("foo2",ns1);</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.2</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-family:Tahoma;color:maroon'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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 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 without a builder. In other words programmatically
+built OMNodes do not have a reference to 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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>In order to understand the requirement of the builder
+reference in each and every OMNode, 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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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 builders.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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 <b>API</b> 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 document either with the abstraction of SOAP or drill down to the
+underlying XML Object model with a simple casting. The following illustration
+of the actual class diagram will be helpful in understanding this.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'><img border=0 width=636 height=342
+src="Axis%202%20OM%20Tutorial_files/image004.jpg"></span></p>
+
+<h2><a name="_Toc95752366"></a><a name="_Toc92017318">Addition of Nodes</a></h2>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>Addition
+and removal methods are primarily defined in the OMElement interface. The
+following are the most important in adding nodes.</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>public void addChild(OMNode omNode);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>public void insertAttribute(OMAttribute attr);</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.3</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>This code
+segment shows how the addition takes place. Note that it is related to the code
+segment shown in the creation section.</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>//set the children</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>elt11.addChild(elt21);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>elt12.addChild(elt22);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>root.addChild(elt11);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>root.addChild(elt12);</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.4</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>Note that
+AddChild method will always add the child as the first child of the parent.</span></p>
+
+<h2><a name="_Toc95752367"></a><a name="_Toc92017319">Removal of Nodes</a></h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>A given node can be removed from the tree by calling the detach()
+method.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<h2><a name="_Toc95752368"></a><a name="_Toc92017320">Handling namespaces</a></h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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. </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Almost all the namespace related methods are included in
+the OMNamedNode abstract class and the OMElement class. Following are the
+important methods to handle namespaces.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:"Lucida Console";color:maroon'>public OMNamespace
+declareNamespace(String uri, String prefix);</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:"Lucida Console";color:maroon'>public OMNamespace
+declareNamespace(OMNamespace namespace);</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:"Lucida Console";color:maroon'>public OMNamespace
+findInScopeNamespace(String uri, String prefix) throws OMException;</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:"Lucida Console";color:maroon'>public OMNamespace
+findDeclaredNamespace(String uri, String prefix) throws OMException;</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.5</span></p>
+
+<p class=MsoNormal> </p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma;color:black'>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. These namespace declarations will serialize into xmlns:prefix=uri
+type string inside an element.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma;color:black'>FindInscopeNamespaces 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 its not
+found. The search progresses up the tree until a matching namespace is found or
+the root has been reached.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma;color:black'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span
+style='position:relative;z-index:4'><span style='position:absolute;left:-1px;
+top:-1px;width:654px;height:71px'>
+
+<table cellpadding=0 cellspacing=0>
+ <tr>
+ <td width=654 height=71 bgcolor=silver style='border:.75pt solid black;
+ vertical-align:top;background:silver'><span style='position:absolute;
+ z-index:4'>
+ <table cellpadding=0 cellspacing=0 width="100%">
+ <tr>
+ <td>
+ <div style='padding:4.35pt 7.95pt 4.35pt 7.95pt'>
+ <table class=MsoTableGrid border=0 cellspacing=0 cellpadding=0
+ style='border-collapse:collapse'>
+ <tr>
+ <td width=67 valign=top style='width:.7in;padding:0in 5.4pt 0in 5.4pt'>
+ <p class=MsoNormal style='text-align:justify'><span style='font-size:
+ 9.0pt;font-family:Tahoma;color:black'><img width=35 height=57
+ src="Axis%202%20OM%20Tutorial_files/image005.gif"> </span></p>
+ </td>
+ <td width=576 valign=top style='width:6.0in;padding:0in 5.4pt 0in 5.4pt'>
+ <p class=MsoNormal style='text-align:justify'><b><i><span
+ style='font-size:9.0pt;font-family:Tahoma;color:black'>FindInscopeNamespaces</span></i></b><b><span
+ style='font-size:9.0pt;font-family:Tahoma;color:black'> method can be
+ computationally expensive, if the search commenced from a deep branch of
+ the tree and hence should be used with caution.</span></b></p>
+ <p class=MsoNormal style='text-align:justify'><span style='font-size:
+ 9.0pt;font-family:Tahoma;color:black'> </span></p>
+ </td>
+ </tr>
+ </table>
+ <p class=MsoNormal style='margin-left:1.0in;text-align:justify'> </p>
+ </div>
+ </td>
+ </tr>
+ </table>
+ </span> </td>
+ </tr>
+</table>
+
+</span></span><span style='font-size:9.0pt;font-family:Tahoma;color:black'><img
+border=0 width=649 height=66 src="Axis%202%20OM%20Tutorial_files/image006.gif"></span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma;color:black'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma;color:black'>findDeclaredNamespace is similar to the
+FindInscopeNamespace method except that it searches for the namespace only in
+its own declarations section.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>During the serialization a directly created namespace from
+the factory will only be added to the declarations when that prefix is
+encountered by the serializer. More of the serialization matters will be
+discussed in the serializer section.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The following simple code segment shows how the namespaces
+are dealt with in OM</span></p>
+
+<p class=MsoNormal> </p>
+
+<p class=MsoNormal><span class=q1><span style='font-size:9.0pt;font-family:
+"Lucida Console";color:#993300'>OMFactory factory = OMFactory.newInstance();</span></span><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'><br>
+<span class=q1><span style='color:#993300'>OMNamespace ns1 =
+factory.createOMNamespace("bar","x");</span></span><br>
+OMElement root = factory.createOMElement("root",ns1);<br>
+OMNamespace ns2 = root.declareNamespace("bar1","y");<br>
+<span class=q1><span style='color:#993300'>OMElement elt1 = factory.createOMElement("foo",ns1);</span></span><br>
+<span class=q1><span style='color:#993300'>OMElement elt2 =
+factory.createOMElement("yuck",ns2);</span></span><br>
+<span class=q1><span style='color:#993300'>OMText txt1 =
+factory.createText(elt2,"blah");</span></span><br>
+elt2.addChild(txt1);<br>
+elt1.addChild(elt2);<br>
+root.addChild(elt1);</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.6</span></p>
+
+<p class=MsoNormal> </p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>Serilization
+of the root element produces the following XML </span></p>
+
+<p class=MsoNormal> </p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Arial;color:blue'><x:root
+xmlns:x="bar" xmlns:y="bar1"><br>
+<x:foo><br>
+ <y:yuck>blah</y:yuck><br>
+ </x:foo><br>
+</x:root></span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Arial;color:blue'> </span></p>
+
+<h2><a name="_Toc95752369"></a><a name="_Toc92017321">Traversing</a></h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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
+more convenient than a list for sequential access.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>Iterator children = root.getChildren();</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>While(children.hasNext()){</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> OMNode node = (OMNode)children.next();</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>}</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.7</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Apart from this every OMNode has links to its siblings. If
+more thorough navigation is needed the nextSibling() and PreviousSibling()
+methods can be used.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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 children. The advantage of these iterators is that
+they wont build the whole object structure at once, until its required.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'><img width=654 height=84
+src="Axis%202%20OM%20Tutorial_files/image007.gif"
+alt="Text Box: 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. "></span></p>
+
+<h2><a name="_Toc95752370"></a><a name="_Toc92017324">Serializing</a></h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The most interesting part of the OM is its serialization. Serilalization
+refers to writing out the object structure to another form (most probably text)</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+ font-family:Tahoma'>OM</span><span style='font-size:9.0pt;font-family:Tahoma'>
+can be serialized either as the pure object model or the pull event stream. The
+serialization uses a XMLStreamWriter 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.,).</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>A caching flag is provided by OM to control the building of
+the in-memory OM.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The OMNode has a method serialize(XMLStreamWriter,cache).
+When the cache flag is reset the serializer does not cache the stream. Hence
+the object model will not be built if the cache flag is not set. </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The serializer serializes namespaces the following way.</span></p>
+
+<p class=MsoNormal style='margin-left:.5in;text-align:justify;text-indent:-.25in'><span
+style='font-size:9.0pt;font-family:Tahoma'>1.<span style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>When a namespace
+that is in the scope but not yet declared is encountered, then it will be
+declared.</span></p>
+
+<p class=MsoNormal style='margin-left:.5in;text-align:justify;text-indent:-.25in'><span
+style='font-size:9.0pt;font-family:Tahoma'>2.<span style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>When a namespace
+that is in scope and already declared is encountered, the existing declarations
+prefix is used.</span></p>
+
+<p class=MsoNormal style='margin-left:.5in;text-align:justify;text-indent:-.25in'><span
+style='font-size:9.0pt;font-family:Tahoma'>3.<span style='font:7.0pt "Times New Roman"'>
+</span></span><span style='font-size:9.0pt;font-family:Tahoma'>When the
+namespaces are declared explicitly using the elements declareNamespace()
+method, they will be serialized even if those namespaces are not used in that
+scope.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Because of this behavior, if a fragment of the XML is
+serialized, it will also be "namespace qualified" with the necessary
+namespace declarations.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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 envelope.</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>XMLStreamWriter writer =
+XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>//dump the output to console with caching</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>envelope.serialize(writer,true);</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.8</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>The example
+is from code listing 2.6 which creates a small OM programmatically.</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>Serialization
+of the root element produces</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Arial;color:blue'><x:root
+xmlns:x="bar" xmlns:y="bar1"><br>
+<x:foo><br>
+ <y:yuck>blah</y:yuck><br>
+ </x:foo><br>
+</x:root></span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>However
+serialization of only the <b>foo</b> element produces </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Arial;color:blue'><br>
+<x:foo xmlns:x="bar"><br>
+ <y:yuck xmlns:y="bar1">blah</y:yuck><br>
+ </x:foo><br>
+<br>
+</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>Note how
+the serializer puts the relevant namespace declarations in place.</span></p>
+
+<h2><a name="_Toc95752371">Complete code for the </a>OM based document building
+and serialization</h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'> </p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>//create the parser</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>XMLStreamReader parser =
+XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>//create the builder</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>OMXMLParserWrapper builder =
+OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMFactory.newInstance(),parser);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>//get the root element (in this case the envelope)</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>SOAPEnvelope envelope =
+(SOAPEnvelope)builder.getDocumentElement();</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:maroon'>//get the writer</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>XMLStreamWriter writer =
+XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>//dump the out put to console with caching</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:"Lucida Console";color:#993300'>envelope.serialize(writer,true);</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 2.9</span></p>
+
+<p class=MsoNormal style='text-align:justify'> </p>
+
+<h1><a name="_Toc95752372">Section 3 Advanced Operations with </a>OM</h1>
+
+<h2><a name="_Toc95752373"></a><a name="_Toc92017322">Use of the OMNavigator</a>
+for Traversal</h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>OM provides a utility class to navigate the OM structure. The navigator provides an in-order traversal of the OM tree <b><i>up to the
+last-built node.</i></b> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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 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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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
+navigable. When the navigator is complete it is not navigable anymore. However
+it is possible for a navigator to become non-navigable without being complete.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The following code sample shows how the navigator should be
+used and handled using its states.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>//Create a navigator</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>OMNavigator navigator = new OMNavigator(envelope);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>OMNode node = null;</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>while (navigator.isNavigable()) {</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> node = navigator.next();</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>}</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 3.1</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> </span></p>
+
+<h2><a name="_Toc95752374"></a><a name="_Toc92017323">Accessing the Pull Parser</a>
+</h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+ font-family:Tahoma'>OM</span><span style='font-size:9.0pt;font-family:Tahoma'>
+is tightly integrated with StAX and the getPullParser(Boolean cache) method in
+the OMElement provides a XMLStreamReader object. </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>This XMLStreamReader 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 completely transparent to the
+user. This is further explained in the following paragraphs.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The getPullparser() 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. </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'><img width=654 height=79
+src="Axis%202%20OM%20Tutorial_files/image008.gif"
+alt="Text Box: For consistency reasons once the cache is switched off it cannot be switched on again. "></span></p>
+
+<h2><a name="_Toc95752375">Building </a>OM from Objects - Use of ObjectToOMBuilder</h2>
+
+<p class=MsoNormal> </p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>There is a requirement to build an OM with a given object
+structure. A Typical scenario will be to build OM from an object structure that
+is returned from a data binding tool. So when the need arises to generate an OM from an object, a special builder class is to be used. The ObjectToOMBuilder class
+implements the XMLParserWrapper (which is effectively the builder interface), but
+unlike the other builders such a conversion cannot be pull based. It is push
+based which means that the builder should have access to a content handler in
+order to push events. Hence the ObjectToOmBuilder implements the
+registerContentHandler method which accepts an instance of the SAX ContentHandler.interface.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>In serializing however the user need not worry whether the
+inner parts of the OM tree consists of Object builders which are push based.
+The serializing mechanism automatically registers a
+StreamToContentHandlerConverter which effectively redirects all the
+ContentHandler events into the relevant XMLStreamWriter. </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The ObjectToOMBuilder expects an
+org.apache.axis.om.OutObject interface from the third party for registering a
+SAX ContentHandler. The ObjctToOMBuilder should also be supplied with the
+parent element which the supplied object should be serialized under. When the ObjectToOMBuilder
+is asked to proceed the call is in turn passed to the OutObject to fire SAX
+events. The ObjectToOMBuilder will take care of building the structure (if
+needed).</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The following code segment explains this scenario</span><span
+style='font-size:10.0pt;font-family:Tahoma'>.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:10.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span class=q1><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'>// create
+the parent element</span></span></p>
+
+<p class=MsoNormal style='text-align:justify'><span class=q1><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'>OMFactory
+omFactory = OMFactory.newInstance();</span></span></p>
+
+<p class=MsoNormal style='text-align:justify'><span class=q1><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'>OMNamespace
+ns = omFactory.createOMNamespace(OMConstants.SOAP_ENVELOPE_NAMESPACE_URI,
+OMConstants.SOAPENVELOPE_NAMESPACE_PREFIX);</span></span></p>
+
+<p class=MsoNormal style='text-align:justify'><span class=q1><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'>
+element = omFactory.createOMElement("Body", ns);</span></span></p>
+
+<p class=MsoNormal style='text-align:justify'><span class=q1><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'> </span></span></p>
+
+<p class=MsoNormal style='text-align:justify'><span class=q1><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'>OutObject
+outObject = // get the third party object here</span></span></p>
+
+<p class=MsoNormal style='text-align:justify'><span class=q1><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'>new
+ObjectToOMBuilder(element,outObject).next();</span></span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 3.2</span></p>
+
+<h1><a name="_Toc95752376">Section 4 Known Limitations of </a>OM</h1>
+
+<h2><a name="_Toc95752377">Incomplete XML Info set support</a></h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>The OM deliberately dropped the support for XML info set
+items such as DTDs and Processing Instructions (PIs). Hence the OM cannot be called a complete info set representation. The initial reason for this was
+because the design goal of the OM was not to be yet-another-object-model but
+to be a SOAP specific Object model. Since DTDs and PIs are not supposed to be
+present in SOAP messages.</span></p>
+
+<h2><a name="_Toc95752378">Inefficient Namespace serialization</a></h2>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>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.</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span class=q1><span style='font-size:9.0pt;font-family:
+"Lucida Console";color:#993300'>OMFactory factory = OMFactory.newInstance();</span></span><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'><br>
+<span class=q1><span style='color:#993300'>OMNamespace ns1 =
+factory.createOMNamespace("bar","x");</span></span><br>
+OMElement root = factory.createOMElement("root",ns1);<br>
+OMNamespace ns2 = root.declareNamespace("bar1","y");<br>
+<span class=q1><span style='color:#993300'>OMElement elt1 =
+factory.createOMElement("foo",ns1);</span></span><br>
+<span class=q1><span style='color:#993300'>OMElement elt2 =
+factory.createOMElement("yuck",ns2);</span></span></span></p>
+
+<p class=MsoNormal><span class=q1><b><span style='font-size:9.0pt;font-family:
+"Lucida Console";color:#993300'>OMElement elt3 =
+factory.createOMElement("yuck",ns2);</span></b></span><b><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'><br>
+</span></b><span class=q1><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>OMText txt1 = factory.createText(elt2,"blah");</span></span></p>
+
+<p class=MsoNormal><span class=q1><b><span style='font-size:9.0pt;font-family:
+"Lucida Console";color:#993300'>OMText txt2 = factory.createText(elt3,"blahblah");</span></b></span><b><span
+style='font-size:9.0pt;font-family:"Lucida Console";color:#993300'><br>
+elt3.addchild(txt2);</span></b></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>elt2.addChild(txt1);<br>
+elt1.addChild(elt2);</span></p>
+
+<p class=MsoNormal><b><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>elt1.addChild(elt3);</span></b></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>root.addChild(elt1);</span></p>
+
+<p class=MsoNormal align=center style='text-align:center'><span
+style='font-size:9.0pt;font-family:Tahoma'>Code listing 4.1</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>Serialization of the root element provides the following
+XML</span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Arial;color:blue'><x:root
+xmlns:x="bar" xmlns:y="bar1"><br>
+<x:foo></span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Arial;color:blue'>
+ <y:yuck>blahblah</y:yuck><br>
+ <y:yuck>blah</y:yuck><br>
+ </x:foo><br>
+</x:root></span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal style='text-align:justify'><span style='font-size:9.0pt;
+font-family:Tahoma'>However if the serialization is carried on the foo element then
+the following XML is produced</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Arial;color:blue'><x:foo
+xmlns:x="bar" ></span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Arial;color:blue'>
+ <y:yuck <b>" xmlns:y="bar1"</b>>blahblah</y:yuck><br>
+ <y:yuck " <b>xmlns:y="bar1"</b>>blah</y:yuck><br>
+ </x:foo></span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>Note that
+the same Namespace is serialized twice. This XML is semantically correct but
+the same semantics could have been achieved by placing the y namespace
+declaration on the parent element. </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'>This
+behavior is due to the nature of the serialization where it tries to be
+accurate but not optimal. It is deliberately kept unchanged since such optimizations
+slow down the common case. </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:Tahoma'> </span></p>
+
+<h1><a name="_Toc95752379">Appendix</a></h1>
+
+<h2><a name="_Toc95752380">Program listing for complete </a>OM build and
+serialize</h2>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>import org.apache.axis.om.SOAPEnvelope;</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>import org.apache.axis.om.OMFactory;</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>import org.apache.axis.om.OMXMLParserWrapper;</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>import org.apache.axis.impl.llom.factory.OMXMLBuilderFactory;</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>import javax.xml.stream.*;</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>import java.io.FileReader;</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>import java.io.FileNotFoundException;</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>public class TestOMBuilder {</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> </span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> /**</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> * Pass the file name as an argument</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> * @param args</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> */</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> public static void main(String[] args) {</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> try {</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> //create the parser</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> XMLStreamReader parser =
+XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(args[0]));</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> //create the builder</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> OMXMLParserWrapper builder =
+OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMFactory.newInstance(),
+parser);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> //get the root element (in this case the envelope)</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> SOAPEnvelope envelope = (SOAPEnvelope)
+builder.getDocumentElement();</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> //get the writer</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> XMLStreamWriter writer =
+XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> //dump the out put to console with caching</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> envelope.serialize(writer, true);</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> } catch (XMLStreamException e) {</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> e.printStackTrace();</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> } catch (FileNotFoundException e) {</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> e.printStackTrace();</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> }</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'> }</span></p>
+
+<p class=MsoNormal><span style='font-size:9.0pt;font-family:"Lucida Console";
+color:#993300'>}</span></p>
+
+</div>
+
+</body>
+
+</html>