From 909f6f7cc924d9a3793b700b2fa37cbb364a4cca Mon Sep 17 00:00:00 2001 From: dims Date: Wed, 27 Feb 2002 16:04:55 +0000 Subject: [PATCH] Upgrading to sax 2.0.1 (sax2r2) from http://sourceforge.net/projects/sax/ as per Edwin Goei. git-svn-id: https://svn.apache.org/repos/asf/xml/commons/trunk@225961 13f79535-47bb-0310-9956-ffa450edef68 --- java/external/ChangeLog-sax | 277 ++++++++++++++---- java/external/README-sax | 54 ++-- .../src/org/xml/sax/AttributeList.java | 8 +- java/external/src/org/xml/sax/Attributes.java | 21 +- .../src/org/xml/sax/ContentHandler.java | 64 +++- java/external/src/org/xml/sax/DTDHandler.java | 31 +- .../src/org/xml/sax/DocumentHandler.java | 8 +- .../src/org/xml/sax/EntityResolver.java | 31 +- .../src/org/xml/sax/ErrorHandler.java | 10 +- .../external/src/org/xml/sax/HandlerBase.java | 8 +- .../external/src/org/xml/sax/InputSource.java | 45 ++- java/external/src/org/xml/sax/Locator.java | 46 +-- java/external/src/org/xml/sax/Parser.java | 8 +- .../src/org/xml/sax/SAXException.java | 11 +- .../xml/sax/SAXNotRecognizedException.java | 10 +- .../org/xml/sax/SAXNotSupportedException.java | 10 +- .../src/org/xml/sax/SAXParseException.java | 34 ++- java/external/src/org/xml/sax/XMLFilter.java | 10 +- java/external/src/org/xml/sax/XMLReader.java | 101 +++---- .../src/org/xml/sax/ext/DeclHandler.java | 36 +-- .../src/org/xml/sax/ext/LexicalHandler.java | 31 +- .../external/src/org/xml/sax/ext/package.html | 123 ++------ .../xml/sax/helpers/AttributeListImpl.java | 8 +- .../org/xml/sax/helpers/AttributesImpl.java | 29 +- .../org/xml/sax/helpers/DefaultHandler.java | 33 ++- .../src/org/xml/sax/helpers/LocatorImpl.java | 8 +- .../org/xml/sax/helpers/NamespaceSupport.java | 157 +++++++--- .../src/org/xml/sax/helpers/NewInstance.java | 80 +++++ .../org/xml/sax/helpers/ParserAdapter.java | 247 ++++++++-------- .../org/xml/sax/helpers/ParserFactory.java | 14 +- .../org/xml/sax/helpers/XMLFilterImpl.java | 123 +++----- .../org/xml/sax/helpers/XMLReaderAdapter.java | 12 +- .../org/xml/sax/helpers/XMLReaderFactory.java | 161 +++++++--- .../src/org/xml/sax/helpers/package.html | 26 +- java/external/src/org/xml/sax/package.html | 177 +++++++++-- 35 files changed, 1283 insertions(+), 769 deletions(-) create mode 100644 java/external/src/org/xml/sax/helpers/NewInstance.java diff --git a/java/external/ChangeLog-sax b/java/external/ChangeLog-sax index ee6cfd4..c0fa553 100644 --- a/java/external/ChangeLog-sax +++ b/java/external/ChangeLog-sax @@ -1,3 +1,159 @@ +2002-Jan-29 David Brownell + + * SAX2 r2 (SAX 2.0.1) release + +2002-Jan-12 David Brownell + + * Doc clarifications + - skippedEntity() within markup constructs isn't done, + matching startEntity()/endEntity() + +2002-Jan-11 David Brownell + + * Doc clarifications + - Locator I18N issue for column/line numbers + - Locator getSystemId() absolutization examples + - SAXParseException relationship to Locator + +2002-Jan-10 David Brownell + + * 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 + + * Doc clarifications + - ContentHandler.skippedEntity() reported once per skip, + not once to cover all times it's skipped! + +2001-Nov-29 David Brownell + + * 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 + + * 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 + * 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 + + * 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 + + * NamespaceSupport now enforces declare-before-use constraint. + +2001-Oct-14 David Brownell + + * 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 + + * 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 + + * Removed refs to sax@megginson.com email (by request :) + * Doc clarifications + - InputSource + - NamespaceSupport + +2001-Aug-03 David Brownell + + * 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 + + * 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 + + 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 + + * Created http://sourceforge.net/projects/sax and + imported CVS history + 2000-12-28 David Megginson * SAX2 r2 prerelease @@ -27,6 +183,37 @@ - specified that getSystemId() returns null when no system ID is available +2000-10-04 David Megginson + + [extensions] + + * RELEASED VERSION 1.0 + + * updated version numbers + +2000-09-26 David Megginson + + [extensions] + + * RELEASED VERSION 1.0pre + +2000-09-25 David Megginson + + [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 * src/org/xml/sax/Attributes.java: @@ -192,6 +379,18 @@ - minor documentation cleanups - clarified attribute types and tokenized values +2000-04-14 David Megginson + + * 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 * 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 + + * 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 * 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 + + * 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 - added docs/quick-start.html @@ -257,63 +474,3 @@ SAX2beta2 RELEASED -==== -SAX2-EXT-1.0\ChangeLog -2000-10-04 David Megginson - - * RELEASED VERSION 1.0 - - * updated version numbers - -2000-09-26 David Megginson - - * RELEASED VERSION 1.0pre - -2000-09-25 David Megginson - - * 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 - - * 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 - - * 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 - - * 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 - diff --git a/java/external/README-sax b/java/external/README-sax index 6469277..da66eae 100644 --- a/java/external/README-sax +++ b/java/external/README-sax @@ -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 -A build.xml file is included for users of Apache's ant build tool (a -Java-based Makefile substitute). +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". -sax@megginson.com +For more information, see the current home for SAX on the web: -==== -SAX2-ext 1.0 + http://www.saxproject.org -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 +As a SourceForge project, SAX now has public CVS access, a database +for bugs and RFEs, mailing lists, and a web site. +- David Brownell + dbrownell@users.sourceforge.net diff --git a/java/external/src/org/xml/sax/AttributeList.java b/java/external/src/org/xml/sax/AttributeList.java index 388d503..2391b50 100644 --- a/java/external/src/org/xml/sax/AttributeList.java +++ b/java/external/src/org/xml/sax/AttributeList.java @@ -1,4 +1,5 @@ // SAX Attribute List Interface. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -10,6 +11,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

This is the original SAX1 interface for reporting an element's @@ -61,9 +64,8 @@ package org.xml.sax; * {@link org.xml.sax.Attributes Attributes} * interface, which includes Namespace support. * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 */ diff --git a/java/external/src/org/xml/sax/Attributes.java b/java/external/src/org/xml/sax/Attributes.java index 54cf8da..8e4f27c 100644 --- a/java/external/src/org/xml/sax/Attributes.java +++ b/java/external/src/org/xml/sax/Attributes.java @@ -1,5 +1,6 @@ // 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$ @@ -14,6 +15,8 @@ package org.xml.sax; *

* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

This interface allows access to a list of attributes in @@ -30,7 +33,13 @@ package org.xml.sax; * contain attributes used as Namespace declarations (xmlns*) unless * the http://xml.org/sax/features/namespace-prefixes * feature is set to true (it is false by - * default).

+ * 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. + *

* *

If the namespace-prefixes feature (see above) is false, * access by qualified name may not be available; if the @@ -47,10 +56,10 @@ package org.xml.sax; * vary from implementation to implementation.

* * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @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 { diff --git a/java/external/src/org/xml/sax/ContentHandler.java b/java/external/src/org/xml/sax/ContentHandler.java index ea30826..4f74805 100644 --- a/java/external/src/org/xml/sax/ContentHandler.java +++ b/java/external/src/org/xml/sax/ContentHandler.java @@ -1,5 +1,6 @@ // 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$ @@ -13,6 +14,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

This is the main interface that most SAX applications @@ -48,9 +51,8 @@ package org.xml.sax; * bug.

* * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public interface ContentHandler * Receive notification of the beginning of a document. * *

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}).

* * @exception org.xml.sax.SAXException Any SAX exception, possibly @@ -136,18 +137,21 @@ public interface ContentHandler * itself, if necessary.

* *

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.

* *

There should never be start/endPrefixMapping events for the * "xml" prefix, since it is predeclared and immutable.

* * @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 @@ public interface ContentHandler * End the scope of a prefix-URI mapping. * *

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.

* * @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 @@ public interface ContentHandler * property is true (it is false by default, and support for a * true value is optional).

* + *

Like {@link #characters characters()}, attribute values may have + * characters that need more than one char value.

+ * * @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 @@ public interface ContentHandler * @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 @@ public interface ContentHandler * @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 @@ public interface ContentHandler *

The application must not attempt to read from the array * outside of the specified range.

* + *

Individual characters may consist of more than one Java + * char 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 Surrogate Pair, + * 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.

+ * + *

Your code should not assume that algorithms using + * char-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.

+ * *

Note that some parsers will report whitespace in element * content using the {@link #ignorableWhitespace ignorableWhitespace} * method rather than this one (validating parsers must @@ -336,6 +361,10 @@ public interface ContentHandler * section 2.8) or a text declaration (XML 1.0, section 4.3.1) * using this method.

* + *

Like {@link #characters characters()}, processing instruction + * data may have characters that need more than one char + * value.

+ * * @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 @@ public interface ContentHandler /** * 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.) * - *

The Parser will invoke this method once for each entity + *

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 diff --git a/java/external/src/org/xml/sax/DTDHandler.java b/java/external/src/org/xml/sax/DTDHandler.java index 5aeb31e..8ed7b41 100644 --- a/java/external/src/org/xml/sax/DTDHandler.java +++ b/java/external/src/org/xml/sax/DTDHandler.java @@ -1,4 +1,5 @@ // SAX DTD handler. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -10,6 +11,8 @@ package org.xml.sax; *

* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

If a SAX application needs information about notations and @@ -27,7 +30,10 @@ package org.xml.sax; * 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.

+ * startElement event. + * (If the {@link org.xml.sax.ext.LexicalHandler LexicalHandler} is + * used, these events must also be reported before the endDTD event.) + *

* *

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 @@ package org.xml.sax; * notation corresponding with the attribute value.

* * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public interface DTDHandler { * Receive notification of a notation declaration event. * *

It is up to the application to record the notation for later - * reference, if necessary.

+ * reference, if necessary; + * notations may appear as attribute values and in unparsed entity + * declarations, and are sometime used with processing instruction + * target names.

* *

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 @@ public interface DTDHandler { * @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 @@ public interface DTDHandler { *

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.

+ * reference, if necessary; + * unparsed entities may appear as attribute values. + *

* *

If the system identifier is a URL, the parser must resolve it * fully before passing it to the application.

@@ -93,9 +102,9 @@ public interface DTDHandler { * @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, diff --git a/java/external/src/org/xml/sax/DocumentHandler.java b/java/external/src/org/xml/sax/DocumentHandler.java index 7c27e11..363457b 100644 --- a/java/external/src/org/xml/sax/DocumentHandler.java +++ b/java/external/src/org/xml/sax/DocumentHandler.java @@ -1,4 +1,5 @@ // SAX document handler. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -10,6 +11,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

This was the main event-handling interface for SAX1; in @@ -35,9 +38,8 @@ package org.xml.sax; * {@link org.xml.sax.ContentHandler ContentHandler} * interface, which includes Namespace support. * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 diff --git a/java/external/src/org/xml/sax/EntityResolver.java b/java/external/src/org/xml/sax/EntityResolver.java index 7d1b6bd..560f245 100644 --- a/java/external/src/org/xml/sax/EntityResolver.java +++ b/java/external/src/org/xml/sax/EntityResolver.java @@ -1,4 +1,5 @@ // SAX entity resolver. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -13,6 +14,8 @@ import java.io.IOException; *

* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

If a SAX application needs to implement customized handling @@ -58,10 +61,9 @@ import java.io.IOException; * (possibly by using the public identifier).

* * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public interface EntityResolver { /** * Allow the application to resolve external entities. * - *

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 + *

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.

+ * use data provided by the application (as a character or byte + * input stream).

* *

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).

+ * 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.

* *

If the system identifier is a URL, the SAX parser must * resolve it fully before reporting it to the application.

diff --git a/java/external/src/org/xml/sax/ErrorHandler.java b/java/external/src/org/xml/sax/ErrorHandler.java index b8cec00..fe5d0d8 100644 --- a/java/external/src/org/xml/sax/ErrorHandler.java +++ b/java/external/src/org/xml/sax/ErrorHandler.java @@ -1,4 +1,5 @@ // SAX error handler. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -11,6 +12,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

If a SAX application needs to implement customized error @@ -33,10 +36,9 @@ package org.xml.sax; * could catch an exception and report a fatalError).

* * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 { diff --git a/java/external/src/org/xml/sax/HandlerBase.java b/java/external/src/org/xml/sax/HandlerBase.java index c8d2cd8..104abc7 100644 --- a/java/external/src/org/xml/sax/HandlerBase.java +++ b/java/external/src/org/xml/sax/HandlerBase.java @@ -1,4 +1,5 @@ // SAX default handler base class. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -10,6 +11,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

This class implements the default behaviour for four SAX1 @@ -32,9 +35,8 @@ package org.xml.sax; * {@link org.xml.sax.helpers.DefaultHandler DefaultHandler} * class. * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 diff --git a/java/external/src/org/xml/sax/InputSource.java b/java/external/src/org/xml/sax/InputSource.java index 53f82d2..a819bd6 100644 --- a/java/external/src/org/xml/sax/InputSource.java +++ b/java/external/src/org/xml/sax/InputSource.java @@ -1,4 +1,5 @@ // SAX input source. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -13,6 +14,8 @@ import java.io.InputStream; *

* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

This class allows a SAX application to encapsulate information @@ -20,28 +23,36 @@ import java.io.InputStream; * a public identifier, a system identifier, a byte stream (possibly * with a specified encoding), and/or a character stream.

* - *

There are two places that the application will deliver this + *

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.

* *

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.

* *

An InputSource object belongs to the application: the SAX parser * shall never modify it in any way (it may modify a copy if - * necessary).

+ * 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.

* * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 class InputSource { * public identifier as well, or setEncoding to specify * the character encoding, if known.

* - *

If the system identifier is a URL, it must be full resolved.

+ *

If the system identifier is a URL, it must be fully + * resolved (it may not be a relative URL).

* * @param systemId The system identifier (URI). * @see #setPublicId @@ -87,9 +99,9 @@ public class InputSource { /** * Create a new input source with a byte stream. * - *

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 + *

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.

* * @param byteStream The raw byte stream containing the document. @@ -108,8 +120,8 @@ public class InputSource { /** * Create a new input source with a character stream. * - *

Application writers may use setSystemId() to provide a base - * for resolving relative URIs, and setPublicId to include a + *

Application writers should use setSystemId() to provide a base + * for resolving relative URIs, and may use setPublicId to include a * public identifier.

* *

The character stream shall not include a byte order mark.

@@ -169,7 +181,8 @@ public class InputSource { * object pointed to by the system identifier, it can register * the encoding using the setEncoding method.

* - *

If the system ID is a URL, it must be fully resolved.

+ *

If the system identifier is a URL, it must be fully + * resolved (it may not be a relative URL).

* * @param systemId The system identifier as a string. * @see #setEncoding @@ -263,6 +276,8 @@ public class InputSource { /** * 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 diff --git a/java/external/src/org/xml/sax/Locator.java b/java/external/src/org/xml/sax/Locator.java index 9890494..823db76 100644 --- a/java/external/src/org/xml/sax/Locator.java +++ b/java/external/src/org/xml/sax/Locator.java @@ -1,4 +1,5 @@ // SAX locator interface for document events. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -11,6 +12,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

If a SAX parser provides location information to the SAX @@ -18,13 +21,13 @@ package org.xml.sax; * 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.

* *

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.

+ * locator at any other time, or after parsing completes.

* *

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 @@ package org.xml.sax; * available.

* * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @version 2.0r2pre + * @author David Megginson + * @version 2.0.1 (sax2r2) * @see org.xml.sax.ContentHandler#setDocumentLocator */ public interface Locator { @@ -65,7 +67,9 @@ public interface Locator { * triggering the event appears.

* *

If the system identifier is a URL, the parser must resolve it - * fully before passing it to the application.

+ * fully before passing it to the application. For example, a file + * name must always be provided as a file:... URL, and other + * kinds of relative URI are also resolved against their bases.

* * @return A string containing the system identifier, or null * if none is available. @@ -76,11 +80,16 @@ public interface Locator { /** * Return the line number where the current document event ends. + * Lines are delimited by line ends, which are defined in + * the XML specification. * *

Warning: 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.

+ * 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.

* *

The return value is an approximation of the line number * in the document entity or external parsed entity where the @@ -88,7 +97,7 @@ public interface Locator { * *

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.

+ * event. The first line is line 1.

* * @return The line number, or -1 if none is available. * @see #getColumnNumber @@ -98,11 +107,16 @@ public interface Locator { /** * Return the column number where the current document event ends. + * This is one-based number of Java char values since + * the last line end. * *

Warning: 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.

+ * 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.

* *

The return value is an approximation of the column number * in the document entity or external parsed entity where the @@ -110,10 +124,6 @@ public interface Locator { * *

If possible, the SAX driver should provide the line position * of the first character after the text associated with the document - * event.

- * - *

If possible, the SAX driver should provide the line position - * of the first character after the text associated with the document * event. The first column in each line is column 1.

* * @return The column number, or -1 if none is available. diff --git a/java/external/src/org/xml/sax/Parser.java b/java/external/src/org/xml/sax/Parser.java index c359274..4f91eb1 100644 --- a/java/external/src/org/xml/sax/Parser.java +++ b/java/external/src/org/xml/sax/Parser.java @@ -1,4 +1,5 @@ // SAX parser interface. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -14,6 +15,8 @@ import java.util.Locale; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

This was the main event supplier interface for SAX1; it has @@ -37,9 +40,8 @@ import java.util.Locale; * {@link org.xml.sax.XMLReader XMLReader} * interface, which includes Namespace support. * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 diff --git a/java/external/src/org/xml/sax/SAXException.java b/java/external/src/org/xml/sax/SAXException.java index 5a8b970..0ffd56e 100644 --- a/java/external/src/org/xml/sax/SAXException.java +++ b/java/external/src/org/xml/sax/SAXException.java @@ -1,4 +1,5 @@ // SAX exception class. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -10,6 +11,8 @@ package org.xml.sax; *

* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

This class can contain basic error or warning information from @@ -27,9 +30,8 @@ package org.xml.sax; * {@link org.xml.sax.SAXParseException SAXParseException} subclass.

* * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public class SAXException extends Exception { * 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 @@ public class SAXException extends Exception { * * @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 @@ public class SAXException extends Exception { * the detail message from the embedded exception.

* * @return The error or warning message. - * @see org.xml.sax.Parser#setLocale */ public String getMessage () { diff --git a/java/external/src/org/xml/sax/SAXNotRecognizedException.java b/java/external/src/org/xml/sax/SAXNotRecognizedException.java index 5e75196..f5afae1 100644 --- a/java/external/src/org/xml/sax/SAXNotRecognizedException.java +++ b/java/external/src/org/xml/sax/SAXNotRecognizedException.java @@ -1,5 +1,6 @@ // 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$ @@ -14,6 +15,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

An XMLReader will throw this exception when it finds an @@ -21,9 +24,8 @@ package org.xml.sax; * extensions may use this class for other, similar purposes.

* * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @version 2.0r2pre + * @author David Megginson + * @version 2.0.1 (sax2r2) * @see org.xml.sax.SAXNotSupportedException */ public class SAXNotRecognizedException extends SAXException diff --git a/java/external/src/org/xml/sax/SAXNotSupportedException.java b/java/external/src/org/xml/sax/SAXNotSupportedException.java index d0ef4ed..3e1654f 100644 --- a/java/external/src/org/xml/sax/SAXNotSupportedException.java +++ b/java/external/src/org/xml/sax/SAXNotSupportedException.java @@ -1,5 +1,6 @@ // 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$ @@ -13,6 +14,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

An XMLReader will throw this exception when it recognizes a @@ -21,9 +24,8 @@ package org.xml.sax; * extensions may use this class for similar purposes.

* * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @version 2.0r2pre + * @author David Megginson + * @version 2.0.1 (sax2r2) * @see org.xml.sax.SAXNotRecognizedException */ public class SAXNotSupportedException extends SAXException diff --git a/java/external/src/org/xml/sax/SAXParseException.java b/java/external/src/org/xml/sax/SAXParseException.java index 3e2a169..b25df30 100644 --- a/java/external/src/org/xml/sax/SAXParseException.java +++ b/java/external/src/org/xml/sax/SAXParseException.java @@ -1,4 +1,5 @@ // SAX exception class. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -10,10 +11,13 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* - *

This exception will include information for locating the error - * in the original XML document. Note that although the application + *

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 @@ package org.xml.sax; * SAXException}, it inherits the ability to wrap another exception.

* * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public class SAXParseException extends SAXException { * @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 @@ public class SAXParseException extends SAXException { * 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 @@ public class SAXParseException extends SAXException { * *

This constructor is most useful for parser writers.

* - *

If the system identifier is a URL, the parser must resolve it - * fully before creating the exception.

+ *

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.

+ * * * @param message The error or warning message. * @param publicId The public identifer of the entity that generated @@ -108,7 +112,6 @@ public class SAXParseException extends SAXException { * 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 @@ public class SAXParseException extends SAXException { * need to wrap an exception that is not a subclass of * {@link org.xml.sax.SAXException SAXException}.

* - *

If the system identifier is a URL, the parser must resolve it - * fully before creating the exception.

+ *

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.

* * @param message The error or warning message, or null to use * the message from the embedded exception. @@ -139,7 +144,6 @@ public class SAXParseException extends SAXException { * @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 @@ public class SAXParseException extends SAXException { /** * Get the system identifier of the entity where the exception occurred. * - *

If the system identifier is a URL, it will be resolved + *

If the system identifier is a URL, it will have been resolved * fully.

* * @return A string containing the system identifier, or null @@ -201,6 +205,8 @@ public class SAXParseException extends SAXException { /** * The line number of the end of the text where the exception occurred. * + *

The first line is line 1.

+ * * @return An integer representing the line number, or -1 * if none is available. * @see org.xml.sax.Locator#getLineNumber diff --git a/java/external/src/org/xml/sax/XMLFilter.java b/java/external/src/org/xml/sax/XMLFilter.java index 5c4d7fe..ecf9f4e 100644 --- a/java/external/src/org/xml/sax/XMLFilter.java +++ b/java/external/src/org/xml/sax/XMLFilter.java @@ -1,5 +1,6 @@ // 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$ @@ -14,6 +15,8 @@ package org.xml.sax; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

An XML filter is like an XML reader, except that it obtains its @@ -28,9 +31,8 @@ package org.xml.sax; * ErrorHandler} events automatically.

* * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @version 2.0r2pre + * @author David Megginson + * @version 2.0.1 (sax2r2) * @see org.xml.sax.helpers.XMLFilterImpl */ public interface XMLFilter extends XMLReader diff --git a/java/external/src/org/xml/sax/XMLReader.java b/java/external/src/org/xml/sax/XMLReader.java index d27bdfc..62488c1 100644 --- a/java/external/src/org/xml/sax/XMLReader.java +++ b/java/external/src/org/xml/sax/XMLReader.java @@ -1,5 +1,6 @@ // 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$ @@ -15,6 +16,8 @@ import java.io.IOException; *
* This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
* *

Note: despite its name, this interface does @@ -36,7 +39,7 @@ import java.io.IOException; *

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:

+ * interface (as well as some minor ones):

* *
    *
  1. it adds a standard way to query and set features and @@ -49,9 +52,8 @@ import java.io.IOException; * a SAX2 XMLReader and vice-versa.

    * * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public interface XMLReader /** - * Look up the value of a feature. + * Look up the value of a feature flag. * *

    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.

    + * 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.)

    * *

    All XMLReaders are required to recognize the * http://xml.org/sax/features/namespaces and the * http://xml.org/sax/features/namespace-prefixes feature names.

    * - *

    Some feature values may be available only in specific - * contexts, such as before, during, or after a parse.

    - * *

    Typical usage is something like this:

    * * 
    @@ -112,9 +115,9 @@ public interface XMLReader
      * using names built on their own URIs.
    
      *
      * @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 @@ public interface XMLReader
 
 
     /**
-     * Set the state of a feature.
+     * Set the value of a feature flag.
      *
      * 
    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.
    
+     * 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.
    
      *
      * 
    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.
    
      *
-     * 
    Some feature values may be immutable or mutable only 
-     * in specific contexts, such as before, during, or after 
-     * a parse.
    
-     *
      * @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 @@ public interface XMLReader
      *
      * 
    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}.
    
+     * 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.
    
      *
      * 
    XMLReaders are not required to recognize any specific
      * property names, though an initial core set is documented for
      * SAX2.
    
      *
-     * 
    Some property values may be available only in specific
-     * contexts, such as before, during, or after a parse.
    
-     *
      * 
    Implementors are free (and encouraged) to invent their own properties,
      * using names built on their own URIs.
    
      *
      * @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 @@ public interface XMLReader
      *
      * 
    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}.
    
-     *
-     * 
    XMLReaders are not required to recognize setting
-     * any specific property names, though a core set is provided with 
-     * SAX2.
    
-     *
-     * 
    Some property values may be immutable or mutable only 
+     * 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.
    
      *
+     * 
    XMLReaders are not required to recognize setting
+     * any specific property names, though a core set is defined by 
+     * SAX2.
    
+     *
      * 
    This method is also the standard mechanism for setting
      * extended handlers.
    
      *
      * @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 @@ public interface XMLReader
      * resolver immediately.
    
      *
      * @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 @@ public interface XMLReader
      * handler immediately.
    
      *
      * @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 @@ public interface XMLReader
      * handler immediately.
    
      *
      * @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 @@ public interface XMLReader
      * handler immediately.
    
      *
      * @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 @@ public interface XMLReader
 	throws IOException, SAXException;
 
 }
-
-// end of XMLReader.java
diff --git a/java/external/src/org/xml/sax/ext/DeclHandler.java b/java/external/src/org/xml/sax/ext/DeclHandler.java
index fba2515..b72d6d3 100644
--- a/java/external/src/org/xml/sax/ext/DeclHandler.java
+++ b/java/external/src/org/xml/sax/ext/DeclHandler.java
@@ -1,4 +1,5 @@
 // DeclHandler.java - Optional handler for DTD declaration events.
+// http://www.saxproject.org
 // Public Domain: no warranty.
 // $Id$
 
@@ -13,12 +14,14 @@ import org.xml.sax.SAXException;
  * 
    
  * This module, both source code and documentation, is in the
  * Public Domain, and comes with NO WARRANTY.
+ * See http://www.saxproject.org
+ * for further information.
  * 
    
  *
- * 
    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.
    
+ * 
    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.
    
  *
  * 
    Note that data-related DTD declarations (unparsed entities and
  * notations) are already reported through the {@link
@@ -31,18 +34,16 @@ import org.xml.sax.SAXException;
  *
  * 
    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
+ * http://xml.org/sax/properties/declaration-handler
+ * 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.
    
  *
- * @since 1.0
- * @author David Megginson, 
- *         sax@megginson.com
- * @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 @@ public interface DeclHandler
      * "NOTATION" followed by a space followed by a parenthesized
      * token group with all whitespace removed.
    
      *
-     * 
    Any parameter entities in the attribute value will be
-     * expanded, but general entities will not.
    
+     * 
    The value will be the value as reported to applications,
+     * appropriately normalized and with entity and character
+     * references expanded.  
    
      *
      * @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 interface DeclHandler
     public abstract void attributeDecl (String eName,
 					String aName,
 					String type,
-					String valueDefault,
+					String mode,
 					String value)
 	throws SAXException;
 
diff --git a/java/external/src/org/xml/sax/ext/LexicalHandler.java b/java/external/src/org/xml/sax/ext/LexicalHandler.java
index ada8f15..c17059d 100644
--- a/java/external/src/org/xml/sax/ext/LexicalHandler.java
+++ b/java/external/src/org/xml/sax/ext/LexicalHandler.java
@@ -1,4 +1,5 @@
 // LexicalHandler.java - optional handler for lexical parse events.
+// http://www.saxproject.org
 // Public Domain: no warranty.
 // $Id$
 
@@ -12,13 +13,15 @@ import org.xml.sax.SAXException;
  * 
    
  * This module, both source code and documentation, is in the
  * Public Domain, and comes with NO WARRANTY.
+ * See http://www.saxproject.org
+ * for further information.
  * 
    
  *
  * 
    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.
    
+ * and CDATA section boundaries.
+ * XML readers are not required to recognize this handler, and it
+ * is not part of core-only SAX2 distributions.
    
  *
  * 
    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 @@ import org.xml.sax.SAXException;
  *
  * 
    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
+ * http://xml.org/sax/properties/lexical-handler
+ * 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.
    
  *
- * @since 1.0
- * @author David Megginson, 
- *         sax@megginson.com
- * @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 @@ public interface LexicalHandler
      *        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 @@ public interface LexicalHandler
      *
      * 
    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
      * http://xml.org/sax/features/lexical-handler/parameter-entities
      * feature to query or control the reporting of parameter entities.
    
diff --git a/java/external/src/org/xml/sax/ext/package.html b/java/external/src/org/xml/sax/ext/package.html
index f985987..bbb02f9 100644
--- a/java/external/src/org/xml/sax/ext/package.html
+++ b/java/external/src/org/xml/sax/ext/package.html
@@ -1,114 +1,49 @@
-
+
 
-
-
-SAX2-ext: SAX2 Extension Handlers 1.0
-
+
 
-
-
    SAX2-ext: SAX2 Extension Handlers 1.0
    
+
    
+This package contains interfaces to optional SAX2 handlers.
 
-
    
-
    This document is in the PUBLIC
-DOMAIN and comes with NO WARRANTY of any
-kind.
    
-
    
+
    See http://www.saxproject.org
+for more information about SAX.
    
 
-
    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.
    
-
-
    NOTE: 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.
    
-
-
    The SAX2-ext package currently contains two extension handlers for
-SAX2:
    
-
-
      
-
-
    1. LexicalHandler, which reports comments, the DOCTYPE declaration,
-CDATA sections, and (some) entity boundaries; and
      2. 
-
-
    2. DeclHandler, which reports element, attribute, and entity
-declarations.
      3. 
-
-
    
-
-
    This package is independent of the SAX2 core, and that independence
-has several consequences:
    
+
    
+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:
    
 
 
      
 
-
    • SAX2 drivers are not required to support these handlers,
-and you cannot assume that the classes will be present in every SAX2
+
    • SAX2 drivers are not required to recognize these handlers,
+and you cannot assume that the class files will be present in every SAX2
 installation.
      • 
 
 
    • This package may be updated independently of SAX2 (i.e. new
 handlers may be added without updating SAX2 itself).
      • 
 
-
    • The handlers are not supported explicitly by the SAX2
-XMLFilter interface (i.e. events are not passed on by
-default); you can subclass XMLFilter if you need such behaviour.
      • 
+
    • The handlers are not implemented by the SAX2
+org.xml.sax.helpers.DefaultHandler or
+org.xml.sax.helpers.XMLFilterImpl classes.
+You can subclass these if you need such behaviour.
      • 
 
 
    • The handlers need to be registered differently than regular SAX2
 handlers.
      • 
 
 
    
 
-
    To set a LexicalHandler, for example, you need to do something like 
-this:
    
+
    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.  
    
 
-
    -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.");
-}
-
    
+
    NOTE: 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.
    
 
-
-
    
-
    SAX2-ext Properties
    
-
-
    Here is a full definition of the two new SAX2 properties introduced
-in this version of SAX2-ext:
    
-
-
    
-
-
    http://xml.org/sax/properties/lexical-handler
    
-
    data type:
-org.xml.sax.ext.LexicalHandler
    
-
    description: An optional extension handler for
-lexical events like comments.
    
-
    access: read/write
    
-
-
    http://xml.org/sax/properties/declaration-handler
    
-
    data type:
-org.xml.sax.ext.DeclHandler
    
-
    description: An optional extension handler for
-DTD-related events other than notations and unparsed entities.
    
-
    access: read/write
    
-
-
    
-
-
    See also: the package's JavaDoc documentation.
    
-
-
-
    
-
-
    
-
-
    $Id$
    
-
-
-
+
diff --git a/java/external/src/org/xml/sax/helpers/AttributeListImpl.java b/java/external/src/org/xml/sax/helpers/AttributeListImpl.java
index e309417..a1a2515 100644
--- a/java/external/src/org/xml/sax/helpers/AttributeListImpl.java
+++ b/java/external/src/org/xml/sax/helpers/AttributeListImpl.java
@@ -1,4 +1,5 @@
 // SAX default implementation for AttributeList.
+// http://www.saxproject.org
 // No warranty; no copyright -- use this as you will.
 // $Id$
 
@@ -15,6 +16,8 @@ import java.util.Vector;
  * 
    
  * This module, both source code and documentation, is in the
  * Public Domain, and comes with NO WARRANTY.
+ * See http://www.saxproject.org
+ * for further information.
  * 
    
  *
  * 
    AttributeList implements the deprecated SAX1 {@link
@@ -55,9 +58,8 @@ import java.util.Vector;
  *             {@link org.xml.sax.helpers.AttributesImpl 
  *            AttributesImpl} helper class.
  * @since SAX 1.0
- * @author David Megginson, 
- *         sax@megginson.com
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
  * @see org.xml.sax.AttributeList
  * @see org.xml.sax.DocumentHandler#startElement 
  */
diff --git a/java/external/src/org/xml/sax/helpers/AttributesImpl.java b/java/external/src/org/xml/sax/helpers/AttributesImpl.java
index 9e962f0..565b83f 100644
--- a/java/external/src/org/xml/sax/helpers/AttributesImpl.java
+++ b/java/external/src/org/xml/sax/helpers/AttributesImpl.java
@@ -1,5 +1,6 @@
 // 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$
@@ -16,6 +17,8 @@ import org.xml.sax.Attributes;
  * 
    
  * This module, both source code and documentation, is in the
  * Public Domain, and comes with NO WARRANTY.
+ * See http://www.saxproject.org
+ * for further information.
  * 
    
  *
  * 
    This class provides a default implementation of the SAX2
@@ -39,9 +42,8 @@ import org.xml.sax.Attributes;
  * implementation using a single array rather than a set of Vectors.
    
  *
  * @since SAX 2.0
- * @author David Megginson, 
- *         sax@megginson.com
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
  */
 public class AttributesImpl implements Attributes
 {
@@ -320,12 +322,16 @@ public class AttributesImpl implements Attributes
     /**
      * Clear the attribute list for reuse.
      *
-     * 
    Note that no memory is actually freed by this call:
-     * the current arrays are kept so that they can be 
+     * 
    Note that little memory is freed by this call:
+     * the current array is kept so it can be 
      * reused.
    
      */
     public void clear ()
     {
+	if (data != null) {
+	    for (int i = 0; i < (length * 5); i++)
+		data [i] = null;
+	}
 	length = 0;
     }
 
@@ -432,15 +438,16 @@ public class AttributesImpl implements Attributes
     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);
diff --git a/java/external/src/org/xml/sax/helpers/DefaultHandler.java b/java/external/src/org/xml/sax/helpers/DefaultHandler.java
index f18dbb3..5a468ea 100644
--- a/java/external/src/org/xml/sax/helpers/DefaultHandler.java
+++ b/java/external/src/org/xml/sax/helpers/DefaultHandler.java
@@ -1,5 +1,6 @@
 // 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$
@@ -25,6 +26,8 @@ import org.xml.sax.SAXParseException;
  * 
    
  * This module, both source code and documentation, is in the
  * Public Domain, and comes with NO WARRANTY.
+ * See http://www.saxproject.org
+ * for further information.
  * 
    
  *
  * 
    This class is available as a convenience base class for SAX2
@@ -47,9 +50,8 @@ import org.xml.sax.SAXParseException;
  * {@link org.xml.sax.HandlerBase HandlerBase} class.
    
  *
  * @since SAX 2.0
- * @author David Megginson, 
- *         sax@megginson.com
- * @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 @@ public class DefaultHandler
      * each element (such as allocating a new tree node or writing
      * output to a file).
    
      *
-     * @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 @@ public class DefaultHandler
      * each element (such as finalising a tree node or writing
      * output to a file).
    
      *
-     * @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
diff --git a/java/external/src/org/xml/sax/helpers/LocatorImpl.java b/java/external/src/org/xml/sax/helpers/LocatorImpl.java
index e19f7bf..5a59ace 100644
--- a/java/external/src/org/xml/sax/helpers/LocatorImpl.java
+++ b/java/external/src/org/xml/sax/helpers/LocatorImpl.java
@@ -1,4 +1,5 @@
 // SAX default implementation for Locator.
+// http://www.saxproject.org
 // No warranty; no copyright -- use this as you will.
 // $Id$
 
@@ -13,6 +14,8 @@ import org.xml.sax.Locator;
  * 
    
  * This module, both source code and documentation, is in the
  * Public Domain, and comes with NO WARRANTY.
+ * See http://www.saxproject.org
+ * for further information.
  * 
    
  *
  * 
    This class is available mainly for application writers, who
@@ -42,9 +45,8 @@ import org.xml.sax.Locator;
  * requested, rather than constantly updating a Locator object.
    
  *
  * @since SAX 1.0
- * @author David Megginson, 
- *         sax@megginson.com
- * @version 2.0r2pre
+ * @author David Megginson
+ * @version 2.0.1 (sax2r2)
  * @see org.xml.sax.Locator Locator
  */
 public class LocatorImpl implements Locator
diff --git a/java/external/src/org/xml/sax/helpers/NamespaceSupport.java b/java/external/src/org/xml/sax/helpers/NamespaceSupport.java
index 367d25e..cff88dd 100644
--- a/java/external/src/org/xml/sax/helpers/NamespaceSupport.java
+++ b/java/external/src/org/xml/sax/helpers/NamespaceSupport.java
@@ -1,5 +1,6 @@
 // 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$
@@ -13,11 +14,14 @@ import java.util.Vector;
 
 
 /**
- * Encapsulate Namespace logic for use by SAX drivers.
+ * Encapsulate Namespace logic for use by applications using SAX,
+ * or internally by SAX drivers.
  *
  * 
    
  * This module, both source code and documentation, is in the
  * Public Domain, and comes with NO WARRANTY.
+ * See http://www.saxproject.org
+ * for further information.
  * 
    
  *
  * 
    This class encapsulates the logic of Namespace processing:
@@ -39,16 +43,16 @@ import java.util.Vector;
  * 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();
  *
    * @@ -57,10 +61,14 @@ import java.util.Vector; * prefix/URI mapping is repeated for each context (for example), this * class will be somewhat less efficient.

    * + *

    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, - * sax@megginson.com - * @version 2.0r2pre + * @author David Megginson + * @version 2.0.1 (sax2r2) */ public class NamespaceSupport { @@ -72,7 +80,9 @@ public class NamespaceSupport /** - * The XML Namespace as a constant. + * The XML Namespace URI as a constant. + * The value is http://www.w3.org/XML/1998/namespace + * as defined in the XML Namespaces specification. * *

    This is the Namespace URI that is automatically mapped * to the "xml" prefix.

    @@ -125,21 +135,45 @@ public class NamespaceSupport /** * Start a new Namespace context. - * - *

    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.

    + * track of which declarations were made within this context. + * + *

    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 + * ContentHandler.startElement() callback is the right place. + * For elements with such a declaration, it'd done in the first + * ContentHandler.startPrefixMapping() 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 ContentHandler.startElement() + * does that, it always clears the flag. + * + *

    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 + * ContentHandler.startPrefixMapping() 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 + * ContentHandler.startElement() callback is available, + * so it can then be made. * *

    The Namespace support object always starts with a base context * already in force: in this context, only the "xml" prefix is * declared.

    * + * @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 class NamespaceSupport */ public void popContext () { + contexts[contextPos].clear(); contextPos--; if (contextPos < 0) { throw new EmptyStackException(); @@ -193,29 +228,42 @@ public class NamespaceSupport /** - * 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. * *

    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.

    * - *

    To declare a default Namespace, use the empty string. The - * prefix must not be "xml" or "xmlns".

    + *

    To declare the default element Namespace, use the empty string as + * the prefix.

    * *

    Note that you must not declare a prefix after - * you've pushed and popped another Namespace.

    + * you've pushed and popped another Namespace context, or + * treated the declarations phase as complete by processing + * a prefixed name.

    * - *

    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, + *

    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.

    * - * @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 @@ public class NamespaceSupport /** - * 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()}. * *

    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 @@ public class NamespaceSupport * *

    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.

    * * @param qName The raw XML 1.0 name to be processed. @@ -419,9 +468,14 @@ public class NamespaceSupport /** * Internal class for a single Namespace context. * - *

    This module caches and reuses Namespace contexts, so the number allocated + *

    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).

    + * 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. + *

    */ final class Context { @@ -436,6 +490,8 @@ public class NamespaceSupport /** * (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 @@ public class NamespaceSupport 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 @@ public class NamespaceSupport 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 @@ public class NamespaceSupport 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 @@ public class NamespaceSupport } // 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 @@ public class NamespaceSupport } else { name[0] = defaultNS; } - name[1] = qName.intern(); - name[2] = name[1]; + name[1] = name[2]; } // Prefix @@ -548,12 +629,11 @@ public class NamespaceSupport } 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 @@ public class NamespaceSupport } elementNameTable = new Hashtable(); attributeNameTable = new Hashtable(); - tablesDirty = true; + declSeen = true; } @@ -673,6 +753,7 @@ public class NamespaceSupport Hashtable elementNameTable; Hashtable attributeNameTable; String defaultNS = null; + boolean declsOK = true; @@ -681,7 +762,7 @@ public class NamespaceSupport //////////////////////////////////////////////////////////////// private Vector declarations = null; - private boolean tablesDirty = false; + private boolean declSeen = false; private Context parent = null; } } diff --git a/java/external/src/org/xml/sax/helpers/NewInstance.java b/java/external/src/org/xml/sax/helpers/NewInstance.java new file mode 100644 index 0000000..a5a124b --- /dev/null +++ b/java/external/src/org/xml/sax/helpers/NewInstance.java @@ -0,0 +1,80 @@ +// NewInstance.java - create a new instance of a class by name. +// http://www.saxproject.org +// Written by Edwin Goei, edwingo@apache.org +// and by David Brownell, dbrownell@users.sourceforge.net +// NO WARRANTY! This class is in the Public Domain. + +// $Id$ + +package org.xml.sax.helpers; + +import java.lang.reflect.Method; +import java.lang.reflect.InvocationTargetException; + +/** + * Create a new instance of a class by name. + * + *
    + * This module, both source code and documentation, is in the + * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. + *
    + * + *

    This class contains a static method for creating an instance of a + * class from an explicit class name. It tries to use the thread's context + * ClassLoader if possible and falls back to using + * Class.forName(String).

    + * + *

    This code is designed to compile and run on JDK version 1.1 and later + * including versions of Java 2.

    + * + * @author Edwin Goei, David Brownell + * @version 2.0.1 (sax2r2) + */ +class NewInstance { + + /** + * Creates a new instance of the specified class name + * + * Package private so this code is not exposed at the API level. + */ + static Object newInstance (ClassLoader classLoader, String className) + throws ClassNotFoundException, IllegalAccessException, + InstantiationException + { + Class driverClass; + if (classLoader == null) { + driverClass = Class.forName(className); + } else { + driverClass = classLoader.loadClass(className); + } + return driverClass.newInstance(); + } + + /** + * Figure out which ClassLoader to use. For JDK 1.2 and later use + * the context ClassLoader. + */ + static ClassLoader getClassLoader () + { + Method m = null; + + try { + m = Thread.class.getMethod("getContextClassLoader", null); + } catch (NoSuchMethodException e) { + // Assume that we are running JDK 1.1, use the current ClassLoader + return NewInstance.class.getClassLoader(); + } + + try { + return (ClassLoader) m.invoke(Thread.currentThread(), null); + } catch (IllegalAccessException e) { + // assert(false) + throw new UnknownError(e.getMessage()); + } catch (InvocationTargetException e) { + // assert(e.getTargetException() instanceof SecurityException) + throw new UnknownError(e.getMessage()); + } + } +} diff --git a/java/external/src/org/xml/sax/helpers/ParserAdapter.java b/java/external/src/org/xml/sax/helpers/ParserAdapter.java index a5f7f7a..2a45663 100644 --- a/java/external/src/org/xml/sax/helpers/ParserAdapter.java +++ b/java/external/src/org/xml/sax/helpers/ParserAdapter.java @@ -1,5 +1,6 @@ // 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$ @@ -34,6 +35,8 @@ import org.xml.sax.SAXNotSupportedException; *
    * This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
    * *

    This class wraps a SAX1 {@link org.xml.sax.Parser Parser} @@ -46,9 +49,8 @@ import org.xml.sax.SAXNotSupportedException; * attribute names.

    * * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler *

    Use the "org.xml.sax.parser" property to locate the * embedded SAX1 driver.

    * - * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler 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. * - *

    The only features supported are namespaces and + *

    The only features recognized are namespaces and * namespace-prefixes.

    * * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** - * Check a parser feature. + * Check a parser feature flag. * - *

    The only features supported are namespaces and + *

    The only features recognized are namespaces and * namespace-prefixes.

    * * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** * Set a parser property. * - *

    No special properties are currently supported.

    + *

    No properties are currently recognized.

    * * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** * Get a parser property. * - *

    No special properties are currently supported.

    + *

    No properties are currently recognized.

    * * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** + * Adapter implementation method; do not call. * Adapt a SAX1 document locator event. * * @param locator A document locator. @@ -458,9 +428,10 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** + * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** + * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** + * Adapter implementation method; do not call. * Adapt a SAX1 startElement event. * *

    If necessary, perform Namespace processing.

    * * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler // 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** + * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** + * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** + * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler /** + * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler * @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 @@ public class ParserAdapter implements XMLReader, DocumentHandler 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler * 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 @@ public class ParserAdapter implements XMLReader, DocumentHandler */ private SAXParseException makeException (String message) { - SAXParseException e; if (locator != null) { return new SAXParseException(message, locator); } else { @@ -785,7 +776,7 @@ public class ParserAdapter implements XMLReader, DocumentHandler * * @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) diff --git a/java/external/src/org/xml/sax/helpers/ParserFactory.java b/java/external/src/org/xml/sax/helpers/ParserFactory.java index 85c895d..de726dd 100644 --- a/java/external/src/org/xml/sax/helpers/ParserFactory.java +++ b/java/external/src/org/xml/sax/helpers/ParserFactory.java @@ -1,4 +1,5 @@ // SAX parser factory. +// http://www.saxproject.org // No warranty; no copyright -- use this as you will. // $Id$ @@ -19,6 +20,8 @@ import org.xml.sax.Parser; *
    * This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
    * *

    Note: This class is designed to work with the now-deprecated @@ -40,11 +43,8 @@ import org.xml.sax.Parser; * {@link org.xml.sax.Parser Parser} * interface. * @since SAX 1.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public class ParserFactory { InstantiationException, ClassCastException { - return (Parser)(Class.forName(className).newInstance()); + return (Parser) NewInstance.newInstance ( + NewInstance.getClassLoader (), className); } } -// end of ParserFactory.java diff --git a/java/external/src/org/xml/sax/helpers/XMLFilterImpl.java b/java/external/src/org/xml/sax/helpers/XMLFilterImpl.java index a102b2a..4ebf552 100644 --- a/java/external/src/org/xml/sax/helpers/XMLFilterImpl.java +++ b/java/external/src/org/xml/sax/helpers/XMLFilterImpl.java @@ -1,5 +1,6 @@ // 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$ @@ -29,6 +30,8 @@ import org.xml.sax.SAXNotRecognizedException; *

    * This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
    * *

    This class is designed to sit between an {@link org.xml.sax.XMLReader @@ -39,9 +42,8 @@ import org.xml.sax.SAXNotRecognizedException; * requests as they pass through.

    * * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public class XMLFilterImpl * *

    This filter will have no parent: you must assign a parent * before you start a parse or do any configuration with - * setFeature or setProperty.

    + * setFeature or setProperty, unless you use this as a pure event + * consumer rather than as an {@link XMLReader}.

    * * @see org.xml.sax.XMLReader#setFeature * @see org.xml.sax.XMLReader#setProperty + * @see #setParent */ public XMLFilterImpl () { @@ -105,14 +109,10 @@ public class XMLFilterImpl * or to set or get a feature or property will fail.

    * * @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 @@ public class XMLFilterImpl /** - * Set the state of a feature. + * Set the value of a feature. * *

    This will always fail if the parent is null.

    * * @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 @@ public class XMLFilterImpl /** - * Look up the state of a feature. + * Look up the value of a feature. * *

    This will always fail if the parent is null.

    * * @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 @@ public class XMLFilterImpl *

    This will always fail if the parent is null.

    * * @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 @@ public class XMLFilterImpl * * @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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * * @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 @@ public class XMLFilterImpl * * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * 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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl /** * 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 @@ public class XMLFilterImpl * @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 @@ public class XMLFilterImpl * @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 diff --git a/java/external/src/org/xml/sax/helpers/XMLReaderAdapter.java b/java/external/src/org/xml/sax/helpers/XMLReaderAdapter.java index f2a96d4..44f3c8c 100644 --- a/java/external/src/org/xml/sax/helpers/XMLReaderAdapter.java +++ b/java/external/src/org/xml/sax/helpers/XMLReaderAdapter.java @@ -1,5 +1,6 @@ // 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$ @@ -31,6 +32,8 @@ import org.xml.sax.SAXNotSupportedException; *
    * This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
    * *

    This class wraps a SAX2 {@link org.xml.sax.XMLReader XMLReader} @@ -42,9 +45,8 @@ import org.xml.sax.SAXNotSupportedException; * property, that will also be used to improve efficiency.

    * * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ public class XMLReaderAdapter implements Parser, ContentHandler * * @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 @@ public class XMLReaderAdapter implements Parser, ContentHandler * * @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 diff --git a/java/external/src/org/xml/sax/helpers/XMLReaderFactory.java b/java/external/src/org/xml/sax/helpers/XMLReaderFactory.java index 36dbbf4..2983df4 100644 --- a/java/external/src/org/xml/sax/helpers/XMLReaderFactory.java +++ b/java/external/src/org/xml/sax/helpers/XMLReaderFactory.java @@ -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$ 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 @@ import org.xml.sax.SAXException; *
    * This module, both source code and documentation, is in the * Public Domain, and comes with NO WARRANTY. + * See http://www.saxproject.org + * for further information. *
    * *

    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 org.xml.sax.driver system - * property:

    + * from an explicit class name, or based on runtime defaults:

    * * 
      * try {
@@ -31,23 +35,20 @@ import org.xml.sax.SAXException;
  * }
  *
    * - *

    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.

    - * - *

    Note to implementors: 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.

    + *

    Note to Distributions bundled with parsers: + * You should modify the implementation of the no-arguments + * createXMLReader 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 org.xml.sax.driver so + * those configuration mechanisms would see it.

    * * @since SAX 2.0 - * @author David Megginson, - * sax@megginson.com - * @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 @@ final public class XMLReaderFactory { } + private static final String property = "org.xml.sax.driver"; /** - * Attempt to create an XML reader from a system property. + * 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:

      * - *

      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.

      + *
    • If the system property org.xml.sax.driver + * has a value, that is used as an XMLReader class name.
      • * - *

      Note that many Java interpreters allow system properties - * to be specified on the command line.

      + *
    • The JAR "Services API" is used to look for a class name + * in the META-INF/services/org.xml.sax.driver file in + * jarfiles available to the runtime.
      • + * + *
    • 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.
      • + * + *
    • 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 org.xml.sax.parser system + * property will often be usable.)
      • + * + *
    + * + *

    In environments such as small embedded systems, which can not + * support that flexibility, other mechanisms to determine the default + * may be used.

    + * + *

    Note that many Java environments allow system properties to be + * initialized on a command line. This means that in most cases + * 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. + *

    * * @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 @@ final public class XMLReaderFactory *

    Given a class name, this method attempts to load * and instantiate the class as an XML reader.

    * + *

    Note that this method will not be usable in environments where + * the caller (perhaps an applet) is not permitted to load classes + * dynamically.

    + * * @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 @@ final public class XMLReaderFactory " 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 diff --git a/java/external/src/org/xml/sax/helpers/package.html b/java/external/src/org/xml/sax/helpers/package.html index 582db76..155182d 100644 --- a/java/external/src/org/xml/sax/helpers/package.html +++ b/java/external/src/org/xml/sax/helpers/package.html @@ -1,23 +1,13 @@ - + - - -SAX 2.0 r2 prerelease helper interfaces - + - -

    SAX 2.0 r2 prerelease helper interfaces

    + -
    -

    This document is in the PUBLIC -DOMAIN and comes with NO WARRANTY of any -kind.

    -
    +

    This package contains "helper" classes, including +support for bootstrapping SAX-based applications. -

    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.

    +

    See http://www.saxproject.org +for more information about SAX.

    - - + diff --git a/java/external/src/org/xml/sax/package.html b/java/external/src/org/xml/sax/package.html index c679f3c..1691077 100644 --- a/java/external/src/org/xml/sax/package.html +++ b/java/external/src/org/xml/sax/package.html @@ -1,23 +1,164 @@ - + - - -SAX 2.0 r2 prerelease interfaces - + - -

    SAX 2.0 r2 prerelease interfaces

    + -
    -

    This document is in the PUBLIC -DOMAIN and comes with NO WARRANTY of any -kind.

    -
    +

    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.

    -

    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.

    +

    See http://www.saxproject.org +for more information about SAX.

    - - + +

    SAX2 Standard Feature Flags

    + +

    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 +http://xml.org/sax/features/ before an identifier such as +validation. Turn features on or off using +setFeature. Those standard identifiers are:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Feature IDDefaultDescription
    external-general-entitiesunspecified Reports whether this parser processes external + general entities; always true if validating
    external-parameter-entitiesunspecified Reports whether this parser processes external + parameter entities; always true if validating
    lexical-handler/parameter-entitiesunspecified true indicates that the LexicalHandler will report the + beginning and end of parameter entities +
    namespacestrue true indicates namespace URIs and unprefixed local names + for element and attribute names will be available
    namespace-prefixesfalse true indicates XML 1.0 names (with prefixes) and attributes + (including xmlns* attributes) will be available
    string-interningunspecified true if all XML names (for elements, prefixes, attributes, + entities, notations, and local names), + as well as Namespace URIs, will have been interned + using java.lang.String.intern. This supports fast + testing of equality/inequality against string constants.
    validationunspecified controls whether the parser is reporting all validity + errors; if true, all external entities will be read.
    + +

    Support for the default values of the +namespaces and namespace-prefixes +properties is required. +

    + +

    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. +

    + +

    SAX2 Standard Handler and Property IDs

    + +

    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 +http://xml.org/sax/properties/ before an identifier such as +lexical-handler or +dom-node. Manage those properties using +setProperty(). Those identifiers are:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Property IDDescription
    declaration-handler Used to see most DTD declarations except those treated + as lexical ("document element name is ...") or which are + mandatory for all SAX parsers (DTDHandler). + The Object must implement org.xml.sax.ext.DeclHandler. +
    dom-node For "DOM Walker" style parsers, which ignore their + parser.parse() parameters, this is used to + specify the DOM (sub)tree being walked by the parser. + The Object must implement the + org.w3c.dom.Node interface. +
    lexical-handler 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 org.xml.sax.ext.LexicalHandler. +
    xml-string Readable only during a parser callback, this exposes a TBS + chunk of characters responsible for the current event.
    + +

    All of these standard properties are optional; +XMLReader implementations need not support them. +

    + +