Author: veithen
Date: Sat Aug 1 21:19:59 2009
New Revision: 799928
URL: http://svn.apache.org/viewvc?rev=799928&view=rev
Log:
Adding a section to the user guide about closing/releasing the parser.
Modified:
webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml
Modified: webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml?rev=799928&r1=799927&r2=799928&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml (original)
+++ webservices/commons/trunk/modules/axiom/src/docbkx/userguide.xml Sat Aug 1
21:19:59 2009
@@ -629,6 +629,33 @@
XMLStreamReader reader = StAXUtils.createXMLStreamReader(in);</programlisting>
</section>
<section>
+ <title>Releasing the parser</title>
+ <para>
+ As we have seen previously, when creating an object model from
a stream, all nodes keep a
+ reference to the builder and thus to the underlying parser.
Since an XML parser instance is
+ a heavyweight object, it is important to release it as soon as
it is no longer required.
+ The <methodname>close</methodname> method defined by the
<classname>OMNode</classname>
+ interface it used for that. Note that it doesn't matter an
which node this method is
+ called; it will always close and release the parser for the
whole tree. The
+ <varname>build</varname> parameter of the
<methodname>close</methodname> method specifies
+ if the node should be built before closing the parser.
+ </para>
+ <para>
+ To illustrate this, consider <xref linkend="list1"/>. After
finishing the processing of the
+ object model and assuming that it will not access the object
model afterwards, the code should
+ be completed by the following instruction:
+ </para>
+<programlisting>documentElement.close(false);</programlisting>
+ <para>
+ Closing the parser is especially important in applications
that process large numbers of
+ XML documents. In addition, some StAX implementation are able
to <quote>recycle</quote>
+ parsers, i.e. to reset a parser instance and to reuse it on
another input stream. However, this
+ can only work if the parser has been closed explicitly or if
the instance has been marked for
+ finalization by the Java VM. Closing the parser explicitly as
shown above will reduce the
+ memory footprint of the application if this type of parser is
used.
+ </para>
+ </section>
+ <section>
<title>Exception handling</title>
<para>
The fact that Axiom uses deferred building means that a call
to a method in one
