You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commons-cvs@xml.apache.org by di...@apache.org on 2002/02/27 17:04:19 UTC
cvs commit: xml-commons/java/external/src/org/xml/sax/helpers AttributeListImpl.java AttributesImpl.java DefaultHandler.java LocatorImpl.java NamespaceSupport.java ParserAdapter.java ParserFactory.java XMLFilterImpl.java XMLReaderAdapter.java XMLReaderFactory.java package.html
dims 02/02/27 08:04:18
Modified: java/external ChangeLog-sax README-sax
java/external/src/org/xml/sax AttributeList.java
Attributes.java ContentHandler.java DTDHandler.java
DocumentHandler.java EntityResolver.java
ErrorHandler.java HandlerBase.java InputSource.java
Locator.java Parser.java SAXException.java
SAXNotRecognizedException.java
SAXNotSupportedException.java
SAXParseException.java XMLFilter.java
XMLReader.java package.html
java/external/src/org/xml/sax/ext DeclHandler.java
LexicalHandler.java package.html
java/external/src/org/xml/sax/helpers AttributeListImpl.java
AttributesImpl.java DefaultHandler.java
LocatorImpl.java NamespaceSupport.java
ParserAdapter.java ParserFactory.java
XMLFilterImpl.java XMLReaderAdapter.java
XMLReaderFactory.java package.html
Log:
Upgrading to sax 2.0.1 (sax2r2) from http://sourceforge.net/projects/sax/ as per Edwin Goei.
Revision Changes Path
1.2 +217 -60 xml-commons/java/external/ChangeLog-sax
Index: ChangeLog-sax
===================================================================
RCS file: /home/cvs/xml-commons/java/external/ChangeLog-sax,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ChangeLog-sax 20 May 2001 03:12:55 -0000 1.1
+++ ChangeLog-sax 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,3 +1,159 @@
+2002-Jan-29 David Brownell <db...@users.sourceforge.net>
+
+ * SAX2 r2 (SAX 2.0.1) release
+
+2002-Jan-12 David Brownell <db...@users.sourceforge.net>
+
+ * Doc clarifications
+ - skippedEntity() within markup constructs isn't done,
+ matching startEntity()/endEntity()
+
+2002-Jan-11 David Brownell <db...@users.sourceforge.net>
+
+ * Doc clarifications
+ - Locator I18N issue for column/line numbers
+ - Locator getSystemId() absolutization examples
+ - SAXParseException relationship to Locator
+
+2002-Jan-10 David Brownell <db...@users.sourceforge.net>
+
+ * Doc clarifications
+ - reword empty string for startPrefixMapping() [501777]
+ - inconsistent parameter naming [501901]
+ - add missing @see in XMLFilterImpl [501915],
+ remove duplicates [501919], fix typo [501927]
+ - mention multi-char character issues in ContentHandler
+ * Mention JDK 1.4 update procedure in README
+
+2001-Dec-04 David Brownell <db...@users.sourceforge.net>
+
+ * Doc clarifications
+ - ContentHandler.skippedEntity() reported once per skip,
+ not once to cover all times it's skipped!
+
+2001-Nov-29 David Brownell <db...@users.sourceforge.net>
+
+ * Doc clarifications
+ - Attributes: remind that namespace decls have no namespace
+ - ContentHandler: empty prefix means default namespace, and
+ startDocument() also precedes extension callbacks
+ - InputStream: with Reader, encoding not necessarily ignored;
+ it might hold Infoset [character encoding scheme]
+
+2001-Nov-20 David Brownell <db...@users.sourceforge.net>
+
+ * SAX2 r2pre3 release
+ - marked files in "sax2r2" branch using @version
+ - javadoc disclaimers point to 'www.saxproject.org'
+ (but 'sax.sourceforge.net' is still hosting SAX)
+
+2001-Nov-12 David Brownell <db...@users.sourceforge.net>
+ * LexicalHandler, DeclHandler
+ - Clarify recognize != support
+ - setProperty() text matches current implementations
+ * LexicalHandler.startDTD()
+ - Clarify systemId: do NOT absolutize this URI
+ (matches current implementations)
+ * Patch (from Edwin Goei) to factory support class
+ - helpers/NewInstance.java (internal) compiles on JDK 1.1
+ * DTDHandler
+ - Revert change from Aug-01, not all implementations agree
+ the spec is wrong. A new "resolve-dtd-entities" feature
+ flag addresses the behavior (extension defined separately)
+ * Locator
+ - Clarify when this object may be used
+
+2001-Nov-05 David Brownell <db...@users.sourceforge.net>
+
+ * XmlReader, XmlFilterImpl, ParserAdapter:
+ - Clarify that SAXNotRecognizedException means the
+ feature/property isn't gettable/settable
+ - Set-to-null isn't an error for handlers. Most parsers
+ (and now XMLFilterImpl, ParserAdapter) treat it as
+ restoring the default setting.
+ - fixed [476507], javadoc param names wrong
+
+2001-Oct-23 David Brownell <db...@users.sourceforge.net>
+
+ * NamespaceSupport now enforces declare-before-use constraint.
+
+2001-Oct-14 David Brownell <db...@users.sourceforge.net>
+
+ * Doc updates:
+ - NamespaceSupport, identifying different usage modes
+ (application vs SAX driver) and minor bugfixes
+ - DeclHandler, attributeDecl() doesn't leave anything
+ unexpanded (or process PEs)
+
+2001-Sep-28 David Brownell <db...@users.sourceforge.net>
+
+ * Fix minor error path bug on ParserAdapter, path[0,1] null
+ * XMLReaderFactory updates
+ - Better robustness by expecting distro-specific fallback
+ - Merge more correct ClassLoader support from Crimson
+ (contributed by Edwin Goei, edwingo@apache.org)
+ - More configurability by META-INF/services support
+ * ParserFactory update for more correct ClassLoader usage
+
+2001-Sep-26 David Brownell <db...@users.sourceforge.net>
+
+ * Removed refs to sax@megginson.com email (by request :)
+ * Doc clarifications
+ - InputSource
+ - NamespaceSupport
+
+2001-Aug-03 David Brownell <db...@users.sourceforge.net>
+
+ * ParserAdapter
+ - process declarations before references
+ - only process "xmlns:foo" and "xmlns", not "xmlnsf:oo"
+ * Doc updates (mostly @see to SAX2 not SAX1) to:
+ - DTDHandler
+ - EntityResolver
+ - ErrorHandler
+
+2001-Aug-01 David Brownell <db...@users.sourceforge.net>
+
+ * AttributesImpl
+ - remove array bounds bug
+ - removeAttribute() frees memory
+ * DTDHandler
+ - clarify relationship with LexicalHandler.endDTD()
+ - notationDecl(), parser doesn't guess whether systemId
+ is a URL or not; matches current implementations.
+ * NamespaceSupport
+ - be explicit about declarations preceding references
+ - clear state on popContext(); less memory usage
+
+2001-July-30 David Brownell <db...@users.sourceforge.net>
+
+ This list includes some changes done earlier, but not added
+ at that time to the ChangeLog. Full details are in CVS in
+ the "sax" project at SourceForge.
+
+ * Re-merged SAX2 "extensions" 1.0 into main distribution,
+ including ChangeLog entries.
+
+ * Doc bugs fixed:
+ - add "package.html" entries
+ - filters.html, typo
+ - DeclHandler, fix omission w.r.t. attribute default value
+ - DefaultHandler, params needed documentation
+ - EntityResolver, clarify
+ - Locator, remove duplication
+ - ParserAdapter, workaround javadoc tool issue
+ - XMLReaderAdapter, exceptions needed documentation
+
+ * Fixed behavioral bugs/problems:
+ - AttributesImpl, clear() frees all memory
+ - ParserAdapter, remove JDK 1.2 dependency
+ - XMLReaderFactory, synch not needed
+
+2000-July David Megginson <da...@megginson.com>
+
+ * Created http://sourceforge.net/projects/sax and
+ imported CVS history
+
2000-12-28 David Megginson <da...@megginson.com>
* SAX2 r2 prerelease
@@ -27,6 +183,37 @@
- specified that getSystemId() returns null when no system ID is
available
+2000-10-04 David Megginson <da...@megginson.com>
+
+ [extensions]
+
+ * RELEASED VERSION 1.0
+
+ * updated version numbers
+
+2000-09-26 David Megginson <da...@megginson.com>
+
+ [extensions]
+
+ * RELEASED VERSION 1.0pre
+
+2000-09-25 David Megginson <da...@megginson.com>
+
+ [extensions]
+
+ * src/org/xml/sax/ext/DeclHandler.java:
+ - doc: bumped version to 1.0pre
+
+ * src/org/xml/sax/ext/LexicalHandler.java:
+ - doc: bumped version to 1.0pre
+ - doc: typo fixed (corrected org.xml.sax.DeclHandler to
+ org.xml.sax.ext.DeclHandler)
+ - doc: explicitly mention order of comment/PI events in
+ DOCTYPE
+ - doc: explicitly mention that comment/PI are not required to
+ appear in correct positions relative to DTDHandler or DeclHandler
+ events.
+
2000-09-12 David Megginson <da...@megginson.com>
* src/org/xml/sax/Attributes.java:
@@ -192,6 +379,18 @@
- minor documentation cleanups
- clarified attribute types and tokenized values
+2000-04-14 David Megginson <da...@megginson.com>
+
+ * RELEASED extensions VERSION 1.0beta
+
+ * src/org/xml/sax/ext/DeclHandler.java:
+ - doc: specified that content models may be normalized
+ - doc: specified that NOTATION attributes also have token group
+ - doc: specified that parameter entities are expanded in content
+ models, attribute value literals, and entity values
+ - doc: specified that general entities are not expanded in
+ attribute value literals and entity values
+
2000-04-10 David Megginson <da...@megginson.com>
* src/org/xml/sax/helpers/NamespaceSupport.java:
@@ -225,6 +424,13 @@
- renamed rawName to qName and rawAtts to qAtts throughout
+2000-03-27 David Megginson <da...@megginson.com>
+
+ * src/org/xml/sax/ext/LexicalHandler.java:
+ - separated from main SAX2 distribution
+ - added documentation to clarify relationship between
+ start/endEntity, start/endDTD, DeclHandler, and DTDHandler
+
2000-03-25 David Megginson <da...@megginson.com>
* src/org/xml/sax/ext/LexicalHandler.java
@@ -237,6 +443,17 @@
- for createXMLReader(), if org.xml.sax.driver is not specified,
try ParserFactory.makeParser() and return it wrapped if successful
+2000-03-25 David Megginson <da...@megginson.com>
+
+ * src/org/xml/sax/ext/LexicalHandler.java:
+ - corrected property name in JavaDoc
+ - added
+ http://xml.org/sax/features/lexical-handler/parameter-entities
+ feature to JavaDoc
+
+ * src/org/xml/sax/ext/DeclHandler.java:
+ - corrected property name in JavaDoc
+
2000-03-24 David Megginson <da...@megginson.com>
- added docs/quick-start.html
@@ -256,64 +473,4 @@
SAX2beta2 RELEASED
-
-====
-SAX2-EXT-1.0\ChangeLog
-2000-10-04 David Megginson <da...@megginson.com>
-
- * RELEASED VERSION 1.0
-
- * updated version numbers
-
-2000-09-26 David Megginson <da...@megginson.com>
-
- * RELEASED VERSION 1.0pre
-
-2000-09-25 David Megginson <da...@megginson.com>
-
- * src/org/xml/sax/ext/DeclHandler.java:
- - doc: bumped version to 1.0pre
-
- * src/org/xml/sax/ext/LexicalHandler.java:
- - doc: bumped version to 1.0pre
- - doc: typo fixed (corrected org.xml.sax.DeclHandler to
- org.xml.sax.ext.DeclHandler)
- - doc: explicitly mention order of comment/PI events in
- DOCTYPE
- - doc: explicitly mention that comment/PI are not required to
- appear in correct positions relative to DTDHandler or DeclHandler
- events.
-
-2000-04-14 David Megginson <da...@megginson.com>
-
- * RELEASED VERSION 1.0beta
-
- * src/org/xml/sax/ext/DeclHandler.java:
- - doc: specified that content models may be normalized
- - doc: specified that NOTATION attributes also have token group
- - doc: specified that parameter entities are expanded in content
- models, attribute value literals, and entity values
- - doc: specified that general entities are not expanded in
- attribute value literals and entity values
-
-2000-03-27 David Megginson <da...@megginson.com>
-
- * src/org/xml/sax/ext/LexicalHandler.java:
- - separated from main SAX2 distribution
- - added documentation to clarify relationship between
- start/endEntity, start/endDTD, DeclHandler, and DTDHandler
-
- * src/org/xml/sax/ext/DeclHandler.java:
- - separated from main SAX2 distribution
-
-2000-03-25 David Megginson <da...@megginson.com>
-
- * src/org/xml/sax/ext/LexicalHandler.java:
- - corrected property name in JavaDoc
- - added
- http://xml.org/sax/features/lexical-handler/parameter-entities
- feature to JavaDoc
-
- * src/org/xml/sax/ext/DeclHandler.java:
- - corrected property name in JavaDoc
1.2 +31 -29 xml-commons/java/external/README-sax
Index: README-sax
===================================================================
RCS file: /home/cvs/xml-commons/java/external/README-sax,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- README-sax 20 May 2001 03:12:55 -0000 1.1
+++ README-sax 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,34 +1,36 @@
-SAX 2.0 r2 prerelease
+SAX 2.0.1 (sax2r2)
+29-January-2002
-This is a prerelease of a bugfix release for SAX2, the second
-generation of the Simple API for XML. For information, see
-docs/index.html.
+This is a bugfix release for SAX2, the second generation of the Simple
+API for XML. Changes from the SAX 2.0 release can be summarized as:
-This release includes a simple test application in src/SAXTest.java.
+ - Numerous documentation improvements and clarifications.
+ - Bundling the optional "SAX2 Extensions 1.0" support.
+ - Bugfixes:
+ * Bugfixed classes include ParserAdapter, AttributesImpl
+ * Factory classes use the correct class loader (JDK 1.2 and later)
+ * Some exceptions were missing default constructors
+ * DefaultHandler was missing an exception spec
+ * Resetting handlers to their default values is legal
+ - Slightly less memory use in NamespaceSupport, AttributesImpl.
+ - Better configurability for the default XMLReader.
+ - NamespaceSupport enforces its declare-before-use constraint
+
+Other than bugfixes, the APIs have not been changed. This is intended to
+be a drop-in replacement for the previous SAX2 release. API-conformant
+code will not notice any differences.
+
+If you are using JDK 1.4, you should be able to copy "sax.jar" into
+the $JAVA_HOME/jre/lib/endorsed directory to have it replace the older
+version of SAX2 that is distributed with that JVM. If you're using
+JRE 1.4, that path won't include the "jre".
+
+For more information, see the current home for SAX on the web:
-A build.xml file is included for users of Apache's ant build tool (a
-Java-based Makefile substitute).
+ http://www.saxproject.org
+As a SourceForge project, SAX now has public CVS access, a database
+for bugs and RFEs, mailing lists, and a web site.
-sax@megginson.com
-
-====
-SAX2-ext 1.0
-
-This module is in the PUBLIC DOMAIN, and comes with NO WARRANTY of any
-kind.
-
-
-This is the 1.0 release of SAX2-ext, an extension package for the
-second generation of the Simple API for XML. Please send comments and
-bug reports to sax@megginson.com before Monday 2 October 2000.
-
-For more information about the package, please see docs/index.html.
-
-A build.xml file is included for the Apache project's "ant" project
-management tool.
-
-
-David Megginson, david@megginson.com
-2000-10-04
-
+- David Brownell
+ dbrownell@users.sourceforge.net
1.2 +6 -4 xml-commons/java/external/src/org/xml/sax/AttributeList.java
Index: AttributeList.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/AttributeList.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- AttributeList.java 20 May 2001 03:12:56 -0000 1.1
+++ AttributeList.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX Attribute List Interface.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: AttributeList.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: AttributeList.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -10,6 +11,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This is the original SAX1 interface for reporting an element's
@@ -61,9 +64,8 @@
* {@link org.xml.sax.Attributes Attributes}
* interface, which includes Namespace support.
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.DocumentHandler#startElement startElement
* @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl
*/
1.2 +16 -7 xml-commons/java/external/src/org/xml/sax/Attributes.java
Index: Attributes.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/Attributes.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Attributes.java 20 May 2001 03:12:56 -0000 1.1
+++ Attributes.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,8 +1,9 @@
// Attributes.java - attribute list with Namespace support
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the public domain.
-// $Id: Attributes.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: Attributes.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -14,6 +15,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This interface allows access to a list of attributes in
@@ -30,7 +33,13 @@
* contain attributes used as Namespace declarations (xmlns*) unless
* the <code>http://xml.org/sax/features/namespace-prefixes</code>
* feature is set to <var>true</var> (it is <var>false</var> by
- * default).</p>
+ * default).
+ * Because SAX2 conforms to the "Namespaces in XML" specification,
+ * it does not give namespace declaration attributes a namespace URI.
+ * Some other W3C specifications are in conflict with that, expecting
+ * these declarations to be in a namespace.
+ * Handler code may need to resolve that conflict.
+ * </p>
*
* <p>If the namespace-prefixes feature (see above) is <var>false</var>,
* access by qualified name may not be available; if the
@@ -47,10 +56,10 @@
* vary from implementation to implementation.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
- * @see org.xml.sax.helpers.AttributeListImpl
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
+ * @see org.xml.sax.helpers.AttributesImpl
+ * @see org.xml.sax.ext.DeclHandler#attributeDecl
*/
public interface Attributes
{
1.2 +50 -16 xml-commons/java/external/src/org/xml/sax/ContentHandler.java
Index: ContentHandler.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/ContentHandler.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ContentHandler.java 20 May 2001 03:12:56 -0000 1.1
+++ ContentHandler.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,8 +1,9 @@
// ContentHandler.java - handle main document content.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the public domain.
-// $Id: ContentHandler.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: ContentHandler.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -13,6 +14,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This is the main interface that most SAX applications
@@ -48,9 +51,8 @@
* bug.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.XMLReader
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.ErrorHandler
@@ -90,8 +92,7 @@
* Receive notification of the beginning of a document.
*
* <p>The SAX parser will invoke this method only once, before any
- * other methods in this interface or in {@link org.xml.sax.DTDHandler
- * DTDHandler} (except for {@link #setDocumentLocator
+ * other event callbacks (except for {@link #setDocumentLocator
* setDocumentLocator}).</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
@@ -136,18 +137,21 @@
* itself, if necessary.</p>
*
* <p>Note that start/endPrefixMapping events are not
- * guaranteed to be properly nested relative to each-other:
- * all startPrefixMapping events will occur before the
+ * guaranteed to be properly nested relative to each other:
+ * all startPrefixMapping events will occur immediately before the
* corresponding {@link #startElement startElement} event,
* and all {@link #endPrefixMapping endPrefixMapping}
- * events will occur after the corresponding {@link #endElement
- * endElement} event, but their order is not otherwise
+ * events will occur immediately after the corresponding
+ * {@link #endElement endElement} event,
+ * but their order is not otherwise
* guaranteed.</p>
*
* <p>There should never be start/endPrefixMapping events for the
* "xml" prefix, since it is predeclared and immutable.</p>
*
* @param prefix The Namespace prefix being declared.
+ * An empty string is used for the default element namespace,
+ * which has no prefix.
* @param uri The Namespace URI the prefix is mapped to.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
@@ -162,12 +166,13 @@
* End the scope of a prefix-URI mapping.
*
* <p>See {@link #startPrefixMapping startPrefixMapping} for
- * details. This event will always occur after the corresponding
- * {@link #endElement endElement} event, but the order of
+ * details. These events will always occur immediately after the
+ * corresponding {@link #endElement endElement} event, but the order of
* {@link #endPrefixMapping endPrefixMapping} events is not otherwise
* guaranteed.</p>
*
* @param prefix The prefix that was being mapping.
+ * This is the empty string when a default mapping scope ends.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
* @see #startPrefixMapping
@@ -220,6 +225,9 @@
* property is true (it is false by default, and support for a
* true value is optional).</p>
*
+ * <p>Like {@link #characters characters()}, attribute values may have
+ * characters that need more than one <code>char</code> value. </p>
+ *
* @param uri The Namespace URI, or the empty string if the
* element has no Namespace URI or if Namespace
* processing is not being performed.
@@ -236,7 +244,7 @@
* @see #endElement
* @see org.xml.sax.Attributes
*/
- public void startElement (String namespaceURI, String localName,
+ public void startElement (String uri, String localName,
String qName, Attributes atts)
throws SAXException;
@@ -262,7 +270,7 @@
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
*/
- public void endElement (String namespaceURI, String localName,
+ public void endElement (String uri, String localName,
String qName)
throws SAXException;
@@ -280,6 +288,23 @@
* <p>The application must not attempt to read from the array
* outside of the specified range.</p>
*
+ * <p>Individual characters may consist of more than one Java
+ * <code>char</code> value. There are two important cases where this
+ * happens, because characters can't be represented in just sixteen bits.
+ * In one case, characters are represented in a <em>Surrogate Pair</em>,
+ * using two special Unicode values. Such characters are in the so-called
+ * "Astral Planes", with a code point above U+FFFF. A second case involves
+ * composite characters, such as a base character combining with one or
+ * more accent characters. </p>
+ *
+ * <p> Your code should not assume that algorithms using
+ * <code>char</code>-at-a-time idioms will be working in character
+ * units; in some cases they will split characters. This is relevant
+ * wherever XML permits arbitrary characters, such as attribute values,
+ * processing instruction data, and comments as well as in data reported
+ * from this method. It's also generally relevant whenever Java code
+ * manipulates internationalized text; the issue isn't unique to XML.</p>
+ *
* <p>Note that some parsers will report whitespace in element
* content using the {@link #ignorableWhitespace ignorableWhitespace}
* method rather than this one (validating parsers <em>must</em>
@@ -336,6 +361,10 @@
* section 2.8) or a text declaration (XML 1.0, section 4.3.1)
* using this method.</p>
*
+ * <p>Like {@link #characters characters()}, processing instruction
+ * data may have characters that need more than one <code>char</code>
+ * value. </p>
+ *
* @param target The processing instruction target.
* @param data The processing instruction data, or null if
* none was supplied. The data does not include any
@@ -349,8 +378,13 @@
/**
* Receive notification of a skipped entity.
+ * This is not called for entity references within markup constructs
+ * such as element start tags or markup declarations. (The XML
+ * recommendation requires reporting skipped external entities.
+ * SAX also reports internal entity expansion/non-expansion, except
+ * within markup constructs.)
*
- * <p>The Parser will invoke this method once for each entity
+ * <p>The Parser will invoke this method each time the entity is
* skipped. Non-validating processors may skip entities if they
* have not seen the declarations (because, for example, the
* entity was declared in an external DTD subset). All processors
1.2 +21 -12 xml-commons/java/external/src/org/xml/sax/DTDHandler.java
Index: DTDHandler.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/DTDHandler.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DTDHandler.java 20 May 2001 03:12:56 -0000 1.1
+++ DTDHandler.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX DTD handler.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: DTDHandler.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: DTDHandler.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -10,6 +11,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>If a SAX application needs information about notations and
@@ -27,7 +30,10 @@
* of the order in which the notations and unparsed entities were
* declared; however, all DTD events must be reported after the
* document handler's startDocument event, and before the first
- * startElement event.</p>
+ * startElement event.
+ * (If the {@link org.xml.sax.ext.LexicalHandler LexicalHandler} is
+ * used, these events must also be reported before the endDTD event.)
+ * </p>
*
* <p>It is up to the application to store the information for
* future use (perhaps in a hash table or object tree).
@@ -37,11 +43,9 @@
* notation corresponding with the attribute value.</p>
*
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
- * @see org.xml.sax.Parser#setDTDHandler
- * @see org.xml.sax.HandlerBase
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
+ * @see org.xml.sax.XMLReader#setDTDHandler
*/
public interface DTDHandler {
@@ -50,7 +54,10 @@
* Receive notification of a notation declaration event.
*
* <p>It is up to the application to record the notation for later
- * reference, if necessary.</p>
+ * reference, if necessary;
+ * notations may appear as attribute values and in unparsed entity
+ * declarations, and are sometime used with processing instruction
+ * target names.</p>
*
* <p>At least one of publicId and systemId must be non-null.
* If a system identifier is present, and it is a URL, the SAX
@@ -68,7 +75,7 @@
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #unparsedEntityDecl
- * @see org.xml.sax.AttributeList
+ * @see org.xml.sax.Attributes
*/
public abstract void notationDecl (String name,
String publicId,
@@ -82,7 +89,9 @@
* <p>Note that the notation name corresponds to a notation
* reported by the {@link #notationDecl notationDecl} event.
* It is up to the application to record the entity for later
- * reference, if necessary.</p>
+ * reference, if necessary;
+ * unparsed entities may appear as attribute values.
+ * </p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before passing it to the application.</p>
@@ -93,9 +102,9 @@
* @param publicId The entity's public identifier, or null if none
* was given.
* @param systemId The entity's system identifier.
- * @param notation name The name of the associated notation.
+ * @param notationName The name of the associated notation.
* @see #notationDecl
- * @see org.xml.sax.AttributeList
+ * @see org.xml.sax.Attributes
*/
public abstract void unparsedEntityDecl (String name,
String publicId,
1.2 +6 -4 xml-commons/java/external/src/org/xml/sax/DocumentHandler.java
Index: DocumentHandler.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/DocumentHandler.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DocumentHandler.java 20 May 2001 03:12:56 -0000 1.1
+++ DocumentHandler.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX document handler.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: DocumentHandler.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: DocumentHandler.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -10,6 +11,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This was the main event-handling interface for SAX1; in
@@ -35,9 +38,8 @@
* {@link org.xml.sax.ContentHandler ContentHandler}
* interface, which includes Namespace support.
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.Parser#setDocumentHandler
* @see org.xml.sax.Locator
* @see org.xml.sax.HandlerBase
1.2 +21 -12 xml-commons/java/external/src/org/xml/sax/EntityResolver.java
Index: EntityResolver.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/EntityResolver.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- EntityResolver.java 20 May 2001 03:12:56 -0000 1.1
+++ EntityResolver.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX entity resolver.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: EntityResolver.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: EntityResolver.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -13,6 +14,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>If a SAX application needs to implement customized handling
@@ -58,10 +61,9 @@
* (possibly by using the public identifier).</p>
*
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
- * @see org.xml.sax.Parser#setEntityResolver
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
+ * @see org.xml.sax.XMLReader#setEntityResolver
* @see org.xml.sax.InputSource
*/
public interface EntityResolver {
@@ -70,19 +72,26 @@
/**
* Allow the application to resolve external entities.
*
- * <p>The Parser will call this method before opening any external
- * entity except the top-level document entity (including the
- * external DTD subset, external entities referenced within the
- * DTD, and external entities referenced within the document
- * element): the application may request that the parser resolve
+ * <p>The parser will call this method before opening any external
+ * entity except the top-level document entity. Such entities include
+ * the external DTD subset and external parameter entities referenced
+ * within the DTD (in either case, only if the parser reads external
+ * parameter entities), and external general entities referenced
+ * within the document element (if the parser reads external general
+ * entities). The application may request that the parser locate
* the entity itself, that it use an alternative URI, or that it
- * use an entirely different input source.</p>
+ * use data provided by the application (as a character or byte
+ * input stream).</p>
*
* <p>Application writers can use this method to redirect external
* system identifiers to secure and/or local URIs, to look up
* public identifiers in a catalogue, or to read an entity from a
* database or other input source (including, for example, a dialog
- * box).</p>
+ * box). Neither XML nor SAX specifies a preferred policy for using
+ * public or system IDs to resolve resources. However, SAX specifies
+ * how to interpret any InputSource returned by this method, and that
+ * if none is returned, then the system ID will be dereferenced as
+ * a URL. </p>
*
* <p>If the system identifier is a URL, the SAX parser must
* resolve it fully before reporting it to the application.</p>
1.2 +7 -5 xml-commons/java/external/src/org/xml/sax/ErrorHandler.java
Index: ErrorHandler.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/ErrorHandler.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ErrorHandler.java 20 May 2001 03:12:56 -0000 1.1
+++ ErrorHandler.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX error handler.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: ErrorHandler.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: ErrorHandler.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -11,6 +12,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>If a SAX application needs to implement customized error
@@ -33,10 +36,9 @@
* could catch an exception and report a fatalError).</p>
*
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
- * @see org.xml.sax.Parser#setErrorHandler
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
+ * @see org.xml.sax.XMLReader#setErrorHandler
* @see org.xml.sax.SAXParseException
*/
public interface ErrorHandler {
1.2 +6 -4 xml-commons/java/external/src/org/xml/sax/HandlerBase.java
Index: HandlerBase.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/HandlerBase.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- HandlerBase.java 20 May 2001 03:12:56 -0000 1.1
+++ HandlerBase.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX default handler base class.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: HandlerBase.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: HandlerBase.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -10,6 +11,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class implements the default behaviour for four SAX1
@@ -32,9 +35,8 @@
* {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
* class.
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.EntityResolver
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.DocumentHandler
1.2 +31 -16 xml-commons/java/external/src/org/xml/sax/InputSource.java
Index: InputSource.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/InputSource.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- InputSource.java 20 May 2001 03:12:56 -0000 1.1
+++ InputSource.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX input source.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: InputSource.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: InputSource.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -13,6 +14,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class allows a SAX application to encapsulate information
@@ -20,28 +23,36 @@
* a public identifier, a system identifier, a byte stream (possibly
* with a specified encoding), and/or a character stream.</p>
*
- * <p>There are two places that the application will deliver this
+ * <p>There are two places that the application can deliver an
* input source to the parser: as the argument to the Parser.parse
* method, or as the return value of the EntityResolver.resolveEntity
* method.</p>
*
* <p>The SAX parser will use the InputSource object to determine how
* to read XML input. If there is a character stream available, the
- * parser will read that stream directly; if not, the parser will use
- * a byte stream, if available; if neither a character stream nor a
+ * parser will read that stream directly, disregarding any text
+ * encoding declaration found in that stream.
+ * If there is no character stream, but there is
+ * a byte stream, the parser will use that byte stream, using the
+ * encoding specified in the InputSource or else (if no encoding is
+ * specified) autodetecting the character encoding using an algorithm
+ * such as the one in the XML specification. If neither a character
+ * stream nor a
* byte stream is available, the parser will attempt to open a URI
* connection to the resource identified by the system
* identifier.</p>
*
* <p>An InputSource object belongs to the application: the SAX parser
* shall never modify it in any way (it may modify a copy if
- * necessary).</p>
+ * necessary). However, standard processing of both byte and
+ * character streams is to close them on as part of end-of-parse cleanup,
+ * so applications should not attempt to re-use such streams after they
+ * have been handed to a parser. </p>
*
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
- * @see org.xml.sax.Parser#parse
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
+ * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
* @see org.xml.sax.EntityResolver#resolveEntity
* @see java.io.InputStream
* @see java.io.Reader
@@ -69,7 +80,8 @@
* public identifier as well, or setEncoding to specify
* the character encoding, if known.</p>
*
- * <p>If the system identifier is a URL, it must be full resolved.</p>
+ * <p>If the system identifier is a URL, it must be fully
+ * resolved (it may not be a relative URL).</p>
*
* @param systemId The system identifier (URI).
* @see #setPublicId
@@ -87,9 +99,9 @@
/**
* Create a new input source with a byte stream.
*
- * <p>Application writers may use setSystemId to provide a base
- * for resolving relative URIs, setPublicId to include a
- * public identifier, and/or setEncoding to specify the object's
+ * <p>Application writers should use setSystemId() to provide a base
+ * for resolving relative URIs, may use setPublicId to include a
+ * public identifier, and may use setEncoding to specify the object's
* character encoding.</p>
*
* @param byteStream The raw byte stream containing the document.
@@ -108,8 +120,8 @@
/**
* Create a new input source with a character stream.
*
- * <p>Application writers may use setSystemId() to provide a base
- * for resolving relative URIs, and setPublicId to include a
+ * <p>Application writers should use setSystemId() to provide a base
+ * for resolving relative URIs, and may use setPublicId to include a
* public identifier.</p>
*
* <p>The character stream shall not include a byte order mark.</p>
@@ -169,7 +181,8 @@
* object pointed to by the system identifier, it can register
* the encoding using the setEncoding method.</p>
*
- * <p>If the system ID is a URL, it must be fully resolved.</p>
+ * <p>If the system identifier is a URL, it must be fully
+ * resolved (it may not be a relative URL).</p>
*
* @param systemId The system identifier as a string.
* @see #setEncoding
@@ -263,6 +276,8 @@
/**
* Get the character encoding for a byte stream or URI.
+ * This value will be ignored when the application provides a
+ * character stream.
*
* @return The encoding, or null if none was supplied.
* @see #setByteStream
1.2 +29 -19 xml-commons/java/external/src/org/xml/sax/Locator.java
Index: Locator.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/Locator.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Locator.java 20 May 2001 03:12:56 -0000 1.1
+++ Locator.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX locator interface for document events.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: Locator.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: Locator.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -11,6 +12,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>If a SAX parser provides location information to the SAX
@@ -18,13 +21,13 @@
* passing an instance to the application using the content
* handler's {@link org.xml.sax.ContentHandler#setDocumentLocator
* setDocumentLocator} method. The application can use the
- * object to obtain the location of any other content handler event
+ * object to obtain the location of any other SAX event
* in the XML source document.</p>
*
* <p>Note that the results returned by the object will be valid only
- * during the scope of each content handler method: the application
+ * during the scope of each callback method: the application
* will receive unpredictable results if it attempts to use the
- * locator at any other time.</p>
+ * locator at any other time, or after parsing completes.</p>
*
* <p>SAX parsers are not required to supply a locator, but they are
* very strongly encouraged to do so. If the parser supplies a
@@ -35,9 +38,8 @@
* available.</p>
*
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.ContentHandler#setDocumentLocator
*/
public interface Locator {
@@ -65,7 +67,9 @@
* triggering the event appears.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
- * fully before passing it to the application.</p>
+ * fully before passing it to the application. For example, a file
+ * name must always be provided as a <em>file:...</em> URL, and other
+ * kinds of relative URI are also resolved against their bases.</p>
*
* @return A string containing the system identifier, or null
* if none is available.
@@ -76,11 +80,16 @@
/**
* Return the line number where the current document event ends.
+ * Lines are delimited by line ends, which are defined in
+ * the XML specification.
*
* <p><strong>Warning:</strong> The return value from the method
- * is intended only as an approximation for the sake of error
- * reporting; it is not intended to provide sufficient information
- * to edit the character content of the original XML document.</p>
+ * is intended only as an approximation for the sake of diagnostics;
+ * it is not intended to provide sufficient information
+ * to edit the character content of the original XML document.
+ * In some cases, these "line" numbers match what would be displayed
+ * as columns, and in others they may not match the source text
+ * due to internal entity expansion. </p>
*
* <p>The return value is an approximation of the line number
* in the document entity or external parsed entity where the
@@ -88,7 +97,7 @@
*
* <p>If possible, the SAX driver should provide the line position
* of the first character after the text associated with the document
- * event. The first line in the document is line 1.</p>
+ * event. The first line is line 1.</p>
*
* @return The line number, or -1 if none is available.
* @see #getColumnNumber
@@ -98,19 +107,20 @@
/**
* Return the column number where the current document event ends.
+ * This is one-based number of Java <code>char</code> values since
+ * the last line end.
*
* <p><strong>Warning:</strong> The return value from the method
- * is intended only as an approximation for the sake of error
- * reporting; it is not intended to provide sufficient information
- * to edit the character content of the original XML document.</p>
+ * is intended only as an approximation for the sake of diagnostics;
+ * it is not intended to provide sufficient information
+ * to edit the character content of the original XML document.
+ * For example, when lines contain combining character sequences, wide
+ * characters, surrogate pairs, or bi-directional text, the value may
+ * not correspond to the column in a text editor's display. </p>
*
* <p>The return value is an approximation of the column number
* in the document entity or external parsed entity where the
* markup triggering the event appears.</p>
- *
- * <p>If possible, the SAX driver should provide the line position
- * of the first character after the text associated with the document
- * event.</p>
*
* <p>If possible, the SAX driver should provide the line position
* of the first character after the text associated with the document
1.2 +6 -4 xml-commons/java/external/src/org/xml/sax/Parser.java
Index: Parser.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/Parser.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- Parser.java 20 May 2001 03:12:56 -0000 1.1
+++ Parser.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX parser interface.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: Parser.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: Parser.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -14,6 +15,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This was the main event supplier interface for SAX1; it has
@@ -37,9 +40,8 @@
* {@link org.xml.sax.XMLReader XMLReader}
* interface, which includes Namespace support.
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.EntityResolver
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.DocumentHandler
1.2 +6 -7 xml-commons/java/external/src/org/xml/sax/SAXException.java
Index: SAXException.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/SAXException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- SAXException.java 20 May 2001 03:12:56 -0000 1.1
+++ SAXException.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX exception class.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: SAXException.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: SAXException.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -10,6 +11,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class can contain basic error or warning information from
@@ -27,9 +30,8 @@
* {@link org.xml.sax.SAXParseException SAXParseException} subclass.</p>
*
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.SAXParseException
*/
public class SAXException extends Exception {
@@ -49,7 +51,6 @@
* Create a new SAXException.
*
* @param message The error or warning message.
- * @see org.xml.sax.Parser#setLocale
*/
public SAXException (String message) {
super(message);
@@ -81,7 +82,6 @@
*
* @param message The detail message.
* @param e The exception to be wrapped in a SAXException.
- * @see org.xml.sax.Parser#setLocale
*/
public SAXException (String message, Exception e)
{
@@ -98,7 +98,6 @@
* the detail message from the embedded exception.</p>
*
* @return The error or warning message.
- * @see org.xml.sax.Parser#setLocale
*/
public String getMessage ()
{
1.2 +7 -5 xml-commons/java/external/src/org/xml/sax/SAXNotRecognizedException.java
Index: SAXNotRecognizedException.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/SAXNotRecognizedException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- SAXNotRecognizedException.java 20 May 2001 03:12:56 -0000 1.1
+++ SAXNotRecognizedException.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,8 +1,9 @@
// SAXNotRecognizedException.java - unrecognized feature or value.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the Public Domain.
-// $Id: SAXNotRecognizedException.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: SAXNotRecognizedException.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -14,6 +15,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>An XMLReader will throw this exception when it finds an
@@ -21,9 +24,8 @@
* extensions may use this class for other, similar purposes.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.SAXNotSupportedException
*/
public class SAXNotRecognizedException extends SAXException
1.2 +7 -5 xml-commons/java/external/src/org/xml/sax/SAXNotSupportedException.java
Index: SAXNotSupportedException.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/SAXNotSupportedException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- SAXNotSupportedException.java 20 May 2001 03:12:56 -0000 1.1
+++ SAXNotSupportedException.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,8 +1,9 @@
// SAXNotSupportedException.java - unsupported feature or value.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the Public Domain.
-// $Id: SAXNotSupportedException.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: SAXNotSupportedException.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -13,6 +14,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>An XMLReader will throw this exception when it recognizes a
@@ -21,9 +24,8 @@
* extensions may use this class for similar purposes.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.SAXNotRecognizedException
*/
public class SAXNotSupportedException extends SAXException
1.2 +21 -15 xml-commons/java/external/src/org/xml/sax/SAXParseException.java
Index: SAXParseException.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/SAXParseException.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- SAXParseException.java 20 May 2001 03:12:56 -0000 1.1
+++ SAXParseException.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,6 +1,7 @@
// SAX exception class.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: SAXParseException.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: SAXParseException.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -10,10 +11,13 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
- * <p>This exception will include information for locating the error
- * in the original XML document. Note that although the application
+ * <p>This exception may include information for locating the error
+ * in the original XML document, as if it came from a {@link Locator}
+ * object. Note that although the application
* will receive a SAXParseException as the argument to the handlers
* in the {@link org.xml.sax.ErrorHandler ErrorHandler} interface,
* the application is not actually required to throw the exception;
@@ -24,9 +28,8 @@
* SAXException}, it inherits the ability to wrap another exception.</p>
*
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.SAXException
* @see org.xml.sax.Locator
* @see org.xml.sax.ErrorHandler
@@ -50,7 +53,6 @@
* @param locator The locator object for the error or warning (may be
* null).
* @see org.xml.sax.Locator
- * @see org.xml.sax.Parser#setLocale
*/
public SAXParseException (String message, Locator locator) {
super(message);
@@ -77,7 +79,6 @@
* null).
* @param e Any exception.
* @see org.xml.sax.Locator
- * @see org.xml.sax.Parser#setLocale
*/
public SAXParseException (String message, Locator locator,
Exception e) {
@@ -96,8 +97,11 @@
*
* <p>This constructor is most useful for parser writers.</p>
*
- * <p>If the system identifier is a URL, the parser must resolve it
- * fully before creating the exception.</p>
+ * <p>All parameters except the message are as if
+ * they were provided by a {@link Locator}. For example, if the
+ * system identifier is a URL (including relative filename), the
+ * caller must resolve it fully before creating the exception.</p>
+ *
*
* @param message The error or warning message.
* @param publicId The public identifer of the entity that generated
@@ -108,7 +112,6 @@
* caused the error or warning.
* @param columnNumber The column number of the end of the text that
* cause the error or warning.
- * @see org.xml.sax.Parser#setLocale
*/
public SAXParseException (String message, String publicId, String systemId,
int lineNumber, int columnNumber)
@@ -125,8 +128,10 @@
* need to wrap an exception that is not a subclass of
* {@link org.xml.sax.SAXException SAXException}.</p>
*
- * <p>If the system identifier is a URL, the parser must resolve it
- * fully before creating the exception.</p>
+ * <p>All parameters except the message and exception are as if
+ * they were provided by a {@link Locator}. For example, if the
+ * system identifier is a URL (including relative filename), the
+ * caller must resolve it fully before creating the exception.</p>
*
* @param message The error or warning message, or null to use
* the message from the embedded exception.
@@ -139,7 +144,6 @@
* @param columnNumber The column number of the end of the text that
* cause the error or warning.
* @param e Another exception to embed in this one.
- * @see org.xml.sax.Parser#setLocale
*/
public SAXParseException (String message, String publicId, String systemId,
int lineNumber, int columnNumber, Exception e)
@@ -185,7 +189,7 @@
/**
* Get the system identifier of the entity where the exception occurred.
*
- * <p>If the system identifier is a URL, it will be resolved
+ * <p>If the system identifier is a URL, it will have been resolved
* fully.</p>
*
* @return A string containing the system identifier, or null
@@ -200,6 +204,8 @@
/**
* The line number of the end of the text where the exception occurred.
+ *
+ * <p>The first line is line 1.</p>
*
* @return An integer representing the line number, or -1
* if none is available.
1.2 +7 -5 xml-commons/java/external/src/org/xml/sax/XMLFilter.java
Index: XMLFilter.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/XMLFilter.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XMLFilter.java 20 May 2001 03:12:56 -0000 1.1
+++ XMLFilter.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,8 +1,9 @@
// XMLFilter.java - filter SAX2 events.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the Public Domain.
-// $Id: XMLFilter.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: XMLFilter.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -14,6 +15,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>An XML filter is like an XML reader, except that it obtains its
@@ -28,9 +31,8 @@
* ErrorHandler} events automatically.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.helpers.XMLFilterImpl
*/
public interface XMLFilter extends XMLReader
1.2 +42 -59 xml-commons/java/external/src/org/xml/sax/XMLReader.java
Index: XMLReader.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/XMLReader.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XMLReader.java 20 May 2001 03:12:56 -0000 1.1
+++ XMLReader.java 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,8 +1,9 @@
// XMLReader.java - read an XML document.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the Public Domain.
-// $Id: XMLReader.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
+// $Id: XMLReader.java,v 1.2 2002/02/27 16:04:17 dims Exp $
package org.xml.sax;
@@ -15,6 +16,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p><strong>Note:</strong> despite its name, this interface does
@@ -36,7 +39,7 @@
* <p>This interface replaces the (now deprecated) SAX 1.0 {@link
* org.xml.sax.Parser Parser} interface. The XMLReader interface
* contains two important enhancements over the old Parser
- * interface:</p>
+ * interface (as well as some minor ones):</p>
*
* <ol>
* <li>it adds a standard way to query and set features and
@@ -49,9 +52,8 @@
* a SAX2 XMLReader and vice-versa.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.XMLFilter
* @see org.xml.sax.helpers.ParserAdapter
* @see org.xml.sax.helpers.XMLReaderAdapter
@@ -66,22 +68,23 @@
/**
- * Look up the value of a feature.
+ * Look up the value of a feature flag.
*
* <p>The feature name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a feature name but
- * to be unable to return its value; this is especially true
- * in the case of an adapter for a SAX1 Parser, which has
- * no way of knowing whether the underlying parser is
- * performing validation or expanding external entities.</p>
+ * temporarily be unable to return its value.
+ * Some feature values may be available only in specific
+ * contexts, such as before, during, or after a parse.
+ * Also, some feature values may not be programmatically accessible.
+ * (In the case of an adapter for SAX1 {@link Parser}, there is no
+ * implementation-independent way to expose whether the underlying
+ * parser is performing validation, expanding external entities,
+ * and so forth.) </p>
*
* <p>All XMLReaders are required to recognize the
* http://xml.org/sax/features/namespaces and the
* http://xml.org/sax/features/namespace-prefixes feature names.</p>
*
- * <p>Some feature values may be available only in specific
- * contexts, such as before, during, or after a parse.</p>
- *
* <p>Typical usage is something like this:</p>
*
* <pre>
@@ -112,9 +115,9 @@
* using names built on their own URIs.</p>
*
* @param name The feature name, which is a fully-qualified URI.
- * @return The current state of the feature (true or false).
- * @exception org.xml.sax.SAXNotRecognizedException When the
- * XMLReader does not recognize the feature name.
+ * @return The current value of the feature (true or false).
+ * @exception org.xml.sax.SAXNotRecognizedException If the feature
+ * value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the feature name but
* cannot determine its value at this time.
@@ -125,27 +128,23 @@
/**
- * Set the state of a feature.
+ * Set the value of a feature flag.
*
* <p>The feature name is any fully-qualified URI. It is
- * possible for an XMLReader to recognize a feature name but
- * to be unable to set its value; this is especially true
- * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser Parser},
- * which has no way of affecting whether the underlying parser is
- * validating, for example.</p>
+ * possible for an XMLReader to expose a feature value but
+ * to be unable to change the current value.
+ * Some feature values may be immutable or mutable only
+ * in specific contexts, such as before, during, or after
+ * a parse.</p>
*
* <p>All XMLReaders are required to support setting
* http://xml.org/sax/features/namespaces to true and
* http://xml.org/sax/features/namespace-prefixes to false.</p>
*
- * <p>Some feature values may be immutable or mutable only
- * in specific contexts, such as before, during, or after
- * a parse.</p>
- *
* @param name The feature name, which is a fully-qualified URI.
- * @param state The requested state of the feature (true or false).
- * @exception org.xml.sax.SAXNotRecognizedException When the
- * XMLReader does not recognize the feature name.
+ * @param value The requested value of the feature (true or false).
+ * @exception org.xml.sax.SAXNotRecognizedException If the feature
+ * value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the feature name but
* cannot set the requested value.
@@ -160,24 +159,21 @@
*
* <p>The property name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a property name but
- * to be unable to return its state; this is especially true
- * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser
- * Parser}.</p>
+ * temporarily be unable to return its value.
+ * Some property values may be available only in specific
+ * contexts, such as before, during, or after a parse.</p>
*
* <p>XMLReaders are not required to recognize any specific
* property names, though an initial core set is documented for
* SAX2.</p>
*
- * <p>Some property values may be available only in specific
- * contexts, such as before, during, or after a parse.</p>
- *
* <p>Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.</p>
*
* @param name The property name, which is a fully-qualified URI.
* @return The current value of the property.
- * @exception org.xml.sax.SAXNotRecognizedException When the
- * XMLReader does not recognize the property name.
+ * @exception org.xml.sax.SAXNotRecognizedException If the property
+ * value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot determine its value at this time.
@@ -192,25 +188,22 @@
*
* <p>The property name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a property name but
- * to be unable to set its value; this is especially true
- * in the case of an adapter for a SAX1 {@link org.xml.sax.Parser
- * Parser}.</p>
+ * to be unable to change the current value.
+ * Some property values may be immutable or mutable only
+ * in specific contexts, such as before, during, or after
+ * a parse.</p>
*
* <p>XMLReaders are not required to recognize setting
- * any specific property names, though a core set is provided with
+ * any specific property names, though a core set is defined by
* SAX2.</p>
*
- * <p>Some property values may be immutable or mutable only
- * in specific contexts, such as before, during, or after
- * a parse.</p>
- *
* <p>This method is also the standard mechanism for setting
* extended handlers.</p>
*
* @param name The property name, which is a fully-qualified URI.
- * @param state The requested value for the property.
- * @exception org.xml.sax.SAXNotRecognizedException When the
- * XMLReader does not recognize the property name.
+ * @param value The requested value for the property.
+ * @exception org.xml.sax.SAXNotRecognizedException If the property
+ * value can't be assigned or retrieved.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot set the requested value.
@@ -236,8 +229,6 @@
* resolver immediately.</p>
*
* @param resolver The entity resolver.
- * @exception java.lang.NullPointerException If the resolver
- * argument is null.
* @see #getEntityResolver
*/
public void setEntityResolver (EntityResolver resolver);
@@ -264,8 +255,6 @@
* handler immediately.</p>
*
* @param handler The DTD handler.
- * @exception java.lang.NullPointerException If the handler
- * argument is null.
* @see #getDTDHandler
*/
public void setDTDHandler (DTDHandler handler);
@@ -293,8 +282,6 @@
* handler immediately.</p>
*
* @param handler The content handler.
- * @exception java.lang.NullPointerException If the handler
- * argument is null.
* @see #getContentHandler
*/
public void setContentHandler (ContentHandler handler);
@@ -324,8 +311,6 @@
* handler immediately.</p>
*
* @param handler The error handler.
- * @exception java.lang.NullPointerException If the handler
- * argument is null.
* @see #getErrorHandler
*/
public void setErrorHandler (ErrorHandler handler);
@@ -411,5 +396,3 @@
throws IOException, SAXException;
}
-
-// end of XMLReader.java
1.2 +162 -21 xml-commons/java/external/src/org/xml/sax/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 20 May 2001 03:12:56 -0000 1.1
+++ package.html 27 Feb 2002 16:04:17 -0000 1.2
@@ -1,23 +1,164 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html><head>
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<title>SAX 2.0 r2 prerelease interfaces</title>
-</head>
-
-<body>
-<h1>SAX 2.0 r2 prerelease interfaces</h1>
-
-<blockquote>
-<p class="copyright">This document is in the <strong>PUBLIC
-DOMAIN</strong> and comes with <strong>NO WARRANTY</strong> of any
-kind.</p>
-</blockquote>
-
-<p>This is a prerelease of a bugfix release for SAX2, the second
-generation of the Simple API for XML. For information, see
-docs/index.html.</p>
+<!-- $Id: package.html,v 1.2 2002/02/27 16:04:17 dims Exp $ -->
-</body>
-</html>
+</head><body>
+
+<p> This package provides the core SAX APIs.
+Some SAX1 APIs are deprecated to encourage integration of
+namespace-awareness into designs of new applications
+and into maintainance of existing infrastructure. </p>
+
+<p>See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+for more information about SAX.</p>
+
+
+<h2> SAX2 Standard Feature Flags </h2>
+
+<p> One of the essential characteristics of SAX2 is that it added
+feature flags which can be used to examine and perhaps modify
+parser modes, in particular modes such as validation.
+Since features are identified by (absolute) URIs, anyone
+can define such features.
+Currently defined standard feature URIs have the prefix
+<code>http://xml.org/sax/features/</code> before an identifier such as
+<code>validation</code>. Turn features on or off using
+<em>setFeature</em>. Those standard identifiers are: </p>
+
+
+<table border="1" cellpadding="3" cellspacing="0" width="100%">
+ <tr align="center" bgcolor="#ccccff">
+ <th>Feature ID</th>
+ <th>Default</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>external-general-entities</td>
+ <td><em>unspecified</em></td>
+ <td> Reports whether this parser processes external
+ general entities; always true if validating</td>
+ </tr>
+
+ <tr>
+ <td>external-parameter-entities</td>
+ <td><em>unspecified</em></td>
+ <td> Reports whether this parser processes external
+ parameter entities; always true if validating</td>
+ </tr>
+
+ <tr>
+ <td>lexical-handler/parameter-entities</td>
+ <td><em>unspecified</em></td>
+ <td> true indicates that the LexicalHandler will report the
+ beginning and end of parameter entities
+ </td>
+ </tr>
+
+ <tr>
+ <td>namespaces</td>
+ <td>true</td>
+ <td> true indicates namespace URIs and unprefixed local names
+ for element and attribute names will be available </td>
+ </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>
+ </tr>
+
+ <tr>
+ <td>string-interning</td>
+ <td><em>unspecified</em></td>
+ <td> true if all XML names (for elements, prefixes, attributes,
+ entities, notations, and local names),
+ as well as Namespace URIs, will have been interned
+ using <em>java.lang.String.intern</em>. This supports fast
+ testing of equality/inequality against string constants.</td>
+ </tr>
+
+ <tr>
+ <td>validation</td>
+ <td><em>unspecified</em></td>
+ <td> controls whether the parser is reporting all validity
+ errors; if true, all external entities will be read. </td>
+ </tr>
+
+</table>
+
+<p> Support for the default values of the
+<em>namespaces</em> and <em>namespace-prefixes</em>
+properties is required.
+</p>
+
+<p> For default values not specified by SAX2,
+each XMLReader implementation specifies its default,
+or may choose not to expose the feature flag.
+Unless otherwise specified here,
+implementations may support changing current values
+of these standard feature flags, but not while parsing.
+</p>
+
+<h2> SAX2 Standard Handler and Property IDs </h2>
+
+<p> For parser interface characteristics that are described
+as objects, a separate namespace is defined. The
+objects in this namespace are again identified by URI, and
+the standard property URIs have the prefix
+<code>http://xml.org/sax/properties/</code> before an identifier such as
+<code>lexical-handler</code> or
+<code>dom-node</code>. Manage those properties using
+<em>setProperty()</em>. Those identifiers are: </p>
+
+<table border="1" cellpadding="3" cellspacing="0" width="100%">
+ <tr align="center" bgcolor="#ccccff">
+ <th>Property ID</th>
+ <th>Description</th>
+ </tr>
+
+ <tr>
+ <td>declaration-handler</td>
+ <td> Used to see most DTD declarations except those treated
+ as lexical ("document element name is ...") or which are
+ mandatory for all SAX parsers (<em>DTDHandler</em>).
+ The Object must implement <a href="ext/DeclHandler.html"
+ ><em>org.xml.sax.ext.DeclHandler</em></a>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>dom-node</td>
+ <td> For "DOM Walker" style parsers, which ignore their
+ <em>parser.parse()</em> parameters, this is used to
+ specify the DOM (sub)tree being walked by the parser.
+ The Object must implement the
+ <em>org.w3c.dom.Node</em> interface.
+ </td>
+ </tr>
+
+ <tr>
+ <td>lexical-handler</td>
+ <td> Used to see some syntax events that are essential in some
+ applications: comments, CDATA delimeters, selected general
+ entity inclusions, and the start and end of the DTD
+ (and declaration of document element name).
+ The Object must implement <a href="ext/LexicalHandler.html"
+ ><em>org.xml.sax.ext.LexicalHandler</em></a>.
+ </td>
+ </tr>
+
+ <tr>
+ <td>xml-string</td>
+ <td> Readable only during a parser callback, this exposes a <b>TBS</b>
+ chunk of characters responsible for the current event. </td>
+ </tr>
+
+</table>
+
+<p> All of these standard properties are optional;
+XMLReader implementations need not support them.
+</p>
+
+</body></html>
1.2 +20 -18 xml-commons/java/external/src/org/xml/sax/ext/DeclHandler.java
Index: DeclHandler.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/ext/DeclHandler.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DeclHandler.java 20 May 2001 03:12:57 -0000 1.1
+++ DeclHandler.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,6 +1,7 @@
// DeclHandler.java - Optional handler for DTD declaration events.
+// http://www.saxproject.org
// Public Domain: no warranty.
-// $Id: DeclHandler.java,v 1.1 2001/05/20 03:12:57 curcuru Exp $
+// $Id: DeclHandler.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.ext;
@@ -13,12 +14,14 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
- * <p>This is an optional extension handler for SAX2 to provide
- * information about DTD declarations in an XML document. XML
- * readers are not required to support this handler, and this
- * handler is not included in the core SAX2 distribution.</p>
+ * <p>This is an optional extension handler for SAX2 to provide more
+ * complete information about DTD declarations in an XML document.
+ * XML readers are not required to recognize this handler, and it
+ * is not part of core-only SAX2 distributions.</p>
*
* <p>Note that data-related DTD declarations (unparsed entities and
* notations) are already reported through the {@link
@@ -31,18 +34,16 @@
*
* <p>To set the DeclHandler for an XML reader, use the
* {@link org.xml.sax.XMLReader#setProperty setProperty} method
- * with the propertyId "http://xml.org/sax/properties/declaration-handler".
- * If the reader does not support declaration events, it will throw a
+ * with the property name
+ * <code>http://xml.org/sax/properties/declaration-handler</code>
+ * and an object implementing this interface (or null) as the value.
+ * If the reader does not report declaration events, it will throw a
* {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
- * or a
- * {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException}
* when you attempt to register the handler.</p>
*
- * @since 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 1.0
- * @see org.xml.sax.XMLReader
+ * @since SAX 2.0 (extensions 1.0)
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
*/
public interface DeclHandler
{
@@ -78,13 +79,14 @@
* "NOTATION" followed by a space followed by a parenthesized
* token group with all whitespace removed.</p>
*
- * <p>Any parameter entities in the attribute value will be
- * expanded, but general entities will not.</p>
+ * <p>The value will be the value as reported to applications,
+ * appropriately normalized and with entity and character
+ * references expanded. </p>
*
* @param eName The name of the associated element.
* @param aName The name of the attribute.
* @param type A string representing the attribute type.
- * @param valueDefault A string representing the attribute default
+ * @param mode A string representing the attribute defaulting mode
* ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if
* none of these applies.
* @param value A string representing the attribute's default value,
@@ -94,7 +96,7 @@
public abstract void attributeDecl (String eName,
String aName,
String type,
- String valueDefault,
+ String mode,
String value)
throws SAXException;
1.2 +17 -16 xml-commons/java/external/src/org/xml/sax/ext/LexicalHandler.java
Index: LexicalHandler.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/ext/LexicalHandler.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LexicalHandler.java 20 May 2001 03:12:57 -0000 1.1
+++ LexicalHandler.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,6 +1,7 @@
// LexicalHandler.java - optional handler for lexical parse events.
+// http://www.saxproject.org
// Public Domain: no warranty.
-// $Id: LexicalHandler.java,v 1.1 2001/05/20 03:12:57 curcuru Exp $
+// $Id: LexicalHandler.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.ext;
@@ -12,13 +13,15 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This is an optional extension handler for SAX2 to provide
* lexical information about an XML document, such as comments
- * and CDATA section boundaries; XML readers are not required to
- * support this handler, and it is not part of the core SAX2
- * distribution.</p>
+ * and CDATA section boundaries.
+ * XML readers are not required to recognize this handler, and it
+ * is not part of core-only SAX2 distributions.</p>
*
* <p>The events in the lexical handler apply to the entire document,
* not just to the document element, and all lexical handler events
@@ -27,20 +30,16 @@
*
* <p>To set the LexicalHandler for an XML reader, use the
* {@link org.xml.sax.XMLReader#setProperty setProperty} method
- * with the propertyId "http://xml.org/sax/properties/lexical-handler".
- * If the reader does not support lexical events, it will throw a
+ * with the property name
+ * <code>http://xml.org/sax/properties/lexical-handler</code>
+ * and an object implementing this interface (or null) as the value.
+ * If the reader does not report lexical events, it will throw a
* {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
- * or a
- * {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException}
* when you attempt to register the handler.</p>
*
- * @since 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 1.0
- * @see org.xml.sax.XMLReader#setProperty
- * @see org.xml.sax.SAXNotRecognizedException
- * @see org.xml.sax.SAXNotSupportedException
+ * @since SAX 2.0 (extensions 1.0)
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
*/
public interface LexicalHandler
{
@@ -76,6 +75,8 @@
* external DTD subset, or null if none was declared.
* @param systemId The declared system identifier for the
* external DTD subset, or null if none was declared.
+ * (Note that this is not resolved against the document
+ * base URI.)
* @exception SAXException The application may raise an
* exception.
* @see #endDTD
@@ -105,7 +106,7 @@
*
* <p>The reporting of parameter entities (including
* the external DTD subset) is optional, and SAX2 drivers that
- * support LexicalHandler may not support it; you can use the
+ * report LexicalHandler events may not implement it; you can use the
* <code
* >http://xml.org/sax/features/lexical-handler/parameter-entities</code>
* feature to query or control the reporting of parameter entities.</p>
1.2 +29 -94 xml-commons/java/external/src/org/xml/sax/ext/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/ext/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 20 May 2001 03:12:57 -0000 1.1
+++ package.html 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,114 +1,49 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML><HEAD>
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<title>SAX2-ext: SAX2 Extension Handlers 1.0</title>
-</head>
-
-<body>
-<h1>SAX2-ext: SAX2 Extension Handlers 1.0</h1>
-
-<blockquote>
-<p class="copyright">This document is in the <strong>PUBLIC
-DOMAIN</strong> and comes with <strong>NO WARRANTY</strong> of any
-kind.</p>
-</blockquote>
-
-<p>This package, SAX2-ext, is an extension package for SAX2. It is
-designed both to allow SAX drivers to pass certain types of none-core
-information to applications and to serve as a simple model for other
-SAX2 extension packages.</p>
+</HEAD><BODY>
-<p><strong>NOTE:</strong> this package alone does add any
-functionality; it simply provides optional interfaces for SAX2 drivers
-to use. You must find a SAX2 driver that supports these interfaces if
-you actually want to have access to lexical and declaration
-information.</p>
-
-<p>The SAX2-ext package currently contains two extension handlers for
-SAX2:</p>
-
-<ol>
+<p>
+This package contains interfaces to optional SAX2 handlers.
-<li><a href="javadoc/org/xml/sax/ext/LexicalHandler.html"
->LexicalHandler</a>, which reports comments, the DOCTYPE declaration,
-CDATA sections, and (some) entity boundaries; and</li>
+<p>See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+for more information about SAX.</p>
-<li><a href="javadoc/org/xml/sax/ext/DeclHandler.html"
->DeclHandler</a>, which reports element, attribute, and entity
-declarations.</li>
-
-</ol>
-
-<p>This package is independent of the SAX2 core, and that independence
-has several consequences:</p>
+<p>
+The package is independent of the SAX2 core, though the functionality
+exposed generally needs to be implemented within a parser.
+That independence has several consequences:</p>
<ul>
-<li>SAX2 drivers are <em>not</em> required to support these handlers,
-and you cannot assume that the classes will be present in every SAX2
+<li>SAX2 drivers are <em>not</em> required to recognize these handlers,
+and you cannot assume that the class files will be present in every SAX2
installation.</li>
<li>This package may be updated independently of SAX2 (i.e. new
handlers may be added without updating SAX2 itself).</li>
-<li>The handlers are not supported explicitly by the SAX2
-<var>XMLFilter</var> interface (i.e. events are not passed on by
-default); you can subclass XMLFilter if you need such behaviour.</li>
+<li>The handlers are not implemented by the SAX2
+<code>org.xml.sax.helpers.DefaultHandler</code> or
+<code>org.xml.sax.helpers.XMLFilterImpl</code> classes.
+You can subclass these if you need such behaviour.</li>
<li>The handlers need to be registered differently than regular SAX2
handlers.</li>
</ul>
-<p>To set a LexicalHandler, for example, you need to do something like
-this:</p>
-
-<blockquote><pre xml:space="preserve">
-LexicalHandler lh = new MyLexicalHandler();
-try {
- xmlReader.setProperty("http://xml.org/sax/properties/lexical-handler",
- lh);
-} catch (SAXException e) {
- System.out.println("LexicalHandler not supported by this SAX2 driver.");
-}
-</pre></blockquote>
-
-
-<div>
-<h2>SAX2-ext Properties</h2>
-
-<p>Here is a full definition of the two new SAX2 properties introduced
-in this version of SAX2-ext:</p>
+<p>This package, SAX2-ext, is a standardized extension to SAX2. It is
+designed both to allow SAX parsers to pass certain types of information
+to applications, and to serve as a simple model for other SAX2 parser
+extension packages. Not all such extension packages should need to
+be recognized directly by parsers, however.
+As an example, most schema systems can be cleanly layered on top
+of parsers supporting the standardized SAX2 interfaces. </p>
-<dl>
-
-<dt><code>http://xml.org/sax/properties/lexical-handler</code></dt>
-<dd><strong>data type:</strong>
-<code>org.xml.sax.ext.LexicalHandler</code></dd>
-<dd><strong>description:</strong> An optional extension handler for
-lexical events like comments.</dd>
-<dd><strong>access:</strong> read/write</dd>
-
-<dt><code>http://xml.org/sax/properties/declaration-handler</code></dt>
-<dd><strong>data type:</strong>
-<code>org.xml.sax.ext.DeclHandler</code></dd>
-<dd><strong>description:</strong> An optional extension handler for
-DTD-related events other than notations and unparsed entities.</dd>
-<dd><strong>access:</strong> read/write</dd>
-
-</dl>
-
-<p><strong>See also:</strong> the package's <a
-href="javadoc/index.html">JavaDoc</a> documentation.</p>
-
-<!-- end of "SAX2-ext Properties" -->
-</div>
-
-<hr />
-
-<address>$Id: package.html,v 1.1 2001/05/20 03:12:57 curcuru Exp $</address>
+<p><strong>NOTE:</strong> this package alone does add any
+functionality; it simply provides optional interfaces for SAX2 drivers
+to use. You must use a SAX2 driver that recognizes these interfaces if
+you actually want to have access to lexical and declaration
+information.</p>
-</body>
-</html>
+</BODY></HTML>
1.2 +6 -4 xml-commons/java/external/src/org/xml/sax/helpers/AttributeListImpl.java
Index: AttributeListImpl.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/AttributeListImpl.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- AttributeListImpl.java 20 May 2001 03:12:58 -0000 1.1
+++ AttributeListImpl.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,6 +1,7 @@
// SAX default implementation for AttributeList.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: AttributeListImpl.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
+// $Id: AttributeListImpl.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -15,6 +16,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>AttributeList implements the deprecated SAX1 {@link
@@ -55,9 +58,8 @@
* {@link org.xml.sax.helpers.AttributesImpl
* AttributesImpl} helper class.
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.AttributeList
* @see org.xml.sax.DocumentHandler#startElement
*/
1.3 +19 -12 xml-commons/java/external/src/org/xml/sax/helpers/AttributesImpl.java
Index: AttributesImpl.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/AttributesImpl.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- AttributesImpl.java 31 May 2001 18:08:19 -0000 1.2
+++ AttributesImpl.java 27 Feb 2002 16:04:18 -0000 1.3
@@ -1,8 +1,9 @@
// AttributesImpl.java - default implementation of Attributes.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the public domain.
-// $Id: AttributesImpl.java,v 1.2 2001/05/31 18:08:19 garyp Exp $
+// $Id: AttributesImpl.java,v 1.3 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -16,6 +17,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class provides a default implementation of the SAX2
@@ -39,9 +42,8 @@
* implementation using a single array rather than a set of Vectors.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
*/
public class AttributesImpl implements Attributes
{
@@ -320,12 +322,16 @@
/**
* Clear the attribute list for reuse.
*
- * <p>Note that no memory is actually freed by this call:
- * the current arrays are kept so that they can be
+ * <p>Note that little memory is freed by this call:
+ * the current array is kept so it can be
* reused.</p>
*/
public void clear ()
{
+ if (data != null) {
+ for (int i = 0; i < (length * 5); i++)
+ data [i] = null;
+ }
length = 0;
}
@@ -432,15 +438,16 @@
public void removeAttribute (int index)
{
if (index >= 0 && index < length) {
- data[index*5] = null;
- data[index*5+1] = null;
- data[index*5+2] = null;
- data[index*5+3] = null;
- data[index*5+4] = null;
if (index < length - 1) {
System.arraycopy(data, (index+1)*5, data, index*5,
(length-index-1)*5);
}
+ index = (length - 1) * 5;
+ data [index++] = null;
+ data [index++] = null;
+ data [index++] = null;
+ data [index++] = null;
+ data [index] = null;
length--;
} else {
badIndex(index);
1.2 +26 -9 xml-commons/java/external/src/org/xml/sax/helpers/DefaultHandler.java
Index: DefaultHandler.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/DefaultHandler.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- DefaultHandler.java 20 May 2001 03:12:58 -0000 1.1
+++ DefaultHandler.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,8 +1,9 @@
// DefaultHandler.java - default implementation of the core handlers.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the public domain.
-// $Id: DefaultHandler.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
+// $Id: DefaultHandler.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -25,6 +26,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class is available as a convenience base class for SAX2
@@ -47,9 +50,8 @@
* {@link org.xml.sax.HandlerBase HandlerBase} class.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson,
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.EntityResolver
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.ContentHandler
@@ -252,8 +254,17 @@
* each element (such as allocating a new tree node or writing
* output to a file).</p>
*
- * @param name The element type name.
- * @param attributes The specified or defaulted attributes.
+ * @param uri The Namespace URI, or the empty string if the
+ * element has no Namespace URI or if Namespace
+ * processing is not being performed.
+ * @param localName The local name (without prefix), or the
+ * empty string if Namespace processing is not being
+ * performed.
+ * @param qName The qualified name (with prefix), or the
+ * empty string if qualified names are not available.
+ * @param atts The attributes attached to the element. If
+ * there are no attributes, it shall be an empty
+ * Attributes object.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#startElement
@@ -274,8 +285,14 @@
* each element (such as finalising a tree node or writing
* output to a file).</p>
*
- * @param name The element type name.
- * @param attributes The specified or defaulted attributes.
+ * @param uri The Namespace URI, or the empty string if the
+ * element has no Namespace URI or if Namespace
+ * processing is not being performed.
+ * @param localName The local name (without prefix), or the
+ * empty string if Namespace processing is not being
+ * performed.
+ * @param qName The qualified 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.
* @see org.xml.sax.ContentHandler#endElement
1.2 +6 -4 xml-commons/java/external/src/org/xml/sax/helpers/LocatorImpl.java
Index: LocatorImpl.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/LocatorImpl.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- LocatorImpl.java 20 May 2001 03:12:58 -0000 1.1
+++ LocatorImpl.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,6 +1,7 @@
// SAX default implementation for Locator.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: LocatorImpl.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
+// $Id: LocatorImpl.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -13,6 +14,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class is available mainly for application writers, who
@@ -42,9 +45,8 @@
* requested, rather than constantly updating a Locator object.</p>
*
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.Locator Locator
*/
public class LocatorImpl implements Locator
1.2 +121 -40 xml-commons/java/external/src/org/xml/sax/helpers/NamespaceSupport.java
Index: NamespaceSupport.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/NamespaceSupport.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- NamespaceSupport.java 20 May 2001 03:12:58 -0000 1.1
+++ NamespaceSupport.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,8 +1,9 @@
// NamespaceSupport.java - generic Namespace support for SAX.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// This class is in the Public Domain. NO WARRANTY!
-// $Id: NamespaceSupport.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
+// $Id: NamespaceSupport.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -13,11 +14,14 @@
/**
- * Encapsulate Namespace logic for use by SAX drivers.
+ * Encapsulate Namespace logic for use by applications using SAX,
+ * or internally by SAX drivers.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class encapsulates the logic of Namespace processing:
@@ -39,16 +43,16 @@
* support.declarePrefix("", "http://www.w3.org/1999/xhtml");
* support.declarePrefix("dc", "http://www.purl.org/dc#");
*
- * String parts[] = support.processName("p", parts, false);
+ * parts = support.processName("p", parts, false);
* System.out.println("Namespace URI: " + parts[0]);
* System.out.println("Local name: " + parts[1]);
* System.out.println("Raw name: " + parts[2]);
-
- * String parts[] = support.processName("dc:title", parts, false);
+ *
+ * parts = support.processName("dc:title", parts, false);
* System.out.println("Namespace URI: " + parts[0]);
* System.out.println("Local name: " + parts[1]);
* System.out.println("Raw name: " + parts[2]);
-
+ *
* support.popContext();
* </pre>
*
@@ -57,10 +61,14 @@
* prefix/URI mapping is repeated for each context (for example), this
* class will be somewhat less efficient.</p>
*
+ * <p>Although SAX drivers (parsers) may choose to use this class to
+ * implement namespace handling, they are not required to do so.
+ * Applications must track namespace information themselves if they
+ * want to use namespace information.
+ *
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
*/
public class NamespaceSupport
{
@@ -72,7 +80,9 @@
/**
- * The XML Namespace as a constant.
+ * The XML Namespace URI as a constant.
+ * The value is <code>http://www.w3.org/XML/1998/namespace</code>
+ * as defined in the XML Namespaces specification.
*
* <p>This is the Namespace URI that is automatically mapped
* to the "xml" prefix.</p>
@@ -125,21 +135,45 @@
/**
* Start a new Namespace context.
- *
- * <p>Normally, you should push a new context at the beginning
- * of each XML element: the new context will automatically inherit
+ * The new context will automatically inherit
* the declarations of its parent context, but it will also keep
- * track of which declarations were made within this context.</p>
+ * track of which declarations were made within this context.
+ *
+ * <p>Event callback code should start a new context once per element.
+ * This means being ready to call this in either of two places.
+ * For elements that don't include namespace declarations, the
+ * <em>ContentHandler.startElement()</em> callback is the right place.
+ * For elements with such a declaration, it'd done in the first
+ * <em>ContentHandler.startPrefixMapping()</em> callback.
+ * A boolean flag can be used to
+ * track whether a context has been started yet. When either of
+ * those methods is called, it checks the flag to see if a new context
+ * needs to be started. If so, it starts the context and sets the
+ * flag. After <em>ContentHandler.startElement()</em>
+ * does that, it always clears the flag.
+ *
+ * <p>Normally, SAX drivers would push a new context at the beginning
+ * of each XML element. Then they perform a first pass over the
+ * attributes to process all namespace declarations, making
+ * <em>ContentHandler.startPrefixMapping()</em> callbacks.
+ * Then a second pass is made, to determine the namespace-qualified
+ * names for all attributes and for the element name.
+ * Finally all the information for the
+ * <em>ContentHandler.startElement()</em> callback is available,
+ * so it can then be made.
*
* <p>The Namespace support object always starts with a base context
* already in force: in this context, only the "xml" prefix is
* declared.</p>
*
+ * @see org.xml.sax.ContentHandler
* @see #popContext
*/
public void pushContext ()
{
int max = contexts.length;
+
+ contexts [contextPos].declsOK = false;
contextPos++;
// Extend the array if necessary
@@ -178,6 +212,7 @@
*/
public void popContext ()
{
+ contexts[contextPos].clear();
contextPos--;
if (contextPos < 0) {
throw new EmptyStackException();
@@ -193,29 +228,42 @@
/**
- * Declare a Namespace prefix.
+ * Declare a Namespace prefix. All prefixes must be declared
+ * before they are referenced. For example, a SAX driver (parser)
+ * would scan an element's attributes
+ * in two passes: first for namespace declarations,
+ * then a second pass using {@link #processName processName()} to
+ * interpret prefixes against (potentially redefined) prefixes.
*
* <p>This method declares a prefix in the current Namespace
* context; the prefix will remain in force until this context
* is popped, unless it is shadowed in a descendant context.</p>
*
- * <p>To declare a default Namespace, use the empty string. The
- * prefix must not be "xml" or "xmlns".</p>
+ * <p>To declare the default element Namespace, use the empty string as
+ * the prefix.</p>
*
* <p>Note that you must <em>not</em> declare a prefix after
- * you've pushed and popped another Namespace.</p>
- *
- * <p>Note that there is an asymmetry in this library: while {@link
- * #getPrefix getPrefix} will not return the default "" prefix,
- * even if you have declared one; to check for a default prefix,
+ * you've pushed and popped another Namespace context, or
+ * treated the declarations phase as complete by processing
+ * a prefixed name.</p>
+ *
+ * <p>Note that there is an asymmetry in this library: {@link
+ * #getPrefix getPrefix} will not return the "" prefix,
+ * even if you have declared a default element namespace.
+ * To check for a default namespace,
* you have to look it up explicitly using {@link #getURI getURI}.
* This asymmetry exists to make it easier to look up prefixes
* for attribute names, where the default prefix is not allowed.</p>
*
- * @param prefix The prefix to declare, or null for the empty
- * string.
+ * @param prefix The prefix to declare, or the empty string to
+ * indicate the default element namespace. This may never have
+ * the value "xml" or "xmlns".
* @param uri The Namespace URI to associate with the prefix.
* @return true if the prefix was legal, false otherwise
+ * @exception IllegalStateException when a prefix is declared
+ * after looking up a name in the context, or after pushing
+ * another context on top of it.
+ *
* @see #processName
* @see #getURI
* @see #getPrefix
@@ -232,7 +280,8 @@
/**
- * Process a raw XML 1.0 name.
+ * 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
@@ -255,7 +304,7 @@
*
* <p>Note that attribute names are processed differently than
* element names: an unprefixed element name will received the
- * default Namespace (if any), while an unprefixed element name
+ * default Namespace (if any), while an unprefixed attribute name
* will not.</p>
*
* @param qName The raw XML 1.0 name to be processed.
@@ -419,9 +468,14 @@
/**
* Internal class for a single Namespace context.
*
- * <p>This module caches and reuses Namespace contexts, so the number allocated
+ * <p>This module caches and reuses Namespace contexts,
+ * so the number allocated
* will be equal to the element depth of the document, not to the total
- * number of elements (i.e. 5-10 rather than tens of thousands).</p>
+ * number of elements (i.e. 5-10 rather than tens of thousands).
+ * Also, data structures used to represent contexts are shared when
+ * possible (child contexts without declarations) to further reduce
+ * the amount of memory that's consumed.
+ * </p>
*/
final class Context {
@@ -436,6 +490,8 @@
/**
* (Re)set the parent of this Namespace context.
+ * The context must either have been freshly constructed,
+ * or must have been cleared.
*
* @param context The parent Namespace context object.
*/
@@ -448,7 +504,24 @@
elementNameTable = parent.elementNameTable;
attributeNameTable = parent.attributeNameTable;
defaultNS = parent.defaultNS;
- tablesDirty = false;
+ declSeen = false;
+ declsOK = true;
+ }
+
+ /**
+ * Makes associated state become collectible,
+ * invalidating this context.
+ * {@link #setParent} must be called before
+ * this context may be used again.
+ */
+ void clear ()
+ {
+ parent = null;
+ prefixTable = null;
+ uriTable = null;
+ elementNameTable = null;
+ attributeNameTable = null;
+ defaultNS = null;
}
@@ -462,7 +535,10 @@
void declarePrefix (String prefix, String uri)
{
// Lazy processing...
- if (!tablesDirty) {
+ if (!declsOK)
+ throw new IllegalStateException (
+ "can't declare any more prefixes in this context");
+ if (!declSeen) {
copyTables();
}
if (declarations == null) {
@@ -501,11 +577,14 @@
String name[];
Hashtable table;
+ // detect errors in call sequence
+ declsOK = false;
+
// Select the appropriate table.
if (isAttribute) {
- table = elementNameTable;
- } else {
table = attributeNameTable;
+ } else {
+ table = elementNameTable;
}
// Start by looking in the cache, and
@@ -517,8 +596,11 @@
}
// We haven't seen this name in this
- // context before.
+ // context before. Maybe in the parent
+ // context, but we can't assume prefix
+ // bindings are the same.
name = new String[3];
+ name[2] = qName.intern();
int index = qName.indexOf(':');
@@ -529,8 +611,7 @@
} else {
name[0] = defaultNS;
}
- name[1] = qName.intern();
- name[2] = name[1];
+ name[1] = name[2];
}
// Prefix
@@ -548,12 +629,11 @@
}
name[0] = uri;
name[1] = local.intern();
- name[2] = qName.intern();
}
// Save in the cache for future use.
+ // (Could be shared with parent context...)
table.put(name[2], name);
- tablesDirty = true;
return name;
}
@@ -659,7 +739,7 @@
}
elementNameTable = new Hashtable();
attributeNameTable = new Hashtable();
- tablesDirty = true;
+ declSeen = true;
}
@@ -673,6 +753,7 @@
Hashtable elementNameTable;
Hashtable attributeNameTable;
String defaultNS = null;
+ boolean declsOK = true;
@@ -681,7 +762,7 @@
////////////////////////////////////////////////////////////////
private Vector declarations = null;
- private boolean tablesDirty = false;
+ private boolean declSeen = false;
private Context parent = null;
}
}
1.3 +120 -129 xml-commons/java/external/src/org/xml/sax/helpers/ParserAdapter.java
Index: ParserAdapter.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/ParserAdapter.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ParserAdapter.java 19 Oct 2001 20:30:38 -0000 1.2
+++ ParserAdapter.java 27 Feb 2002 16:04:18 -0000 1.3
@@ -1,8 +1,9 @@
// ParserAdapter.java - adapt a SAX1 Parser to a SAX2 XMLReader.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the public domain.
-// $Id: ParserAdapter.java,v 1.2 2001/10/19 20:30:38 jkesselm Exp $
+// $Id: ParserAdapter.java,v 1.3 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -34,6 +35,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class wraps a SAX1 {@link org.xml.sax.Parser Parser}
@@ -46,9 +49,8 @@
* attribute names.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.helpers.XMLReaderAdapter
* @see org.xml.sax.XMLReader
* @see org.xml.sax.Parser
@@ -68,7 +70,7 @@
* <p>Use the "org.xml.sax.parser" property to locate the
* embedded SAX1 driver.</p>
*
- * @exception org.xml.sax.SAXException If the embedded driver
+ * @exception SAXException If the embedded driver
* cannot be instantiated or if the
* org.xml.sax.parser property is not specified.
*/
@@ -157,46 +159,37 @@
private final static String FEATURES = "http://xml.org/sax/features/";
private final static String NAMESPACES = FEATURES + "namespaces";
private final static String NAMESPACE_PREFIXES = FEATURES + "namespace-prefixes";
- private final static String VALIDATION = FEATURES + "validation";
- private final static String EXTERNAL_GENERAL =
- FEATURES + "external-general-entities";
- private final static String EXTERNAL_PARAMETER =
- FEATURES + "external-parameter-entities";
/**
- * Set a feature for the parser.
+ * Set a feature flag for the parser.
*
- * <p>The only features supported are namespaces and
+ * <p>The only features recognized are namespaces and
* namespace-prefixes.</p>
*
* @param name The feature name, as a complete URI.
- * @param state The requested feature state.
- * @exception org.xml.sax.SAXNotRecognizedException If the feature
- * name is not known.
- * @exception org.xml.sax.SAXNotSupportedException If the feature
- * state is not supported.
+ * @param value The requested feature value.
+ * @exception SAXNotRecognizedException If the feature
+ * can't be assigned or retrieved.
+ * @exception SAXNotSupportedException If the feature
+ * can't be assigned that value.
* @see org.xml.sax.XMLReader#setFeature
*/
- public void setFeature (String name, boolean state)
+ public void setFeature (String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException
{
if (name.equals(NAMESPACES)) {
checkNotParsing("feature", name);
- namespaces = state;
+ namespaces = value;
if (!namespaces && !prefixes) {
prefixes = true;
}
} else if (name.equals(NAMESPACE_PREFIXES)) {
checkNotParsing("feature", name);
- prefixes = state;
+ prefixes = value;
if (!prefixes && !namespaces) {
namespaces = true;
}
- } else if (name.equals(VALIDATION) ||
- name.equals(EXTERNAL_GENERAL) ||
- name.equals(EXTERNAL_PARAMETER)) {
- throw new SAXNotSupportedException("Feature: " + name);
} else {
throw new SAXNotRecognizedException("Feature: " + name);
}
@@ -204,17 +197,17 @@
/**
- * Check a parser feature.
+ * Check a parser feature flag.
*
- * <p>The only features supported are namespaces and
+ * <p>The only features recognized are namespaces and
* namespace-prefixes.</p>
*
* @param name The feature name, as a complete URI.
- * @return The current feature state.
- * @exception org.xml.sax.SAXNotRecognizedException If the feature
- * name is not known.
- * @exception org.xml.sax.SAXNotSupportedException If querying the
- * feature state is not supported.
+ * @return The current feature value.
+ * @exception SAXNotRecognizedException If the feature
+ * value can't be assigned or retrieved.
+ * @exception SAXNotSupportedException If the
+ * feature is not currently readable.
* @see org.xml.sax.XMLReader#setFeature
*/
public boolean getFeature (String name)
@@ -224,10 +217,6 @@
return namespaces;
} else if (name.equals(NAMESPACE_PREFIXES)) {
return prefixes;
- } else if (name.equals(VALIDATION) ||
- name.equals(EXTERNAL_GENERAL) ||
- name.equals(EXTERNAL_PARAMETER)) {
- throw new SAXNotSupportedException("Feature: " + name);
} else {
throw new SAXNotRecognizedException("Feature: " + name);
}
@@ -237,14 +226,14 @@
/**
* Set a parser property.
*
- * <p>No special properties are currently supported.</p>
+ * <p>No properties are currently recognized.</p>
*
* @param name The property name.
* @param value The property value.
- * @exception org.xml.sax.SAXNotRecognizedException If the feature
- * name is not known.
- * @exception org.xml.sax.SAXNotSupportedException If the feature
- * state is not supported.
+ * @exception SAXNotRecognizedException If the property
+ * value can't be assigned or retrieved.
+ * @exception SAXNotSupportedException If the property
+ * can't be assigned that value.
* @see org.xml.sax.XMLReader#setProperty
*/
public void setProperty (String name, Object value)
@@ -257,14 +246,14 @@
/**
* Get a parser property.
*
- * <p>No special properties are currently supported.</p>
+ * <p>No properties are currently recognized.</p>
*
* @param name The property name.
* @return The property value.
- * @exception org.xml.sax.SAXNotRecognizedException If the feature
- * name is not known.
- * @exception org.xml.sax.SAXNotSupportedException If the feature
- * state is not supported.
+ * @exception SAXNotRecognizedException If the property
+ * value can't be assigned or retrieved.
+ * @exception SAXNotSupportedException If the property
+ * value is not currently readable.
* @see org.xml.sax.XMLReader#getProperty
*/
public Object getProperty (String name)
@@ -278,15 +267,10 @@
* Set the entity resolver.
*
* @param resolver The new entity resolver.
- * @exception java.lang.NullPointerException If the entity resolver
- * parameter is null.
* @see org.xml.sax.XMLReader#setEntityResolver
*/
public void setEntityResolver (EntityResolver resolver)
{
- if (resolver == null) {
- throw new NullPointerException("Null entity resolver");
- }
entityResolver = resolver;
}
@@ -307,15 +291,10 @@
* Set the DTD handler.
*
* @param resolver The new DTD handler.
- * @exception java.lang.NullPointerException If the DTD handler
- * parameter is null.
* @see org.xml.sax.XMLReader#setEntityResolver
*/
public void setDTDHandler (DTDHandler handler)
{
- if (handler == null) {
- throw new NullPointerException("Null DTD handler");
- }
dtdHandler = handler;
}
@@ -336,15 +315,10 @@
* Set the content handler.
*
* @param resolver The new content handler.
- * @exception java.lang.NullPointerException If the content handler
- * parameter is null.
* @see org.xml.sax.XMLReader#setEntityResolver
*/
public void setContentHandler (ContentHandler handler)
{
- if (handler == null) {
- throw new NullPointerException("Null content handler");
- }
contentHandler = handler;
}
@@ -365,15 +339,10 @@
* Set the error handler.
*
* @param resolver The new error handler.
- * @exception java.lang.NullPointerException If the error handler
- * parameter is null.
* @see org.xml.sax.XMLReader#setEntityResolver
*/
public void setErrorHandler (ErrorHandler handler)
{
- if (handler == null) {
- throw new NullPointerException("Null error handler");
- }
errorHandler = handler;
}
@@ -396,7 +365,7 @@
* @param systemId The absolute URL of the document.
* @exception java.io.IOException If there is a problem reading
* the raw content of the document.
- * @exception org.xml.sax.SAXException If there is a problem
+ * @exception SAXException If there is a problem
* processing the document.
* @see #parse(org.xml.sax.InputSource)
* @see org.xml.sax.Parser#parse(java.lang.String)
@@ -414,7 +383,7 @@
* @param input An input source for the document.
* @exception java.io.IOException If there is a problem reading
* the raw content of the document.
- * @exception org.xml.sax.SAXException If there is a problem
+ * @exception SAXException If there is a problem
* processing the document.
* @see #parse(java.lang.String)
* @see org.xml.sax.Parser#parse(org.xml.sax.InputSource)
@@ -443,6 +412,7 @@
/**
+ * Adapter implementation method; do not call.
* Adapt a SAX1 document locator event.
*
* @param locator A document locator.
@@ -458,9 +428,10 @@
/**
+ * Adapter implementation method; do not call.
* Adapt a SAX1 start document event.
*
- * @exception org.xml.sax.SAXException The client may raise a
+ * @exception SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#startDocument
*/
@@ -474,9 +445,10 @@
/**
+ * Adapter implementation method; do not call.
* Adapt a SAX1 end document event.
*
- * @exception org.xml.sax.SAXException The client may raise a
+ * @exception SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#endDocument
*/
@@ -490,12 +462,15 @@
/**
+ * Adapter implementation method; do not call.
* Adapt a SAX1 startElement event.
*
* <p>If necessary, perform Namespace processing.</p>
*
* @param qName The qualified (prefixed) name.
* @param qAtts The XML 1.0 attribute list (with qnames).
+ * @exception SAXException The client may raise a
+ * processing exception.
*/
public void startElement (String qName, AttributeList qAtts)
throws SAXException
@@ -520,75 +495,87 @@
// OK, we're doing Namespace processing.
nsSupport.pushContext();
- boolean seenDecl = false;
- atts.clear();
-
- // Take a first pass and copy all
- // attributes into the SAX2 attribute
- // list, noting any Namespace
- // declarations.
int length = qAtts.getLength();
+
+ // First pass: handle NS decls
+ for (int i = 0; i < length; i++) {
+ String attQName = qAtts.getName(i);
+
+ if (!attQName.startsWith("xmlns"))
+ continue;
+ // Could be a declaration...
+ String prefix;
+ int n = attQName.indexOf(':');
+
+ // xmlns=...
+ if (n == -1 && attQName.length () == 5) {
+ prefix = "";
+ } else if (n != 5) {
+ // XML namespaces spec doesn't discuss "xmlnsf:oo"
+ // (and similarly named) attributes ... at most, warn
+ continue;
+ } else // xmlns:foo=...
+ prefix = attQName.substring(n+1);
+
+ String value = qAtts.getValue(i);
+ if (!nsSupport.declarePrefix(prefix, value)) {
+ reportError("Illegal Namespace prefix: " + prefix);
+ continue;
+ }
+ if (contentHandler != null)
+ contentHandler.startPrefixMapping(prefix, value);
+ }
+
+ // Second pass: copy all relevant
+ // attributes into the SAX2 AttributeList
+ // using updated prefix bindings
+ atts.clear();
for (int i = 0; i < length; i++) {
String attQName = qAtts.getName(i);
String type = qAtts.getType(i);
String value = qAtts.getValue(i);
- // Found a declaration...
+ // Declaration?
if (attQName.startsWith("xmlns")) {
String prefix;
int n = attQName.indexOf(':');
- if (n == -1) {
+
+ if (n == -1 && attQName.length () == 5) {
prefix = "";
+ } else if (n != 5) {
+ // XML namespaces spec doesn't discuss "xmlnsf:oo"
+ // (and similarly named) attributes ... ignore
+ prefix = null;
} else {
prefix = attQName.substring(n+1);
}
- if (!nsSupport.declarePrefix(prefix, value)) {
- reportError("Illegal Namespace prefix: " + prefix);
- }
- if (contentHandler != null) {
- contentHandler.startPrefixMapping(prefix, value);
- }
- // We may still have to add this to
- // the list.
- if (prefixes) {
- atts.addAttribute("", "", attQName.intern(),
+ // Yes, decl: report or prune
+ if (prefix != null) {
+ if (prefixes)
+ atts.addAttribute("", "", attQName.intern(),
type, value);
+ continue;
}
- seenDecl = true;
+ }
- // This isn't a declaration.
- } else {
- try {
- String attName[] = processName(attQName, true, true);
- atts.addAttribute(attName[0], attName[1], attName[2],
- type, value);
- } catch (SAXException e) {
- if (exceptions == null)
- exceptions = new Vector();
- exceptions.addElement(e);
- atts.addAttribute("", attQName, attQName, type, value);
- }
+ // Not a declaration -- report
+ try {
+ String attName[] = processName(attQName, true, true);
+ atts.addAttribute(attName[0], attName[1], attName[2],
+ type, value);
+ } catch (SAXException e) {
+ if (exceptions == null)
+ exceptions = new Vector();
+ exceptions.addElement(e);
+ atts.addAttribute("", attQName, attQName, type, value);
}
}
- // If there was a Namespace declaration,
- // we have to make a second pass just
- // to be safe -- this will happen very
- // rarely, possibly only once for each
- // document.
- if (seenDecl) {
- length = atts.getLength();
- for (int i = 0; i < length; i++) {
- String attQName = atts.getQName(i);
- if (!attQName.startsWith("xmlns")) {
- String attName[] = processName(attQName, true, false);
- atts.setURI(i, attName[0]);
- atts.setLocalName(i, attName[1]);
- }
- }
- } else if (exceptions != null && errorHandler != null) {
+ // now handle the deferred exception reports
+ if (exceptions != null && errorHandler != null) {
for (int i = 0; i < exceptions.size(); i++)
- errorHandler.error((SAXParseException)(exceptions.elementAt(i)));
+ errorHandler.error((SAXParseException)
+ (exceptions.elementAt(i)));
}
// OK, finally report the event.
@@ -600,10 +587,11 @@
/**
+ * Adapter implementation method; do not call.
* Adapt a SAX1 end element event.
*
* @param qName The qualified (prefixed) name.
- * @exception org.xml.sax.SAXException The client may raise a
+ * @exception SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#endElement
*/
@@ -634,12 +622,13 @@
/**
+ * Adapter implementation method; do not call.
* Adapt a SAX1 characters event.
*
* @param ch An array of characters.
* @param start The starting position in the array.
* @param length The number of characters to use.
- * @exception org.xml.sax.SAXException The client may raise a
+ * @exception SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#characters
*/
@@ -653,12 +642,13 @@
/**
+ * Adapter implementation method; do not call.
* Adapt a SAX1 ignorable whitespace event.
*
* @param ch An array of characters.
* @param start The starting position in the array.
* @param length The number of characters to use.
- * @exception org.xml.sax.SAXException The client may raise a
+ * @exception SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#ignorableWhitespace
*/
@@ -672,11 +662,12 @@
/**
+ * Adapter implementation method; do not call.
* Adapt a SAX1 processing instruction event.
*
* @param target The processing instruction target.
* @param data The remainder of the processing instruction
- * @exception org.xml.sax.SAXException The client may raise a
+ * @exception SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#processingInstruction
*/
@@ -726,7 +717,7 @@
* @param qName The qualified (prefixed) name.
* @param isAttribute true if this is an attribute name.
* @return The name split into three parts.
- * @exception org.xml.sax.SAXException The client may throw
+ * @exception SAXException The client may throw
* an exception if there is an error callback.
*/
private String [] processName (String qName, boolean isAttribute,
@@ -736,11 +727,12 @@
String parts[] = nsSupport.processName(qName, nameParts,
isAttribute);
if (parts == null) {
- parts = new String[3];
- parts[2] = qName.intern();
if (useException)
throw makeException("Undeclared prefix: " + qName);
reportError("Undeclared prefix: " + qName);
+ parts = new String[3];
+ parts[0] = parts[1] = "";
+ parts[2] = qName.intern();
}
return parts;
}
@@ -750,7 +742,7 @@
* Report a non-fatal error.
*
* @param message The error message.
- * @exception org.xml.sax.SAXException The client may throw
+ * @exception SAXException The client may throw
* an exception.
*/
void reportError (String message)
@@ -768,7 +760,6 @@
*/
private SAXParseException makeException (String message)
{
- SAXParseException e;
if (locator != null) {
return new SAXParseException(message, locator);
} else {
@@ -785,7 +776,7 @@
*
* @param type The type of thing (feature or property).
* @param name The feature or property name.
- * @exception org.xml.sax.SAXNotSupportedException If a
+ * @exception SAXNotSupportedException If a
* document is currently being parsed.
*/
private void checkNotParsing (String type, String name)
1.2 +8 -8 xml-commons/java/external/src/org/xml/sax/helpers/ParserFactory.java
Index: ParserFactory.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/ParserFactory.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- ParserFactory.java 20 May 2001 03:12:58 -0000 1.1
+++ ParserFactory.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,6 +1,7 @@
// SAX parser factory.
+// http://www.saxproject.org
// No warranty; no copyright -- use this as you will.
-// $Id: ParserFactory.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
+// $Id: ParserFactory.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -19,6 +20,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p><strong>Note:</strong> This class is designed to work with the now-deprecated
@@ -40,11 +43,8 @@
* {@link org.xml.sax.Parser Parser}
* interface.
* @since SAX 1.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
- * @see org.xml.sax.Parser
- * @see java.lang.Class
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
*/
public class ParserFactory {
@@ -121,9 +121,9 @@
InstantiationException,
ClassCastException
{
- return (Parser)(Class.forName(className).newInstance());
+ return (Parser) NewInstance.newInstance (
+ NewInstance.getClassLoader (), className);
}
}
-// end of ParserFactory.java
1.2 +35 -90 xml-commons/java/external/src/org/xml/sax/helpers/XMLFilterImpl.java
Index: XMLFilterImpl.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/XMLFilterImpl.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XMLFilterImpl.java 20 May 2001 03:12:58 -0000 1.1
+++ XMLFilterImpl.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,8 +1,9 @@
// XMLFilterImpl.java - base SAX2 filter implementation.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the Public Domain.
-// $Id: XMLFilterImpl.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
+// $Id: XMLFilterImpl.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -29,6 +30,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class is designed to sit between an {@link org.xml.sax.XMLReader
@@ -39,9 +42,8 @@
* requests as they pass through.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.XMLFilter
* @see org.xml.sax.XMLReader
* @see org.xml.sax.EntityResolver
@@ -64,10 +66,12 @@
*
* <p>This filter will have no parent: you must assign a parent
* before you start a parse or do any configuration with
- * setFeature or setProperty.</p>
+ * setFeature or setProperty, unless you use this as a pure event
+ * consumer rather than as an {@link XMLReader}.</p>
*
* @see org.xml.sax.XMLReader#setFeature
* @see org.xml.sax.XMLReader#setProperty
+ * @see #setParent
*/
public XMLFilterImpl ()
{
@@ -105,14 +109,10 @@
* or to set or get a feature or property will fail.</p>
*
* @param parent The parent XML reader.
- * @exception java.lang.NullPointerException If the parent is null.
* @see #getParent
*/
public void setParent (XMLReader parent)
{
- if (parent == null) {
- throw new NullPointerException("Null parent");
- }
this.parent = parent;
}
@@ -136,24 +136,23 @@
/**
- * Set the state of a feature.
+ * Set the value of a feature.
*
* <p>This will always fail if the parent is null.</p>
*
* @param name The feature name.
- * @param state The requested feature state.
- * @exception org.xml.sax.SAXNotRecognizedException When the
- * XMLReader does not recognize the feature name.
+ * @param value The requested feature value.
+ * @exception org.xml.sax.SAXNotRecognizedException If the feature
+ * value can't be assigned or retrieved from the parent.
* @exception org.xml.sax.SAXNotSupportedException When the
- * XMLReader recognizes the feature name but
+ * parent recognizes the feature name but
* cannot set the requested value.
- * @see org.xml.sax.XMLReader#setFeature
*/
- public void setFeature (String name, boolean state)
+ public void setFeature (String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException
{
if (parent != null) {
- parent.setFeature(name, state);
+ parent.setFeature(name, value);
} else {
throw new SAXNotRecognizedException("Feature: " + name);
}
@@ -161,18 +160,17 @@
/**
- * Look up the state of a feature.
+ * Look up the value of a feature.
*
* <p>This will always fail if the parent is null.</p>
*
* @param name The feature name.
- * @return The current state of the feature.
- * @exception org.xml.sax.SAXNotRecognizedException When the
- * XMLReader does not recognize the feature name.
+ * @return The current value of the feature.
+ * @exception org.xml.sax.SAXNotRecognizedException If the feature
+ * value can't be assigned or retrieved from the parent.
* @exception org.xml.sax.SAXNotSupportedException When the
- * XMLReader recognizes the feature name but
- * cannot determine its state at this time.
- * @see org.xml.sax.XMLReader#getFeature
+ * parent recognizes the feature name but
+ * cannot determine its value at this time.
*/
public boolean getFeature (String name)
throws SAXNotRecognizedException, SAXNotSupportedException
@@ -191,13 +189,12 @@
* <p>This will always fail if the parent is null.</p>
*
* @param name The property name.
- * @param state The requested property value.
- * @exception org.xml.sax.SAXNotRecognizedException When the
- * XMLReader does not recognize the property name.
+ * @param value The requested property value.
+ * @exception org.xml.sax.SAXNotRecognizedException If the property
+ * value can't be assigned or retrieved from the parent.
* @exception org.xml.sax.SAXNotSupportedException When the
- * XMLReader recognizes the property name but
+ * parent recognizes the property name but
* cannot set the requested value.
- * @see org.xml.sax.XMLReader#setProperty
*/
public void setProperty (String name, Object value)
throws SAXNotRecognizedException, SAXNotSupportedException
@@ -215,12 +212,11 @@
*
* @param name The property name.
* @return The current value of the property.
- * @exception org.xml.sax.SAXNotRecognizedException When the
- * XMLReader does not recognize the feature name.
+ * @exception org.xml.sax.SAXNotRecognizedException If the property
+ * value can't be assigned or retrieved from the parent.
* @exception org.xml.sax.SAXNotSupportedException When the
- * XMLReader recognizes the property name but
+ * parent recognizes the property name but
* cannot determine its value at this time.
- * @see org.xml.sax.XMLReader#setFeature
*/
public Object getProperty (String name)
throws SAXNotRecognizedException, SAXNotSupportedException
@@ -237,17 +233,10 @@
* Set the entity resolver.
*
* @param resolver The new entity resolver.
- * @exception java.lang.NullPointerException If the resolver
- * is null.
- * @see org.xml.sax.XMLReader#setEntityResolver
*/
public void setEntityResolver (EntityResolver resolver)
{
- if (resolver == null) {
- throw new NullPointerException("Null entity resolver");
- } else {
- entityResolver = resolver;
- }
+ entityResolver = resolver;
}
@@ -255,7 +244,6 @@
* Get the current entity resolver.
*
* @return The current entity resolver, or null if none was set.
- * @see org.xml.sax.XMLReader#getEntityResolver
*/
public EntityResolver getEntityResolver ()
{
@@ -267,17 +255,10 @@
* Set the DTD event handler.
*
* @param resolver The new DTD handler.
- * @exception java.lang.NullPointerException If the handler
- * is null.
- * @see org.xml.sax.XMLReader#setDTDHandler
*/
public void setDTDHandler (DTDHandler handler)
{
- if (handler == null) {
- throw new NullPointerException("Null DTD handler");
- } else {
- dtdHandler = handler;
- }
+ dtdHandler = handler;
}
@@ -285,7 +266,6 @@
* Get the current DTD event handler.
*
* @return The current DTD handler, or null if none was set.
- * @see org.xml.sax.XMLReader#getDTDHandler
*/
public DTDHandler getDTDHandler ()
{
@@ -297,17 +277,10 @@
* Set the content event handler.
*
* @param resolver The new content handler.
- * @exception java.lang.NullPointerException If the handler
- * is null.
- * @see org.xml.sax.XMLReader#setContentHandler
*/
public void setContentHandler (ContentHandler handler)
{
- if (handler == null) {
- throw new NullPointerException("Null content handler");
- } else {
- contentHandler = handler;
- }
+ contentHandler = handler;
}
@@ -315,7 +288,6 @@
* Get the content event handler.
*
* @return The current content handler, or null if none was set.
- * @see org.xml.sax.XMLReader#getContentHandler
*/
public ContentHandler getContentHandler ()
{
@@ -327,17 +299,10 @@
* Set the error event handler.
*
* @param handle The new error handler.
- * @exception java.lang.NullPointerException If the handler
- * is null.
- * @see org.xml.sax.XMLReader#setErrorHandler
*/
public void setErrorHandler (ErrorHandler handler)
{
- if (handler == null) {
- throw new NullPointerException("Null error handler");
- } else {
- errorHandler = handler;
- }
+ errorHandler = handler;
}
@@ -345,7 +310,6 @@
* Get the current error event handler.
*
* @return The current error handler, or null if none was set.
- * @see org.xml.sax.XMLReader#getErrorHandler
*/
public ErrorHandler getErrorHandler ()
{
@@ -362,7 +326,6 @@
* @exception java.io.IOException An IO exception from the parser,
* possibly from a byte stream or character stream
* supplied by the application.
- * @see org.xml.sax.XMLReader#parse(org.xml.sax.InputSource)
*/
public void parse (InputSource input)
throws SAXException, IOException
@@ -381,7 +344,6 @@
* @exception java.io.IOException An IO exception from the parser,
* possibly from a byte stream or character stream
* supplied by the application.
- * @see org.xml.sax.XMLReader#parse(java.lang.String)
*/
public void parse (String systemId)
throws SAXException, IOException
@@ -407,7 +369,6 @@
* @exception java.io.IOException The client may throw an
* I/O-related exception while obtaining the
* new InputSource.
- * @see org.xml.sax.EntityResolver#resolveEntity
*/
public InputSource resolveEntity (String publicId, String systemId)
throws SAXException, IOException
@@ -434,7 +395,6 @@
* @param systemId The notation's system identifier, or null.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.DTDHandler#notationDecl
*/
public void notationDecl (String name, String publicId, String systemId)
throws SAXException
@@ -454,7 +414,6 @@
* @param notationName The name of the associated notation.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.DTDHandler#unparsedEntityDecl
*/
public void unparsedEntityDecl (String name, String publicId,
String systemId, String notationName)
@@ -477,7 +436,6 @@
* Filter a new document locator event.
*
* @param locator The document locator.
- * @see org.xml.sax.ContentHandler#setDocumentLocator
*/
public void setDocumentLocator (Locator locator)
{
@@ -493,7 +451,6 @@
*
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#startDocument
*/
public void startDocument ()
throws SAXException
@@ -509,7 +466,6 @@
*
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#endDocument
*/
public void endDocument ()
throws SAXException
@@ -527,7 +483,6 @@
* @param uri The Namespace URI.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#startPrefixMapping
*/
public void startPrefixMapping (String prefix, String uri)
throws SAXException
@@ -544,7 +499,6 @@
* @param prefix The Namespace prefix.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#endPrefixMapping
*/
public void endPrefixMapping (String prefix)
throws SAXException
@@ -565,7 +519,6 @@
* @param atts The element's attributes.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#startElement
*/
public void startElement (String uri, String localName, String qName,
Attributes atts)
@@ -586,7 +539,6 @@
* string.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#endElement
*/
public void endElement (String uri, String localName, String qName)
throws SAXException
@@ -605,7 +557,6 @@
* @param length The number of characters to use from the array.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#characters
*/
public void characters (char ch[], int start, int length)
throws SAXException
@@ -624,7 +575,6 @@
* @param length The number of characters to use from the array.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#ignorableWhitespace
*/
public void ignorableWhitespace (char ch[], int start, int length)
throws SAXException
@@ -642,7 +592,6 @@
* @param data The text following the target.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#processingInstruction
*/
public void processingInstruction (String target, String data)
throws SAXException
@@ -659,7 +608,6 @@
* @param name The name of the skipped entity.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ContentHandler#skippedEntity
*/
public void skippedEntity (String name)
throws SAXException
@@ -679,10 +627,9 @@
/**
* Filter a warning event.
*
- * @param e The nwarning as an exception.
+ * @param e The warning as an exception.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ErrorHandler#warning
*/
public void warning (SAXParseException e)
throws SAXException
@@ -699,7 +646,6 @@
* @param e The error as an exception.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ErrorHandler#error
*/
public void error (SAXParseException e)
throws SAXException
@@ -716,7 +662,6 @@
* @param e The error as an exception.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
- * @see org.xml.sax.ErrorHandler#fatalError
*/
public void fatalError (SAXParseException e)
throws SAXException
1.2 +9 -5 xml-commons/java/external/src/org/xml/sax/helpers/XMLReaderAdapter.java
Index: XMLReaderAdapter.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/XMLReaderAdapter.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XMLReaderAdapter.java 20 May 2001 03:12:58 -0000 1.1
+++ XMLReaderAdapter.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,8 +1,9 @@
// XMLReaderAdapter.java - adapt an SAX2 XMLReader to a SAX1 Parser
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
// NO WARRANTY! This class is in the public domain.
-// $Id: XMLReaderAdapter.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
+// $Id: XMLReaderAdapter.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
@@ -31,6 +32,8 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class wraps a SAX2 {@link org.xml.sax.XMLReader XMLReader}
@@ -42,9 +45,8 @@
* property, that will also be used to improve efficiency.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
* @see org.xml.sax.Parser
* @see org.xml.sax.XMLReader
*/
@@ -120,6 +122,7 @@
*
* @param The locale for error reporting.
* @see org.xml.sax.Parser#setLocale
+ * @exception org.xml.sax.SAXException Thrown unless overridden.
*/
public void setLocale (Locale locale)
throws SAXException
@@ -412,6 +415,7 @@
*
* @param name The name of the skipped entity.
* @see org.xml.sax.ContentHandler#skippedEntity
+ * @exception org.xml.sax.SAXException Throwable by subclasses.
*/
public void skippedEntity (String name)
throws SAXException
1.2 +117 -50 xml-commons/java/external/src/org/xml/sax/helpers/XMLReaderFactory.java
Index: XMLReaderFactory.java
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/XMLReaderFactory.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- XMLReaderFactory.java 20 May 2001 03:12:58 -0000 1.1
+++ XMLReaderFactory.java 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,11 +1,15 @@
// XMLReaderFactory.java - factory for creating a new reader.
-// Written by David Megginson, sax@megginson.com
+// http://www.saxproject.org
+// Written by David Megginson
+// and by David Brownell
// NO WARRANTY! This class is in the Public Domain.
-// $Id: XMLReaderFactory.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
+// $Id: XMLReaderFactory.java,v 1.2 2002/02/27 16:04:18 dims Exp $
package org.xml.sax.helpers;
-import org.xml.sax.Parser;
+import java.io.BufferedReader;
+import java.io.InputStream;
+import java.io.InputStreamReader;
import org.xml.sax.XMLReader;
import org.xml.sax.SAXException;
@@ -16,12 +20,12 @@
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
+ * See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+ * for further information.
* </blockquote>
*
* <p>This class contains static methods for creating an XML reader
- * from an explicit class name, or for creating an XML reader based
- * on the value of the <code>org.xml.sax.driver</code> system
- * property:</p>
+ * from an explicit class name, or based on runtime defaults:</p>
*
* <pre>
* try {
@@ -31,23 +35,20 @@
* }
* </pre>
*
- * <p>Note that these methods will not be usable in environments where
- * system properties are not accessible or where the application or
- * applet is not permitted to load classes dynamically.</p>
- *
- * <p><strong>Note to implementors:</strong> SAX implementations in specialized
- * environments may replace this class with a different one optimized for the
- * environment, as long as its method signatures remain the same.</p>
+ * <p><strong>Note to Distributions bundled with parsers:</strong>
+ * You should modify the implementation of the no-arguments
+ * <em>createXMLReader</em> to handle cases where the external
+ * configuration mechanisms aren't set up. That method should do its
+ * best to return a parser when one is in the class path, even when
+ * nothing bound its class name to <code>org.xml.sax.driver</code> so
+ * those configuration mechanisms would see it.</p>
*
* @since SAX 2.0
- * @author David Megginson,
- * <a href="mailto:sax@megginson.com">sax@megginson.com</a>
- * @version 2.0r2pre
- * @see org.xml.sax.XMLReader
+ * @author David Megginson, David Brownell
+ * @version 2.0.1 (sax2r2)
*/
final public class XMLReaderFactory
{
-
/**
* Private constructor.
*
@@ -57,43 +58,103 @@
{
}
+ private static final String property = "org.xml.sax.driver";
/**
- * Attempt to create an XML reader from a system property.
- *
- * <p>This method uses the value of the system property
- * "org.xml.sax.driver" as the full name of a Java class
- * and tries to instantiate that class as a SAX2
- * XMLReader.</p>
- *
- * <p>Note that many Java interpreters allow system properties
- * to be specified on the command line.</p>
+ * Attempt to create an XMLReader from system defaults.
+ * In environments which can support it, the name of the XMLReader
+ * class is determined by trying each these options in order, and
+ * using the first one which succeeds:</p> <ul>
+ *
+ * <li>If the system property <code>org.xml.sax.driver</code>
+ * has a value, that is used as an XMLReader class name. </li>
+ *
+ * <li>The JAR "Services API" is used to look for a class name
+ * in the <em>META-INF/services/org.xml.sax.driver</em> file in
+ * jarfiles available to the runtime.</li>
+ *
+ * <li> SAX parser distributions are strongly encouraged to provide
+ * a default XMLReader class name that will take effect only when
+ * previous options (on this list) are not successful.</li>
+ *
+ * <li>Finally, if {@link ParserFactory#makeParser()} can
+ * return a system default SAX1 parser, that parser is wrapped in
+ * a {@link ParserAdapter}. (This is a migration aid for SAX1
+ * environments, where the <code>org.xml.sax.parser</code> system
+ * property will often be usable.) </li>
+ *
+ * </ul>
+ *
+ * <p> In environments such as small embedded systems, which can not
+ * support that flexibility, other mechanisms to determine the default
+ * may be used. </p>
+ *
+ * <p>Note that many Java environments allow system properties to be
+ * initialized on a command line. This means that <em>in most cases</em>
+ * setting a good value for that property ensures that calls to this
+ * method will succeed, except when security policies intervene.
+ * This will also maximize application portability to older SAX
+ * environments, with less robust implementations of this method.
+ * </p>
*
* @return A new XMLReader.
- * @exception org.xml.sax.SAXException If the value of the
- * "org.xml.sax.driver" system property is null,
- * or if the class cannot be loaded and instantiated.
+ * @exception org.xml.sax.SAXException If no default XMLReader class
+ * can be identified and instantiated.
* @see #createXMLReader(java.lang.String)
*/
- public static synchronized XMLReader createXMLReader ()
+ public static XMLReader createXMLReader ()
throws SAXException
{
- String className = System.getProperty("org.xml.sax.driver");
+ String className = null;
+ ClassLoader loader = NewInstance.getClassLoader ();
+
+ // 1. try the JVM-instance-wide system property
+ try { className = System.getProperty (property); }
+ catch (Exception e) { /* normally fails for applets */ }
+
+ // 2. if that fails, try META-INF/services/
if (className == null) {
- Parser parser;
try {
- parser = ParserFactory.makeParser();
+ String service = "META-INF/services/" + property;
+ InputStream in;
+ BufferedReader reader;
+
+ if (loader == null)
+ in = ClassLoader.getSystemResourceAsStream (service);
+ else
+ in = loader.getResourceAsStream (service);
+
+ if (in != null) {
+ reader = new BufferedReader (
+ new InputStreamReader (in, "UTF8"));
+ className = reader.readLine ();
+ in.close ();
+ }
} catch (Exception e) {
- parser = null;
}
- if (parser == null) {
- throw new
- SAXException("System property org.xml.sax.driver not specified");
- } else {
- return new ParserAdapter(parser);
- }
- } else {
- return createXMLReader(className);
+ }
+
+ // 3. Distro-specific fallback
+ if (className == null) {
+// BEGIN DISTRIBUTION-SPECIFIC
+
+ // EXAMPLE:
+ // className = "com.example.sax.XmlReader";
+ // or a $JAVA_HOME/jre/lib/*properties setting...
+
+// END DISTRIBUTION-SPECIFIC
+ }
+
+ // do we know the XMLReader implementation class yet?
+ if (className != null)
+ return loadClass (loader, className);
+
+ // 4. panic -- adapt any SAX1 parser
+ try {
+ return new ParserAdapter (ParserFactory.makeParser ());
+ } catch (Exception e) {
+ throw new SAXException ("Can't create default XMLReader; "
+ + "is system property org.xml.sax.driver set?");
}
}
@@ -104,16 +165,26 @@
* <p>Given a class name, this method attempts to load
* and instantiate the class as an XML reader.</p>
*
+ * <p>Note that this method will not be usable in environments where
+ * the caller (perhaps an applet) is not permitted to load classes
+ * dynamically.</p>
+ *
* @return A new XML reader.
* @exception org.xml.sax.SAXException If the class cannot be
* loaded, instantiated, and cast to XMLReader.
* @see #createXMLReader()
*/
- public static synchronized XMLReader createXMLReader (String className)
+ public static XMLReader createXMLReader (String className)
throws SAXException
{
+ return loadClass (NewInstance.getClassLoader (), className);
+ }
+
+ private static XMLReader loadClass (ClassLoader loader, String className)
+ throws SAXException
+ {
try {
- return (XMLReader)(Class.forName(className).newInstance());
+ return (XMLReader) NewInstance.newInstance (loader, className);
} catch (ClassNotFoundException e1) {
throw new SAXException("SAX2 driver class " + className +
" not found", e1);
@@ -122,15 +193,11 @@
" found but cannot be loaded", e2);
} catch (InstantiationException e3) {
throw new SAXException("SAX2 driver class " + className +
- " loaded but cannot be instantiated (no empty public constructor?)",
+ " loaded but cannot be instantiated (no empty public constructor?)",
e3);
} catch (ClassCastException e4) {
throw new SAXException("SAX2 driver class " + className +
" does not implement XMLReader", e4);
}
-
}
-
}
-
-// end of XMLReaderFactory.java
1.2 +8 -18 xml-commons/java/external/src/org/xml/sax/helpers/package.html
Index: package.html
===================================================================
RCS file: /home/cvs/xml-commons/java/external/src/org/xml/sax/helpers/package.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- package.html 20 May 2001 03:12:58 -0000 1.1
+++ package.html 27 Feb 2002 16:04:18 -0000 1.2
@@ -1,23 +1,13 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<HTML><HEAD>
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
-<title>SAX 2.0 r2 prerelease helper interfaces</title>
-</head>
+<!-- $Id: package.html,v 1.2 2002/02/27 16:04:18 dims Exp $ -->
-<body>
-<h1>SAX 2.0 r2 prerelease helper interfaces</h1>
+</HEAD><BODY>
-<blockquote>
-<p class="copyright">This document is in the <strong>PUBLIC
-DOMAIN</strong> and comes with <strong>NO WARRANTY</strong> of any
-kind.</p>
-</blockquote>
+<p>This package contains "helper" classes, including
+support for bootstrapping SAX-based applications.
-<p>This is a prerelease of a bugfix release for SAX2, the second
-generation of the Simple API for XML. For information, see
-docs/index.html.</p>
+<p>See <a href='http://www.saxproject.org'>http://www.saxproject.org</a>
+for more information about SAX.</p>
-</body>
-</html>
+</BODY></HTML>