CVS Update: xmlpull-api-v1/doc
Aleksander Andrzej Slominski <[email protected]> Mon, 29 Aug 2005 12:30:50 -0500 (EST)
| Newsgroups | gmane.text.xml.xmlpull.devel |
|---|---|
| Message-ID | <[email protected]> |
aslom 05/08/29 12:30:50
Modified: doc addons.html changes.html faq.html features.html
properties.html quick_intro.html quick_write.html
Log:
executed tidy -asxhtml -utf8 -i -w 120 -m on doc/*.html and applied patch by Nahuel ANGELINETTI (thanks!)
from issue 229 Bad html code (http://www.extreme.indiana.edu/bugzilla/show_bug.cgi?id=229)
Revision Changes Path
1.9 +183 -229 xmlpull-api-v1/doc/addons.html
Index: addons.html
===================================================================
RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/addons.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -b -t -w -r1.8 -r1.9
--- addons.html 8 Jul 2003 21:17:34 -0000 1.8
+++ addons.html 29 Aug 2005 17:30:49 -0000 1.9
@@ -1,61 +1,55 @@
-<html><head>
-<title>XmlPull API Addons
-</title>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta name="generator" content="HTML Tidy for Windows (vers 12 April 2005), see www.w3.org" />
+
+ <title>XmlPull API Addons</title>
</head>
<body bgcolor="white">
-
-<h1>XmlPull API Addons
-</h1>
+ <h1>XmlPull API Addons</h1>
<h2>What is it?</h2>
-<p>Addons are reusable components that built on top of XmlPull API.
+ <p>Addons are reusable components that built on top of XmlPull API.</p>
-</p><p>
-All addons can be compiled by build target <code>addons</code> (use: <code>ant addons</code>)
-</p>
+ <p>All addons can be compiled by build target <code>addons</code> (use: <code>ant addons</code>)</p>
+
+ <p>Following addons are available:</p>
-<p>Following addons are available:
<ul>
-<li><a href="#wrapper">Wrapper</a>: set of extensions for parser and serializer interfaces
-and their implementation that seemlesly add functionality to exisitng APIs
-</li>
-<li><a href="#util">Utility Methods</a>: set of static methods that can be easily used
-(good source for few lines of code to solve typical problems)
-</li>
-<li><a href="#dom2_builder">DOM2 Builder</a>: simple class to convert
-XML event streaminto DOM element tree
-</li>
-<li><a href="#parser_pool">Parser pool</a>: simple to use class to make pooling parser instances easy.
-</li>
-<li><a href="#sax2_driver">SAX2 Driver</a>: class that impements SAX2 XMLReader
-and allowsto convert stream of XML pull events into SAX2 events
-
-
-<li><a href="#xmlrpc">XML RPC parser</a>: exmpale of use of XmlPull API to
-do non-trivial databinding
-</li>
+ <li><a href="#wrapper">Wrapper</a>: set of extensions for parser and serializer interfaces and their implementation
+ that seemlesly add functionality to exisitng APIs</li>
+
+ <li><a href="#util">Utility Methods</a>: set of static methods that can be easily used (good source for few lines
+ of code to solve typical problems)</li>
+ <li><a href="#dom2_builder">DOM2 Builder</a>: simple class to convert XML event streaminto DOM element tree</li>
+
+ <li><a href="#parser_pool">Parser pool</a>: simple to use class to make pooling parser instances easy.</li>
+
+ <li><a href="#sax2_driver">SAX2 Driver</a>: class that impements SAX2 XMLReader and allowsto convert stream of XML
+ pull events into SAX2 events</li>
+
+ <li><a href="#xmlrpc">XML RPC parser</a>: exmpale of use of XmlPull API to do non-trivial databinding</li>
</ul>
-</p>
<p> </p>
-<a name="wrapper"><h2>Wrapper: Extended Pull Parser and Serializer Interfaces</h2>
-</a>
+ <h2><a name="wrapper" id="wrapper">Wrapper: Extended Pull Parser and Serializer Interfaces</a></h2>
-<p>This package provides extended XmlPullParser and XmlSerializer interfaces
-called XmlPullParserWrapper and XmlSerializerWrapper that has additional
-methods that make it more convenient and more concise to write parsing and serialzing
-code by providing seemlesly integrated additional methods.
-</p>
+ <p>This package provides extended XmlPullParser and XmlSerializer interfaces called XmlPullParserWrapper and
+ XmlSerializerWrapper that has additional methods that make it more convenient and more concise to write parsing and
+ serialzing code by providing seemlesly integrated additional methods.</p>
-<p>Wrappers can be uesd exactly the same as XmlPullParser and XmlSerialzier as those
-interface <b>extend</b> them.
+ <p>Wrappers can be uesd exactly the same as XmlPullParser and XmlSerialzier as those interface <b>extend</b>
+ them.</p>
<p>Here is example usage:</p>
-<pre>import org.xmlpull.v1.wrapper.*;
+ <pre>
+import org.xmlpull.v1.wrapper.*;
XmlPullWrapperFactory wf = XmlPullWrapperFactory.newInstance();
@@ -73,107 +67,80 @@
</pre>
<p>Another example is how to quickly copy XML input to output:</p>
-
-<pre>while (pp.nextToken() != XmlPullParser.END_DOCUMENT) {
+ <pre>
+while (pp.nextToken() != XmlPullParser.END_DOCUMENT) {
ser.event(pp);
}
</pre>
-<p>It can be compiled by build target <code>wrapper</code>
-
-</p><p>Source code is available in <code>
-<a href="../addons/java/wrapper/src/org/xmlpull/v1/wrapper/">addons/java/wrapper</a></code>
-(<a href="http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/wrapper/src/org/xmlpull/v1/wrapper/">view
-CVS</a>).</p><p>
-TODO: add link to JavaDoc</p>
-
-
-<p>
- </p>
+ <p>It can be compiled by build target <code>wrapper</code></p>
+ <p>Source code is available in <code><a href=
+ "../addons/java/wrapper/src/org/xmlpull/v1/wrapper/">addons/java/wrapper</a></code> (<a href=
+ "http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/wrapper/src/org/xmlpull/v1/wrapper/">view
+ CVS</a>).</p>
+ <p>TODO: add link to JavaDoc</p>
+ <p> </p>
-<a name="util"><h2>Util Addon</h2>
-</a>
+ <h2><a name="util" id="util">Util Addon</a></h2>
-<p>This class provides set of static utility methods for XmlPull parser and
-serializer.
-</p>
+ <p>This class provides set of static utility methods for XmlPull parser and serializer.</p>
<p>Here is example usage:</p>
-<pre>import org.xmlpull.v1.util.XmlPullUtil;
+ <pre>
+import org.xmlpull.v1.util.XmlPullUtil;
XmlPullParser parser = ...
parser.require(XmlPullParser.START_TAG, ..., ...);
XmlPullUtil.skipSubTree(pp);
</pre>
-<p>It can be compiled by build target <code>util</code>
+ <p>It can be compiled by build target <code>util</code></p>
-</p><p>Source code is available in <code>
-<a href="../addons/java/util/src/org/xmlpull/v1/util/">addons/java/util</a></code>
-(<a href="http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/util/src/org/xmlpull/v1/util/">view
+ <p>Source code is available in <code><a href=
+ "../addons/java/util/src/org/xmlpull/v1/util/">addons/java/util</a></code> (<a href=
+ "http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/util/src/org/xmlpull/v1/util/">view
CVS</a>).</p>
-<p>
-TODO: add link to JavaDoc</p>
-
-
-
-
-
-<p>
- </p>
-
-
+ <p>TODO: add link to JavaDoc</p>
+ <p> </p>
-<a name="dom2_builder">
-<h2>DOM2 builder</h2>
-</a>
+ <h2><a name="dom2_builder" id="dom2_builder">DOM2 builder</a></h2>
-<p>This is <em>very</em> simple class to build DOM2 tree using XmlPull parser.
-</p>
+ <p>This is <em>very</em> simple class to build DOM2 tree using XmlPull parser.</p>
<p>Here is example usage:</p>
-<pre>import org.xmlpull.v1.dom2_builder.DOM2XmlPullBuilder;
+ <pre>
+import org.xmlpull.v1.dom2_builder.DOM2XmlPullBuilder;
Reader reader = ...
DOM2XmlPullBuilder builder = new DOM2XmlPullBuilder();
dom2builder.parse(reader);
</pre>
-<p>It can be compiled by build target <code>dom2_builder</code>
-
-</p><p>Source code is available in <code>addons/java/dom2_builder</code>.
+ <p>It can be compiled by build target <code>dom2_builder</code></p>
-</p><p>
-NOTE: this is very simple class and builds DOM2 tree that contains only elements
-and text content (collated).
-</p>
+ <p>Source code is available in <code>addons/java/dom2_builder</code>.</p>
+ <p>NOTE: this is very simple class and builds DOM2 tree that contains only elements and text content (collated).</p>
-</p><p>Source code is available in <code>
-<a href="../addons/java/dom2_builder/src/org/xmlpull/v1/dom2_builder/">addons/java/dom2_builder</a></code>
-(<a href="http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/dom2_builder/src/org/xmlpull/v1/dom2_builder/">view
+ <p>Source code is available in <code><a href=
+ "../addons/java/dom2_builder/src/org/xmlpull/v1/dom2_builder/">addons/java/dom2_builder</a></code> (<a href=
+ "http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/dom2_builder/src/org/xmlpull/v1/dom2_builder/">view
CVS</a>).</p>
-<p>
- </p>
-
-
-
+ <p> </p>
-<a name="parser_pool">
-<h2>Parser pool</h2>
-</a>
+ <h2><a name="parser_pool" id="parser_pool">Parser pool</a></h2>
-<p>This class provides simple parser pool to facilitate parser reuse.
+ <p>This class provides simple parser pool to facilitate parser reuse.</p>
<p>Example usage:</p>
-
-<pre>import org.xmlpull.v1.parser_pool.XmlPullParserPool;
+ <pre>
+import org.xmlpull.v1.parser_pool.XmlPullParserPool;
XmlPullParserPool pool = new XmlPullParserPool();
XmlPullParser parser = pool.getPullParserFromPool();
@@ -181,99 +148,68 @@
pool.returnPullParserToPool(p1);
</pre>
-<p>It can be compiled by build target <code>parser_pool</code>
-
-</p><p>Source code is available in <code>addons/java/parser_pool</code>.</p>
-
-
-
-<p>NOTE: parser pool is safe to share between multiple threads but parser
-instances<b> are not </b>safe to share.</p>
+ <p>It can be compiled by build target <code>parser_pool</code></p>
+ <p>Source code is available in <code>addons/java/parser_pool</code>.</p>
+ <p>NOTE: parser pool is safe to share between multiple threads but parser instances <b>are not</b> safe to
+ share.</p>
-</p><p>Source code is available in <code>
-<a href="../addons/java/parser_pool/src/org/xmlpull/v1/parser_pool/">addons/java/parser_pool</a></code>
-(<a href="http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/parser_pool/src/org/xmlpull/v1/parser_pool/">view
+ <p>Source code is available in <code><a href=
+ "../addons/java/parser_pool/src/org/xmlpull/v1/parser_pool/">addons/java/parser_pool</a></code> (<a href=
+ "http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/parser_pool/src/org/xmlpull/v1/parser_pool/">view
CVS</a>).</p>
-<p> </p>
-
+ <p> </p><a name="sax2" id="sax2"></a>
-<a name="sax2">
-</a>
-<a name="sax2_driver">
-<h2>SAX2 driver</h2>
-</a>
+ <h2><a name="sax2_driver" id="sax2_driver">SAX2 driver</a></h2>
-<p>This addon allows to use SAX2 API with XmlPull parser. This driver implements
-SAX2
+ <p>This addon allows to use SAX2 API with XmlPull parser. This driver implements SAX2</p>
-</p>
-
-<p>To use simply set system property
-<code>-Dorg.xml.sax.driver=org.xmlpull.v1.sax2.Driver</code> and then SAX2
+ <p>To use simply set system property <code>-Dorg.xml.sax.driver=org.xmlpull.v1.sax2.Driver</code> and then SAX2
standard API:</p>
+ <pre>
+XMLReader parser = XMLReaderFactory.createXMLReader ();
+</pre>
-<pre>XMLReader parser = XMLReaderFactory.createXMLReader ();</pre>
-
-<p>or manually create driver:
-</p>
-
-<pre>XMLReader parser = new <code>org.xmlpull.v1.sax2.Driver</code>();</pre>
-
-<pre></pre>
-
-<p>This addon can be compiled by build target <code>sax2</code>
-
-</p><p>Source code is available in <code>addons/java/sax2_driver</code>.
-
-</p><p>
-NOTE: this driver is not going to work in MIDP environments. To port it to J2ME
-MIDP it is required to change also SAX2 API and to modify Driver not to use URL
-class that is not available in MIDP (check Driver.parse() method).
-</p>
-
-</p><p>Source code is available in <code>
-<a href="../addons/java/sax2_driver/src/org/xmlpull/v1/sax2/">addons/java/sax2</a></code>
-(<a href="http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/sax2_driver/src/org/xmlpull/v1/sax2/">view
-CVS</a>).</p>
-
-<p>
- </p>
+ <p>or manually create driver:</p>
+ <pre>
+XMLReader parser = new <code>org.xmlpull.v1.sax2.Driver</code>();
+</pre>
-<a name="xmlrpc">
-<h2>XML RPC parser</h2>
-</a>
-<p>It can be compiled by build target <code>xmlrpc</code>
+ <p>This addon can be compiled by build target <code>sax2</code></p>
+ <p>Source code is available in <code>addons/java/sax2_driver</code>.</p>
+ <p>NOTE: this driver is not going to work in MIDP environments. To port it to J2ME MIDP it is required to change also
+ SAX2 API and to modify Driver not to use URL class that is not available in MIDP (check Driver.parse() method).</p>
-</p><p>Source code is available in <code>
-<a href="../addons/java/xmlrpc/src/org/xmlpull/v1/xmlrpc/">addons/java/dom2_builder</a></code>
-(<a href="http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/xmlrpc/src/org/xmlpull/v1/xmlrpc/">view
+ <p>Source code is available in <code><a href=
+ "../addons/java/sax2_driver/src/org/xmlpull/v1/sax2/">addons/java/sax2</a></code> (<a href=
+ "http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/sax2_driver/src/org/xmlpull/v1/sax2/">view
CVS</a>).</p>
+ <p> </p>
-</p> </p>
+ <h2><a name="xmlrpc" id="xmlrpc">XML RPC parser</a></h2>
+ <p>It can be compiled by build target <code>xmlrpc</code></p>
+ <p>Source code is available in <code><a href=
+ "../addons/java/xmlrpc/src/org/xmlpull/v1/xmlrpc/">addons/java/dom2_builder</a></code> (<a href=
+ "http://www.xmlpull.org/viewcvs/~checkout~/xmlpull-api-v1/addons/java/xmlrpc/src/org/xmlpull/v1/xmlrpc/">view
+ CVS</a>).</p>
-<a name="notes">
-<h2>Additional notes</h2>
-</a>
+ <h2><a name="notes" id="notes">Additional notes</a></h2>
-<a name="sax2_example">
-<h3>How to extend SAX2 driver to provide Attributes that are safe to keep after
-startElement?</h3>
-</a>
+ <h3><a name="sax2_example" id="sax2_example">How to extend SAX2 driver to provide Attributes that are safe to keep
+ after startElement?</a></h3>
-<p>If you want to extend SAX2 Driver to provides a separate Attributes object
-for each startElement call (so it is safe to keep the reference to Attributes)
-then create class AttributesCachingDriver that extends current SAX2 driver
-(need to do it was requested by Holger Krug), for example:
-</p>
-<pre>import org.xml.sax.SAXException;
+ <p>If you want to extend SAX2 Driver to provides a separate Attributes object for each startElement call (so it is
+ safe to keep the reference to Attributes) then create class AttributesCachingDriver that extends current SAX2 driver
+ (need to do it was requested by Holger Krug), for example:</p>
+ <pre>
+import org.xml.sax.SAXException;
import org.xml.sax.helpers.AttributesImpl;
import org.xmlpull.v1.XmlPullParser;
@@ -303,46 +239,64 @@
}
</pre>
+ <address>
+ <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a> and <a href=
+ "http://www.trantor.de/stefan.haustein/">Stefan Haustein</a>
+ </address>
+ <hr />
+ <font size="-1">Last modified $Id: addons.html,v 1.9 2005/08/29 17:30:49 aslom Exp $</font>
+ <!--extra space at bottom for hyperlinks #anchors to work -->
-</p>
+ <p><br /></p>
+ <p><br /></p>
-<p>
-<address><a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a>
- and <a href="http://www.trantor.de/stefan.haustein/">Stefan Haustein</a>
-</address>
+ <p><br /></p>
-</p><hr>
-<font size="-1">
-Last modified $Id: addons.html,v 1.8 2003/07/08 21:17:34 aslom Exp $
-</font>
+ <p><br /></p>
-<!--extra space at bottom for hyperlinks #anchors to work -->
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
-<p> <br>
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
+
+ <p><br /></p>
-</body></html>
\ No newline at end of file
+ <p><br /></p>
+</body>
+</html>
1.56 +383 -347 xmlpull-api-v1/doc/changes.html
Index: changes.html
===================================================================
RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/changes.html,v
retrieving revision 1.55
retrieving revision 1.56
diff -u -b -t -w -r1.55 -r1.56
--- changes.html 28 Feb 2005 20:41:25 -0000 1.55
+++ changes.html 29 Aug 2005 17:30:49 -0000 1.56
@@ -1,347 +1,383 @@
-<HTML>
-<HEAD>
-<TITLE>XmlPull v1 API Changes
-</TITLE>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="Author" content="Aleksander Slominski [http://www.extreme.indiana.edu/~aslom]">
-</HEAD>
-<BODY BGCOLOR="white">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<H1>Changes to XmlPull v1 API</H1><P>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta name="generator" content="HTML Tidy for Windows (vers 12 April 2005), see www.w3.org" />
+
+ <title>XmlPull v1 API Changes</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta name="Author" content="Aleksander Slominski [http://www.extreme.indiana.edu/~aslom]" />
+</head>
+
+<body bgcolor="white">
+ <h1>Changes to XmlPull v1 API</h1>
+
+ <h3>IN PROGRESS: <a name="XMLPULL_1_2_1" id="XMLPULL_1_2_1"></a>2004-02-... (XMLPULL_1_2_1)</h3>
-<h3>IN PROGRESS: <a name="XMLPULL_1_2_1"></a>2004-02-... (XMLPULL_1_2_1)</h3>
<ul>
-<li>this will be next official stable release (based on last of 1.1.x) to
-incorporate all changes since 1.0.x in stable version </ul>
+ <li>this will be next official stable release (based on last of 1.1.x) to incorporate all changes since 1.0.x in
+ stable version</li>
+ </ul>
<h3>IN PROGRESS INTERIM RELEASE: </h3>
<h3><a name="XMLPULL_1_1_3_*"></a>2005-02- (XMLPULL_1_1_3_*)</h3>
-<ul>
-<li>2005-02-28: replaced xpp.START_TAG with XmlPullParser.START_TAG (and
-similiar) everywhere (removes static access through instance warnings, except
-for mess it is TYPES ...), minor typos fixed, incremented minor version
+ <ul>
+ <li>2005-02-28: replaced xpp.START_TAG with XmlPullParser.START_TAG (and similiar) everywhere (removes static
+ access through instance warnings, except for mess it is TYPES ...), minor typos fixed, incremented minor version
(1.1.3.4b)</li>
-<li>2004-02-13: added sample that demonstrates how to use XmlPullParser that
-implements Cloneable to allow exploring efficient "What-If" parsing, for more
-details see <a href="http://groups.yahoo.com/group/xmlpull-user/message/132">
-mailing list archies</a>.</li>
-<li>2004-02-01: fixed style issue raised by Max Gilead related to unnecessary
-use of public modifier in interfaces (<a href="http://www.extreme.indiana.edu/bugzilla/show_bug.cgi?id=174">bug
-174</a>)</li>
-<li>2004-01-20: stronger serializer tests for case when char values < 32" (TestSerialize.java)</li>
-<li>added <code>target="1.1"</code> to make sure that compiled code can work with JDK 1.1
-(as described in <a href="http://ant.apache.org/manual/CoreTasks/javac.html">ANT Javac Task documentation</a>: (...)
-Generate class files for specific VM version (e.g., 1.1 or 1.2).
-Note that the default value depends on the JVM that is running Ant.
-In particular, if you use JDK 1.4 the generated classes <b>will not be usable for a 1.1 Java VM unless</b>
-you explicitly set this attribute to the value 1.1 (which is the default value for JDK 1.1 to 1.3).
-</li>
-<li>added test to check that workaround from issue "unable to select prefix to
-use when writing startTag, endTag, and attribute" "
-(<a href="http://www.extreme.indiana.edu/bugzilla/show_bug.cgi?id=169">bug 169</a>) is tested</li>
-<li>updated unit test to check for disallowed "]]>" in character content, more
-tests for CDSECT</li>
-<li>changed DOM2 builder addon to be completely stateless factory
-and made factory constructor empty
-</li>
-<li>improved DOM2 builder addon to allow building DOM tree from only part of
-XML pull even stream and still have all namespaces declared
-</li>
-<li>IN PROGRESS (currently code is commented out):
-added methods to wrapper to encapsulate need to read some of XSD simple types
-(partially based on <a href="http://jibx.sourceforge.net/">JiBX</a>)
-</li>
+ <li>2004-02-13: added sample that demonstrates how to use XmlPullParser that implements Cloneable to allow
+ exploring efficient "What-If" parsing, for more details see <a href=
+ "http://groups.yahoo.com/group/xmlpull-user/message/132">mailing list archies</a>.</li>
+
+ <li>2004-02-01: fixed style issue raised by Max Gilead related to unnecessary use of public modifier in interfaces
+ (<a href="http://www.extreme.indiana.edu/bugzilla/show_bug.cgi?id=174">bug 174</a>)</li>
+
+ <li>2004-01-20: stronger serializer tests for case when char values < 32" (TestSerialize.java)</li>
+
+ <li>added <code>target="1.1"</code> to make sure that compiled code can work with JDK 1.1 (as described in <a href=
+ "http://ant.apache.org/manual/CoreTasks/javac.html">ANT Javac Task documentation</a>: (...) Generate class files
+ for specific VM version (e.g., 1.1 or 1.2). Note that the default value depends on the JVM that is running Ant. In
+ particular, if you use JDK 1.4 the generated classes <b>will not be usable for a 1.1 Java VM unless</b> you
+ explicitly set this attribute to the value 1.1 (which is the default value for JDK 1.1 to 1.3).</li>
+
+ <li>added test to check that workaround from issue "unable to select prefix to use when writing startTag, endTag,
+ and attribute" " (<a href="http://www.extreme.indiana.edu/bugzilla/show_bug.cgi?id=169">bug 169</a>) is tested</li>
+
+ <li>updated unit test to check for disallowed "]]>" in character content, more tests for CDSECT</li>
+
+ <li>changed DOM2 builder addon to be completely stateless factory and made factory constructor empty</li>
+
+ <li>improved DOM2 builder addon to allow building DOM tree from only part of XML pull even stream and still have
+ all namespaces declared</li>
+
+ <li>IN PROGRESS (currently code is commented out): added methods to wrapper to encapsulate need to read some of XSD
+ simple types (partially based on <a href="http://jibx.sourceforge.net/">JiBX</a>)</li>
+ </ul>
+
+ <h3><a name="XMLPULL_1_1_3_1" id="XMLPULL_1_1_3_1"></a>2003-05-19 (XMLPULL_1_1_3_1)</h3>
+
+ <ul>
+ <li>added set of <a href="addons.html">addons</a> that add new functionality or extend existing interfaces in
+ XmlPull API</li>
+
+ <li>updated tests to look for boundary cases with PI/comments and next() (thanks to Henry Minsky)</li>
+
+ <li>marked all supported optional features and properties as such in unit tests summary</li>
+
+ <li>changed XmlPullParserFactory.newInstance() to use XmlPullParserFactory class as default class context and not
+ String.class because when using String we will never find /META-INF/services/org.xmlpull.v1.XmlPullParserFactory
+ resource ...</li>
</ul>
+ <h3><a name="XMLPULL_1_1_2_1" id="XMLPULL_1_1_2_1"></a>2003-02-26 (XMLPULL_1_1_2_1)</h3>
-<h3><a name="XMLPULL_1_1_3_1"></a>2003-05-19 (XMLPULL_1_1_3_1)</h3>
<ul>
+ <li>minor release to make available the latest tests and documentation changes</li>
-<li>added set of <a href="addons.html">addons</a> that add new functionality
-or extend existing interfaces in XmlPull API
+ <li>added <a href="quick_write.html">quick introduction to using XmlSerializer</a></li>
-<li>updated tests to look for boundary cases with PI/comments and next() (thanks to Henry Minsky)
-<li>marked all supported optional features and properties as such in unit tests summary
+ <li>added test to check that generating namespace prefix for attributes is allowed (method getPrefix(uri, true)
+ called after startTag() should add new prefix to current start tag elements and not next start tag)</li>
+ <li>added tests to check optional support for formatting XML output from XML serializer</li>
-<li>changed XmlPullParserFactory.newInstance() to use XmlPullParserFactory class
-as default class context and not String.class because when using String we will never
-find /META-INF/services/org.xmlpull.v1.XmlPullParserFactory resource ...
+ <li>SAX2 driver moved to addons, removed AttributesCachingDriver but left documented how to achieve this
+ functionality</li>
+ <li>added to addons XML RPC implementation</li>
</ul>
-<h3><a name="XMLPULL_1_1_2_1"></a>2003-02-26 (XMLPULL_1_1_2_1)</h3>
+ <h3><a name="XMLPULL_1_1_2" id="XMLPULL_1_1_2"></a>2002-10-16 (XMLPULL_1_1_2)</h3>
<ul>
-<li>minor release to make available the latest tests and documentation changes
+ <li><b>NOTE:</b> <b>potentially backward incompatible change to nextToken</b>(): XMLDecl (<?xml ... ?>) will
+ no longer be reported as PROCESSING_INSTRUCTION but instead content of XMLDecl is made available as set of
+ properties <a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-version">XMLDECL VERSION</a> <a href=
+ "http://xmlpull.org/v1/doc/features.html#xmldecl-standalone">XMLDECL STANDALONE</a> and <a href=
+ "http://xmlpull.org/v1/doc/features.html#xmldecl-content">XMLDECL CONTENT</a>.</li>
+
+ <li>J2ME compatibility issue fixed: changed to use <tt>instanceof</tt> instead of .class in
+ XmlPullParserFactory</li>
-<li>added <a href="quick_write.html">quick introduction to using XmlSerializer</a>
+ <li>added to XmlSerializer three new utility methods: getDepth(), getName(), and getNamespace() to allows
+ intelligent closing of serialized output for example when writing error/fault information into serialized XML
+ stream from inside exception handler</li>
-<li>added test to check that generating namespace prefix for attributes is allowed
-(method getPrefix(uri, true) called after startTag() should add new prefix to
-current start tag elements and not next start tag)
+ <li>changed tests to reflect changed handling of XMLDecl and added tests to check for optional XMLDecl
+ properties</li>
-<li>added tests to check optional support for formatting XML output from XML serializer
+ <li>XmlSerializer is now required to throw exception when user tries to write startTag() in default namespace ("")
+ and default namespace is bound to non-empty string, added test to check for it</li>
-<li>SAX2 driver moved to addons,
-removed AttributesCachingDriver but left documented how to achieve this functionality
-<li>added to addons XML RPC implementation
+ <li>added patch by Holger Krug to SAX2 Driver to allow modification in sub classes of how Attributes in
+ startElement() are kept. Added also AttributesCachingDriver that extends SAX2 Driver to create a new copy of
+ Attributes for each startElement() so Attributes provided in startTag() will not change during parsing and can be
+ kept indefinitely (not that Attributes object is created for each startTag() and this is expensive both performance
+ and memory wise and is not required by SAX2.</li>
+
+ <li>more tests to check for CDATA end-of-line normalization</li>
+
+ <li>changed tests to require support for ROUNDTRIP==false and additional checks for EOL normalization of
+ tokens</li>
</ul>
+ <h3> </h3>
-<h3><a name="XMLPULL_1_1_2"></a>2002-10-16 (XMLPULL_1_1_2)</h3>
+ <h3><a name="XMLPULL_1_1_1" id="XMLPULL_1_1_1"></a>2002-08-27 (XMLPULL_1_1_1)</h3>
<ul>
-<li><b>NOTE:</b> <b>potentially backward incompatible change to nextToken</b>():
-XMLDecl (<?xml ... ?>) will no longer be reported as PROCESSING_INSTRUCTION
-but instead content of XMLDecl is made available as set of properties
-<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-version">XMLDECL VERSION</a>
-<a href="http://xmlpull.org/v1/doc/features.html#xmldecl-standalone">XMLDECL STANDALONE</a>
-and
-<a href="http://xmlpull.org/v1/doc/features.html#xmldecl-content">XMLDECL CONTENT</a>.
+ <li><strong>NEW! XmlSerializer API</strong> that is now required part of XMLPULL API on J2SE (on J2ME typically
+ factory is not used and only implementation of serializer or parser may be available).</li>
-<li>J2ME compatibility issue fixed: changed to use <tt>instanceof</tt> instead
-of .class in XmlPullParserFactory
+ <li><b>NOTE:</b> <b>potentially backward incompatible change to nextToken</b>(): content returned by
+ getText()/getTextCharacters() is end-of-line normalized and also IGNORABLE_WHITESPACE for content outside element
+ root and end-of-line unnormalized content for elements MAY not reported by nextToken() (unless optional <a href=
+ "http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP feature</a> is false). However if
+ <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP feature</a> is true parser behavior
+ is exactly the same as in previous XmlPull API version . This change is made to improve compatibility with XML by
+ requiring normalized content as described in <a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0
+ End-of-Line Handling</a> and with XML infoset <a href=
+ "http://www.w3.org/TR/xml-infoset/#infoitem.document">Document Information Item properties</a> which only contain
+ comments and processing instructions but not white space content (so now reporting IGNORABLE_WHITESPACE event
+ outside is optional). </li>
+
+ <li>added optional features EXPAND ENTITY REF and SERIALIZER ATTVALUE USE APOSTROPHE</li>
+
+ <li>added optional properties related to indenting serializer output (pretty printing): SERIALIZER
+ INDENTATION, SERIALIZER LINE SEPARATOR</li>
+
+ <li>added clarification to nextToken() that there is no requirement for reported token events to be coalesced (for
+ example nextToken() may report multiple consecutive TEXT or IGNORABLE_WHITESPACE events). This is different from
+ next() that always report exactly one TEXT event</li>
+
+ <li>conformance tests can be now described in XML allowing to keep tests in format independent from Java (and
+ potentially to use the same XML tests with other XmlPull API bindings such as C++ or PHP) XML files with tests are
+ read from CLASSPATH</li>
-<li>added to XmlSerializer three new utility methods:
-getDepth(), getName(), and getNamespace()
-to allows intelligent closing of serialized output for example
-when writing error/fault information into serialized XML stream
-from inside exception handler
+ <li>added newSerializer() method to XmlPullParserFactory</li>
-<li>changed tests to reflect changed handling of XMLDecl
-and added tests to check for optional XMLDecl properties
+ <li>added new FAQ entries:
-<li>XmlSerializer is now required to throw exception when user tries to
-write startTag() in default namespace ("") and default namespace is bound
-to non-empty string, added test to check for it
+ <ul>
+ <li><a href="faq.html#API_DESIGN">Why is there only one "large" interface, wouldn't it be cleaner to use event
+ objects and polymorphism?</a></li>
-<li>added patch by Holger Krug to SAX2 Driver to allow modification in sub classes
-of how Attributes in startElement() are kept. Added also AttributesCachingDriver
-that extends SAX2 Driver to create a new copy of Attributes for each startElement()
-so Attributes provided in startTag() will not change during parsing and can be kept
-indefinitely (not that Attributes object is created for each startTag() and this
-is expensive both performance and memory wise and is not required by SAX2.
+ <li><a href="faq.html#3NEXT">What is the difference between <tt>nextToken()</tt>, <tt>next()</tt>,
+ <tt>nextTag()</tt>, and <tt>nextText()</tt>?</a></li>
-<li>more tests to check for CDATA end-of-line normalization
+ <li><a href="faq.html#NEXT_MOTIV">Why are there different <tt>next()</tt> methods, wouldn't it be cleaner to
+ have a set method, allowing me to specify the type of events I am interested in in general?</a></li>
+ </ul>
+ </li>
-<li>changed tests to require support for ROUNDTRIP==false
-and additional checks for EOL normalization of tokens
+ <li>list of class names with factory, serializer and/or parser must be now separated by colon in XMLPULL tests
+ property (<code>org.xmlpull.v1.tests</code>), for example:
+ <code>-Dorg.xmlpull.v1.tests=DEFAULT:org.xmlpull.mxp1.MXParser,org.xmlpull.mxp1_serializer.MXSerializer</code></li>
+ <li>changed XmlPullParser constants to be all consistently <samp>int</samp> (few were declared as <samp>byte</samp>
+ ...)</li>
</ul>
-<h3> </h3>
+ <h3><a name="XMLPULL_1_0_8" id="XMLPULL_1_0_8"></a>2002-04-24 (XMLPULL_1_0_8)</h3>
-<h3><a name="XMLPULL_1_1_1"></a>2002-08-27 (XMLPULL_1_1_1)</h3>
<ul>
-<li><strong>NEW! XmlSerializer API</strong> that is now required part of XMLPULL
-API on J2SE (on J2ME typically factory is not used and only implementation of
-serializer or parser may be available).
-
-<li><b>NOTE:</b> <b>potentially backward incompatible change to nextToken</b>():
-content returned by getText()/getTextCharacters() is end-of-line normalized and
-also IGNORABLE_WHITESPACE for content outside element root and end-of-line
-unnormalized content for elements MAY not reported by nextToken() (unless optional
-<a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP
-feature</a> is false). However if
-<a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP
-feature</a> is true parser behavior is exactly the same as in previous XmlPull
-API version . This change is made to improve compatibility with XML
-by requiring normalized content as described in
-<a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line
-Handling</a> and with XML infoset <a href="http://www.w3.org/TR/xml-infoset/#infoitem.document">Document
-Information Item properties</a> which only contain comments and processing
-instructions but not white space content (so now reporting IGNORABLE_WHITESPACE
-event outside is optional).
-
-<li>added optional features EXPAND ENTITY REF and SERIALIZER ATTVALUE USE
-APOSTROPHE<li>added optional properties related to indenting serializer output
-(pretty printing): SERIALIZER INDENTATION, SERIALIZER LINE SEPARATOR<li>added clarification to nextToken() that there is no requirement for reported
-token events to be coalesced (for example nextToken() may report multiple
-consecutive TEXT or IGNORABLE_WHITESPACE events). This is different from next()
-that always report exactly one TEXT event<li>conformance tests can be now described in XML allowing to keep tests in
-format independent from Java (and potentially to use the same XML tests with
-other XmlPull API bindings such as C++ or PHP) XML files with tests are read
-from CLASSPATH<li>added newSerializer() method to XmlPullParserFactory
+ <li>
+ <b>two API changes are not backward compatible</b> with 1.0.7:
-<li>added new FAQ entries:
+ <ul>
+ <li><b>readText</b>() function was <b>removed</b>, please use nextText() instead</li>
+
+ <li><b>require</b>() is <b>changed</b> - no longer will skip white space content</li>
+ </ul>
+ </li>
+
+ <li>added <b>new functions</b>:
<ul>
+ <li>getAttributeType(index)</li>
-<li><a href="faq.html#API_DESIGN">Why is there only one "large" interface,
-wouldn't it be cleaner to use event objects and polymorphism?</a>
+ <li>isAttributeDefault(index)</li>
+ <li>setInput(InputStream is, String inputEncoding)</li>
-<li><a href="faq.html#3NEXT">What is the difference between
-<tt>nextToken()</tt>, <tt>next()</tt>, <tt>nextTag()</tt>, and <tt>nextText()</tt>?</a>
+ <li>getInputEncoding()</li>
-<li><a href="faq.html#NEXT_MOTIV">Why are there different <tt>next()</tt> methods, wouldn't it be cleaner to
-have a set method, allowing me to specify the type of events I am interested in
-in general?</a>
+ <li>nextText()</li>
+ <li>nextTag()</li>
</ul>
+ </li>
+ <li>modified tests to allow -1 for column or line number and updated Javadoc to reflect it</li>
+ <li>updated all tests to check new functions</li>
-<li>list of class names with factory, serializer and/or parser must be now
-separated by colon in XMLPULL tests property (<code>org.xmlpull.v1.tests</code>), for example:
-<code>-Dorg.xmlpull.v1.tests=DEFAULT:org.xmlpull.mxp1.MXParser,org.xmlpull.mxp1_serializer.MXSerializer</code>
+ <li>modified test driver PackageTest to accept list of XMLPULL factories or parsers to check from system property
+ <b>org.xmlpull.v1.test</b>, DEFAULT can be used to indicate using of default parser factory (taken from system
+ property or resource from CLASSPATH), for example:<br />
+ -Dorg.xmlpull.v1.tests=DEFAULT,org.xmlpull.mxp1.MXParser</li>
-<li>changed XmlPullParser constants to be all consistently <samp>int</samp> (few were declared as
-<samp>byte</samp> ...)
+ <li>modified XmlPullParserFactory to use resource from CLASSPATH when not only classNames is null but also if
+ classNames is empty String or if it is equal to "DEFAULT"</li>
+ <li>improved error messages in XmlPullParserFactory to better diagnose why new pull parser can not be created</li>
+
+ <li>added test to check that when on END_TAG namespaces that were declared in corresponding START_TAG are still
+ accessible even though they are not in scope</li>
+
+ <li>added tests to check that setInput() does not read any bytes from input stream or characters from reader until
+ first call to next()</li>
</ul>
-<h3><a name="XMLPULL_1_0_8"></a>2002-04-24 (XMLPULL_1_0_8)</h3>
+ <h3>2002-04-20 (XMLPULL_1_0_7_1)</h3>
+
<ul>
-<li><b>two API changes are not backward compatible</b> with 1.0.7:
+ <li>fixed Quick Introduction to use correct API for getTextCharacters and getEventType (instead of getType)</li>
+
+ <li>added requirement to getNamespace(prefix) to have 'xml' and 'xmlns' pre-declared</li>
+
+ <li>removed from getNamespace(prefiix) exception XmlPullParserException as this function simply returns null when
+ namespace is not declared ...</li>
+
+ <li>updated tests:
+
<ul>
-<li><b>readText</b>() function was <b>removed</b>, please use nextText() instead
-<li><b>require</b>() is <b>changed</b> - no longer will skip white space content
+ <li>updated header with license pointer to <a href="http://www.xmlpull.org">http://www.xmlpull.org</a></li>
+
+ <li>added printing test summary (parser used, supported features)</li>
+
+ <li>added one test to check that tokens are equivalent to events (next() <-> nextToken())</li>
</ul>
-<li>added <b>new functions</b>:<ul>
-<li>getAttributeType(index)
-<li>isAttributeDefault(index)
-<li>setInput(InputStream is, String inputEncoding)
-<li>getInputEncoding()
-<li>nextText()
-<li>nextTag()
+ </li>
</ul>
-<li>modified tests to allow -1 for column or line number and updated Javadoc to reflect it
-<li>
-updated all tests to check new functions<li>
-modified test driver PackageTest to accept list of XMLPULL factories or parsers
-to check from system property <b>org.xmlpull.v1.test</b>, DEFAULT can be used to
-indicate using of default parser factory (taken from system property or resource
-from CLASSPATH), for example: <br>
--Dorg.xmlpull.v1.tests=DEFAULT,org.xmlpull.mxp1.MXParser<li>
-modified XmlPullParserFactory to use resource from CLASSPATH when not only classNames is null
-but also if classNames is empty String or if it is equal to "DEFAULT"<li>
-improved error messages in XmlPullParserFactory to better diagnose why new pull
-parser can not be created<li>
-added test to check that when on END_TAG namespaces that were declared in
-corresponding START_TAG are still accessible even though they are not in scope<li>
-added tests to check that setInput() does not read any bytes from input stream
-or characters from reader until first call to next()</ul>
-<h3>2002-04-20 (XMLPULL_1_0_7_1)</h3>
+ <h3><span style="font-weight: 400"><a name="XMLPULL_1_0_7" id="XMLPULL_1_0_7"></a></span>2002-04-08
+ (XMLPULL_1_0_7)</h3>
+
<ul>
-<li>
-fixed Quick Introduction to use correct API for getTextCharacters and
-getEventType (instead of getType)<li>
-added requirement to getNamespace(prefix) to have 'xml' and 'xmlns' pre-declared<li>
-removed from getNamespace(prefiix) exception XmlPullParserException as this
-function simply returns null when namespace is not declared ...<li>
-updated tests:<ul>
-<li>updated header with license pointer to <a href="http://www.xmlpull.org">
-http://www.xmlpull.org</a>
-<li>added printing test summary (parser used, supported features)
-<li>added one test to check that tokens are equivalent to events (next() <->
-nextToken())
-</ul>
+ <li>changed default namespace semantics: the prefix must be reported as null and not empty string from
+ getNamespacePrefix(depth) and getNamespace(null) must return default namespace if declared in XML</li>
+
+ <li>modified getText() method behavior for ENTITY_REF: in this case getText() must return entity replacement text
+ and getTextCharacters() returns actual input buffer with entity name the same as getName()</li>
+
+ <li>for ENTITY_REF token getName() must return entity name</li>
+
+ <li>added specific requirement that attribute values MUST be normalized</li>
</ul>
-<h3><span style="font-weight: 400"><a name="XMLPULL_1_0_7"></a></span>2002-04-08 (XMLPULL_1_0_7)</h3>
+ <h3>2002-04-06 (XMLPULL_1_0_6)</h3>
+
<ul>
-<li>
-changed default namespace semantics: the prefix must be reported as null and not
-empty string from getNamespacePrefix(depth) and getNamespace(null) must return
-default namespace if declared in XML<li>
-modified getText() method behavior for ENTITY_REF: in this case getText() must
-return entity replacement text and getTextCharacters() returns actual input
-buffer with entity name the same as getName()<li>
-for ENTITY_REF token getName() must return entity name<li>
-added specific requirement that attribute values MUST be normalized</ul>
+ <li>changed hard coded parser factory in XmlPullParserFactory name for KXML2 to org.kxml2.io.KXmlParserFactory</li>
+
+ <li>clarified required semantics in <a href="features.html">features</a> description</li>
+
+ <li>refactored XmlPullParserFactory:
-<h3>2002-04-06 (XMLPULL_1_0_6)</h3>
<ul>
-<li>
-changed hard coded parser factory in XmlPullParserFactory name for KXML2 to
-org.kxml2.io.KXmlParserFactory<li>
-clarified required semantics in <a href="features.html">features</a> description
-<li>
-refactored XmlPullParserFactory: <ul>
-<li>reduced in size as much as possible,
-<li>String classNames
-in newInstance() can now specify both
-factories and parsers
-<li>removed method newInstance(String classNames) the same can be done with newInstance(classNames,
-null)<li>modified tests use newInstance(*,null) instead of one argument version</ul>
-<li>
-removed constructor with line numbers and Throwable from XmlPullParserException<li>
-changed API to add default namespace declaration to be counted in
-getNamespaceCount() and available from getNamespace...(...) methods<li>
-refactored tests for common problem: check if no XMLPULL implementation
-available and print just one error message (instead of dozen...)</ul>
+ <li>reduced in size as much as possible, </li>
+
+ <li>String classNames in newInstance() can now specify both factories and parsers</li>
+
+ <li>removed method newInstance(String classNames) the same can be done with newInstance(classNames, null)</li>
+
+ <li>modified tests use newInstance(*,null) instead of one argument version</li>
+ </ul>
+ </li>
+
+ <li>removed constructor with line numbers and Throwable from XmlPullParserException</li>
+
+ <li>changed API to add default namespace declaration to be counted in getNamespaceCount() and available from
+ getNamespace...(...) methods</li>
+
+ <li>refactored tests for common problem: check if no XMLPULL implementation available and print just one error
+ message (instead of dozen...)</li>
+ </ul>
<h3>2002-04-03 (XMLPULL_1_0_5)</h3>
+
<ul>
-<li>
-changed features URI to point to actual documentation on
-<a href="http://www.xmlpull.org">http://www.xmlpull.org</a>
-<li>
-automatic JUnit tests now covers whole API<li>
-clarified isWhitespace() can only be checked on TEXT, IGNORABLE_WHITESPACES,
-CDSECT<li>
-clarified what is attribute namespace for xmlns:ns='...' when
-FEATURE_REPORT_NAMESPACE_ATTRIBUTES is set<li>
-changed defineCharacterEntity() to defineEntityReplacementText() and described
-semantics of this function and its motivation in J2ME environments<li>
-clarified how nextToken() works: return un-normalized (no end-of-line
-normalization) parts of XML input<li>
-if additional feature i set then XML text of START_TAG and END_TAG token is
-available allowing to do full XML document roundtrip: reproduce on output
-exactly what was in input. However this works on level of UNICODE characters
-(UTF16 char in Java) and output will need to be converted into required encoding
-(like UTF8 or UTF16).<li>
-getNamespacesCount changed to getNamespaceCount for consistency<li>
-getAttributesCount changed to getAttributeCount for consistency</ul>
+ <li>changed features URI to point to actual documentation on <a href=
+ "http://www.xmlpull.org">http://www.xmlpull.org</a> </li>
+
+ <li>automatic JUnit tests now covers whole API</li>
+
+ <li>clarified isWhitespace() can only be checked on TEXT, IGNORABLE_WHITESPACES, CDSECT</li>
+
+ <li>clarified what is attribute namespace for xmlns:ns='...' when FEATURE_REPORT_NAMESPACE_ATTRIBUTES is set</li>
+
+ <li>changed defineCharacterEntity() to defineEntityReplacementText() and described semantics of this function and
+ its motivation in J2ME environments</li>
+
+ <li>clarified how nextToken() works: return un-normalized (no end-of-line normalization) parts of XML input</li>
+
+ <li>if additional feature i set then XML text of START_TAG and END_TAG token is available allowing to do full XML
+ document roundtrip: reproduce on output exactly what was in input. However this works on level of UNICODE
+ characters (UTF16 char in Java) and output will need to be converted into required encoding (like UTF8 or
+ UTF16).</li>
+
+ <li>getNamespacesCount changed to getNamespaceCount for consistency</li>
+
+ <li>getAttributesCount changed to getAttributeCount for consistency</li>
+ </ul>
<h3>2002-03-30 (XMLPULL_1_0_4)</h3>
+
<ul>
-<li>
-added FEATURE_ prefix to all feature constants<li>
-changed function name getType() to getEventType()<li>
-clarified that getNamespacesCount() does not include default namespaces
-declarations (xmlns='...')<li>
-specified that attributes if has no namespace declared will have "" namespace
-(empty string)<li>
-clarified that when getTextCharacters returns null then holder MUST
-contain start and length will be set to -1]
-<li>added more comprehensive JUnit tests for API conformance
+ <li>added FEATURE_ prefix to all feature constants</li>
+
+ <li>changed function name getType() to getEventType()</li>
+
+ <li>clarified that getNamespacesCount() does not include default namespaces declarations (xmlns='...')</li>
+
+ <li>specified that attributes if has no namespace declared will have "" namespace (empty string)</li>
+
+ <li>clarified that when getTextCharacters returns null then holder MUST contain start and length will be set
+ to -1]</li>
+
+ <li>added more comprehensive JUnit tests for API conformance</li>
</ul>
<h3>2002-03-29 (XMLPULL_1_0_3)</h3>
+
<ul>
-<li>
-changed getTextCharacters to use pass by reference two int parameters (char[]
-getTextCharacters (int [] holderForStartAndLength)<li>
-nextToken() is required to return actual input data with getText() (no
-end-of-line normalization) - this will allow to reconstruct input XML</ul>
+ <li>changed getTextCharacters to use pass by reference two int parameters (char[] getTextCharacters (int []
+ holderForStartAndLength)</li>
+
+ <li>nextToken() is required to return actual input data with getText() (no end-of-line normalization) - this
+ will allow to reconstruct input XML</li>
+ </ul>
<h3>2002-03-28 (XMLPULL_1_0_2a)</h3>
+
<ul>
-<li>
-fixed typos in getAttribute(s)* and getNamespace(s)* functions<li>
-numerous improvements to interface documentation<li>
-clarified PROCESS_DOCDECL and removed REPORT_DOCDECL
-<li>
-initial release of JUnit tests (very limited for now ...)</ul>
+ <li>fixed typos in getAttribute(s)* and getNamespace(s)* functions</li>
+
+ <li>numerous improvements to interface documentation</li>
+
+ <li>clarified PROCESS_DOCDECL and removed REPORT_DOCDECL</li>
+
+ <li>initial release of JUnit tests (very limited for now ...)</li>
+ </ul>
<h3>2002-03-25 (XMLPULL_1_0_1)</h3>
+
<ul>
-<li>first interim release of API and supporting files (incomplete)
+ <li>first interim release of API and supporting files (incomplete)</li>
</ul>
+ <hr />
-
-<HR>
-<address><a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a><address>
-</address>
+ <address>
+ <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a>
</address>
+
<p> </p>
+
<p> </p>
-</BODY>
-</HTML>
\ No newline at end of file
+</body>
+</html>
1.11 +228 -276 xmlpull-api-v1/doc/faq.html
Index: faq.html
===================================================================
RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/faq.html,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -b -t -w -r1.10 -r1.11
--- faq.html 11 Mar 2005 16:50:54 -0000 1.10
+++ faq.html 29 Aug 2005 17:30:49 -0000 1.11
@@ -1,304 +1,256 @@
-<html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
<head>
-<title>XMLPULL FAQ
-</title>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="Author" content="Aleksander Slominski">
+ <meta name="generator" content="HTML Tidy for Windows (vers 12 April 2005), see www.w3.org" />
+
+ <title>XMLPULL FAQ</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta name="Author" content="Aleksander Slominski" />
</head>
-<body bgcolor="white">
+<body bgcolor="white">
<h1>XMLPULL API FAQ</h1>
-<pre>Version $Id: faq.html,v 1.10 2005/03/11 16:50:54 aslom Exp $</pre>
-
-
-<h2><a name="XML_COMP"></a>Is the XMLPULL API V1 compatible with XML 1.0?</h2>
+ <pre>
+Version $Id: faq.html,v 1.11 2005/08/29 17:30:49 aslom Exp $
+</pre>
-<p>If <a href="http://xmlpull.org/v1/doc/features.html#process-docdecl">PROCESS DOCDECL</a>
-is set to true, the XMLPULL implementation is conforming to XML 1.0. However
-this feature is switched off by default and it must be turned on explicitly.</p>
-For XML documents that do not have a DTD declaration, the parser behavior is
-independent of this feature.</p>
-
-<p>By default, all features are
-switched off. This avoids confusion with default settings of parsers
-with different capabilities, and allows parsers for the J2ME
-platform to integrate nicely into the XMLPULL framework.</p>
-
-<h2><a name="SAX2"></a>What is the relation between the SAX2 and the XMLPULL API?</h2>
-
-<p>SAX2 defines how to do XML <b>push parsing</b> and is very well doing when one
-needs to process only parts of XML input (for example when filtering XML).
-The XMLPULL API is designed to allow fast and efficient XML <b>pull parsing</b> that
-is performing best in situation when the whole XML input must be processed and
-transformed (for example SOAP deserialization).</p>
-
-<p>It is important to notice that those two APIs are not overlapping but instead
-they supplement each other. In the matter of fact it is possible to switch
-easily from pull to push (a <a href="#SAX2_DRIVER">SAX2 driver</a> built on top of
-XMLPULL is available), but opposite conversion is more difficult and requires
-either to buffer all SAX events, making streaming impossible, or an extra
-thread (this is explained in more details in a
-<a href="http://www.extreme.indiana.edu/xgws/papers/xml_push_pull/">technical
-report</a>, comparing push and pull parsing).</p>
-
-<p>By designing the XMLPULL API, we intended to provide an API for
-XML developers that is familiar to the SAX look and feel, but is designed
-for pull parsing. If you would like to propose improvements, please do not
-hesitate to post them to the <a href="http://www.xmlpull.org/discussion.shtml">XMLPULL
-discussion list</a>.
-
-<h2><a name="SAX2_DRIVER"></a>Is an adapter implementing SAX2 on top of the XMLPULL
-API available?</h2>
-
-<p>Yes - a SAX2 driver that uses the XMLPULL API to do XML parsing is available in
-the <a href="#CVS">CVS repository</a>.</p>
-
-
-<h2><a name="STATUS"></a>How complete is XMLPULL API?</h2>
-
-<p>The current version of the XMLPULL V1 API is stable and we do not plan any
-backward-incompatible changes though some additions may be possible. However, we
-are open to discussing new
-features on the <a href="http://www.xmlpull.org/discussion.shtml">xmlpull-dev</a>
-mailing list, and we are looking forward to prepare the next major release of
-the XMLPULL API when there is significant need for it (and backward compatibility can
-not be maintained).</p>
-
-
-<h2><a name="API_DESIGN"></a>Why is there only one "large" interface,
-wouldn't it be cleaner to use event objects and polymorphism?</h2>
-
-<p>On the first sight, it really seems cleaner to have event objects and
-polymorphism instead of placing all the access methods in one
-relatively large interface. However, while this would make the XMLPULL
-API "look" somewhat nicer, a separate event object would also
-introduce some issues.</p>
-
-<p>Actually, kXML1 and XPP2 had separate event objects, and the experiences
-gained there partially led to not using separate event objects in the
-Common XML PULL API. The problem is that the different object types do
-not have much in common. Polymorphism makes a lot of sense where an
-identical set of methods can be applied to a set of different
-objects. A good example may be AWT components, having common
-properties and methods such as the position, size, and a paint()
-method. XML start tags and an XML text events have only in common that
-they are observed when parsing an XML document, they do not share a
-single common property.</p>
-
-<p>When using separate event objects, there are several additional
-design options. For example, methods like getAttributeValue() make
-only sense for start tags, so it seems natural to place them only
-there. However, when it comes to actual access, one will require an
-<samp>instanceof</samp> check and a type cast:</p>
+ <h2><a name="XML_COMP" id="XML_COMP"></a>Is the XMLPULL API V1 compatible with XML 1.0?</h2>
-<pre>if (parser.getEvent() instanceOf StartTag ) {
+ <p>If <a href="http://xmlpull.org/v1/doc/features.html#process-docdecl">PROCESS DOCDECL</a> is set to true, the
+ XMLPULL implementation is conforming to XML 1.0. However this feature is switched off by default and it must be
+ turned on explicitly.</p>For XML documents that do not have a DTD declaration, the parser behavior is independent of
+ this feature.
+
+ <p>By default, all features are switched off. This avoids confusion with default settings of parsers with different
+ capabilities, and allows parsers for the J2ME platform to integrate nicely into the XMLPULL framework.</p>
+
+ <h2><a name="SAX2" id="SAX2"></a>What is the relation between the SAX2 and the XMLPULL API?</h2>
+
+ <p>SAX2 defines how to do XML <b>push parsing</b> and is very well doing when one needs to process only parts of XML
+ input (for example when filtering XML). The XMLPULL API is designed to allow fast and efficient XML <b>pull
+ parsing</b> that is performing best in situation when the whole XML input must be processed and transformed (for
+ example SOAP deserialization).</p>
+
+ <p>It is important to notice that those two APIs are not overlapping but instead they supplement each other. In the
+ matter of fact it is possible to switch easily from pull to push (a <a href="#SAX2_DRIVER">SAX2 driver</a> built on
+ top of XMLPULL is available), but opposite conversion is more difficult and requires either to buffer all SAX events,
+ making streaming impossible, or an extra thread (this is explained in more details in a <a href=
+ "http://www.extreme.indiana.edu/xgws/papers/xml_push_pull/">technical report</a>, comparing push and pull
+ parsing).</p>
+
+ <p>By designing the XMLPULL API, we intended to provide an API for XML developers that is familiar to the SAX look
+ and feel, but is designed for pull parsing. If you would like to propose improvements, please do not hesitate to post
+ them to the <a href="http://www.xmlpull.org/discussion.shtml">XMLPULL discussion list</a>.</p>
+
+ <h2><a name="SAX2_DRIVER" id="SAX2_DRIVER"></a>Is an adapter implementing SAX2 on top of the XMLPULL API
+ available?</h2>
+
+ <p>Yes - a SAX2 driver that uses the XMLPULL API to do XML parsing is available in the <a href="#CVS">CVS
+ repository</a>.</p>
+
+ <h2><a name="STATUS" id="STATUS"></a>How complete is XMLPULL API?</h2>
+
+ <p>The current version of the XMLPULL V1 API is stable and we do not plan any backward-incompatible changes though
+ some additions may be possible. However, we are open to discussing new features on the <a href=
+ "http://www.xmlpull.org/discussion.shtml">xmlpull-dev</a> mailing list, and we are looking forward to prepare the
+ next major release of the XMLPULL API when there is significant need for it (and backward compatibility can not be
+ maintained).</p>
+
+ <h2><a name="API_DESIGN" id="API_DESIGN"></a>Why is there only one "large" interface, wouldn't it be cleaner to use
+ event objects and polymorphism?</h2>
+
+ <p>On the first sight, it really seems cleaner to have event objects and polymorphism instead of placing all the
+ access methods in one relatively large interface. However, while this would make the XMLPULL API "look" somewhat
+ nicer, a separate event object would also introduce some issues.</p>
+
+ <p>Actually, kXML1 and XPP2 had separate event objects, and the experiences gained there partially led to not using
+ separate event objects in the Common XML PULL API. The problem is that the different object types do not have much in
+ common. Polymorphism makes a lot of sense where an identical set of methods can be applied to a set of different
+ objects. A good example may be AWT components, having common properties and methods such as the position, size, and a
+ paint() method. XML start tags and an XML text events have only in common that they are observed when parsing an XML
+ document, they do not share a single common property.</p>
+
+ <p>When using separate event objects, there are several additional design options. For example, methods like
+ getAttributeValue() make only sense for start tags, so it seems natural to place them only there. However, when it
+ comes to actual access, one will require an <samp>instanceof</samp> check and a type cast:</p>
+ <pre>
+if (parser.getEvent() instanceOf StartTag ) {
StartTag st = (StartTag) parser.getEvent ();
// access tag via st
}
else ...
</pre>
-<p>While the overhead does not seem very large at the first sight,
-please keep in mind that in many cases there is not much done
-with the event, often access is as simple as a name check or
-similar.</p>
-
-<p>Alternatively to the previous approach, we could also use different
-access methods depending on the event type, avoiding the type
-cast. This would look like the next example:</p>
+ <p>While the overhead does not seem very large at the first sight, please keep in mind that in many cases there is
+ not much done with the event, often access is as simple as a name check or similar.</p>
-<pre>if ( parser.getEventType() == parser.START_TAG ) {
+ <p>Alternatively to the previous approach, we could also use different access methods depending on the event type,
+ avoiding the type cast. This would look like the next example:</p>
+ <pre>
+if ( parser.getEventType() == parser.START_TAG ) {
StartTag st = parser.getStartTag ();
// access tag via st
}
else ...
</pre>
-<p>Obviously, while in this case neither an instanceof check nor
-a type cast is required, this approach would add a lot of methods
-to the parser, and it would be no longer significantly smaller
-than the integrated interface that is now used in the XMLPULL API.</p>
-
-<p>Another option may be to add the access methods of
-all event types to the event base class. However, in that case
-the event object would be nearly as huge as the integrated
-interface of the XMLPULL API, and the API
-readability advantage would be lost.</p>
-
-<p>Finally, the event objects are not for free. Creating lots of
-objects that are used just for extracting some information to build an
-application dependent structure may create significant overhead. While
-this overhead may be reduced by reusing event objects, reusing event
-objects is extremely dangerous since an object given to the user will
-change in the background without further notice. In contrast, in the
-XMLPULL API it is obvious that the return values of query methods like
-getEventType, getText() and getName() will be different after a call
-to one of the next() method that advance the parser to the next
-event. </p>
-
+ <p>Obviously, while in this case neither an instanceof check nor a type cast is required, this approach would add a
+ lot of methods to the parser, and it would be no longer significantly smaller than the integrated interface that is
+ now used in the XMLPULL API.</p>
+
+ <p>Another option may be to add the access methods of all event types to the event base class. However, in that case
+ the event object would be nearly as huge as the integrated interface of the XMLPULL API, and the API readability
+ advantage would be lost.</p>
+
+ <p>Finally, the event objects are not for free. Creating lots of objects that are used just for extracting some
+ information to build an application dependent structure may create significant overhead. While this overhead may be
+ reduced by reusing event objects, reusing event objects is extremely dangerous since an object given to the user will
+ change in the background without further notice. In contrast, in the XMLPULL API it is obvious that the return values
+ of query methods like getEventType, getText() and getName() will be different after a call to one of the next()
+ method that advance the parser to the next event.</p>
-<h2><a name="3NEXT"></a>What is the difference between
-<tt>nextToken()</tt>, <tt>next()</tt>, <tt>nextTag()</tt>, and <tt>nextText()</tt>?</h2>
+ <h2><a name="3NEXT"></a>What is the difference between <tt>nextToken()</tt>, <tt>next()</tt>, <tt>nextTag()</tt>, and
+ <tt>nextText()</tt>?</h2>
-<p>All those methods have in common that they advance the parser to
-a next event. </p>
+ <p>All those methods have in common that they advance the parser to a next event.</p>
<ul>
+ <li><tt>nextToken()</tt> provides fine grained access to all XML events, including "low level" events like comments
+ and processing instructions.</li>
-<li><tt>nextToken()</tt> provides fine grained access to all XML events,
-including "low level" events like comments and processing instructions. </li>
-
-<li><tt>next()</tt> works similar to <tt>nextToken()</tt>, but it skips low
-level events like comments and processing instructions. Text events that are
-interrupted by comments or processing instructions are aggregated to a single
-text event.
-
-<li><tt>nextTag()</tt> works like <tt>next()</tt>, but also skips
-text fragments that contain only whitespace. If the next
-event observed is not a start tag or end tag, an exception
-is thrown.
-
-<li><tt>nextText()</tt> has the precondition that the current event is a start
-tag. It reads text until the corresponding end tag is reached and stops on the
-end tag. The return value of <tt>nextText()</tt> is the text that was read. If
-<tT>nextText()</tT> observes an additional start tag while parsing text, an
-exception is thrown. The motivation behind this method is to provide an unified
-handling for the cases "<tag></tag>", "<tag/>", and
-</tag>some text</tag>". </li>
-
+ <li><tt>next()</tt> works similar to <tt>nextToken()</tt>, but it skips low level events like comments and
+ processing instructions. Text events that are interrupted by comments or processing instructions are aggregated to
+ a single text event.</li>
+
+ <li><tt>nextTag()</tt> works like <tt>next()</tt>, but also skips text fragments that contain only whitespace. If
+ the next event observed is not a start tag or end tag, an exception is thrown.</li>
+
+ <li><tt>nextText()</tt> has the precondition that the current event is a start tag. It reads text until the
+ corresponding end tag is reached and stops on the end tag. The return value of <tt>nextText()</tt> is the text that
+ was read. If <tt>nextText()</tt> observes an additional start tag while parsing text, an exception is thrown. The
+ motivation behind this method is to provide an unified handling for the cases "<tag></tag>",
+ "<tag/>", and </tag>some text</tag>".</li>
</ul>
+ <h2><a name="NEXT_MOTIV" id="NEXT_MOTIV"></a>Why are there different <tt>next()</tt> methods, wouldn't it be cleaner
+ to have a set method, allowing me to specify the type of events I am interested in in general?</h2>
-<h2><a name="NEXT_MOTIV"></a>Why are there different <tt>next()</tt> methods, wouldn't it be cleaner to
-have a set method, allowing me to specify the type of events I am interested in
-in general?</h2>
-
-<p>A significant advantage of pull parsers over push parsers
-is that they can easily be handed over to different methods as
-a parameter. Those methods can then handle their subtree.
-However, when the parser would have a lot of state options, at
-each of those hand over points it would be necessary to
-make sure that the state matches the requirements of the
-subroutine. The same checks would be necessary when the
-subroutine returns and the original processor regains
-control.</p>
-
-
-<h2><a name="ROUNDTRIP"></a>Is it possible to perform an
-exact 1:1 XML roundtrip using the XMLPULL API? For instance,
-is it possible to build an XML editor on
-top of the XMLPULL API that does not change anything that
+ <p>A significant advantage of pull parsers over push parsers is that they can easily be handed over to different
+ methods as a parameter. Those methods can then handle their subtree. However, when the parser would have a lot of
+ state options, at each of those hand over points it would be necessary to make sure that the state matches the
+ requirements of the subroutine. The same checks would be necessary when the subroutine returns and the original
+ processor regains control.</p>
+
+ <h2><a name="ROUNDTRIP" id="ROUNDTRIP"></a>Is it possible to perform an exact 1:1 XML roundtrip using the XMLPULL
+ API? For instance, is it possible to build an XML editor on top of the XMLPULL API that does not change anything that
is not "touched"?</h2>
-<p>If the feature <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">
-XML ROUNDTRIP</a> is enabled, an exact XML 1.0 round-tripping is possible. The
-parser will make the exact content of XML start tags and end tags
-including white spaces and attribute formatting available to applications.
-However, this may not be possible for other than standard XML 1.0
-representations of the XML infoset such as WBXML. But even when
-<a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP</a>
-feature is not enabled, round-tripping at XML-Infoset level can be accomplished
-by using the
-<a href="http://www.xmlpull.org/v1/doc/api/org/xmlpull/v1/XmlPullParser.html#nextToken()">
-nextToken()</a> method instead of next().
-
-
-<h2><a name="SERIALIZE"></a>How to write XML output with XMLPULL API?</h2>
-
-<p>This is currently not supported though one can always write custom method for
-this purpose. For instance, one of internal JUnit tests shows an example how
-to round-trip XML - this is used to test XMLPULL API. Also, a prototype of an
-XmlSerializer interface can already be obtained from the CVS repository.
-For details, please refer to the ongoing discussion on
-the xmlpull-dev mailing list.<h2>
-
-
-<a name="FACTORY_ABSTRACT"></a>Why is the XmlPullParserFactory class not abstract?</h2>
-
-<p>The XmlPullParserFactory is not abstract to allow to use it "directly".
-Typical XMLPULL V1 API implementation should provide its own factory that
-extends XmlPullParserFactory. However if implementation factory class is
-not created, the default XmlPullParserFactory can be used to create
-parser instances. For that purpose, a comma separated list of parser class
-names, implementing the XmlPullParser interface,
-must be specified in the resource file
-<code>/META-INF/services/org.xmlpull.v1.XmlPullParserFactory</code>.
-This mechanism can also be used to specify factories extending the
-XmlPullParserFactory class. Making XmlPullParserFactory not abstract
-and allowing it to create parser instances directly allows to
-minimize size of XMLPULL implementations in J2ME environments - there
-is no need to write a factory class since the default XmlPullParserFactory
-can be used. Of course, for really tight memory environments, it may
-be more appropriate to use the constructor of a
-parser implementation directly, trading of the need of a
-factory class for some flexibility.</p>
+ <p>If the feature <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP</a> is enabled, an
+ exact XML 1.0 round-tripping is possible. The parser will make the exact content of XML start tags and end tags
+ including white spaces and attribute formatting available to applications. However, this may not be possible for
+ other than standard XML 1.0 representations of the XML infoset such as WBXML. But even when <a href=
+ "http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP</a> feature is not enabled, round-tripping at
+ XML-Infoset level can be accomplished by using the <a href=
+ "http://www.xmlpull.org/v1/doc/api/org/xmlpull/v1/XmlPullParser.html#nextToken()">nextToken()</a> method instead of
+ next().</p>
+
+ <h2><a name="SERIALIZE" id="SERIALIZE"></a>How to write XML output with XMLPULL API?</h2>
+
+ <p>This is currently not supported though one can always write custom method for this purpose. For instance, one of
+ internal JUnit tests shows an example how to round-trip XML - this is used to test XMLPULL API. Also, a prototype of
+ an XmlSerializer interface can already be obtained from the CVS repository. For details, please refer to the ongoing
+ discussion on the xmlpull-dev mailing list.</p>
+
+ <h2><a name="FACTORY_ABSTRACT" id="FACTORY_ABSTRACT"></a>Why is the XmlPullParserFactory class not abstract?</h2>
+
+ <p>The XmlPullParserFactory is not abstract to allow to use it "directly". Typical XMLPULL V1 API implementation
+ should provide its own factory that extends XmlPullParserFactory. However if implementation factory class is not
+ created, the default XmlPullParserFactory can be used to create parser instances. For that purpose, a comma separated
+ list of parser class names, implementing the XmlPullParser interface, must be specified in the resource file
+ <code>/META-INF/services/org.xmlpull.v1.XmlPullParserFactory</code>. This mechanism can also be used to specify
+ factories extending the XmlPullParserFactory class. Making XmlPullParserFactory not abstract and allowing it to
+ create parser instances directly allows to minimize size of XMLPULL implementations in J2ME environments - there is
+ no need to write a factory class since the default XmlPullParserFactory can be used. Of course, for really tight
+ memory environments, it may be more appropriate to use the constructor of a parser implementation directly, trading
+ of the need of a factory class for some flexibility.</p>
<p>To summarize, the XmlPullParserFactory has two distinct roles:</p>
+
<ul>
- <li>it is a base class that can be used to create factory classes
- for an API implementations (similarly to JAXP)</li>
- <li>it can be used in memory restricted environments to create parser
- instances directly</li>
+ <li>it is a base class that can be used to create factory classes for an API implementations (similarly to
+ JAXP)</li>
+
+ <li>it can be used in memory restricted environments to create parser instances directly</li>
</ul>
-<p>Please note that though XmlPullParserFactory is not abstract,
-it still can be used exactly the
-same way as if it were abstract. And in this respect it works exactly like
-factories in JAXP. Moreover, XMLPULL implementations should override
-XmlPullParserFactory to provide more customized and faster factories - the default
-factory uses Class.forName() and therefore may have a negative impact on
-performance.</p>
-
-<h2><a name="TYPES"></a>Why not use final method instead of TYPES array?</h2>
-
-<p>The problem with modifiable entries in array is that user may by mistake modify
-entries (there is no way in java to declare a read-only array). However, this array
-is provided only to make conversion of parser event types to diagnostic text
-description easier; it has no influence on the parsing process itself. In the worst
-case, parser error messages using the TYPES array may be affected.</p>
-
-<p>It looks like a method would have been nicer - and would provide
-read-only conversion. But in that case it would not have been possible
-to put this functionality in the XmlPullParser interface without needing
-additional implementation effort in the parser.
-
-
-<h2><a name="CVS"></a>How to access the latest source code?</h2>
-
-<p>The latest packaged releases are available
-at <a href="http://www.xmlpull.org/">http://www.xmlpull.org/</a>,
-and the latest source (if you want to be on the cutting edge) can
-be obtained from anonymous CVS at:</p>
-<pre>cvs -d :pserver:[email protected]:/l/extreme/cvspub login
+ <p>Please note that though XmlPullParserFactory is not abstract, it still can be used exactly the same way as if it
+ were abstract. And in this respect it works exactly like factories in JAXP. Moreover, XMLPULL implementations should
+ override XmlPullParserFactory to provide more customized and faster factories - the default factory uses
+ Class.forName() and therefore may have a negative impact on performance.</p>
+
+ <h2><a name="TYPES" id="TYPES"></a>Why not use final method instead of TYPES array?</h2>
+
+ <p>The problem with modifiable entries in array is that user may by mistake modify entries (there is no way in java
+ to declare a read-only array). However, this array is provided only to make conversion of parser event types to
+ diagnostic text description easier; it has no influence on the parsing process itself. In the worst case, parser
+ error messages using the TYPES array may be affected.</p>
+
+ <p>It looks like a method would have been nicer - and would provide read-only conversion. But in that case it would
+ not have been possible to put this functionality in the XmlPullParser interface without needing additional
+ implementation effort in the parser.</p>
+
+ <h2><a name="CVS" id="CVS"></a>How to access the latest source code?</h2>
+
+ <p>The latest packaged releases are available at <a href="http://www.xmlpull.org/">http://www.xmlpull.org/</a>, and
+ the latest source (if you want to be on the cutting edge) can be obtained from anonymous CVS at:</p>
+ <pre>
+cvs -d :pserver:[email protected]:/l/extreme/cvspub login
CVS password: cvsanon
cvs -d :pserver:[email protected]:/l/extreme/cvspub co xmlpull-api-v1
</pre>
-
<h2>More questions?</h2>
-<p>Please send additional questions and/or comments to the
-<a href="http://www.xmlpull.org/discussion.shtml">XMLPULL mailing list</a>.
-
+ <p>Please send additional questions and/or comments to the <a href="http://www.xmlpull.org/discussion.shtml">XMLPULL
+ mailing list</a>.</p>
<hr />
-<address><a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a>
- and <a href="http://www.trantor.de/stefan.haustein/">Stefan Haustein</a>
+
+ <address>
+ <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a> and <a href=
+ "http://www.trantor.de/stefan.haustein/">Stefan Haustein</a>
</address>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
</body>
</html>
1.22 +322 -319 xmlpull-api-v1/doc/features.html
Index: features.html
===================================================================
RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/features.html,v
retrieving revision 1.21
retrieving revision 1.22
diff -u -b -t -w -r1.21 -r1.22
--- features.html 28 Aug 2004 20:38:42 -0000 1.21
+++ features.html 29 Aug 2005 17:30:49 -0000 1.22
@@ -1,319 +1,322 @@
-<HTML>
-<HEAD>
-<TITLE>XmlPull v1 API Features
-</TITLE>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="Author" content="Aleksander Slominski">
-</HEAD>
-<BODY BGCOLOR="white">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta name="generator" content="HTML Tidy for Windows (vers 12 April 2005), see www.w3.org" />
+
+ <title>XmlPull v1 API Features</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta name="Author" content="Aleksander Slominski" />
+</head>
+
+<body bgcolor="white">
<h1>XmlPull v1 API Features</h1>
-<P>
+ <p>The feature defines a discoverable and possibly changeable characteristic of XmlPull parser.</p>
-The feature defines a discoverable and possibly changeable characteristic of
-XmlPull parser.<p>Please note: the key words "<b>MUST</b>", "<b>MUST NOT</b>", "<b>REQUIRED</b>",
-"<b>SHALL</b>", "<b>SHALL NOT</b>", "<b>SHOULD</b>", "<b>SHOULD NOT</b>", "<b>RECOMMENDED</b>",
-"<b>MAY</b>", and "<b>OPTIONAL</b>" in this document are to be interpreted as
-described in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.</p><h2>
-
-Standard features</h2>
-<P>
-
-The semantics of of all standard features <b>MUST</b> be followed by every
-XmlPull v1 API
-implementation.<P>
-
-All standard feature values <b>MUST NOT</b> change unless setFeature() is called
-(even when setInput() is called!)<P>
-
- <h3>
-
-<a name="process-namespaces"></a>Standard feature: PROCESS NAMESPACES</h3>
-
-<p>
-The feature is identified by
-<a href="http://xmlpull.org/v1/doc/features.html#process-namespaces">
-http://xmlpull.org/v1/doc/features.html#process-namespaces</a> <p>
-Processing of namespaces in XMLPULL V1 parser <b>MUST</b> be by default set to false.<p>
-This feature <b>MUST</b> be recognized and allowed to be set both to true and
-false by every XMLPULL V1 API compliant parser implementation.<p>
-If set to false XML namespaces <b>MUST</b> not be processed and instead
-namespace attributes (starting with xmlns) will be treated as normal
-attributes. <p>
-If set to true than XML namespaces <b>MUST</b> be processed
-according to <a href="http://www.w3.org/TR/1998/PR-xml-names-19981117">
-Namespaces in XML specification</a>.<p>
-The feature <b>MUST</b> be allowed to be changed only when parser is in
-START_DOCUMENT state i.e. this feature can not be changed during parsing.
-
-<p>
- <h3>
-<a name="process-docdecl"></a>Standard feature: PROCESS DOCDECL</h3>
-<p>
-Identified by <a href="http://xmlpull.org/v1/doc/features.html#process-docdecl">
-http://xmlpull.org/v1/doc/features.html#process-docdecl</a> <p>
-The default value of the feature is undefined.<p>
-If the VALIDATION feature is true then this feature <b>MUST</b> not be modified
-and <b>MUST</b> be reported as true<p>
-If the feature is set to false and if
-<a href="http://www.w3.org/TR/2000/REC-xml-20001006#NT-doctypedecl">XML document
-type declaration</a> (in short DOCDECL) is encountered it <b>MUST</b> be reported by nextToken() and
-<b>MUST</b> be ignored by next().
-<p>
-As the DOCDECL was ignored, references to entities cannot be expanded (they will
-produce a fatal error if you call next(), but will be reported as ENTITY_REF if
-you call nextToken() instead).<p>
-If the feature is true and VALIDATION feature is false then parser <b>MUST</b> be non validating as defined
-in <a href="http://www.w3.org/TR/2000/REC-xml-20001006">XML 1.0 specification</a>
-(DOCDECL <b>MUST</b> be parsed and processed by parser). <p>
-If the feature is true and VALIDATION feature is true then parser <b>MUST</b> be validating
-as defined in <a href="http://www.w3.org/TR/2000/REC-xml-20001006">XML 1.0
-specification</a>.<p>
-The feature <b>MUST</b> be allowed to be changed only when parser is in
-START_DOCUMENT state i.e. this feature can not be changed during parsing. <p>
- <h3>
-<a name="validation"></a>Standard feature: VALIDATION</h3>
-<p>
-Identified by <a href="http://xmlpull.org/v1/doc/features.html#validation">
-http://xmlpull.org/v1/doc/features.html#validation</a> <p>
-The feature <b>MUST</b> be false by default.<p>
-See description of <a href="#process-docdecl">PROCESS DOCDECL</a> feature for
-required behavior.<p>
-If the feature is set to true then PROCESS DOCDECL <b>MUST</b> be automatically
-set to true as well.<p>
-The feature <b>MUST</b> be allowed to be changed only when parser is in
-START_DOCUMENT state i.e. this feature can not be changed during parsing.
-<p> </p>
-<hr>
-<h2>
-Optional features</h2>
-<p>
-They <b>MAY</b> be supported but are not part of XmlPull API<p>
-
-
-
-<p>
-
-<h3>
-<a name="report-namespace-prefixes"></a>Optional feature: REPORT NAMESPACE ATTRIBUTES</h3>
-<p>
-The feature is identified by
-<a href="http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes">
-http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes</a> <p>
-The feature <b>MUST</b> be false by default and only meaningful when PROCESS NAMESPACES feature
-is on.<p>
-This feature <b>MAY</b> be recognized and allowed to be set to true (by default as other optional features it is false)
-
-<p>
-When set to true then XMLPULL parser <b>MUST</b> report namespace attributes
-also - they can be distinguished looking for prefix == "xmlns" or prefix == ""
-and name == "xmlns<p>
-The feature <b>MUST</b> be allowed to be changed only when parser is in
-START_DOCUMENT state i.e. this feature can not be changed during parsing.
+ <p>Please note: the key words "<b>MUST</b>", "<b>MUST NOT</b>", "<b>REQUIRED</b>", "<b>SHALL</b>", "<b>SHALL
+ NOT</b>", "<b>SHOULD</b>", "<b>SHOULD NOT</b>", "<b>RECOMMENDED</b>", "<b>MAY</b>", and "<b>OPTIONAL</b>" in this
+ document are to be interpreted as described in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.</p>
-<p>
-
+ <h2>Standard features</h2>
-<h3>
-<a name="names-interned"></a>Optional feature: NAMES INTERNED<br>
- </h3>
-<p>This feature is identified by
-<a href="http://xmlpull.org/v1/doc/features.html#names-interned">
-http://xmlpull.org/v1/doc/features.html#names-interned</a> </p>
-<p>If set to true then XMLPULL parser <b>MUST</b> intern all returned names
-using java.lang.String.intern that includes following functions: getName(),
-getPrefix(), getNamespace(), getNamespace(prefix), getNamespacePrefix(int),
-getNamespaceUri(int pos) , getAttributeName(), getAttributeNamespace(),
-getAttributePrefix(), getAttributeType(). However this feature provides no
-assurance about String values (like getText()) or attribute values
-(getAttributeValue()). </p>
+ <p>The semantics of of all standard features <b>MUST</b> be followed by every XmlPull v1 API implementation.</p>
+
+ <p>All standard feature values <b>MUST NOT</b> change unless setFeature() is called (even when setInput() is
+ called!)</p>
+
+ <p> </p>
+
+ <h3><a name="process-namespaces" id="process-namespaces"></a>Standard feature: PROCESS NAMESPACES</h3>
+
+ <p>The feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#process-namespaces">http://xmlpull.org/v1/doc/features.html#process-namespaces</a></p>
+
+ <p>Processing of namespaces in XMLPULL V1 parser <b>MUST</b> be by default set to false.</p>
+
+ <p>This feature <b>MUST</b> be recognized and allowed to be set both to true and false by every XMLPULL V1 API
+ compliant parser implementation.</p>
+
+ <p>If set to false XML namespaces <b>MUST</b> not be processed and instead namespace attributes (starting with xmlns)
+ will be treated as normal attributes.</p>
+
+ <p>If set to true than XML namespaces <b>MUST</b> be processed according to <a href=
+ "http://www.w3.org/TR/1998/PR-xml-names-19981117">Namespaces in XML specification</a>.</p>
+
+ <p>The feature <b>MUST</b> be allowed to be changed only when parser is in START_DOCUMENT state i.e. this feature can
+ not be changed during parsing.</p>
+
+ <p> </p>
+
+ <h3><a name="process-docdecl" id="process-docdecl"></a>Standard feature: PROCESS DOCDECL</h3>
+
+ <p>Identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#process-docdecl">http://xmlpull.org/v1/doc/features.html#process-docdecl</a></p>
+
+ <p>The default value of the feature is undefined.</p>
+
+ <p>If the VALIDATION feature is true then this feature <b>MUST</b> not be modified and <b>MUST</b> be reported as
+ true</p>
+
+ <p>If the feature is set to false and if <a href="http://www.w3.org/TR/2000/REC-xml-20001006#NT-doctypedecl">XML
+ document type declaration</a> (in short DOCDECL) is encountered it <b>MUST</b> be reported by nextToken() and
+ <b>MUST</b> be ignored by next().</p>
+
+ <p>As the DOCDECL was ignored, references to entities cannot be expanded (they will produce a fatal error if you call
+ next(), but will be reported as ENTITY_REF if you call nextToken() instead).</p>
+
+ <p>If the feature is true and VALIDATION feature is false then parser <b>MUST</b> be non validating as defined in
+ <a href="http://www.w3.org/TR/2000/REC-xml-20001006">XML 1.0 specification</a> (DOCDECL <b>MUST</b> be parsed and
+ processed by parser).</p>
+
+ <p>If the feature is true and VALIDATION feature is true then parser <b>MUST</b> be validating as defined in <a href=
+ "http://www.w3.org/TR/2000/REC-xml-20001006">XML 1.0 specification</a>.</p>
+
+ <p>The feature <b>MUST</b> be allowed to be changed only when parser is in START_DOCUMENT state i.e. this feature can
+ not be changed during parsing.</p>
+
+ <p> </p>
-<p>NOTE: when enabled this feature allows for fast testing of equality against
-string constants (no need to use String.equals()). </p>
+ <h3><a name="validation" id="validation"></a>Standard feature: VALIDATION</h3>
-<h3>
+ <p>Identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#validation">http://xmlpull.org/v1/doc/features.html#validation</a></p>
+
+ <p>The feature <b>MUST</b> be false by default.</p>
+
+ <p>See description of <a href="#process-docdecl">PROCESS DOCDECL</a> feature for required behavior.</p>
+
+ <p>If the feature is set to true then PROCESS DOCDECL <b>MUST</b> be automatically set to true as well.</p>
+
+ <p>The feature <b>MUST</b> be allowed to be changed only when parser is in START_DOCUMENT state i.e. this feature can
+ not be changed during parsing.</p>
+
+ <p> </p>
+ <hr />
+
+ <h2>Optional features</h2>
+
+ <p>They <b>MAY</b> be supported but are not part of XmlPull API</p>
+
+ <p> </p>
+
+ <p> </p>
+
+ <h3><a name="report-namespace-prefixes" id="report-namespace-prefixes"></a>Optional feature: REPORT NAMESPACE
+ ATTRIBUTES</h3>
+
+ <p>The feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes">http://xmlpull.org/v1/doc/features.html#report-namespace-prefixes</a></p>
+
+ <p>The feature <b>MUST</b> be false by default and only meaningful when PROCESS NAMESPACES feature is on.</p>
+
+ <p>This feature <b>MAY</b> be recognized and allowed to be set to true (by default as other optional features it is
+ false)</p>
+
+ <p>When set to true then XMLPULL parser <b>MUST</b> report namespace attributes also - they can be distinguished
+ looking for prefix == "xmlns" or prefix == "" and name == "xmlns</p>
+
+ <p>The feature <b>MUST</b> be allowed to be changed only when parser is in START_DOCUMENT state i.e. this feature can
+ not be changed during parsing.</p>
+
+ <p> </p>
+
+ <h3><a name="names-interned" id="names-interned"></a>Optional feature: NAMES INTERNED<br />
</h3>
-<h3>
-<a name="expand-entity-ref"></a>Optional feature: EXPAND ENTITY REF</h3>
-<p>This feature is identified by
-<a href="http://xmlpull.org/v1/doc/features.html#expand-entity-ref">
-http://xmlpull.org/v1/doc/features.html#expand-entity-ref</a> </p>
-
-<p>
-This optional feature changes behavior of nextToken() and when enabled parser <b>
-MUST</b> report expanded entity reference content as tokens and <b>MUST</b>
-report end of expanded entity ref as ENTITY_REF with name that is null
+
+ <p>This feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#names-interned">http://xmlpull.org/v1/doc/features.html#names-interned</a></p>
+
+ <p>If set to true then XMLPULL parser <b>MUST</b> intern all returned names using java.lang.String.intern that
+ includes following functions: getName(), getPrefix(), getNamespace(), getNamespace(prefix),
+ getNamespacePrefix(int), getNamespaceUri(int pos) , getAttributeName(), getAttributeNamespace(),
+ getAttributePrefix(), getAttributeType(). However this feature provides no assurance about String values (like
+ getText()) or attribute values (getAttributeValue()). </p>
+
+ <p>NOTE: when enabled this feature allows for fast testing of equality against string constants (no need to use
+ String.equals()).</p>
+
+ <h3> </h3>
+
+ <h3><a name="expand-entity-ref" id="expand-entity-ref"></a>Optional feature: EXPAND ENTITY REF</h3>
+
+ <p>This feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#expand-entity-ref">http://xmlpull.org/v1/doc/features.html#expand-entity-ref</a></p>
+
+ <p>This optional feature changes behavior of nextToken() and when enabled parser <b>MUST</b> report expanded entity
+ reference content as tokens and <b>MUST</b> report end of expanded entity ref as ENTITY_REF with name that is null
(getText() returns null).</p>
-<p>
-For example if entity foo was defined to have replacement text bar then parser
-will report following tokens: ENTITY_REF with 'foo' as entity name, TEXT with
-value 'bar' and ENTITY_REF with no name to signal end of expansion) . If
-PROCESS_DOCDECL is true then reported tokens may include START_TAG/END_TAG if
-entity has embedded markup and ENTITY_REF for recursively expanded entity
-references (following calls to nextToken() will report entity content as
-possibly multiple TEXT, START_TAG, END_TAG, ENTITY_REF etc.). </p>
-
-<p>
-NOTE: it can only be supported when PROCESS_DOCDECL is true as
-defineEntityReplacementText() will always escape markup or entity references.</p>
-
-<p>
-NOTE: next() will always expand entity ref and report combined TEXT event and
-this feature does not affect next() behavior.<br>
+ <p>For example if entity foo was defined to have replacement text bar then parser will report following tokens:
+ ENTITY_REF with 'foo' as entity name, TEXT with value 'bar' and ENTITY_REF with no name to signal end of expansion) .
+ If PROCESS_DOCDECL is true then reported tokens may include START_TAG/END_TAG if entity has embedded markup and
+ ENTITY_REF for recursively expanded entity references (following calls to nextToken() will report entity
+ content as possibly multiple TEXT, START_TAG, END_TAG, ENTITY_REF etc.).</p>
+
+ <p>NOTE: it can only be supported when PROCESS_DOCDECL is true as defineEntityReplacementText() will always escape
+ markup or entity references.</p>
+
+ <p>NOTE: next() will always expand entity ref and report combined TEXT event and this feature does not affect next()
+ behavior.<br />
</p>
-<h3>
-<a name="xml-roundtrip"></a>Optional feature: XML ROUNDTRIP</h3>
-<p>This feature is identified by
-<a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">
-http://xmlpull.org/v1/doc/features.html#xml-roundtrip</a> </p>
-<p>If ROUNDTRIP is on it is affecting getText/getTextCharacters() when
-nextToken() is used to make possible an exact roundtrip of XML 1.0 input -
-here are constraints on values returned by getText()/getTextCharacters:</p>
+
+ <h3><a name="xml-roundtrip" id="xml-roundtrip"></a>Optional feature: XML ROUNDTRIP</h3>
+
+ <p>This feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#xml-roundtrip">http://xmlpull.org/v1/doc/features.html#xml-roundtrip</a></p>
+
+ <p>If ROUNDTRIP is on it is affecting getText/getTextCharacters() when nextToken() is used to make possible an
+ exact roundtrip of XML 1.0 input - here are constraints on values returned by getText()/getTextCharacters:</p>
<ul>
- <li>for all tokens exactly what was in input<b> MUST</b> be returned -
- in particular returned content <b>MUST NOT</b> be end-of-line normalized (the
- algorithm described in
-<a href="http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line
-Handling</a> is not applied)</li>
- <li>for START_TAG and END_TAG event original XML value <b>MUST</b> be returned
- for events for start/end tag (for example "tag" for <tag>)</li>
- <li>for PROCESSING INSTRUCTION event exact content of PI <b>MUST</b> be
- returned: in <?target data?> white spaces between target and
- data must be preserved</li>
- <li>content of XMLDecl must be reported as not null by
- <a href="http://xmlpull.org/v1/doc/features.html#xmldecl-content">XMLDECL
- CONTENT</a> property</li>
+ <li>for all tokens exactly what was in input <b>MUST</b> be returned - in particular returned content <b>MUST
+ NOT</b> be end-of-line normalized (the algorithm described in <a href=
+ "http://www.w3.org/TR/REC-xml#sec-line-ends">XML 1.0 End-of-Line Handling</a> is not applied)</li>
+
+ <li>for START_TAG and END_TAG event original XML value <b>MUST</b> be returned for events for start/end tag (for
+ example "tag" for <tag>)</li>
+
+ <li>for PROCESSING INSTRUCTION event exact content of PI <b>MUST</b> be returned: in <?target
+ data?> white spaces between target and data must be preserved</li>
+
+ <li>content of XMLDecl must be reported as not null by <a href=
+ "http://xmlpull.org/v1/doc/features.html#xmldecl-content">XMLDECL CONTENT</a> property</li>
+
<li>DOCDECL <b>MUST</b> be reported exactly as in input</li>
</ul>
+
<ul>
- <li>additionally for nextToken(): ignorable whites spaces outside root element
- <b>MUST</b> be reported as IGNORABLE_WHITESPACE </li>
+ <li>additionally for nextToken(): ignorable whites spaces outside root element <b>MUST</b> be reported as
+ IGNORABLE_WHITESPACE</li>
</ul>
-<p>By default this feature is off and it implies unchanged behavior of
-XmlPullParser:</p>
+
+ <p>By default this feature is off and it implies unchanged behavior of XmlPullParser:</p>
<ul>
- <li>for all tokens call to getText()/getTextCharacters returns end-of-line
- normalized content<br>
- (that includes beside TEXT, IGNORABLE_WHITESPACE also COMMENT,
- PROCESSING_INSTRUCTION, ENTITY_REF etc.)</li>
+ <li>for all tokens call to getText()/getTextCharacters returns end-of-line normalized content<br />
+ (that includes beside TEXT, IGNORABLE_WHITESPACE also COMMENT, PROCESSING_INSTRUCTION, ENTITY_REF etc.)</li>
+
<li>getText() for START_TAG and END_TAG event MUST return null</li>
- <li>PROCESSING_INSTRUCTION MUST be reported as target + ' ' + data or exactly
- as it was in input</li>
- <li>DOCDECL MUST be reported exactly if PROCESS DOCDECL is true otherwise MAY
- be reported (but does not have to and may be even null)</li>
- <li>ignorable whites spaces (event IGNORABLE_WHITESPACE) outside root element<b>
- </b>MAY<b> </b>be reported by nextToken()</li>
+
+ <li>PROCESSING_INSTRUCTION MUST be reported as target + ' ' + data or exactly as it was in input</li>
+
+ <li>DOCDECL MUST be reported exactly if PROCESS DOCDECL is true otherwise MAY be reported (but does not have to and
+ may be even null)</li>
+
+ <li>ignorable whites spaces (event IGNORABLE_WHITESPACE) outside root element MAY be reported by nextToken()</li>
</ul>
-<p>Note that content outside of root element is typically not reported by
-parsers to make it
-consistent with XML infoset
-<a href="http://www.w3.org/TR/xml-infoset/#infoitem.document">Document
-Information Item properties</a> in which white spaces in prolog and part root
-element are ignored. If reported IGNORABLE_WHITESPACE event may be used to
+
+ <p>Note that content outside of root element is typically not reported by parsers to make it consistent with XML
+ infoset <a href="http://www.w3.org/TR/xml-infoset/#infoitem.document">Document Information Item properties</a> in
+ which white spaces in prolog and part root element are ignored. If reported IGNORABLE_WHITESPACE event may be used to
preserved formatting of XML input when serializing it.</p>
-<p>However as IGNORABLE_WHITESPACE event MAY be reported make sure that
-application will be prepared to ignore IGNORABLE_WHITESPACE evens from
-nextToken() when processing content outside of root element (getDepth() == 0).</p>
+ <p>However as IGNORABLE_WHITESPACE event MAY be reported make sure that application will be prepared to ignore
+ IGNORABLE_WHITESPACE evens from nextToken() when processing content outside of root element (getDepth() == 0).</p>
<p> </p>
-<h3>
-<a name="detect-encoding"></a>Optional feature: DETECT ENCODING<br>
+ <h3><a name="detect-encoding" id="detect-encoding"></a>Optional feature: DETECT ENCODING<br />
</h3>
-<p>This feature is identified by
-<a href="http://xmlpull.org/v1/doc/features.html#detect-encoding">
-http://xmlpull.org/v1/doc/features.html#detect-encoding</a> </p>
-<p>If this feature is true it means that XmlPull parser <b>MUST</b> detect
-encoding from input stream when inputEncoding is null
-in call setInput(InputStream inputStream, String inputEncoding).</p>
-
-<p>Parameter
-inputStream from setInput(InputStream inputStream, String inputEncoding)
-contains raw byte input stream of possibly
-unknown encoding (when inputEncoding is null) and in such case the parser
-must derive encoding from <?xml declaration or assume UTF8 or UTF16 as
-described in <a href="http://www.w3.org/TR/REC-xml#sec-guessing-no-ext-info">XML 1.0
-Appendix F.1 Detection Without External Encoding Information</a>
-otherwise if inputEncoding is present then it must be used
-(this is consistent with
-<a href="http://www.w3.org/TR/REC-xml#sec-guessing-with-ext-info">XML 1.0
-Appendix F.2 Priorities in the Presence of External Encoding Information</a>
-that allows for exception only for files and in such cases inputEncoding should
-be null to trigger auto detecting.
-
-</p>
+
+ <p>This feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#detect-encoding">http://xmlpull.org/v1/doc/features.html#detect-encoding</a></p>
+
+ <p>If this feature is true it means that XmlPull parser <b>MUST</b> detect encoding from input stream when
+ inputEncoding is null in call setInput(InputStream inputStream, String inputEncoding).</p>
+
+ <p>Parameter inputStream from setInput(InputStream inputStream, String inputEncoding) contains raw byte input stream
+ of possibly unknown encoding (when inputEncoding is null) and in such case the parser must derive encoding from
+ <?xml declaration or assume UTF8 or UTF16 as described in <a href=
+ "http://www.w3.org/TR/REC-xml#sec-guessing-no-ext-info">XML 1.0 Appendix F.1 Detection Without External Encoding
+ Information</a> otherwise if inputEncoding is present then it must be used (this is consistent with <a href=
+ "http://www.w3.org/TR/REC-xml#sec-guessing-with-ext-info">XML 1.0 Appendix F.2 Priorities in the Presence of External
+ Encoding Information</a> that allows for exception only for files and in such cases inputEncoding should be null to
+ trigger auto detecting.</p>
<p> </p>
-<h3>
-<a name="serializer-attvalue-use-apostrophe"></a>Optional feature: SERIALIZER
-ATTVALUE USE APOSTROPHE<br>
+ <h3><a name="serializer-attvalue-use-apostrophe" id="serializer-attvalue-use-apostrophe"></a>Optional feature:
+ SERIALIZER ATTVALUE USE APOSTROPHE<br />
</h3>
-<p>This feature is identified by
-<a href="http://xmlpull.org/v1/doc/features.html#serializer-attvalue-use-apostrophe">
-http://xmlpull.org/v1/doc/features.html#serializer-attvalue-use-apostrophe</a> </p>
-<p>If this feature is supported that means that XmlSerializer output for
-attribute value quotation can be controlled (when serializing XML 1.0 it allows
-to chose one of <a href="http://www.w3.org/TR/REC-xml#NT-AttValue">alternative
-representations for AttValue</a>).</p>
-<p>If the feature is set to true it means than XmlSerializer parser <b>MUST</b>
-use apostrophe (') to quote attribute value.</p>
+ <p>This feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#serializer-attvalue-use-apostrophe">http://xmlpull.org/v1/doc/features.html#serializer-attvalue-use-apostrophe</a></p>
-<p>If the feature is set to false it means than XmlSerializer parser <b>MUST</b>
-use quotation mark (") to quote attribute value.</p>
+ <p>If this feature is supported that means that XmlSerializer output for attribute value quotation can be controlled
+ (when serializing XML 1.0 it allows to chose one of <a href="http://www.w3.org/TR/REC-xml#NT-AttValue">alternative
+ representations for AttValue</a>).</p>
+
+ <p>If the feature is set to true it means than XmlSerializer parser <b>MUST</b> use apostrophe (') to quote attribute
+ value.</p>
+ <p>If the feature is set to false it means than XmlSerializer parser <b>MUST</b> use quotation mark (") to quote
+ attribute value.</p>
<p> </p>
-<h3>
-<a name="relaxed"></a>Optional feature: RELAXED<br>
+ <h3><a name="relaxed" id="relaxed"></a>Optional feature: RELAXED<br />
</h3>
-<p>This feature is identified by
-<a href="http://xmlpull.org/v1/doc/features.html#relaxed">
-http://xmlpull.org/v1/doc/features.html#relaxed</a> </p>
-<p>If this feature is supported that means that XmlPull parser will be lenient
-when checking XML well formedness. </p>
-<p><b>NOTE</b>: use it only if XML input is not well-formed and in general usage
-if this feature is <b>discouraged</b> </p>
+ <p>This feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/features.html#relaxed">http://xmlpull.org/v1/doc/features.html#relaxed</a></p>
+
+ <p>If this feature is supported that means that XmlPull parser will be lenient when checking XML well formedness.</p>
-<p><b>NOTE</b>: as there is no definition of what is relaxed XML parsing
-therefore what parser will do completely depends on implementation used</p>
+ <p><b>NOTE</b>: use it only if XML input is not well-formed and in general usage if this feature is
+ <b>discouraged</b></p>
+
+ <p><b>NOTE</b>: as there is no definition of what is relaxed XML parsing therefore what parser will do completely
+ depends on implementation used</p>
<p> </p>
<p> </p>
<p> </p>
+ <hr />
-<HR>
-<address><a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a><address>
-</address>
+ <address>
+ <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a>
</address>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
-</BODY>
-</HTML>
\ No newline at end of file
+</body>
+</html>
1.10 +136 -143 xmlpull-api-v1/doc/properties.html
Index: properties.html
===================================================================
RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/properties.html,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -t -w -r1.9 -r1.10
--- properties.html 23 Apr 2003 12:25:18 -0000 1.9
+++ properties.html 29 Aug 2005 17:30:49 -0000 1.10
@@ -1,192 +1,185 @@
-<HTML>
-<HEAD>
-<TITLE>XmlPull v1 API Properties</TITLE>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="Author" content="Aleksander Slominski">
-</HEAD>
-<BODY BGCOLOR="white">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<h1>XmlPull v1 API Properties</h1>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta name="generator" content="HTML Tidy for Windows (vers 12 April 2005), see www.w3.org" />
+
+ <title>XmlPull v1 API Properties</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta name="Author" content="Aleksander Slominski" />
+</head>
-<P>
+<body bgcolor="white">
+ <h1>XmlPull v1 API Properties</h1>
-The property mechanism allows to pass information to
-XmlPull parser implementation that is not part of API.<p>Please note: the key words "<b>MUST</b>", "<b>MUST NOT</b>", "<b>REQUIRED</b>",
-"<b>SHALL</b>", "<b>SHALL NOT</b>", "<b>SHOULD</b>", "<b>SHOULD NOT</b>", "<b>RECOMMENDED</b>",
-"<b>MAY</b>", and "<b>OPTIONAL</b>" in this document are to be interpreted as
-described in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.</p><h2>
+ <p>The property mechanism allows to pass information to XmlPull parser implementation that is not part of API.</p>
+ <p>Please note: the key words "<b>MUST</b>", "<b>MUST NOT</b>", "<b>REQUIRED</b>", "<b>SHALL</b>", "<b>SHALL
+ NOT</b>", "<b>SHOULD</b>", "<b>SHOULD NOT</b>", "<b>RECOMMENDED</b>", "<b>MAY</b>", and "<b>OPTIONAL</b>" in this
+ document are to be interpreted as described in <a href="http://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.</p>
+ <h2>Standard properties</h2>
+ <p>Currently there is no standard properties defined.</p>
-Standard properties</h2>
-<P>
+ <p> </p>
+ <hr />
-Currently there is no standard properties defined.<P>
+ <h2>Optional properties</h2>
- <hr>
-<h2>
-Optional properties</h2>
-<p>
-They <b>MAY</b> be supported but are not part of
-<a href="http://www.xmlpull.org/">XmlPull API</a>.<p>
-Please report suggestions for other useful properties to
-<a href="http://www.xmlpull.org/discussion.shtml">XmlPull discussion group</a> so they can be added here and
-made easier to discover.<p> </p>
+ <p>They <b>MAY</b> be supported but are not part of <a href="http://www.xmlpull.org/">XmlPull API</a>.</p>
+ <p>Please report suggestions for other useful properties to <a href="http://www.xmlpull.org/discussion.shtml">XmlPull
+ discussion group</a> so they can be added here and made easier to discover.</p>
-<p><b>NOTE:</b> to detect if optional property
-is supported try to call getProperty()
-and only if it returns non-null value
-it can be assumed that the property is supported.
-Implementations are required to return null
-for all unknown properties names as null
-is assumed to be default value for all properties. </p>
+ <p> </p>
+ <p><b>NOTE:</b> to detect if optional property is supported try to call getProperty() and only if it returns non-null
+ value it can be assumed that the property is supported. Implementations are required to return null for all unknown
+ properties names as null is assumed to be default value for all properties.</p>
<p> </p>
-<h3>
-<a name="location"></a>Optional property: LOCATION</h3>
-<p>This property is identified by
-<a href="http://xmlpull.org/v1/doc/properties.html#location">http://xmlpull.org/v1/doc/properties.html#location</a> </p>
-
-<p>This property takes String as value. If supported this property can be set after setInput() to indicate
-location of input (for parser) or output (for serializer). The value of this
-property will be then used in getPositionDescription() and in exception messages
-to provide better diagnostic messages.</pre>
+ <h3><a name="location" id="location"></a>Optional property: LOCATION</h3>
+ <p>This property is identified by <a href=
+ "http://xmlpull.org/v1/doc/properties.html#location">http://xmlpull.org/v1/doc/properties.html#location</a></p>
+ <p>This property takes String as value. If supported this property can be set after setInput() to indicate location
+ of input (for parser) or output (for serializer). The value of this property will be then used in
+ getPositionDescription() and in exception messages to provide better diagnostic messages.</p>
<p> </p>
-<h3>
-<a name="xmldecl-version"></a>Optional property: XMLDECL VERSION</h3>
-<p>This property is identified by
-<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-version">
-http://xmlpull.org/v1/doc/properties.html#xmldecl-version</a> </p>
-<p>If <a href="http://xmlpull.org/v1/doc/features.html#process-docdecl">PROCESS
-DOCDECL</a> feature is enabled it is REQUIRED property with String otherwise it
-is optional.</p>
+ <h3><a name="xmldecl-version" id="xmldecl-version"></a>Optional property: XMLDECL VERSION</h3>
-<p>If supported and there was
-<a href="http://www.w3.org/TR/REC-xml#NT-VersionInfo">VersionInfo</a> version in
-<a href="http://www.w3.org/TR/REC-xml#NT-XMLDecl">XMLDecl</a> then it returns
-its content if standalone='no' otherwise if there was no standalone declaration
-or this property is not supported it returns null.</p>
+ <p>This property is identified by <a href=
+ "http://xmlpull.org/v1/doc/properties.html#xmldecl-version">http://xmlpull.org/v1/doc/properties.html#xmldecl-version</a></p>
-<p>For example if input XML stream contained <?xml version='1.0'
-standalone='true'?> then this property will contain "1.0".</p>
+ <p>If <a href="http://xmlpull.org/v1/doc/features.html#process-docdecl">PROCESS DOCDECL</a> feature is enabled it is
+ REQUIRED property with String otherwise it is optional.</p>
+
+ <p>If supported and there was <a href="http://www.w3.org/TR/REC-xml#NT-VersionInfo">VersionInfo</a> version in
+ <a href="http://www.w3.org/TR/REC-xml#NT-XMLDecl">XMLDecl</a> then it returns its content if standalone='no'
+ otherwise if there was no standalone declaration or this property is not supported it returns null.</p>
+
+ <p>For example if input XML stream contained <?xml version='1.0' standalone='true'?> then this property
+ will contain "1.0".</p>
<p> </p>
+ <h3><a name="xmldecl-standalone" id="xmldecl-standalone"></a>Optional property: XMLDECL STANDALONE</h3>
+
+ <p>This feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone">http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone</a></p>
-<h3>
-<a name="xmldecl-standalone"></a>Optional property: XMLDECL STANDALONE</h3>
-<p>This feature is identified by
-<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone">
-http://xmlpull.org/v1/doc/properties.html#xmldecl-standalone</a> </p>
-<p>If <a href="http://xmlpull.org/v1/doc/features.html#process-docdecl">PROCESS
-DOCDECL</a> feature is enabled it is REQUIRED property with Boolean otherwise it
-is optional.</p>
+ <p>If <a href="http://xmlpull.org/v1/doc/features.html#process-docdecl">PROCESS DOCDECL</a> feature is enabled it is
+ REQUIRED property with Boolean otherwise it is optional.</p>
-<p>If supported and there was <a href="http://www.w3.org/TR/REC-xml#NT-SDDecl">
-SDDecl</a> standalone in <a href="http://www.w3.org/TR/REC-xml#NT-XMLDecl">
-XMLDecl</a> then it returns Boolean(true) if standalone='yes' or Boolean(false)
-if standalone='no' otherwise if there was no standalone declaration or this
-property is not supported it returns null.</p>
+ <p>If supported and there was <a href="http://www.w3.org/TR/REC-xml#NT-SDDecl">SDDecl</a> standalone in <a href=
+ "http://www.w3.org/TR/REC-xml#NT-XMLDecl">XMLDecl</a> then it returns Boolean(true) if standalone='yes' or
+ Boolean(false) if standalone='no' otherwise if there was no standalone declaration or this property is not supported
+ it returns null.</p>
<p> </p>
+ <h3><a name="xmldecl-standalone" id="xmldecl-standalone"></a>Optional property: XMLDECL CONTENT</h3>
-<h3>
-<a name="xmldecl-standalone"></a>Optional property: XMLDECL CONTENT</h3>
-<p>This feature is identified by
-<a href="http://xmlpull.org/v1/doc/properties.html#xmldecl-content">
-http://xmlpull.org/v1/doc/properties.html#xmldecl-content</a></p>
-<p>If <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML
-ROUNDTRIP</a> feature is enabled it is REQUIRED property with String otherwise
-it is optional.</p>
+ <p>This feature is identified by <a href=
+ "http://xmlpull.org/v1/doc/properties.html#xmldecl-content">http://xmlpull.org/v1/doc/properties.html#xmldecl-content</a></p>
-<p>If XML ROUNDTRIP feature is true then this property MUST contain everything
-after '<?xml' and before final '?>' if XML input contained XMLDecl (see section
-<a href="http://www.w3.org/TR/REC-xml#NT-XMLDecl">2.8 Prolog and Document Type
-Declaration</a> in XML 1.0 ). For example if input XML stream contained <?xml
-version='1.0' standalone='true'?> then this property will contain "
-version='1.0' standalone='true'".</p>
+ <p>If <a href="http://xmlpull.org/v1/doc/features.html#xml-roundtrip">XML ROUNDTRIP</a> feature is enabled it is
+ REQUIRED property with String otherwise it is optional.</p>
+
+ <p>If XML ROUNDTRIP feature is true then this property MUST contain everything after '<?xml' and before final
+ '?>' if XML input contained XMLDecl (see section <a href="http://www.w3.org/TR/REC-xml#NT-XMLDecl">2.8 Prolog and
+ Document Type Declaration</a> in XML 1.0 ). For example if input XML stream contained <?xml version='1.0'
+ standalone='true'?> then this property will contain " version='1.0' standalone='true'".</p>
<p> </p>
-<h3>
-<a name="serializer-indentation"></a>Optional property: SERIALIZER INDENTATION</h3>
-<p>This property is identified by
-<a href="http://xmlpull.org/v1/doc/properties.html#serializer-indentation">
-http://xmlpull.org/v1/doc/properties.html#serializer-indentation</a> </p>
+ <h3><a name="serializer-indentation" id="serializer-indentation"></a>Optional property: SERIALIZER INDENTATION</h3>
+
+ <p>This property is identified by <a href=
+ "http://xmlpull.org/v1/doc/properties.html#serializer-indentation">http://xmlpull.org/v1/doc/properties.html#serializer-indentation</a></p>
+
<p>OPTIONAL property with String value </p>
<p>If passed string is not empty that it is used to indent output by one level.</p>
-<p>If passed string is empty only line separator (depending on
-<a href="#serializer-line-separator">LINE SEPARATOR property</a>) will be
-written for indentation (if any).</p>
+ <p>If passed string is empty only line separator (depending on <a href="#serializer-line-separator">LINE SEPARATOR
+ property</a>) will be written for indentation (if any).</p>
-<p>Otherwise if string is null no indentation
-is not done</p>
+ <p>Otherwise if string is null no indentation is not done</p>
-<p>For example use TAB ("\t") or few spaces (" ")
-as string value.</p>
+ <p>For example use TAB ("\t") or few spaces (" ") as string value.</p>
<p> </p>
-<h3>
-<a name="serializer-line-separator"></a>Optional property: SERIALIZER LINE
+ <h3><a name="serializer-line-separator" id="serializer-line-separator"></a>Optional property: SERIALIZER LINE
SEPARATOR</h3>
-<p>This property is identified by
-<a href="http://xmlpull.org/v1/doc/properties.html#serializer-line-separator">
-http://xmlpull.org/v1/doc/properties.html#serializer-line-separator</a> </p>
+
+ <p>This property is identified by <a href=
+ "http://xmlpull.org/v1/doc/properties.html#serializer-line-separator">http://xmlpull.org/v1/doc/properties.html#serializer-line-separator</a></p>
+
<p>OPTIONAL property with String value </p>
<p>If indentation is enabled passed string will be used as line separator.</p>
-<p>If supported by default this property should be initialized just new line
-character ("\n").</p>
+ <p>If supported by default this property should be initialized just new line character ("\n").</p>
-<p>If value of property is null or it is String of length() == 0 no line separator
-will be written.</p>
+ <p>If value of property is null or it is String of length() == 0 no line separator will be written.</p>
<p> </p>
-
-
-
<p> </p>
+ <hr />
+ <address>
+ <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a>
-
-
-<HR>
-<address><a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a><address>
-<font size="2">Last Modified: $Id: properties.html,v 1.9 2003/04/23 12:25:18 aslom Exp $</font><address>
-</address>
+ <address>
+ <font size="2">Last Modified: $Id: properties.html,v 1.10 2005/08/29 17:30:49 aslom Exp $</font>
</address>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
+
<p> </p>
-</BODY>
-</HTML>
\ No newline at end of file
+ </address>
+</body>
+</html>
1.9 +124 -115 xmlpull-api-v1/doc/quick_intro.html
Index: quick_intro.html
===================================================================
RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/quick_intro.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -b -t -w -r1.8 -r1.9
--- quick_intro.html 26 Feb 2003 04:50:23 -0000 1.8
+++ quick_intro.html 29 Aug 2005 17:30:49 -0000 1.9
@@ -1,99 +1,114 @@
-<HTML>
-<HEAD>
-<TITLE>Quick Introduction to XmlPull v1 API
-</TITLE>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="Author" content="Aleksander Slominski">
-</HEAD>
-<BODY BGCOLOR="white">
-
-<H1>Quick Introduction to XmlPull v1 API</H2><P>
-
-<p>XmlPull v1 API is a simple to use XML pull parsing API that was designed for
-simplicity and very good performance both in constrained environment such as
-defined by J2ME and on server side when used in J2EE application servers. XML
-pull parsing allows incremental (sometimes called streaming) parsing of XML where
-application is in control - the parsing can be interrupted at any given moment
-and resumed when application is ready to consume more input.<p>This document
-will show step by step how to create a simple application that is using
-XmlPull API to parse XML. If you need to write XML output check a companion
-document <a href="quick_write.html">Quick Introduction to writing XML with
-XmlSerializer</a>. For more comprehensive introduction to XmlPull v1 API and XML pull
-parsing in general read JavaWorld.com article "<a href="http://www.javaworld.com/javaworld/jw-04-2002/jw-0426-xmljava3.html">XML
-documents on the run, Part 3</a>" by <a href="http://www.sosnoski.com/">Dennis
-M. Sosnoski</a>.<H2>Main features of API</H2>
-
-
-<P>Java version of XmlPull v1 API provides:<ul>
-<li><b>simple interface</b> - parser consists of one interface, one exception
-and one factory to create parser<li><b>implementation independent</b> - factory
-class is modeled after JAXP and allows easily to switch to different XmlPull V1
-API implementation without even modifying source code<li><b>ease of use</b> -
-there is only one key method <b><i>next()</i></b> that is used to retrieve next
-event and there are <b>only five events</b>:
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta name="generator" content="HTML Tidy for Windows (vers 12 April 2005), see www.w3.org" />
+
+ <title>Quick Introduction to XmlPull v1 API</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta name="Author" content="Aleksander Slominski" />
+</head>
+
+<body bgcolor="white">
+ <h1>Quick Introduction to XmlPull v1 API</h1>
+
+ <p>XmlPull v1 API is a simple to use XML pull parsing API that was designed for simplicity and very good performance
+ both in constrained environment such as defined by J2ME and on server side when used in J2EE application servers. XML
+ pull parsing allows incremental (sometimes called streaming) parsing of XML where application is in control - the
+ parsing can be interrupted at any given moment and resumed when application is ready to consume more input.</p>
+
+ <p>This document will show step by step how to create a simple application that is using XmlPull API to parse
+ XML. If you need to write XML output check a companion document <a href=
+ "http://www.extreme.indiana.edu/bugzilla/quick_write.html">Quick Introduction to writing XML with
+ XmlSerializer</a>. For more comprehensive introduction to XmlPull v1 API and XML pull parsing in general read
+ JavaWorld.com article "<a href="http://www.javaworld.com/javaworld/jw-04-2002/jw-0426-xmljava3.html">XML documents on
+ the run, Part 3</a>" by <a href="http://www.sosnoski.com/">Dennis M. Sosnoski</a>.</p>
+
+ <h2>Main features of API</h2>
+
+ <p>Java version of XmlPull v1 API provides:</p>
+
+ <ul>
+ <li><b>simple interface</b> - parser consists of one interface, one exception and one factory to create parser</li>
+
+ <li><b>implementation independent</b> - factory class is modeled after JAXP and allows easily to switch to
+ different XmlPull V1 API implementation without even modifying source code</li>
+
+ <li>
+ <b>ease of use</b> - there is only one key method <b><i>next()</i></b> that is used to retrieve next event and
+ there are <b>only five events</b>:
+
<dl>
-<dt><b> START DOCUMENT</b> <dd>document start - parser has not yet read any input
-<dt><b> START_TAG</b> <dd> parser is on start tag
-<dt><b> TEXT</b> <dd> parser is on element content
-<dt><b> END_TAG</b> <dd> parser is on end tag
-<dt><b> END_DOCUMENT</b> <dd> document finished and no more parsing is allowed
-</dl>
-<li><b>versatility</b> - it is generic interface for XML parser and allows for
-multiple implementations and extensibility through features and properties
-<li><b>performance</b> - the interface is designed to allow implementing very fast XML parsers
-<li><b>minimal requirements</b> - designed to be compatible with J2ME (Java 2 Micro Edition)
-to work and on small devices and to allow create XmlPull compliant parsers of very small
-memory footprint.
-</ul>
+ <dt><b> START DOCUMENT</b></dt>
+ <dd>document start - parser has not yet read any input</dd>
-<H2><a name="reqs"></a>Requirements</H2>
+ <dt><b> START_TAG</b></dt>
-<p>XmlPull is API and it requires implementation to run.
+ <dd>parser is on start tag</dd>
-See <a href="http://www.xmlpull.org/impls.shtml">list of implementations</a>
-on XmlPull website. After downloading one of implementations of XmlPull API v1 (version 1.1
-or newer)
-add jar file to your CLASSPATH. As XmlPull uses factory there is no need to
-explicitly state what is class with parser implementation: it will be picked up
-automatically from implementation jar file.<H2>Code step-by-step</H2>
-
-<p>First we need to create an instance of parser.
-To do this three steps are required:<ul>
-<li>get instance of XmlPull factory
-<li>(optional step) by default factory will produce parsers that are not
-namespace aware; to change setNamespaceAware() function must be called
-<li>create an instance of the parser
-</ul>
+ <dt><b> TEXT</b></dt>
-Before doing anything make sure to import XmlPull v1 API classes:
+ <dd>parser is on element content</dd>
-<pre>import org.xmlpull.v1.XmlPullParser;
-import org.xmlpull.v1.XmlPullParserException;
-import org.xmlpull.v1.XmlPullParserFactory;
-</pre>
+ <dt><b> END_TAG</b></dt>
+ <dd>parser is on end tag</dd>
-and the code to do this may look similar to this:
+ <dt><b> END_DOCUMENT</b></dt>
-<pre> XmlPullParserFactory factory = XmlPullParserFactory.newInstance(
- System.getProperty(XmlPullParserFactory.PROPERTY_NAME), null);
- factory.setNamespaceAware(true);
- XmlPullParser xpp = factory.newPullParser();
-</pre>
+ <dd>document finished and no more parsing is allowed</dd>
+ </dl>
+ </li>
-Next step is to set parser input:
+ <li><b>versatility</b> - it is generic interface for XML parser and allows for multiple implementations and
+ extensibility through features and properties</li>
-<pre> xpp.setInput ( new FileReader ( args [i] ) );
-</pre>
+ <li><b>performance</b> - the interface is designed to allow implementing very fast XML parsers</li>
+
+ <li><b>minimal requirements</b> - designed to be compatible with J2ME (Java 2 Micro Edition) to work and on small
+ devices and to allow create XmlPull compliant parsers of very small memory footprint.</li>
+ </ul>
+
+ <h2><a name="reqs" id="reqs"></a>Requirements</h2>
+
+ <p>XmlPull is API and it requires implementation to run. See <a href="http://www.xmlpull.org/impls.shtml">list of
+ implementations</a> on XmlPull website. After downloading one of implementations of XmlPull API v1 (version 1.1 or
+ newer) add jar file to your CLASSPATH. As XmlPull uses factory there is no need to explicitly state what is class
+ with parser implementation: it will be picked up automatically from implementation jar file.</p>
-and now we can start parsing!
+ <h2>Code step-by-step</h2>
-<p>Typical XmlPull applicaition will repeatedly call
-next() function to retrieve next event, process event
-until the even is END_DOCUMENT:
+ <p>First we need to create an instance of parser. To do this three steps are required:</p>
-<pre> public void processDocument(XmlPullParser xpp)
+ <ul>
+ <li>get instance of XmlPull factory</li>
+
+ <li>(optional step) by default factory will produce parsers that are not namespace aware; to change
+ setNamespaceAware() function must be called</li>
+
+ <li>create an instance of the parser</li>
+ </ul>Before doing anything make sure to import XmlPull v1 API classes:
+ <pre>
+import org.xmlpull.v1.XmlPullParser;
+import org.xmlpull.v1.XmlPullParserException;
+import org.xmlpull.v1.XmlPullParserFactory;
+</pre>and the code to do this may look similar to this:
+ <pre>
+ XmlPullParserFactory factory = XmlPullParserFactory.newInstance(
+ System.getProperty(XmlPullParserFactory.PROPERTY_NAME), null);
+ factory.setNamespaceAware(true);
+ XmlPullParser xpp = factory.newPullParser();
+</pre>Next step is to set parser input:
+ <pre>
+ xpp.setInput ( new FileReader ( args [i] ) );
+</pre>and now we can start parsing!
+
+ <p>Typical XmlPull applicaition will repeatedly call next() function to retrieve next event, process event until the
+ even is END_DOCUMENT:</p>
+ <pre>
+ public void processDocument(XmlPullParser xpp)
throws XmlPullParserException, IOException
{
int eventType = xpp.getEventType();
@@ -114,11 +129,10 @@
}
</pre>
-
-<p>Let see how to process start tag.
-Processing end tag is very similar - main difference is that the end tag has no attributes.
-
-<pre> public void processStartElement (XmlPullParser xpp)
+ <p>Let see how to process start tag. Processing end tag is very similar - main difference is that the end tag has no
+ attributes.</p>
+ <pre>
+ public void processStartElement (XmlPullParser xpp)
{
String name = xpp.getName();
String uri = xpp.getNamespace();
@@ -128,18 +142,19 @@
System.out.println("Start element: {" + uri + "}" + name);
}
}
-</pre>
-<p>And now let see how element content is retrieved and printed:
+</pre>
-<pre> int holderForStartAndLength[] = new int[2];
+ <p>And now let see how element content is retrieved and printed:</p>
+ <pre>
+ int holderForStartAndLength[] = new int[2];
public void processText (XmlPullParser xpp) throws XmlPullParserException
{
char ch[] = xpp.getTextCharacters(holderForStartAndLength);
int start = holderForStartAndLength[0];
int length = holderForStartAndLength[1];
System.out.print("Characters: \"");
- for (int i = start; i < start + length; i++) {
+ for (int i = start; i < start + length; i++) {
switch (ch[i]) {
case '\\':
System.out.print("\\\\");
@@ -165,23 +180,17 @@
}
</pre>
-<H2>Complete sample</H2>
-
-
-<dl>
+ <h2>Complete sample</h2>
+ <p>The finished working sample created that was described is in <a href=
+ "http://www.extreme.indiana.edu/src/java/samples/MyXmlPullApp.java">MyXmlPullApp.java</a> file in <a href=
+ "http://www.extreme.indiana.edu/src/java/samples/">src/java/samples</a> directory.</p>
-The finished working sample created that was described is in
-<a href="../src/java/samples/MyXmlPullApp.java">MyXmlPullApp.java</a> file in
-<a href="../src/java/samples/">src/java/samples</a> directory.
+ <p>For more information please visit <a href="http://www.xmlpull.org/">http://www.xmlpull.org/</a>.</p>
-<p>For more information please visit <a href="http://www.xmlpull.org/">
-http://www.xmlpull.org/</a>.</p>
-
-<H2>Output</H2>
-
-
-<pre>java MyXmlPullApp
+ <h2>Output</h2>
+ <pre>
+java MyXmlPullApp
parser implementation class is class org.xmlpull.xpp3.PullParser
Parsing simple sample XML
Start document
@@ -209,10 +218,10 @@
Characters: "\n"
End element: {http://www.megginson.com/ns/exp/poetry}poem
</pre>
+ <hr />
-<HR>
-<address><a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a><address>
+ <address>
+ <a href="http://www.extreme.indiana.edu/%7Easlom/">Aleksander Slominski</a>
</address>
-</dl>
-</BODY>
-</HTML>
\ No newline at end of file
+</body>
+</html>
1.4 +162 -182 xmlpull-api-v1/doc/quick_write.html
Index: quick_write.html
===================================================================
RCS file: /l/extreme/cvspub/xmlpull-api-v1/doc/quick_write.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -b -t -w -r1.3 -r1.4
--- quick_write.html 24 Jan 2005 12:39:58 -0000 1.3
+++ quick_write.html 29 Aug 2005 17:30:49 -0000 1.4
@@ -1,235 +1,215 @@
-<HTML>
-<HEAD>
-<TITLE>Quick Introduction to generting XML with XmlPull v1 API
-</TITLE>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="Author" content="Aleksander Slominski">
-</HEAD>
-<BODY BGCOLOR="white">
-
-<H1>Quick Introduction to generating XML with XmlPull v1 API</H2><P>
-
-<p>This document describes how to use XmlSerializer that is part of XmlPull API
-to generate/write/serialize XML (If you want to do XML parsing read
-<a href="quick_intro.html">quick introduction to XML pull parsing</a>)<h2>Main features of API</h2>
-
-
-<P>XmlSerializer provides:<ul>
-
-<li><b>simple to use</b> API that concentrates on how to generate correct XML
-quickly and in straightforward manner<li><b>support for namespaces</b> with automatic prefix declaration to make
-it as easy as possible to generate valid XML 1.0 documents with XML Namespaces
-
-
-<li><b>control over namespace prefixes</b> even though control over namespace
-prefixes is typically not needed
-but as prefixes are used in attribute values so it is important to allow
-control on how namespace prefixes are assigned if needed<li><b>performance</b>
-- the interface is designed to allow implementing <i>very fast</i> XML serializer
-
-<li><b>minimal requirements</b> - designed to be compatible with J2ME (Java 2 Micro Edition)
-to work on small devices and to allow creating XmlPull compliant serializer
-implementation with very small
-memory footprint.
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-</ul>
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+ <meta name="generator" content="HTML Tidy for Windows (vers 12 April 2005), see www.w3.org" />
+ <title>Quick Introduction to generting XML with XmlPull v1 API</title>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta name="Author" content="Aleksander Slominski" />
+</head>
-<h2>Requirements</h2>
+<body bgcolor="white">
+ <h1>Quick Introduction to generating XML with XmlPull v1 API</h1>
-<p>Before running sample code make sure to have parser that implements XmlPull
-API 1.1.x (read <a href="quick_intro.html#reqs">relevant part from Quick
-Introduction</a>)<h2>Writing XML: in few easy steps</h2>
-
-<p>All XML generating can be done by using XmlSerializer interface.
-However before we can start writing we need to obtain instance of class that
-implements this interface.
-
-<p>XmlPull API allows multiple implementations to be used.
-To achieve this flexibility serializer class is not created directly but by
-using configurable factory that is responsible for locating and creating
-implementation. In general that involves following steps:
+ <p>This document describes how to use XmlSerializer that is part of XmlPull API to generate/write/serialize XML (If
+ you want to do XML parsing read <a href="quick_intro.html">quick introduction to XML pull parsing</a>)</p>
-<ul>
-<li>get instance of XmlPull factory - you can use system property as argument
-to configure factory with list of implementation to try and you can pass
-class to use as class loader context (important in servlet and application servers environments)
-<li>create an instance of the serializer
-</ul>
+ <h2>Main features of API</h2>
-In your code as the first thing make sure to import XmlPull v1 API classes:
+ <p>XmlSerializer provides:</p>
-<pre>import org.xmlpull.v1.XmlPullParserException;
-import org.xmlpull.v1.XmlPullParserFactory;
-import org.xmlpull.v1.XmlSerializer;
-</pre>
+ <ul>
+ <li><b>simple to use</b> API that concentrates on how to generate correct XML quickly and in straightforward
+ manner</li>
+ <li><b>support for namespaces</b> with automatic prefix declaration to make it as easy as possible to generate
+ valid XML 1.0 documents with XML Namespaces</li>
-and the code to create serializer may look like this:
+ <li><b>control over namespace prefixes</b> even though control over namespace prefixes is typically not needed but
+ as prefixes are used in attribute values so it is important to allow control on how namespace prefixes are assigned
+ if needed</li>
-<pre> XmlPullParserFactory factory = XmlPullParserFactory.newInstance(
- System.getProperty(XmlPullParserFactory.PROPERTY_NAME), null);
- XmlSerializer serializer = factory.newSerializer();
-</pre>
+ <li><b>performance</b> - the interface is designed to allow implementing <i>very fast</i> XML serializer</li>
-Next step is to set serializer output - in this case it is set to write to
-standard output but can easily redirected to file or socket:
+ <li><b>minimal requirements</b> - designed to be compatible with J2ME (Java 2 Micro Edition) to work on small
+ devices and to allow creating XmlPull compliant serializer implementation with very small memory footprint.</li>
+ </ul>
-<pre> serializer.setOutput(new PrintWriter( System.out ));
-</pre>
+ <h2>Requirements</h2>
-and now we can start using <code>serializer</code> to write XML!
+ <p>Before running sample code make sure to have parser that implements XmlPull API 1.1.x (read <a href=
+ "quick_intro.html#reqs">relevant part from Quick Introduction</a>)</p>
-<p>Typical applicaition will write XML declaration and then follow
-with writing few element start and end tags and their content.
+ <h2>Writing XML: in few easy steps</h2>
-<p>Output must always have at least one start tag:
-<pre> serializer.startTag(NAMESPACE, "poem");
-</pre>
+ <p>All XML generating can be done by using XmlSerializer interface. However before we can start writing we need to
+ obtain instance of class that implements this interface.</p>
-then we cna start writing more start tags, text cotnent, and end tags:
+ <p>XmlPull API allows multiple implementations to be used. To achieve this flexibility serializer class is not
+ created directly but by using configurable factory that is responsible for locating and creating implementation. In
+ general that involves following steps:</p>
-<pre> serializer.startTag(NAMESPACE, "title");
+ <ul>
+ <li>get instance of XmlPull factory - you can use system property as argument to configure factory with list of
+ implementation to try and you can pass class to use as class loader context (important in servlet and application
+ servers environments)</li>
+
+ <li>create an instance of the serializer</li>
+ </ul>In your code as the first thing make sure to import XmlPull v1 API classes:
+ <pre>
+import org.xmlpull.v1.XmlPullParserException;
+import org.xmlpull.v1.XmlPullParserFactory;
+import org.xmlpull.v1.XmlSerializer;
+</pre>and the code to create serializer may look like this:
+ <pre>
+ XmlPullParserFactory factory = XmlPullParserFactory.newInstance(
+ System.getProperty(XmlPullParserFactory.PROPERTY_NAME), null);
+ XmlSerializer serializer = factory.newSerializer();
+</pre>Next step is to set serializer output - in this case it is set to write to standard output but can easily
+redirected to file or socket:
+ <pre>
+ serializer.setOutput(new PrintWriter( System.out ));
+</pre>and now we can start using <code>serializer</code> to write XML!
+
+ <p>Typical applicaition will write XML declaration and then follow with writing few element start and end tags and
+ their content.</p>
+
+ <p>Output must always have at least one start tag:</p>
+ <pre>
+ serializer.startTag(NAMESPACE, "poem");
+</pre>then we cna start writing more start tags, text cotnent, and end tags:
+ <pre>
+ serializer.startTag(NAMESPACE, "title");
serializer.text("Roses are Red");
serializer.endTag(NAMESPACE, "title");
+</pre>where namespace is declared as string constant
+ <pre>
+private final static String NAMESPACE = "http://www.megginson.com/ns/exp/poetry";
</pre>
-where namespace is declared as string constant
-<pre>private final static String NAMESPACE = "http://www.megginson.com/ns/exp/poetry";</pre>
-
-<p>it is possible to chain multiple calls:
-
-<pre> serializer.startTag(NAMESPACE, "l")
+ <p>it is possible to chain multiple calls:</p>
+ <pre>
+ serializer.startTag(NAMESPACE, "l")
.text("Roses are red,")
.endTag(NAMESPACE, "l");
-</pre>
-
-or put them even in one line:
-<pre> serializer.startTag(NAMESPACE, "l").text("Violets are blue;").endTag(NAMESPACE, "l");
-</pre>
-
-but what make API really flexible and modular is to define functions that
-outputs well defined parts of XML, for example:
-<pre> private static void writeLine(XmlSerializer serializer, String line, boolean addNewLine)
+</pre>or put them even in one line:
+ <pre>
+ serializer.startTag(NAMESPACE, "l").text("Violets are blue;").endTag(NAMESPACE, "l");
+</pre>but what make API really flexible and modular is to define functions that outputs well defined parts of XML, for
+example:
+ <pre>
+ private static void writeLine(XmlSerializer serializer, String line, boolean addNewLine)
throws IOException {
serializer.startTag(NAMESPACE, "l");
serializer.text(line);
serializer.endTag(NAMESPACE, "l");
if(addNewLine) serializer.text("\n");
}
-</pre>
-
-and then to write chunkof XML output it is enough to simply call:
-<pre> writeLine(serializer, "Sugar is sweet,", addNewLine);
+</pre>and then to write chunkof XML output it is enough to simply call:
+ <pre>
+ writeLine(serializer, "Sugar is sweet,", addNewLine);
writeLine(serializer, "And I love you.,", addNewLine);
</pre>
+ <p>Serializer will check that end tag name and namespace is the same as of matching start tag (very good to validate
+ that XML output is correct) so to finish writing XML we should close top level start tag:</p>
+ <pre>
+ serializer.endTag(NAMESPACE, "poem");
+</pre>
-<p>Serializer will check that end tag name and namespace is the same as
-of matching start tag (very good to validate that XML output is correct)
-so to finish writing XML we should close top level start tag:
-
-<pre> serializer.endTag(NAMESPACE, "poem");</pre>
-
-<p>It is important to inform serializer when XML output is finished
-so any remianing buffered XML output is send to putput stream and
-serializer will not allow any more input to do this call endDocument():
-
-<pre> serializer.endDocument();</pre>
-
-
-
+ <p>It is important to inform serializer when XML output is finished so any remianing buffered XML output is send to
+ putput stream and serializer will not allow any more input to do this call endDocument():</p>
+ <pre>
+ serializer.endDocument();
+</pre>
-<h3>Controlling namespace prefixes</h3>
+ <h3>Controlling namespace prefixes</h3>There is no need to manually set prefixes as XmlSerializer will automatically
+ declare prefixes when needed. However sometimes it is necessary to indicate what prefix should be used:
+ <pre>
+ serializer.setPrefix("ns", NAMESPACE);
+</pre>or what namespace should be bound as default namespace (to special empty string prefix):
+ <pre>
+ serializer.setPrefix("", NAMESPACE);
+</pre>
-There is no need to manually set prefixes as XmlSerializer will automatically
-declare prefixes when needed. However sometimes it is necessary to indicate
-what prefix should be used:
+ <p>Prefix declaration must be done just before call to start tag and the prefix declaration scope starts on this star
+ tag and finishes when corresponding end tag is reached.</p>
-<pre> serializer.setPrefix("ns", NAMESPACE);</pre>
+ <h3>Controlling output formatting</h3>
-or what namespace should be bound as default namespace (to special empty string prefix):
+ <p>XmlSerializer allows to create any infoset so it is possible to add manually new lines or indentation. for exmaple
+ if would like to have new line after every end tag it is as easy as to call text() with new line:</p>
+ <pre>
+ if(addNewLine) serializer.text("\n");
+</pre>
-<pre> serializer.setPrefix("", NAMESPACE);</pre>
+ <p>If serializer supports optional formatting properties and features then they can be used to have output indented
+ automatically. Read more about them:</p>
-<p>Prefix declaration must be done just before call to start tag and
-the prefix declaration scope starts on this star tag and finishes when corresponding
-end tag is reached.
+ <ul>
+ <li>optional property: <a href="http://xmlpull.org/v1/doc/properties.html#serializer-indentation">SERIALIZER
+ INDENTATION</a></li>
-<h3>Controlling output formatting</h3>
+ <li>optional property: <a href="http://xmlpull.org/v1/doc/properties.html#serializer-line-separator">SERIALIZER
+ LINE SEPARATOR</a></li>
-<p>XmlSerializer allows to create any infoset so it is possible to add manually
-new lines or indentation. for exmaple if would like to have new line after every end tag
-it is as easy as to call text() with new line:
-
-<pre> if(addNewLine) serializer.text("\n");</pre>
-
-<p>If serializer supports optional formatting properties and features then
-they can be used to have output indented automatically.
-Read more about them:
-<ul>
-<li>optional property:
-<a href="http://xmlpull.org/v1/doc/properties.html#serializer-indentation">SERIALIZER INDENTATION</a>
-<li>optional property:
-<a href="http://xmlpull.org/v1/doc/properties.html#serializer-line-separator">SERIALIZER LINE SEPARATOR</a>
-<li>optional feature:
-<a href="http://xmlpull.org/v1/doc/features.html#serializer-attvalue-use-apostrophe">SERIALIZER ATTVALUE USE APOSTROPHE</a>
+ <li>optional feature: <a href=
+ "http://xmlpull.org/v1/doc/features.html#serializer-attvalue-use-apostrophe">SERIALIZER ATTVALUE USE
+ APOSTROPHE</a></li>
</ul>
-<p> </p>
-</p>
-
+ <p> </p>
<h2>Sample code</h2>
-<p>
-The finished working sample created that was described is in
-<a href="../src/java/samples/MyXmlWriteApp.java">MyXmlWriteApp.java</a> file in
-<a href="../src/java/samples/">src/java/samples</a> directory.
-
-<p>For more information about XmlPull API
-please visit
-<a href="http://www.xmlpull.org/">http://www.xmlpull.org/</a>.
-</p>
-
-
-
+ <p>The finished working sample created that was described is in <a href=
+ "../src/java/samples/MyXmlWriteApp.java">MyXmlWriteApp.java</a> file in <a href=
+ "../src/java/samples/">src/java/samples</a> directory.</p>
+ <p>For more information about XmlPull API please visit <a href=
+ "http://www.xmlpull.org/">http://www.xmlpull.org/</a>.</p>
<h2>Output from sample application</h2>
-<p>When new lines are added manually:
-
-<pre>java MyXmlWriteApp -n
+ <p>When new lines are added manually:</p>
+ <pre>
+java MyXmlWriteApp -n
serializer implementation class is class org.kxml2.io.KXmlSerializer
-<?xml version="1.0"?>
+<?xml version="1.0"?>
-<poem xmlns="http://www.megginson.com/ns/exp/poetry">
-<title>Roses are Red</title>
-<l>Roses are red,</l>
-<<l>Violets are blue;</l>
-<l>Sugar is sweet,</l>
-<l>And I love you.,</l>
-</poem>
+<poem xmlns="http://www.megginson.com/ns/exp/poetry">
+<title>Roses are Red</title>
+<l>Roses are red,</l>
+<l>Violets are blue;</l>
+<l>Sugar is sweet,</l>
+<l>And I love you.,</l>
+</poem>
</pre>
-<p>When using one of optional formatting properties to set indentation:
-
-<pre>java MyXmlWriteApp -i 4
+ <p>When using one of optional formatting properties to set indentation:</p>
+ <pre>
+java MyXmlWriteApp -i 4
serializer implementation class is class org.xmlpull.mxp1_serializer.MXSerializer
-<?xml version="1.0"?>
+<?xml version="1.0"?>
-<poem xmlns="http://www.megginson.com/ns/exp/poetry">
- <title>Roses are Red</title>
- <l>Roses are red,</l>
- <l>Violets are blue;</l>
- <l>Sugar is sweet,</l>
- <l>And I love you.,</l>
-</poem>
-</pre>
-
-<hr>
-<address><a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a><address>
-Last modified: $Id: quick_write.html,v 1.3 2005/01/24 12:39:58 aslom Exp $</address>
-</BODY>
-</HTML>
\ No newline at end of file
+<poem xmlns="http://www.megginson.com/ns/exp/poetry">
+ <title>Roses are Red</title>
+ <l>Roses are red,</l>
+ <l>Violets are blue;</l>
+ <l>Sugar is sweet,</l>
+ <l>And I love you.,</l>
+</poem>
+</pre>
+ <hr />
+
+ <address>
+ <a href="http://www.extreme.indiana.edu/~aslom/">Aleksander Slominski</a>
+
+ <address>
+ Last modified: $Id: quick_write.html,v 1.4 2005/08/29 17:30:49 aslom Exp $
+ </address>
+ </address>
+</body>
+</html>
------------------------ Yahoo! Groups Sponsor --------------------~-->
Fair play? Video games influencing politics. Click and talk back!
http://us.click.yahoo.com/T8sf5C/tzNLAA/TtwFAA/2U_rlB/TM
--------------------------------------------------------------------~->
Yahoo! Groups Links
<*> To visit your group on the web, go to:
http://groups.yahoo.com/group/xmlpull-dev/
<*> To unsubscribe from this group, send an email to:
[email protected]
<*> Your use of Yahoo! Groups is subject to:
http://docs.yahoo.com/info/terms/