[
Lists Home |
Date Index |
Thread Index
]
I've committed some proposed changes to SAX2 into the SourceForge CVS. I'm
attaching (as text) the SAX TODO list and the diffs for my changes.
Let's take the week for people to chew over these, then if everything is
relatively quiet, I can put out an official (non-beta) minor maintenance
release on the weekend.
All the best,
David
SAX TODO -*-Outline-*-
* 2004-0001: beta status
- changed docs for all beta features to released status
[dpm: automatic upon release?]
* 2004-0002: XML 1.1 support
- add a read-only feature to check for XML 1.1 support
[added to docs/features.html]
- add a read-only string property to return the version number of the
document being parsed
[added to docs/features.html]
- remove all unnecessary references to XML 1.0 from the docs
[kept references to specific sections in the XML 1.0 REC and to error
codes based on 1.0; removed things like "raw XML 1.0 names"]
* 2004-0003: Unicode normalization
- add a feature to request Unicode normalization checking (false by
default)
[added to docs/features.html]
- use error() to report all normalization problems
[added to docs/features.html]
- add a new exception subclass for normalization errors
[not this time]
* 2004-0004: xmlns Namespace
- commit paragraph from CVS Attributes.java about xmlns-uris feature
[added to docs/features.html]
- document interaction between xmlns-uris and namespace-prefixes
features
[added to docs/features.html]
* 2004-0005: endDocument
- note that a parser might not invoke endDocument after reporting a
fatal error (this produces the fewest incompatibilities)
[added JavaDocs to endDocument() and fatalError()]
* 2004-0006: Locator2
- allow getEncoding() and getXMLVersion() to return null if the
information is not yet available
[added to Locator2.java]
Index: docs/changes.html
===================================================================
RCS file: /cvsroot/sax/sax2/docs/changes.html,v
retrieving revision 1.2
diff -c -u -r1.2 changes.html
--- docs/changes.html 28 Dec 2000 20:34:52 -0000 1.2
+++ docs/changes.html 8 Mar 2004 12:59:11 -0000
@@ -235,7 +235,7 @@
<p>SAX2 contains complete Namespace support, which is available by
default from any <a
href="javadoc/org/xml/sax/XMLReader.html">XMLReader</a>. An XML
-reader can also optionally supply raw XML 1.0 names. See <a
+reader can also optionally supply raw XML qnames. See <a
href="namespaces.html">SAX2: Namespaces</a> for more details.</p>
<p>An XML reader is fully configurable: it is possible to attempt to
Index: docs/features.html
===================================================================
RCS file: /cvsroot/sax/sax2/docs/features.html,v
retrieving revision 1.1.1.1
diff -c -u -r1.1.1.1 features.html
--- docs/features.html 8 Sep 2000 02:26:00 -0000 1.1.1.1
+++ docs/features.html 8 Mar 2004 12:59:11 -0000
@@ -93,7 +93,9 @@
<dt><code>http://xml.org/sax/features/namespace-prefixes</code></dt>
<dd><strong>true:</strong> Report the original prefixed names and
-attributes used for Namespace declarations.</dd>
+attributes used for Namespace declarations if the
+<var>http://xml.org/sax/features/xmlns-uris</var> feature is false or
+not supported, or the URI and local name if that feature is true.</dd>
<dd><strong>false:</strong> Do not report attributes used for
Namespace declarations, and optionally do not report original prefixed
names.</dd>
@@ -133,6 +135,35 @@
<dd><strong>access:</strong> (parsing) read-only; (not parsing)
read/write</dd>
+<dt><code>http://xml.org/sax/features/xml-1.1</code></dt>
+<dd><strong>true:</strong> The XML parser supports both XML 1.1 and
+XML 1.0.</dd>
+<dd><strong>false:</strong> The XML parser supports only XML 1.0.</dd>
+<dd><strong>access:</strong> read-only.</dd>
+
+<dt><code>http://xml.org/sax/features/unicode-normalization-checking</code></dt>
+<dd><strong>true:</strong> Report Unicode normalization errors as
+described in section 2.13 and Appendix B of the XML 1.1
+Recommendation, using the ErrorHandler.error() callback. Such errors
+are not fatal in themselves (though, obviously, other Unicode-related
+encoding errors may be).</dd>
+<dd><strong>false:</strong> Do not report Unicode normalization
+errors.</dd>
+<dd><strong>access:</strong> (parsing) read-only; (not parsing)
+read/write</dd>
+
+<dt><code>http://xml.org/sax/features/xmlns-uris</code></dt>
+<dd>Report a Namespace URI for <var>xmlns</var> attributes when the
+<var>http://xml.org/sax/features/namespace-prefixes</var> feature is
+true (when it is false, <var>xmlns</var> attributes are not reported
+at all).</dd>
+<dd><strong>true:</strong> Assign a Namespace URI to xmlns
+attributes.</dd>
+<dd><strong>false:</strong> Do not assign a Namespace URI to xmlns
+attributes.</dd>
+<dd><strong>access:</strong> (parsing) read-only; (not parsing)
+read/write</dd>
+
</dl>
<!-- end of "Core Features" -->
@@ -164,6 +195,12 @@
that was the source for the current event.</dd>
<dd><strong>access:</strong> read-only</dd>
+<dt><code>http://xml.org/sax/properties/document-xml-version</code></dt>
+<dd><strong>data type:</strong> <code>java.lang.String</code></dd>
+<dd><strong>description:</strong> A literal string describing the
+actual XML version of the document, such as "1.0" or "1.1".</dd>
+<dd><strong>access:</strong> read-only</dd>
+
</dl>
<!-- end of "Core Properties" -->
Index: docs/quick-start.html
===================================================================
RCS file: /cvsroot/sax/sax2/docs/quick-start.html,v
retrieving revision 1.1.1.1
diff -c -u -r1.1.1.1 quick-start.html
--- docs/quick-start.html 8 Sep 2000 02:26:00 -0000 1.1.1.1
+++ docs/quick-start.html 8 Mar 2004 12:59:11 -0000
@@ -270,8 +270,8 @@
<p>These methods print a message every time an element starts or ends,
with the Namespace URI in braces before the element's local name. The
-<var>qName</var> contains the raw XML 1.0 name, and since not all
-SAX drivers will report it, it is best to ignore that parameter for
+<var>qName</var> contains the raw XML qname, and since not all SAX
+drivers will report it, it is best to ignore that parameter for
now.</p>
<p>Finally, SAX2 reports regular character data through the <a
Index: src/org/xml/sax/Attributes.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/Attributes.java,v
retrieving revision 1.11
diff -c -u -r1.11 Attributes.java
--- src/org/xml/sax/Attributes.java 25 May 2002 20:11:11 -0000 1.11
+++ src/org/xml/sax/Attributes.java 8 Mar 2004 12:59:12 -0000
@@ -38,14 +38,13 @@
* </p>
*
* <p>Some SAX2 parsers may support using an optional feature flag
- * (<code>http://xml.org/sax/features/xmlns-uris</code>) to request that
- * those attributes be given URIs, conforming to a later
- * backwards-incompatible revision of that recommendation.
- * (The attribute's "local name" will be the prefix, or the empty
- * string when defining a default element namespace.)
- * For portability, handler code should always resolve that conflict,
- * rather than requiring parsers that can change the setting of that
- * feature flag.
+ * (<code>http://xml.org/sax/features/xmlns-uris</code>) to request
+ * that those attributes be given URIs, conforming to a later
+ * backwards-incompatible revision of that recommendation. (The
+ * attribute's "local name" will be the prefix, or the empty string
+ * when defining a default element namespace.) For portability,
+ * handler code should always resolve that conflict, rather than
+ * requiring parsers that can change the setting of that feature flag.
* </p>
*
* <p>If the namespace-prefixes feature (see above) is <var>false</var>,
@@ -118,10 +117,10 @@
/**
- * Look up an attribute's XML 1.0 qualified name by index.
+ * Look up an attribute's XML qualified (prefixed) name by index.
*
* @param index The attribute index (zero-based).
- * @return The XML 1.0 qualified name, or the empty string
+ * @return The XML qualified name, or the empty string
* if none is available, or null if the index
* is out of range.
* @see #getLength
@@ -187,7 +186,7 @@
/**
- * Look up the index of an attribute by XML 1.0 qualified name.
+ * Look up the index of an attribute by XML qualified (prefixed) name.
*
* @param qName The qualified (prefixed) name.
* @return The index of the attribute, or -1 if it does not
@@ -213,12 +212,12 @@
/**
- * Look up an attribute's type by XML 1.0 qualified name.
+ * Look up an attribute's type by XML qualified (prefixed) name.
*
* <p>See {@link #getType(int) getType(int)} for a description
* of the possible types.</p>
*
- * @param qName The XML 1.0 qualified name.
+ * @param qName The XML qualified name.
* @return The attribute type as a string, or null if the
* attribute is not in the list or if qualified names
* are not available.
@@ -242,12 +241,12 @@
/**
- * Look up an attribute's value by XML 1.0 qualified name.
+ * Look up an attribute's value by XML qualified (prefixed) name.
*
* <p>See {@link #getValue(int) getValue(int)} for a description
* of the possible values.</p>
*
- * @param qName The XML 1.0 qualified name.
+ * @param qName The XML qualified name.
* @return The attribute value as a string, or null if the
* attribute is not in the list or if qualified names
* are not available.
Index: src/org/xml/sax/ContentHandler.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/ContentHandler.java,v
retrieving revision 1.10
diff -c -u -r1.10 ContentHandler.java
--- src/org/xml/sax/ContentHandler.java 21 Apr 2002 23:50:34 -0000 1.10
+++ src/org/xml/sax/ContentHandler.java 8 Mar 2004 12:59:12 -0000
@@ -107,6 +107,14 @@
/**
* Receive notification of the end of a document.
*
+ * <p><strong>There is an apparent contradiction between the
+ * documentation for this method and the documentation for {@link
+ * org.xml.sax.ErrorHandler#fatalError}. Until this ambiguity is
+ * resolved in a future major release, clients should make no
+ * assumptions about whether endDocument() will or will not be
+ * invoked when the parser has reported a fatalError() or thrown
+ * an exception.</strong></p>
+ *
* <p>The SAX parser will invoke this method only once, and it will
* be the last method invoked during the parse. The parser shall
* not invoke this method until it has either abandoned parsing
@@ -266,7 +274,7 @@
* @param localName The local name (without prefix), or the
* empty string if Namespace processing is not being
* performed.
- * @param qName The qualified XML 1.0 name (with prefix), or the
+ * @param qName The qualified XML name (with prefix), or the
* empty string if qualified names are not available.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
@@ -327,9 +335,10 @@
* Receive notification of ignorable whitespace in element content.
*
* <p>Validating Parsers must use this method to report each chunk
- * of whitespace in element content (see the W3C XML 1.0 recommendation,
- * section 2.10): non-validating parsers may also use this method
- * if they are capable of parsing and using content models.</p>
+ * of whitespace in element content (see the W3C XML 1.0
+ * recommendation, section 2.10): non-validating parsers may also
+ * use this method if they are capable of parsing and using
+ * content models.</p>
*
* <p>SAX parsers may return all contiguous whitespace in a single
* chunk, or they may split it into several chunks; however, all of
Index: src/org/xml/sax/ErrorHandler.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/ErrorHandler.java,v
retrieving revision 1.9
diff -c -u -r1.9 ErrorHandler.java
--- src/org/xml/sax/ErrorHandler.java 7 May 2002 01:56:47 -0000 1.9
+++ src/org/xml/sax/ErrorHandler.java 8 Mar 2004 12:59:12 -0000
@@ -53,8 +53,9 @@
* Receive notification of a warning.
*
* <p>SAX parsers will use this method to report conditions that
- * are not errors or fatal errors as defined by the XML 1.0
- * recommendation. The default behaviour is to take no action.</p>
+ * are not errors or fatal errors as defined by the XML
+ * recommendation. The default behaviour is to take no
+ * action.</p>
*
* <p>The SAX parser must continue to provide normal parsing events
* after invoking this method: it should still be possible for the
@@ -82,12 +83,12 @@
* validity constraint. The default behaviour is to take no
* action.</p>
*
- * <p>The SAX parser must continue to provide normal parsing events
- * after invoking this method: it should still be possible for the
- * application to process the document through to the end. If the
- * application cannot do so, then the parser should report a fatal
- * error even if the XML 1.0 recommendation does not require it to
- * do so.</p>
+ * <p>The SAX parser must continue to provide normal parsing
+ * events after invoking this method: it should still be possible
+ * for the application to process the document through to the end.
+ * If the application cannot do so, then the parser should report
+ * a fatal error even if the XML recommendation does not require
+ * it to do so.</p>
*
* <p>Filters may use this method to report other, non-XML errors
* as well.</p>
@@ -105,6 +106,14 @@
/**
* Receive notification of a non-recoverable error.
*
+ * <p><strong>There is an apparent contradiction between the
+ * documentation for this method and the documentation for {@link
+ * org.xml.sax.ContentHandler#endDocument}. Until this ambiguity
+ * is resolved in a future major release, clients should make no
+ * assumptions about whether endDocument() will or will not be
+ * invoked when the parser has reported a fatalError() or thrown
+ * an exception.</strong></p>
+ *
* <p>This corresponds to the definition of "fatal error" in
* section 1.2 of the W3C XML 1.0 Recommendation. For example, a
* parser would use this callback to report the violation of a
Index: src/org/xml/sax/SAXParseException.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/SAXParseException.java,v
retrieving revision 1.9
diff -c -u -r1.9 SAXParseException.java
--- src/org/xml/sax/SAXParseException.java 7 May 2002 01:55:38 -0000 1.9
+++ src/org/xml/sax/SAXParseException.java 8 Mar 2004 12:59:12 -0000
@@ -235,12 +235,12 @@
/**
* Returns the identifier for the exception which is being reported.
*
- * @return URI identifying the exception. SAX standardizes the
- * identifiers for errors relating to the specifications that it relies
- * on for XML parsing (including <em>XML 1.0</em> and
- * <em>Namespaces in XML</em>).
- * See <a href="package-summary.html#exceptions">the <em>org.xml.sax</em>
- * package summary</a> for more information.
+ * @return URI identifying the exception. SAX standardizes the *
+ * identifiers for errors relating to the specifications that it
+ * relies * on for XML parsing (including <em>XML</em> and *
+ * <em>Namespaces in XML</em>). * See <a
+ * href="package-summary.html#exceptions">the <em>org.xml.sax</em>
+ * * package summary</a> for more information.
*
* @since SAX 2.1
*/
@@ -255,11 +255,11 @@
* if none has yet been assigned.
*
* @param id URI identifying the exception. SAX standardizes the
- * identifiers for errors relating to the specifications that it relies
- * on for XML parsing (including <em>XML 1.0</em> and
- * <em>Namespaces in XML</em>).
- * See <a href="package-summary.html#exceptions">the <em>org.xml.sax</em>
- * package summary</a> for more information.
+ * * identifiers for errors relating to the specifications that it
+ * relies * on for XML parsing (including <em>XML</em> and *
+ * <em>Namespaces in XML</em>). * See <a
+ * href="package-summary.html#exceptions">the <em>org.xml.sax</em>
+ * * package summary</a> for more information.
* @exception IllegalStateException If the ID was already assigned.
*
* @since SAX 2.1
Index: src/org/xml/sax/package.html
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/package.html,v
retrieving revision 1.13
diff -c -u -r1.13 package.html
--- src/org/xml/sax/package.html 25 May 2002 20:11:11 -0000 1.13
+++ src/org/xml/sax/package.html 8 Mar 2004 12:59:13 -0000
@@ -71,10 +71,9 @@
</tr>
<tr>
- <td>namespace-prefixes</td>
- <td>false</td>
- <td> true indicates XML 1.0 names (with prefixes) and attributes
- (including <em>xmlns*</em> attributes) will be available </td>
+ <td>namespace-prefixes</td> <td>false</td> <td> true indicates
+ XML qualified names (with prefixes) and attributes (including
+ <em>xmlns*</em> attributes) will be available </td>
</tr>
<tr>
@@ -258,7 +257,7 @@
</p>
<p>Moreover, for the XML (and related) standards relied on by the SAX
-specification itself (including <em>XML 1.0</em> and
+specification itself (including <em>XML</em> and
<em>Namespaces in XML</em>), SAX also standardizes the IDs used
to identify those errors.
The identifiers all start with the exception base URI
Index: src/org/xml/sax/ext/Attributes2.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/ext/Attributes2.java,v
retrieving revision 1.5
diff -c -u -r1.5 Attributes2.java
--- src/org/xml/sax/ext/Attributes2.java 22 Apr 2002 00:10:05 -0000 1.5
+++ src/org/xml/sax/ext/Attributes2.java 8 Mar 2004 12:59:13 -0000
@@ -58,7 +58,7 @@
* as CDATA: ones that were declared (and hence are usually valid),
* and those that were not (and which are never valid).
*
- * @param qName The XML 1.0 qualified name.
+ * @param qName The XML qualified (prefixed) name.
* @return true if the attribute was declared in the DTD,
* false otherwise.
* @exception java.lang.IllegalArgumentException When the
@@ -122,7 +122,7 @@
* Returns true unless the attribute value was provided
* by DTD defaulting.
*
- * @param qName The XML 1.0 qualified name.
+ * @param qName The XML qualified (prefixed) name.
* @return true if the value was found in the XML text,
* false if the value was provided by DTD defaulting.
* @exception java.lang.IllegalArgumentException When the
Index: src/org/xml/sax/ext/Attributes2Impl.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/ext/Attributes2Impl.java,v
retrieving revision 1.4
diff -c -u -r1.4 Attributes2Impl.java
--- src/org/xml/sax/ext/Attributes2Impl.java 22 Apr 2002 00:10:05 -0000 1.4
+++ src/org/xml/sax/ext/Attributes2Impl.java 8 Mar 2004 12:59:13 -0000
@@ -158,7 +158,7 @@
/**
* Returns the current value of an attribute's "specified" flag.
*
- * @param qName The XML 1.0 qualified name.
+ * @param qName The XML qualified (prefixed) name.
* @return current flag value
* @exception java.lang.IllegalArgumentException When the
* supplied name does not identify an attribute.
Index: src/org/xml/sax/ext/Locator2.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/ext/Locator2.java,v
retrieving revision 1.3
diff -c -u -r1.3 Locator2.java
--- src/org/xml/sax/ext/Locator2.java 12 Jan 2002 19:06:15 -0000 1.3
+++ src/org/xml/sax/ext/Locator2.java 8 Mar 2004 12:59:13 -0000
@@ -43,7 +43,8 @@
* different rules about which characters are legal in XML names.
*
* @return Identifier for the XML version being used to interpret
- * the entity's text.
+ * the entity's text, or null if that information is not yet
+ * available in the current parsing state.
*/
public String getXMLVersion ();
@@ -70,8 +71,9 @@
* and comparisons should be case-insensitive.
*
* @return Name of the character encoding being used to interpret
- * the entity's text, or null if this was not provided for a
- * character stream passed through an InputSource.
+ * * the entity's text, or null if this was not provided for a *
+ * character stream passed through an InputSource or is otherwise
+ * not yet available in the current parsing state.
*/
public String getEncoding ();
}
Index: src/org/xml/sax/helpers/NamespaceSupport.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/helpers/NamespaceSupport.java,v
retrieving revision 1.12
diff -c -u -r1.12 NamespaceSupport.java
--- src/org/xml/sax/helpers/NamespaceSupport.java 25 May 2002 20:11:11 -0000 1.12
+++ src/org/xml/sax/helpers/NamespaceSupport.java 8 Mar 2004 12:59:14 -0000
@@ -23,11 +23,11 @@
* for further information.
* </blockquote>
*
- * <p>This class encapsulates the logic of Namespace processing:
- * it tracks the declarations currently in force for each context
- * and automatically processes qualified XML 1.0 names into their
- * Namespace parts; it can also be used in reverse for generating
- * XML 1.0 from Namespaces.</p>
+ * <p>This class encapsulates the logic of Namespace processing: it
+ * tracks the declarations currently in force for each context and
+ * automatically processes qualified XML names into their Namespace
+ * parts; it can also be used in reverse for generating XML qnames
+ * from Namespaces.</p>
*
* <p>Namespace support objects are reusable, but the reset method
* must be invoked between each session.</p>
@@ -305,12 +305,13 @@
/**
- * Process a raw XML 1.0 name, after all declarations in the current
- * context have been handled by {@link #declarePrefix declarePrefix()}.
- *
- * <p>This method processes a raw XML 1.0 name in the current
- * context by removing the prefix and looking it up among the
- * prefixes currently declared. The return value will be the
+ * Process a raw XML qualified name, after all declarations in the
+ * current context have been handled by {@link #declarePrefix
+ * declarePrefix()}.
+ *
+ * <p>This method processes a raw XML qualified name in the
+ * current context by removing the prefix and looking it up among
+ * the prefixes currently declared. The return value will be the
* array supplied by the caller, filled in as follows:</p>
*
* <dl>
@@ -332,14 +333,14 @@
* default Namespace (if any), while an unprefixed attribute name
* will not.</p>
*
- * @param qName The raw XML 1.0 name to be processed.
+ * @param qName The XML qualified name to be processed.
* @param parts An array supplied by the caller, capable of
* holding at least three members.
* @param isAttribute A flag indicating whether this is an
* attribute name (true) or an element name (false).
* @return The supplied array holding three internalized strings
* representing the Namespace URI (or empty string), the
- * local name, and the raw XML 1.0 name; or null if there
+ * local name, and the XML qualified name; or null if there
* is an undeclared prefix.
* @see #declarePrefix
* @see java.lang.String#intern */
@@ -625,9 +626,9 @@
/**
- * Process a raw XML 1.0 name in this context.
+ * Process an XML qualified name in this context.
*
- * @param qName The raw XML 1.0 name.
+ * @param qName The XML qualified name.
* @param isAttribute true if this is an attribute name.
* @return An array of three strings containing the
* URI part (or empty string), the local part,
Index: src/org/xml/sax/helpers/ParserAdapter.java
===================================================================
RCS file: /cvsroot/sax/sax2/src/org/xml/sax/helpers/ParserAdapter.java,v
retrieving revision 1.14
diff -c -u -r1.14 ParserAdapter.java
--- src/org/xml/sax/helpers/ParserAdapter.java 29 May 2003 15:33:21 -0000 1.14
+++ src/org/xml/sax/helpers/ParserAdapter.java 8 Mar 2004 12:59:14 -0000
@@ -473,7 +473,7 @@
* <p>If necessary, perform Namespace processing.</p>
*
* @param qName The qualified (prefixed) name.
- * @param qAtts The XML 1.0 attribute list (with qnames).
+ * @param qAtts The XML attribute list (with qnames).
* @exception SAXException The client may raise a
* processing exception.
*/
|
