You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ws.apache.org by ch...@apache.org on 2005/12/02 15:01:09 UTC
svn commit: r351729 [2/12] - in /webservices/site/trunk/targets/axis2: ./
images/ images/archi-guide/ images/userguide/ multiproject/axis2-Samples/
multiproject/axis2-Samples/amazonSearch/ multiproject/axis2-Tools/
multiproject/axis2-addressing/ multip...
Modified: webservices/site/trunk/targets/axis2/OMTutorial.html
URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/OMTutorial.html?rev=351729&r1=351728&r2=351729&view=diff
==============================================================================
--- webservices/site/trunk/targets/axis2/OMTutorial.html (original)
+++ webservices/site/trunk/targets/axis2/OMTutorial.html Fri Dec 2 05:57:44 2005
@@ -2,76 +2,140 @@
@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/axis/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 26 September 2005
- | Doc for 0.92</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="">Download Axis2</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></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api/index.html">Online Java Docs</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</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="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="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 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="Section_1-Introduction"></a><h3>Section 1-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 developed for Axis 2.
-XML infoset refers to the information included inside the XML and for programmatical manipulation it is convenient to have a representation of this XML infoset in a language specific manner. For an object oriented language the obvious choice is a model made up of objects. DOM and JDOM are two such XML models. OM is conceptually similar to such an XML model by its external behavior but deep down it is very much different.
-The objective of this tutorial is to introduce the basics of OM and explain the best practices to follow while using OM. However before entering the deep ends of OM it is better to skim the surface and see what it is all about!</p></div><div class="subsection"><a name="For_whom_is_this_Tutorial_"></a><h3>For whom is this Tutorial?</h3><p>This tutorial can be used by anybody who is interested in OM and needs to go deeper in it. However it is assumed that the reader has a basic understanding of the concepts of XML (such as Namespaces) and a working knowledge of tools such as Ant. Knowledge in similar object models such as DOM will be quite helpful in understanding but such knowledge is not assumed.
-Several Links are listed in the appendix/ links section that will help anybody who lacks the basic understanding of XML.</p></div><div class="subsection"><a name="What_is_pull_parsing__"></a><h3>What is pull parsing ?</h3><p>
-Pull parsing is a recent trend in XML processing. The previously popular XML processing frameworks such as SAX and DOM were "push-based" which means
-the control of the parsing was with the parser itself. This approach is fine and easy to use but it was not efficient in
-handling large XML documents since a complete memory model will be generated in the memory. Pull parsing inverts the control
-and hence the parser only proceeds at the users command. The user can decide to store or discard events generated from the
-parser.
-OM is based on pull parsing. To learn more about XML pull parsing see the <a href="http://www.bearcave.com/software/java/xml/xmlpull.html" class="externalLink" title="External Link">XML pull parsing introduction</a>.
-</p></div><div class="subsection"><a name="A_Bit_of_History"></a><h3>A Bit of History</h3><p>The original OM was proposed as a store for the pull parser events for later processing, at the Axis summit held at Colombo in September 2004. However this approach was soon improved and OM was pursued as a complete info set model due to its flexibility.
-Several implementation techniques were attempted during the initial phases. The two most promising techniques were the table based technique and the link list based technique. During the intermediate performance tests the link list based technique proved to be much more memory efficient for smaller and mid sized XML documents (the advantage of the table based OM was only visible for the large and very large XML documents) and hence the link list based technique was chosen as the most suitable.
-Initial efforts were focused on implementing the XML info set items which are relevant to the SOAP specification (DTD support, Processing Instruction support, etc were not considered). The advantage of having a tight integration was evident at this stage and this resulted in having SOAP specific interfaces as part of OM rather than a layer on top of it.
-OM was deliberately made API centric. It allows the implementations to take place independently and swapped without affecting the program later.</p></div><div class="subsection"><a name="Features_of_OM"></a><h3>Features of OM</h3><p>OM is a lightweight, differed built XML info set representation based on StAX (<a href="http://www.jcp.org/aboutJava/communityprocess/first/jsr173/" class="externalLink" title="External Link">JSR 173</a>), which is the standard streaming pull parser API. The object model can be manipulated as flexibly as any other object model (Such as
-<a href="http://www.jdom.org/" class="externalLink" title="External Link">JDOM</a>), but underneath the objects will be created only when they are absolutely required. This leads to much less memory intensive programming.
-Following is a short feature overview of OM.</p><ul>
- <li>Lightweight , OM is specifically targeted to be lightweight. This is achieved by reducing the depth of the hierarchy, number of methods and the attributes enclosed in the objects. This makes the objects less memory intensive.</li>
-<li>Differed building , By far this is the most important feature of OM. The objects are not made unless a need arises for them. This passes the control of building over to the object model itself rather than an external builder. </li>
-<li>Pull based , For a differed building mechanism a pull based parser is required. OM is based on StAX, the standard pull parser API.</li>
+ Last published: 02 December 2005
+ | Doc for 0.93</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="">Download Axis2</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></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api.html">Online Java Docs</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</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="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="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 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="Section_1-Introduction"></a><h3>Section 1-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 developed for Axis 2. XML infoset
+refers to the information included inside the XML and for programmatical
+manipulation it is convenient to have a representation of this XML infoset in
+a language specific manner. For an object oriented language the obvious
+choice is a model made up of objects. DOM and JDOM are two such XML models.
+OM is conceptually similar to such an XML model by its external behavior but
+deep down it is very much different. The objective of this tutorial is to
+introduce the basics of OM and explain the best practices to follow while
+using OM. However before entering the deep ends of OM it is better to skim
+the surface and see what it is all about!</p></div><div class="subsection"><a name="For_whom_is_this_Tutorial_"></a><h3>For whom is this Tutorial?</h3><p>This tutorial can be used by anybody who is interested in OM and needs to
+go deeper in it. However it is assumed that the reader has a basic
+understanding of the concepts of XML (such as Namespaces) and a working
+knowledge of tools such as Ant. Knowledge in similar object models such as
+DOM will be quite helpful in understanding but such knowledge is not assumed.
+Several Links are listed in the appendix/ links section that will help
+anybody who lacks the basic understanding of XML.</p></div><div class="subsection"><a name="What_is_pull_parsing__"></a><h3>What is pull parsing ?</h3><p>
+Pull parsing is a recent trend in XML processing. The previously popular XML
+processing frameworks such as SAX and DOM were "push-based" which means the
+control of the parsing was with the parser itself. This approach is fine and
+easy to use but it was not efficient in handling large XML documents since a
+complete memory model will be generated in the memory. Pull parsing inverts
+the control and hence the parser only proceeds at the users command. The user
+can decide to store or discard events generated from the parser. OM is based
+on pull parsing. To learn more about XML pull parsing see the <a href="http://www.bearcave.com/software/java/xml/xmlpull.html" class="externalLink" title="External Link">XML pull
+parsing introduction</a>.
+
+</p></div><div class="subsection"><a name="A_Bit_of_History"></a><h3>A Bit of History</h3><p>The original OM was proposed as a store for the pull parser events for
+later processing, at the Axis summit held at Colombo in September 2004.
+However this approach was soon improved and OM was pursued as a complete info
+set model due to its flexibility. Several implementation techniques were
+attempted during the initial phases. The two most promising techniques were
+the table based technique and the link list based technique. During the
+intermediate performance tests the link list based technique proved to be
+much more memory efficient for smaller and mid sized XML documents (the
+advantage of the table based OM was only visible for the large and very large
+XML documents) and hence the link list based technique was chosen as the most
+suitable. Initial efforts were focused on implementing the XML info set items
+which are relevant to the SOAP specification (DTD support, Processing
+Instruction support, etc were not considered). The advantage of having a
+tight integration was evident at this stage and this resulted in having SOAP
+specific interfaces as part of OM rather than a layer on top of it. OM was
+deliberately made API centric. It allows the implementations to take place
+independently and swapped without affecting the program later.</p></div><div class="subsection"><a name="Features_of_OM"></a><h3>Features of OM</h3><p>OM is a lightweight, differed built XML info set representation based on
+StAX (<a href="http://www.jcp.org/aboutJava/communityprocess/first/jsr173/" class="externalLink" title="External Link">JSR
+173</a>), which is the standard streaming pull parser API. The object model
+can be manipulated as flexibly as any other object model (Such as <a href="http://www.jdom.org/" class="externalLink" title="External Link">JDOM</a>), but underneath the objects will be
+created only when they are absolutely required. This leads to much less
+memory intensive programming. Following is a short feature overview of OM.</p><ul>
+ <li>Lightweight , OM is specifically targeted to be lightweight. This is
+ achieved by reducing the depth of the hierarchy, number of methods and
+ the attributes enclosed in the objects. This makes the objects less
+ memory intensive.</li>
+ <li>Differed building , By far this is the most important feature of OM.
+ The objects are not made unless a need arises for them. This passes the
+ control of building over to the object model itself rather than an
+ external builder.</li>
+ <li>Pull based , For a differed building mechanism a pull based parser is
+ required. OM is based on StAX, the standard pull parser API.</li>
</ul><p>
-</p><p class="special">
-<table class="bodyTable"><tr class="b"><td>
- <img src="images/OM005.gif" alt="Rememeber 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></table>
-</p><p>
+
+</p><p class="special"></p><table class="bodyTable"><tbody>
+ <tr class="a"><td><img src="images/OM005.gif" alt="Rememeber 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>
+
</p><p>The Following image shows how OM API is viewed by the user</p><p>
-</p><p align="center" class="img">
-<img src="images/archi006.jpg" alt="OM Structure" class="img" width="490" height="282"></img>
-</p><p align="center" class="img-title">Figure 1</p><p>
-
-</p><p>OM Builder wraps the raw xml character stream through the StAX reader API. Hence the complexities of the pull event stream is covered</p></div><div class="subsection"><a name="A_bit_about_caching"></a><h3>A bit about caching</h3><p>Since OM is a differed built Object model, It incorporates the concept of caching.
-Caching refers to the creation of the objects while parsing the pull stream.
-The reason why this is so important is because caching can be turned off in certain situations.
-if so
-the parser proceeds without building the object structure. User can extract the raw pull stream from OM and use
-that instead of the OM and in this case it is sometimes beneficial to switch off caching.
-The advanced operations section explains more on accessing the raw pull stream and switching the caching on and off.
-</p></div><div class="subsection"><a name="Where_does_SOAP_come_into_play_"></a><h3>Where does SOAP come into play?</h3><p>In a nutshell SOAP is a information exchange protocol based on XML. SOAP has a defined set of
-XML elements that should be used in messages. Since Axis is a "SOAP Engine" and OM is built for Axis, A set of SOAP
-specific objects were also defined along with OM. These SOAP Objects are extensions of the general OM objects.
-To <a href="http://www.w3schools.com/SOAP/soap_intro.asp" class="externalLink" title="External Link">learn more on SOAP</a></p><p>
-
-</p></div><div class="subsection"><a name="Section_2_-_Working_with_OM"></a><h3>Section 2 - Working with OM</h3></div><div class="subsection"><a name="Obtaining_the_OM_binary"></a><h3>Obtaining the OM binary</h3><p>OM is not a separate product but part of Axis2. However since Axis2 has a modular build structure
-It is possible to obtain an "OM only" jar.
-</p><p>
-The easiest way to obtain the OM binary is to download the Axis2 binary distribution. The lib directory will
-contain the axis2-xml-0.91.jar. However more adventurous users can build the OM from source. The next section describes how
-to build OM from source.</p><p>Detailed information on getting source from Axis2 SVN repository can be found <a href="svn.html" class="newWindow" title="New Window" target="_blank">here</a>.</p><p>After the source download OM-binary can be built.
- For both Windows and Linux move to the project directory and execute the command "maven jar". All other necessary jars will be automatically downloaded.
- When the build finishes successfully, the axis2-xml-0.91.jar can be found in the newly created "targets" directory
-in the XML module.</p><p>Once the OM-binary is obtained by any of the mentioned means , it should be included in the class path for any of the OM based programs to work. The subsequent parts of this tutorial assume that this build step is complete and the Axis-0.91.jar is correctly in the classpath along with the StAX API jar file and a StAX implementation.
-</p></div><div class="subsection"><a name="Creation"></a><h3>Creation</h3><p>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.
-OM 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.
-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.
-The following piece of code shows the correct method of creating an OM document from an input stream. Note that the SOAP builder is used in this example.</p>
+
+</p><p align="center" class="img"><img src="images/archi006.jpg" alt="OM Structure" class="img" width="490" height="282"></img></p><p align="center" class="img-title">Figure 1</p><p>
+
+</p><p>OM Builder wraps the raw xml character stream through the StAX reader API.
+Hence the complexities of the pull event stream is covered</p></div><div class="subsection"><a name="A_bit_about_caching"></a><h3>A bit about caching</h3><p>Since OM is a differed built Object model, It incorporates the concept of
+caching. Caching refers to the creation of the objects while parsing the pull
+stream. The reason why this is so important is because caching can be turned
+off in certain situations. if so the parser proceeds without building the
+object structure. User can extract the raw pull stream from OM and use that
+instead of the OM and in this case it is sometimes beneficial to switch off
+caching. The advanced operations section explains more on accessing the raw
+pull stream and switching the caching on and off.</p></div><div class="subsection"><a name="Where_does_SOAP_come_into_play_"></a><h3>Where does SOAP come into play?</h3><p>In a nutshell SOAP is a information exchange protocol based on XML. SOAP
+has a defined set of XML elements that should be used in messages. Since Axis
+is a "SOAP Engine" and OM is built for Axis, A set of SOAP specific objects
+were also defined along with OM. These SOAP Objects are extensions of the
+general OM objects. To <a href="http://www.w3schools.com/SOAP/soap_intro.asp" class="externalLink" title="External Link">learn more on SOAP</a></p><p>
+
+</p></div><div class="subsection"><a name="Section_2_-_Working_with_OM"></a><h3>Section 2 - Working with OM</h3></div><div class="subsection"><a name="Obtaining_the_OM_binary"></a><h3>Obtaining the OM binary</h3><p>OM is not a separate product but part of Axis2. However since Axis2 has a
+modular build structure It is possible to obtain an "OM only" jar.</p><p>The easiest way to obtain the OM binary is to download the Axis2 binary
+distribution. The lib directory will contain the axis2-xml-0.93.jar. However
+more adventurous users can build the OM from source. The next section
+describes how to build OM from source.</p><p>Detailed information on getting source from Axis2 SVN repository can be
+found <a href="svn.html" class="newWindow" title="New Window" target="_blank">here</a>.</p><p>After the source download OM-binary can be built. For both Windows and
+Linux move to the project directory and execute the command "maven jar". All
+other necessary jars will be automatically downloaded. When the build
+finishes successfully, the axis2-xml-0.93.jar can be found in the newly
+created "targets" directory in the XML module.</p><p>Once the OM-binary is obtained by any of the mentioned means , it should
+be included in the class path for any of the OM based programs to work. The
+subsequent parts of this tutorial assume that this build step is complete and
+the Axis-0.93.jar is correctly in the classpath along with the StAX API jar
+file and a StAX implementation.</p></div><div class="subsection"><a name="Creation"></a><h3>Creation</h3><p>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. OM 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. 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. The following piece of code shows the correct method of
+creating an OM document from an input stream. Note that the SOAP builder is
+used in this example.</p>
<div class="source"><pre><pre>//create the parser<br></br>
XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
<br></br>//create the builder<br></br>
OMXMLParserWrapper builder = OMXMLBuilderFactory.createStAXSOAPModelBuilder(OMAbstractFactory.getSOAP11Factory(), parser);
//get the root element (in this case the envelope)<br></br>
- SOAPEnvelope envelope = (SOAPEnvelope) builder.getDocumentElement();
-</pre></pre></div>
- <div align="left"><b>Code listing 2.1</b></div><p>As the example shows, creating an OM from an input stream is pretty straightforward. However elements and nodes can be created programmatically to modify the structure as well.
-The recommended way to create OM objects programmatically is to use the factory. OMAbstractFactory.getOMFactory() will return the proper factory and the creator methods for each type should be called. Currently OM has two builders, namely the OM builder and the SOAP model builder. These builders provide the necessary information to the XML info set model to build itself. </p><p>
-</p><p class="img">
-<img src="images/archi007.jpg" alt="OM Structure 2" class="img" width="420" height="246"></img>
-</p><p class="img-title">Figure 2</p><p>
+ SOAPEnvelope envelope = (SOAPEnvelope) builder.getDocumentElement();</pre>
+</pre></div>
+ <div align="left">
+<b>Code listing 2.1</b></div><p>As the example shows, creating an OM from an input stream is pretty
+straightforward. However elements and nodes can be created programmatically
+to modify the structure as well. The recommended way to create OM objects
+programmatically is to use the factory. OMAbstractFactory.getOMFactory() will
+return the proper factory and the creator methods for each type should be
+called. Currently OM has two builders, namely the OM builder and the SOAP
+model builder. These builders provide the necessary information to the XML
+info set model to build itself.</p><p>
+
+</p><p class="img"><img src="images/archi007.jpg" alt="OM Structure 2" class="img" width="420" height="246"></img></p><p class="img-title">Figure 2</p><p>
</p><p>A simple example is shown below.</p>
<div class="source"><pre>//create a factory
@@ -85,17 +149,45 @@
OMElement elt12 = factory.createOMElement("foo2",ns1);
</pre></div>
- <div align="left"><b>Code listing 2.2</b></div><p>The reason to have a set of factory.createXXX methods is to cater for different implementations but keep the programmers code intact. Its highly recommend to use the factory for creating OM objects as this will ease the switching of different OM implementations.
-Several differences exist between a programmatically created OMNode and a conventionally built OMNode. The most important difference is that the former will have no builder object enclosed 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. This difference becomes evident when the user tries to get a non caching pull parser from the OMElement. This will be discussed in more detail in the advanced operations section.</p><p>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.
-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.</p><p>The SOAP Object hierarchy is made in the most natural way for a programmer. An inspection of the API will show that it is quite close to the SAAJ API but with no bindings to DOM or any other model. The SOAP classes extend basic OM classes (such as the element) hence one can access a SOAP document either with the abstraction of SOAP or drill down to the underlying XML Object model with a simple casting.</p><p>
-</p></div><div class="subsection"><a name="Addition_of_Nodes"></a><h3>Addition of Nodes</h3><p>Addition and removal methods are primarily defined in the OMElement interface. The following are the most important in adding nodes.</p>
+ <div align="left">
+<b>Code listing 2.2</b></div><p>The reason to have a set of factory.createXXX methods is to cater for
+different implementations but keep the programmers code intact. Its highly
+recommend to use the factory for creating OM objects as this will ease the
+switching of different OM implementations. Several differences exist between
+a programmatically created OMNode and a conventionally built OMNode. The most
+important difference is that the former will have no builder object enclosed
+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. This difference becomes evident when the user tries to get
+a non caching pull parser from the OMElement. This will be discussed in more
+detail in the advanced operations section.</p><p>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. 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.</p><p>The SOAP Object hierarchy is made in the most natural way for a
+programmer. An inspection of the API will show that it is quite close to the
+SAAJ API but with no bindings to DOM or any other model. The SOAP classes
+extend basic OM classes (such as the element) hence one can access a SOAP
+document either with the abstraction of SOAP or drill down to the underlying
+XML Object model with a simple casting.</p><p>
+
+</p></div><div class="subsection"><a name="Addition_of_Nodes"></a><h3>Addition of Nodes</h3><p>Addition and removal methods are primarily defined in the OMElement
+interface. The following are the most important in adding nodes.</p>
<div class="source"><pre>public void addChild(OMNode omNode);
public void addAttribute(OMAttribute attr);
</pre></div>
- <div align="left"><b>Code listing 2.3</b></div><p>This code segment shows how the addition takes place. Note that it is related to the code segment shown in the creation section.</p>
+ <div align="left">
+<b>Code listing 2.3</b></div><p>This code segment shows how the addition takes place. Note that it is
+related to the code segment shown in the creation section.</p>
<div class="source"><pre>//set the children
elt11.addChild(elt21);
elt12.addChild(elt22);
@@ -103,21 +195,36 @@
root.addChild(elt12);
</pre></div>
- <div align="left"><b>Code listing 2.4</b></div><p>Note that AddChild method will always add the child as the first child of the parent.
-Removal of Nodes
-A given node can be removed from the tree by calling the detach() method.
-A node can also be removed from the tree by calling the remove method of the returned iterator which will also call the detach method of the particular node internally.
-Handling namespaces
-Namespaces are a tricky part of any XML object model and is the same in OM. However care has been taken to make the interface to the namespace very simple.
-OMNamespace is the class that represents a namespace with intentionally removed setter methods. This makes the OMNamespace immutable and allows the underlying implementation to share the objects without any difficulty.
-Following are the important methods available in OMElement to handle namespaces.</p>
+ <div align="left">
+<b>Code listing 2.4</b></div><p>Note that AddChild method will always add the child as the first child of
+the parent. Removal of Nodes A given node can be removed from the tree by
+calling the detach() method. A node can also be removed from the tree by
+calling the remove method of the returned iterator which will also call the
+detach method of the particular node internally. Handling namespaces
+Namespaces are a tricky part of any XML object model and is the same in OM.
+However care has been taken to make the interface to the namespace very
+simple. OMNamespace is the class that represents a namespace with
+intentionally removed setter methods. This makes the OMNamespace immutable
+and allows the underlying implementation to share the objects without any
+difficulty. Following are the important methods available in OMElement to
+handle namespaces.</p>
<div class="source"><pre>public OMNamespace declareNamespace(String uri, String prefix);
public OMNamespace declareNamespace(OMNamespace namespace);
public OMNamespace findNamespace(String uri, String prefix) throws OMException;
</pre></div>
- <div align="left"><b>Code listing 2.5</b></div><p>The declareNamespacexx methods are fairly straightforward. They add a namespace to namespace declarations section. Note that a namespace declaration that has already being added will not be added twice.
-FindNamespace is a very handy method to locate a namespace object higher up the object tree. It searches for a matching namespace in its own declarations section and jumps to the parent if it's not found. The search progresses up the tree until a matching namespace is found or the root has been reached.</p><p>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.</p><p>The following simple code segment shows how the namespaces are dealt with in OM</p>
+ <div align="left">
+<b>Code listing 2.5</b></div><p>The declareNamespaceXX methods are fairly straightforward. They add a
+namespace to namespace declarations section. Note that a namespace
+declaration that has already being added will not be added twice.
+FindNamespace is a very handy method to locate a namespace object higher up
+the object tree. It searches for a matching namespace in its own declarations
+section and jumps to the parent if it's not found. The search progresses up
+the tree until a matching namespace is found or the root has been reached.</p><p>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.</p><p>The following simple code segment shows how the namespaces are dealt with
+in OM</p>
<div class="source"><pre>OMFactory factory = OMAbstractFactory.getOMFactory();
OMNamespace ns1 = factory.createOMNamespace("bar","x");
OMElement root = factory.createOMElement("root",ns1);
@@ -130,70 +237,99 @@
root.addChild(elt1);
</pre></div>
- <div align="left"><b>Code listing 2.6</b></div><p>Serilization of the root element produces the following XML </p>
+ <div align="left">
+<b>Code listing 2.6</b></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>
+ <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 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.
-The following code sample shows how the children can be accessed. The children are of the type OMNode that can either be OMText or OMElement.</p>
+ </div><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
+iterator. The Iterator supports the 'OM way' of accessing elements and is
+more convenient than a list for sequential access. The following code sample
+shows how the children can be accessed. The children are of the type OMNode
+that can either be OMText or OMElement.</p>
<div class="source"><pre>Iterator children = root.getChildren();
While(children.hasNext()){
- OMNode node = (OMNode)children.next();
+ OMNode node = (OMNode)children.next();
}
</pre></div>
- <div align="left"><b>Code listing 2.7</b></div><p>Apart from this every OMNode has links to its siblings. If more thorough navigation is needed the nextSibling() and PreviousSibling() methods can be used.
-A more selective set can be chosen by using the getChildrenWithName(QName) methods. The getChildWithName(Qname) method 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 won't build the whole object structure at once, until its required.</p><p>
-</p><p class="special">
-<table class="bodyTable"><tr class="a"><td>
- <img src="images/OM005.gif" alt="Rememeber 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></table>
-</p><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 output and hence the same serialization mechanism can be used to write different types of outputs (such as text, binary, etc.,).</p><p>A caching flag is provided by OM to control the building of the in-memory OM.
-The OMNode has two methods, serializeWithCache and serialize When serialize is
-called the cache flag is reset and the serializer does not cache the stream. Hence the object model will not be built if the cache flag is not set. </p><p>The serializer serializes namespaces in the following way.</p><ol>
-<li>When a namespace that is in the scope but not yet declared is encountered, then it will be declared.</li>
-<li>When a namespace that is in scope and already declared is encountered, the existing declarations prefix is used.</li>
-<li>When the namespaces are declared explicitly using the elements declareNamespace() method, they will be serialized even if those namespaces are not used in that scope.</li>
-</ol><p>
-Because of this behavior, if a fragment of the XML is serialized, it will also be <i>namespace qualified</i> with the necessary namespace declarations.</p><p>Here is an example that shows how to write the output to the console, with reference to the earlier code sample (Code listing 2.1 ) that created a SOAP envelope.</p><p></p>
+ <div align="left">
+<b>Code listing 2.7</b></div><p>Apart from this every OMNode has links to its siblings. If more thorough
+navigation is needed the nextSibling() and PreviousSibling() methods can be
+used. A more selective set can be chosen by using the
+getChildrenWithName(QName) methods. The getChildWithName(Qname) method
+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 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="b"><td><img src="images/OM005.gif" alt="Rememeber 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>
+
+</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
+output and hence the same serialization mechanism can be used to write
+different types of outputs (such as text, binary, etc.,).</p><p>A caching flag is provided by OM to control the building of the in-memory
+OM. The OMNode has two methods, serializeWithCache and serialize When
+serialize is called the cache flag is reset and the serializer does not cache
+the stream. Hence the object model will not be built if the cache flag is not
+set.</p><p>The serializer serializes namespaces in the following way.</p><ol>
+ <li>When a namespace that is in the scope but not yet declared is
+ encountered, then it will be declared.</li>
+ <li>When a namespace that is in scope and already declared is encountered,
+ the existing declarations prefix is used.</li>
+ <li>When the namespaces are declared explicitly using the elements
+ declareNamespace() method, they will be serialized even if those
+ namespaces are not used in that scope.</li>
+</ol><p>Because of this behavior, if a fragment of the XML is serialized, it will
+also be <i>namespace qualified</i> with the necessary namespace
+declarations.</p><p>Here is an example that shows how to write the output to the console, with
+reference to the earlier code sample (Code listing 2.1 ) that created a SOAP
+envelope.</p><p></p>
<div class="source"><pre>XMLStreamWriter writer = XMLOutputFactory.newInstance().createXMLStreamWriter(System.out);
//dump the output to console with caching
envelope.serializeWithCache(writer);
writer.flush();
-
-
+
</pre></div>
- <div align="left"><b>Code listing 2.8</b></div><p>The above mentioned features of the serializer forces a correct serialization even if only a part of the OM tree is serialized. The following serializations show how the serialization mechanism takes the trouble to accurately figure out the namespaces.
-The example is from code listing 2.6 which creates a small OM programmatically.
-Serialization of the root element produces</p>
+ <div align="left">
+<b>Code listing 2.8</b></div><p>The above mentioned features of the serializer forces a correct
+serialization even if only a part of the OM tree is serialized. The following
+serializations show how the serialization mechanism takes the trouble to
+accurately figure out the namespaces. The example is from code listing 2.6
+which creates a small OM programmatically. Serialization of the root element
+produces</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>
- <p>However serialization of only the foo element produces </p>
+ <p>However serialization of only the foo element produces</p>
<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 place.
-Complete code for the OM based document building and serialization
-The following code segment shows how to use the OM for completely building a document and then serializing it into text pushing the output to the console. Only the important sections are shown here and the complete program listing can be found in the appendix.
-</p>
+Complete code for the OM based document building and serialization The
+following code segment shows how to use the OM for completely building a
+document and then serializing it into text pushing the output to the console.
+Only the important sections are shown here and the complete program listing
+can be found in the appendix.</p>
<div class="source"><pre>//create the parser
XMLStreamReader parser = XMLInputFactory.newInstance().createXMLStreamReader(new FileReader(file));
//create the builder
@@ -207,10 +343,20 @@
writer.flush();
</pre></div>
- <div align="left"><b>Code listing 2.9</b></div></div><div class="subsection"><a name="Section_3_-_Advanced_Operations_with_OM"></a><h3>Section 3 - Advanced Operations with OM</h3></div><div class="subsection"><a name="Use_of_the_OMNavigator_for_Traversal"></a><h3>Use of the OMNavigator for Traversal</h3><p>OM provides a utility class to navigate the OM structure. The navigator provides an in-order traversal of the OM tree up to the last-built node.
-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.</p><p>It is possible that the OM tree does not get built completely when it is navigated. The navigable status shows whether the tree structure is 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.
-The following code sample shows how the navigator should be used and handled using its states.
-</p>
+ <div align="left">
+<b>Code listing 2.9</b></div></div><div class="subsection"><a name="Section_3_-_Advanced_Operations_with_OM"></a><h3>Section 3 - Advanced Operations with OM</h3></div><div class="subsection"><a name="Use_of_the_OMNavigator_for_Traversal"></a><h3>Use of the OMNavigator for Traversal</h3><p>OM provides a utility class to navigate the OM structure. The navigator
+provides an in-order traversal of the OM tree up to the last-built node. 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.</p><p>It is possible that the OM tree does not get built completely when it is
+navigated. The navigable status shows whether the tree structure is
+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. The following code sample shows how the navigator should be used
+and handled using its states.</p>
<div class="source"><pre>//Create a navigator
OMNavigator navigator = new OMNavigator(envelope);
OMNode node = null;
@@ -219,19 +365,35 @@
}
</pre></div>
- <div align="left"><b>Code listing 3.1</b></div></div><div class="subsection"><a name="Accessing_the_Pull_Parser"></a><h3>Accessing the Pull Parser</h3><p>OM is tightly integrated with StAX and the getXMLStreamReader()/getXMLStreamReaderWithoutCaching() methods in the OMElement provides a XMLStreamReader object.
-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.</p><p> OM has the concept of caching, and OM is the actual cache of the events fired. However the requester can choose to get the pull events from the underlying stream rather than the OM tree. This can be achieved by getting the pull parser with the cache off. If the pull parser was obtained without switching off cache, the new events fired will be cached and the tree updated.
-This returned pull parser will switch between the object structure and the stream underneath and the users need not worry about the differences caused by the switching. The exact pull stream the original document would have provided would be produced even if the OM tree was fully/partially built.
-The getXMLStreamReaderWithoutCaching() method is very useful when the events need to be handled in a pull based manner without any intermediate models. This makes such operations faster and efficient.
-</p><p>
-</p><p class="special">
-<table class="bodyTable"><tr class="b"><td>
- <img src="images/OM005.gif" alt="Rememeber 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></table>
-</p><p>
-
-</p></div><div class="subsection"><a name=" "></a><h3> </h3></div><div class="subsection"><a name="Section_4_-_Known_Limitations_of_OM"></a><h3>Section 4 - 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 a similar code listing to 1.6 is used but with two elements having the same namespace. Note that the newly added items are in bold.</p>
+ <div align="left">
+<b>Code listing 3.1</b></div></div><div class="subsection"><a name="Accessing_the_Pull_Parser"></a><h3>Accessing the Pull Parser</h3><p>OM is tightly integrated with StAX and the
+getXMLStreamReader()/getXMLStreamReaderWithoutCaching() methods in the
+OMElement provides a XMLStreamReader object. 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.</p><p> OM has the concept of caching, and OM is the actual cache of the
+events fired. However the requester can choose to get the pull events from
+the underlying stream rather than the OM tree. This can be achieved by
+getting the pull parser with the cache off. If the pull parser was obtained
+without switching off cache, the new events fired will be cached and the tree
+updated. This returned pull parser will switch between the object structure
+and the stream underneath and the users need not worry about the differences
+caused by the switching. The exact pull stream the original document would
+have provided would be produced even if the OM tree was fully/partially
+built. The getXMLStreamReaderWithoutCaching() method is very useful when the
+events need to be handled in a pull based manner without any intermediate
+models. This makes such operations faster and efficient. </p><p>
+
+</p><p class="special"></p><table class="bodyTable"><tbody>
+ <tr class="a"><td><img src="images/OM005.gif" alt="Rememeber 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=" "></a><h3> </h3></div><div class="subsection"><a name="Section_4_-_Known_Limitations_of_OM"></a><h3>Section 4 - 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
+a similar code listing to 1.6 is used but with two elements having the same
+namespace. Note that the newly added items are in bold.</p>
<div class="source"><pre>OMFactory factory = OMAbstractFactory.getOMFactory();
OMNamespace ns1 = factory.createOMNamespace("bar","x");
OMElement root = factory.createOMElement("root",ns1);
@@ -247,7 +409,8 @@
root.addChild(elt1);
</pre></div>
- <div align="left"><b>Code listing 4.1</b></div><p>Serialization of the root element provides the following XML</p>
+ <div align="left">
+<b>Code listing 4.1</b></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>
@@ -256,20 +419,27 @@
</x:root>
+
</pre></div>
- <p>However if the serialization is carried on the foo element then the following XML is produced</p>
+ <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>
+
</pre></div>
- <p>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.
-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.
-</p></div><div class="subsection"><a name="Summary"></a><h3>Summary</h3><p>This is meant to be a small yet comprehensive introduction to AXIOM. AXIOM
-however is a lot more than what is described in this tutorial. Readers are
-welcome to explore AXIOM, specially it's capabilities to handle binary content.</p></div><div class="subsection"><a name="Appendix"></a><h3>Appendix</h3></div><div class="subsection"><a name="Program_listing_for_complete_OM_-_build_and_serialize"></a><h3>Program listing for complete OM - build and serialize</h3>
+ <p>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. 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.</p></div><div class="subsection"><a name="Summary"></a><h3>Summary</h3><p>This is meant to be a small yet comprehensive introduction to AXIOM. AXIOM
+however is a lot more than what is described in this tutorial. Readers are
+welcome to explore AXIOM, specially it's capabilities to handle binary
+content.</p></div><div class="subsection"><a name="Appendix"></a><h3>Appendix</h3></div><div class="subsection"><a name="Program_listing_for_complete_OM_-_build_and_serialize"></a><h3>Program listing for complete OM - build and serialize</h3>
<div class="source"><pre>import org.apache.axis2.om.SOAPEnvelope;
import org.apache.axis2.om.OMFactory;
import org.apache.axis2.om.OMXMLParserWrapper;
@@ -312,9 +482,13 @@
</pre></div>
</div><div class="subsection"><a name="Links"></a><h3>Links</h3><p>
For basics in XML
- <ul>
- <li><a href="http://www-128.ibm.com/developerworks/xml/newto/index.html" class="externalLink" title="External Link">Developerworks Introduction to XML</a></li>
- <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"><tr class="a"><td align="center">All rights reserved by Apache Software Foundation</td></tr></table></div></div></div><div class="clear"><hr></hr></div><div id="footer"><div class="xright">© 2004-2005, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
+<ul>
+ <li><a href="http://www-128.ibm.com/developerworks/xml/newto/index.html" class="externalLink" title="External Link">Developerworks
+ Introduction to XML</a></li>
+ <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="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-2005, Apache Software Foundation</div><div class="clear"><hr></hr></div></div></body></html>
\ No newline at end of file
Modified: webservices/site/trunk/targets/axis2/ServiceArchiveToolReference.html
URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/ServiceArchiveToolReference.html?rev=351729&r1=351728&r2=351729&view=diff
==============================================================================
--- webservices/site/trunk/targets/axis2/ServiceArchiveToolReference.html (original)
+++ webservices/site/trunk/targets/axis2/ServiceArchiveToolReference.html Fri Dec 2 05:57:44 2005
@@ -2,8 +2,8 @@
@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/axis/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 26 September 2005
- | Doc for 0.92</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="">Download Axis2</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></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api/index.html">Online Java Docs</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</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="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="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 Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Service_Archive_Wizard_-_Eclipse_Plug-in"></a><h2>Service Archive Wizard - Eclipse Plug-in</h2><p>Axis2 comes with a simple service archiver tool. This tool provides easy to use functionality to develop a axis archive or an "aar" file or a "jar" file that can be deployed as a web service to the Axis2. This tool is in the form of
+ Last published: 02 December 2005
+ | Doc for 0.93</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="">Download Axis2</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></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api.html">Online Java Docs</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</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="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="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 Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><a name="Service_Archive_Wizard_-_Eclipse_Plug-in"></a><h2>Service Archive Wizard - Eclipse Plug-in</h2><p>Axis2 comes with a simple service archiver tool. This tool provides easy to use functionality to develop a axis archive or an "aar" file or a "jar" file that can be deployed as a web service to the Axis2. This tool is in the form of
an Eclipse plug-in and can be downloaded from the downloads section. This document describes how the tool can be used.</p><div class="subsection"><a name="Installation"></a><h3>Installation</h3><p>
Download the binary version of the plug-in and extract the content of the zip
file into the Eclipse installation folder. (The plug-in will actually go into
Modified: webservices/site/trunk/targets/axis2/axis2config.html
URL: http://svn.apache.org/viewcvs/webservices/site/trunk/targets/axis2/axis2config.html?rev=351729&r1=351728&r2=351729&view=diff
==============================================================================
--- webservices/site/trunk/targets/axis2/axis2config.html (original)
+++ webservices/site/trunk/targets/axis2/axis2config.html Fri Dec 2 05:57:44 2005
@@ -2,13 +2,13 @@
@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/axis/images/axis.jpg"></img></a><div class="clear"><hr></hr></div></div><div id="breadcrumbs"><div class="xleft">
- Last published: 26 September 2005
- | Doc for 0.92</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="">Download Axis2</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></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api/index.html">Online Java Docs</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</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="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="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 Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><p>In Axis2 there are three kinds of configuration files to configure the system.
+ Last published: 02 December 2005
+ | Doc for 0.93</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="">Download Axis2</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></ul></li><li class="expanded"><a href="">Getting Started with Axis2</a><ul><li class="none"><a href="installationguide.html">Installation Guide</a></li><li class="none"><a href="userguide.html">User Guide</a></li><li class="none"><a href="webadminguide.html">Web Administration Guide</a></li></ul></li><li class="expanded"><a href="docs.html">Additional Reference</a><ul><li class="none"><a href="http://wiki.apache.org/ws/FrontPage/Axis2" class="externalLink" title="External Link">Axis2 Wiki</a></li><li class="none"><a href="Axis2ArchitectureGuide.html">Architecture Guide</a></li><li class="none"><a href="OMTutorial.html">AXIOM Tutorial</a></li><li class="none"><a href="CodegenToolReference.html">Code Generation Tutorial</a></li><li class="none"><a href="rest-ws.html">REST Support</a></li><li class="none"><a href="mtom-guide.html">Handling Binary Data with Axis2</a></li><li class="none"><a href="axis2config.html">Axis2 Configuration Guide</a></li><li class="none"><a href="migration.html">Migrating from Axis 1.x</a></li><li class="none"><a href="api.html">Online Java Docs</a></li><li class="none"><a href="otherTutorials.html">Other Tutorials</a></li></ul></li><li class="expanded"><a href="overview.html">Get Invloved</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="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="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 Maven" src="./images/logos/maven-button-1.png"></img></a></div></div><div id="bodyColumn"><div class="contentBox"><div class="section"><p>In Axis2 there are three kinds of configuration files to configure the system.
First one configuration file is to configure whole system, second one is to
configure a service and the third one is to configure a module.
<ul>
<li><a href="#global">Global Configuration (axis2.xml)</a></li>
-<li><a href="#service">Service Configuration (service.xml)</a></li>
+<li><a href="#service">Service Configuration (services.xml)</a></li>
<li><a href="#module">Module Configuration (module.xml)</a></li>
</ul>
</p><br></br><font color="blue"><b>Global Configuration </b></font><li><a name="global"></a>Writing axis2.xml</li><p>
@@ -88,6 +88,72 @@
</phaseOrder>
</pre></pre></div>
+
+The most interesting thing is that you can add handlers here as well , if you want to add a handler which should go in to that phase you can directly do that by adding a handler element into it . In addition to that there is no any hard coding stuffs for handler chain in anywhere in Axis2 (at any Axis*) , so all theose configuration are alos done here in phase order element. The complete configuration will look like as follows;
+
+
+ <div class="source"><pre><pre>
+<phaseOrder type="inflow"">
+ <!-- System pre defined phases --">
+ <phase name="TransportIn"/">
+ <phase name="PreDispatch"/">
+ <phase name="Dispatch"">
+ <handler name="AddressingBasedDispatcher"
+ class="org.apache.axis2.engine.AddressingBasedDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ <handler name="RequestURIBasedDispatcher"
+ class="org.apache.axis2.engine.RequestURIBasedDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ <handler name="SOAPActionBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPActionBasedDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ <handler name="SOAPMessageBodyBasedDispatcher"
+ class="org.apache.axis2.engine.SOAPMessageBodyBasedDispatcher"">
+ <order phase="Dispatch"/">
+ </handler">
+ </phase">
+ <phase name="PostDispatch"">
+ <handler name="DispatchPostConditionsEvaluator"
+ class="org.apache.axis2.engine.DispatchingChecker"">
+ <order phase="PostDispatch"/">
+ </handler">
+ <handler name="InstanceDispatcher"
+ class="org.apache.axis2.engine.InstanceDispatcher"">
+ <order phase="PostDispatch"/">
+ </handler">
+ <handler name="SOAPProcessingModelChecker"
+ class="org.apache.axis2.engine.SOAPProcessingModelChecker"">
+ <order phase="PostDispatch"/">
+ </handler">
+ </phase">
+ <!-- System pre defined phases --">
+ <!-- After Postdispatch phase module author or or service author can add any phase he want --">
+ <phase name="userphase1"/">
+ </phaseOrder">
+ <phaseOrder type="outflow"">
+ <!-- user can add his own phases to this area --">
+ <phase name="userphase1"/">
+ <!--system predefined phase--">
+ <!--these phase will run irrespective of the service--">
+ <phase name="PolicyDetermination"/">
+ <phase name="MessageOut"/">
+ </phaseOrder">
+ <phaseOrder type="INfaultflow"">
+ <!-- user can add his own phases to this area --">
+ <phase name="userphase1"/">
+ </phaseOrder">
+ <phaseOrder type="Outfaultflow"">
+ <!-- user can add his own phases to this area --">
+ <phase name="userphase1"/">
+ <phase name="PolicyDetermination"/">
+ <phase name="MessageOut"/">
+ </phaseOrder">
+</pre></pre></div>
+
+
type: the attribute represent type of the flow and which can only be one of the following
</p><ul>
<li>inflow</li>
@@ -144,27 +210,18 @@
that the implementation class should implement AxisObserver interface,
and the class has to be available in the classpath.
</p><br></br><font color="blue"><b>Service Configuration</b></font><li><a name="service"></a>Writing service.xml</li><p>
-The description of service is specified using service.xml, each service archive
-file need to have service.xml in order to be a valid service. And which has to be
+The description of service is specified using services.xml, each service archive
+file need to have services.xml in order to be a valid service. And which has to be
available in META-INF directory of the archive file.
<br></br>
-A very simple service.xml is shown below:
+A very simple services.xml is shown below:
<div class="source"><pre><pre>
-<service name="Name of the service">
+<service >
<description> The description of the service </description>
<parameter name="ServiceClass" locked="xsd:false">org.apache.axis2.sample.echo.EchoImpl</parameter>
- <inflow>
- <handler name="logging" class="org.apache.axis2.sample.handlers.LoggingHandler">
- <order phase="userphase1" phaseFirst="true"/>
- </handler>
- </inflow>
- <outflow/>
- <INfaultflow>?.. </INfaultflow>
- <Outfaultflow> ?.</Outfaultflow>
-
<operation name="echoString">
<module ref=" a module name "/>
<messageReceiver class="org.apache.axis2.receivers.RawXMLINOutMessageReceiver"/>
@@ -173,8 +230,7 @@
</pre></pre></div>
-service name: You can specify the name of the service, if you do not specify the
-service name then the archive file name will be the name of the service.
+service name: the service name will be the name of the archive file.
<br></br>
description: This is an optional element if you want to display any description
about the service via Axis2 web-admin module then the description can be specified here.
@@ -185,25 +241,6 @@
There is a compulsory parameter in a service.xml called ServiceClass which specify the
java class which really does the job and the class will be loaded by MessageReceiver.
</p><p>
-<b>Flow :</b><br></br>
-It is possible to add handlers into a flow directly form service.xml rather than
-engaging a modules and the way of doing that is through flow elements.
-It is possible to add any number of handlers into a flow and those handlers
-will be available in corresponding operations flows in the service
-(inflow consist of two parts, one part is up to post dispatch phase and other
-part is consisting of operation handlers)
-<br></br>
-There are four types of valid flows that can be available in service.xml,
- and the adding the handles into them can be done by following the above procedure.
-<br></br>
-Valid flows:
-<ul>
-<li>Inflow</li>
-<li>outflow</li>
-<li>INfaultflow</li>
-<li>Outfaultflow</li>
-</ul>
-</p><p>
<b>Handler</b><br></br>
Handler element consists of compulsory and optional attribute and the way of defining a handler will be look like follows;
@@ -272,10 +309,24 @@
</p><p>
<b>parameter:</b>
Module can contains any number of parameters and all the listed parameters in the module.xml will be transformed into corresponding ModuleDescription of the module.
-</p><p>
-<b>flow:</b>
-Flow concept is exactly the same as service flows.
-</p><p>
+</p><b>Flow :</b><br></br><p>
+It is possible to add handlers into a flow directly form service.xml rather than
+engaging a modules and the way of doing that is through flow elements.
+It is possible to add any number of handlers into a flow and those handlers
+will be available in corresponding operations flows in the service
+(inflow consist of two parts, one part is up to post dispatch phase and other
+part is consisting of operation handlers)
+</p><br></br><p>
+There are four types of valid flows that can be available in service.xml,
+ and the adding the handles into them can be done by following the above procedure.
+</p><br></br><p>
+Valid flows:
+<ul>
+<li>Inflow</li>
+<li>outflow</li>
+<li>INfaultflow</li>
+<li>Outfaultflow</li>
+</ul></p><p>
<b>operations</b>
If a module wants to add an operation when it is engaged into a service it can be done by adding operation tag in module.xml and the way of specifying the operation is same as operation in service.xml.