You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commons-cvs@xml.apache.org by cu...@apache.org on 2001/05/20 05:13:00 UTC
cvs commit: xml-commons/java/external/xdocs/sax changes.html features.html filters.html namespaces.html quick-start.html sax-style.css sax.html
curcuru 01/05/19 20:13:00
Added: java/external BUGS-sax ChangeLog-sax README-sax
build-sax.xml
java/external/src/org/xml/sax AttributeList.java
Attributes.java ContentHandler.java DTDHandler.java
DocumentHandler.java EntityResolver.java
ErrorHandler.java HandlerBase.java InputSource.java
Locator.java Parser.java SAXException.java
SAXNotRecognizedException.java
SAXNotSupportedException.java
SAXParseException.java XMLFilter.java
XMLReader.java package.html
java/external/src/org/xml/sax/ext DeclHandler.java
LexicalHandler.java package.html
java/external/src/org/xml/sax/helpers AttributeListImpl.java
AttributesImpl.java DefaultHandler.java
LocatorImpl.java NamespaceSupport.java
ParserAdapter.java ParserFactory.java
XMLFilterImpl.java XMLReaderAdapter.java
XMLReaderFactory.java package.html
java/external/xdocs/sax changes.html features.html
filters.html namespaces.html quick-start.html
sax-style.css sax.html
Log:
Checkin external modules: SAX 2.0 r2 prerelease; SAX2-ext 1.0
Revision Changes Path
1.1 xml-commons/java/external/BUGS-sax
Index: BUGS-sax
===================================================================
SAX2 Bugs -*-Outline-*-
* SAXException
[FIXED]
- should have default constructor (wdehora@cromwellmedia.co.uk);
retracts in following message, but it's probably a good idea
[SKIPPED: cannot be reproduced]
- getMessage() is not getting message from superclass correctly
(zbeckman@creativesun.com)
* InputSource
[FIXED]
- should document what getSystemId() returns if none has been
supplied: null or empty string (chris.laprun@nist.gov)
[SKIPPED: requires interface change]
- no way to allow parser to close InputStream returned
(markd@lutris.com)
* DefaultHandler
[FIXED]
- resolveEntity() should throw IOException as well as SAXException
(Matt Jones <jo...@nceas.ucsb.edu>) (zaphod@catori.com)
* EntityResolver
[PASSED: explicitly mention that precedence is unspecified]
- document what a processor should do in each situation (just
systemId, just public Id, several, etc.), i.e. precedence (Andy
Clark)
* AttributesImpl
[FIXED]
- ensureCapacity needs to be more robust -- see 2000-07-19 message for
details (cziegeler@sundn.de) and 2000-07-17 message
(Andrew@instmak.com) (gordonp@niji.imb.nrc.ca)
[FIXED]
- removeAttributes uses index rather than index*5 and erases the wrong
attribute -- see 2000-07-17 message for details (Andrew@instmak.com)
(js@pro-solutions.com)
* ParserAdapter
[FIXED]
- rejects Namespace prefix used before declaration
(Michael.Kay@icl.com)
* Attributes
[FIXED]
- in getIndex, use localName instead of localpart for consistency
(elharo@metalab.unc.edu)
* XMLReaderAdapter
[FIXED]
- throws exception if no DocumentHandler set
(ksaito@flab.fujitsu.co.jp)
* XMLReaderFactory
[FIXED]
- synchronize static methods (hermod.opstvedt@dnb.no)
====
SAX2-EXT Bugs
- [FIXED] org.xml.sax.DeclHandler instead of
org.xml.sax.ext.DeclHandler in JavaDoc ("Jason H. den Dulk"
<fo...@rivernet.com.au>)
1.1 xml-commons/java/external/ChangeLog-sax
Index: ChangeLog-sax
===================================================================
2000-12-28 David Megginson <da...@megginson.com>
* SAX2 r2 prerelease
2000-12-27 David Megginson <da...@megginson.com>
* src/SAXTest.java:
- added simple test program
* src/org/xml/sax/helpers/XMLReaderFactory.java:
- synchronized both methods for thread safety
* src/org/xml/sax/helpers/ParserAdapter.java:
- added makeException method to build parse exception
- queue up exceptions during first attribute pass, in case there
is no second pass (and we have to throw them)
- modified processName to take an extra argument for throwing an
exception rather than reporting an error
* src/org/xml/sax/helpers/AttributesImpl.java:
- added rewritten ensureCapacity and setAttributes from Andrew
Pittsley (APittsley@InfoHealthNet.com) to fix bug and make
setAttributes more efficient for empty attribute list
- removed buggy statement that in removeAttribute
* src/org/xml/sax/InputSource.java:
- specified that getSystemId() returns null when no system ID is
available
2000-09-12 David Megginson <da...@megginson.com>
* src/org/xml/sax/Attributes.java:
- [docs only] renamed localPart parameter to localName
* src/org/xml/sax/helpers/DefaultHandler.java:
- modified resolveEntity to throw IOException, as in the interface
specification
* src/org/xml/sax/SAXNotRecognizedException.java:
- added default constructor
* src/org/xml/sax/SAXNotSupportedException.java:
- added default constructor
* src/org/xml/sax/SAXException.java:
- added default constructor
2000-05-05 David Megginson <da...@megginson.com>
- all versions bumped to 2.0
* src/org/xml/sax/XMLReader.java:
- documented fact that parse() and event handlers are synchronous
* src/org/xml/sax/ContentHandler.java:
- documented that xml: prefix never has start/endPrefixMapping
events
2000-04-19 David Megginson <da...@megginson.com>
SAX2pre RELEASED!!!
* src/org/xml/sax/helpers/XMLReaderFactory.java:
- bumped version to 2.0pre
- added note that implementors may replace this class
* src/org/xml/sax/helpers/XMLReaderAdapter.java:
- bumped version to 2.0pre
- minor documentation clean-ups
* src/org/xml/sax/helpers/XMLFilterImpl.java:
- bumped version to 2.0pre
- minor documentation clean-ups
* src/org/xml/sax/helpers/ParserFactory.java:
- bumped version to 2.0pre
- minor documentation clean-ups
* src/org/xml/sax/helpers/ParserAdapter.java:
- bumped version to 2.0pre
- minor documentation clean-ups
* src/org/xml/sax/helpers/NamespaceSupport.java:
- bumped version to 2.0pre
- minor documentation clean-ups
- added more clarifications about getPrefix asymmetry
- fixed typos in JavaDoc
* src/org/xml/sax/helpers/LocatorImpl.java:
- bumped version to 2.0pre
2000-04-18 David Megginson <da...@megginson.com>
* src/org/xml/sax/helpers/DefaultHandler.java:
- bumped version to 2.0pre
- minor documentation clean-ups
* src/org/xml/sax/helpers/AttributesImpl.java:
- added setAttributes method to simplify
- bumped version to 2.0pre
- minor documentation clean-ups
* src/org/xml/sax/helpers/AttributeListImpl.java:
- bumped version to 2.0pre
- minor documentation cleanup
- added extra information about deprecation
* src/org/xml/sax/XMLReader.java:
- bumped version to 2.0pre
- minor documentation clean-ups
- removed statement in JavaDoc that XMLReader extends Parser
- added note that this does not extend java.io.Reader
* src/org/xml/sax/XMLFilter.java:
- bumped version to 2.0pre
- minor documentation clean-ups
* src/org/xml/sax/SAXParseException.java:
- bumped version to 2.0pre
- minor documentation clean-ups
- allow a null locator argument in the constructors
- use an internal init() to avoid code duplication
2000-04-17 David Megginson <da...@megginson.com>
* src/org/xml/sax/SAXNotSupportedException.java:
- bumped version to 2.0pre
- minor documentation cleanups
* src/org/xml/sax/SAXNotRecognizedException.java:
- bumped the version to 2.0pre
* src/org/xml/sax/SAXException.java:
- bumped version to 2.0pre
- minor documentation cleanup
* src/org/xml/sax/Parser.java:
- bumped version to 2.0pre
* src/org/xml/sax/Locator.java:
- bumped version to 2.0pre
- documentation cleanups and clarifications
- changed references from DocumentHandler to ContentHandler
- added warnings to getLineNumber and getColumnNumber
- clarified that first line is line 1
* src/org/xml/sax/InputSource.java:
- bumped version to 2.0pre
- minor documentation cleanups
* src/org/xml/sax/HandlerBase.java:
- bumped version to 2.0pre
- minor documentation cleanups
* src/org/xml/sax/ErrorHandler.java:
- bumped version to 2.0pre
- removed outdate references to HandlerBase
- added explicit warning about unreported errors when an
ErrorHandler isn't set
- minor documentation cleanups
* src/org/xml/sax/EntityResolver.java:
- bumped version to 2.0pre
- removed outdated reference to HandlerBase in docs
- minor documentation cleanups
* src/org/xml/sax/DocumentHandler.java:
-bumped version to 2.0pre
2000-04-14 David Megginson <da...@megginson.com>
* src/org/xml/sax/DTDHandler.java:
- bumped version to 2.0pre
- minor documentation cleanups (not done)
- added documentation that notation will not necessarily be reported
before unparsed entities that use it
- added documentation that at least one of publicId and systemId
must be non-null for notationDecl
* src/org/xml/sax/ContentHandler.java:
- for skippedEntity, added documentation that "[dtd]" represents the
external DTD subset
- documented possible confusion with java.net.ContentHandler
- changed doc for processingInstruction to state that space between
the target and data is excluded
- fixed outdated references to DocumentHandler
- minor documentation cleanups
- bumped version to 2.0pre
* src/org/xml/sax/Attributes.java:
- bumped version to 2.0pre
- minor documentation cleanups
- clarified attribute types and tokenized values
2000-04-10 David Megginson <da...@megginson.com>
* src/org/xml/sax/helpers/NamespaceSupport.java:
- removed spurious comment
- setting "" prefix to "" removes any default mapping
- modified getPrefix to be more efficient (accepting that people
will use this class in reverse); getPrefix will not work
with the default prefix
- getPrefixes no longer returns the default prefix
- getDeclaredPrefixes does return the default prefix
2000-03-30 David Megginson <da...@megginson.com>
* src/org/xml/sax/helpers/AttributesImpl.java:
- fixed bug preventing last attribute from being removed
* src/org/xml/sax/helpers/DefaultHandler.java:
- throw SAXException for notationDecl and unparsedEntityDecl to
allow proper subclassing
2000-03-28 David Megginson <da...@megginson.com>
* src/org/xml/sax/helpers/AttributesImpl.java:
- renamed setRawName to setQName
- renamed getRawName to getQName
* src/org/xml/sax/Attributes.java:
- renamed getRawName to getQName
2000-03-27 David Megginson <da...@megginson.com>
- renamed rawName to qName and rawAtts to qAtts throughout
2000-03-25 David Megginson <da...@megginson.com>
* src/org/xml/sax/ext/LexicalHandler.java
- removed to separate distribution
* src/org/xml/sax/ext/DeclHandler.java
- removed to separate distribution
* src/org/xml/sax/helpers/XMLReaderFactory.java:
- for createXMLReader(), if org.xml.sax.driver is not specified,
try ParserFactory.makeParser() and return it wrapped if successful
2000-03-24 David Megginson <da...@megginson.com>
- added docs/quick-start.html
* src/org/xml/sax/helpers/XMLReaderAdapter.java:
- have parse(String) actually invoke parse(InputSource)
* src/org/xml/sax/helpers/ParserAdapter.java:
- have parse(String) actually invoke parse(InputSource)
* src/org/xml/sax/helpers/XMLFilterImpl.java:
- have parse(String) actually invoke parse(InputSource)
* src/org/xml/sax/helpers/NamespaceSupport.java:
- Added getPrefix(String) and getPrefixes(String) to look up
prefixes currently mapped.
SAX2beta2 RELEASED
====
SAX2-EXT-1.0\ChangeLog
2000-10-04 David Megginson <da...@megginson.com>
* RELEASED VERSION 1.0
* updated version numbers
2000-09-26 David Megginson <da...@megginson.com>
* RELEASED VERSION 1.0pre
2000-09-25 David Megginson <da...@megginson.com>
* src/org/xml/sax/ext/DeclHandler.java:
- doc: bumped version to 1.0pre
* src/org/xml/sax/ext/LexicalHandler.java:
- doc: bumped version to 1.0pre
- doc: typo fixed (corrected org.xml.sax.DeclHandler to
org.xml.sax.ext.DeclHandler)
- doc: explicitly mention order of comment/PI events in
DOCTYPE
- doc: explicitly mention that comment/PI are not required to
appear in correct positions relative to DTDHandler or DeclHandler
events.
2000-04-14 David Megginson <da...@megginson.com>
* RELEASED VERSION 1.0beta
* src/org/xml/sax/ext/DeclHandler.java:
- doc: specified that content models may be normalized
- doc: specified that NOTATION attributes also have token group
- doc: specified that parameter entities are expanded in content
models, attribute value literals, and entity values
- doc: specified that general entities are not expanded in
attribute value literals and entity values
2000-03-27 David Megginson <da...@megginson.com>
* src/org/xml/sax/ext/LexicalHandler.java:
- separated from main SAX2 distribution
- added documentation to clarify relationship between
start/endEntity, start/endDTD, DeclHandler, and DTDHandler
* src/org/xml/sax/ext/DeclHandler.java:
- separated from main SAX2 distribution
2000-03-25 David Megginson <da...@megginson.com>
* src/org/xml/sax/ext/LexicalHandler.java:
- corrected property name in JavaDoc
- added
http://xml.org/sax/features/lexical-handler/parameter-entities
feature to JavaDoc
* src/org/xml/sax/ext/DeclHandler.java:
- corrected property name in JavaDoc
1.1 xml-commons/java/external/README-sax
Index: README-sax
===================================================================
SAX 2.0 r2 prerelease
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 release includes a simple test application in src/SAXTest.java.
A build.xml file is included for users of Apache's ant build tool (a
Java-based Makefile substitute).
sax@megginson.com
====
SAX2-ext 1.0
This module is in the PUBLIC DOMAIN, and comes with NO WARRANTY of any
kind.
This is the 1.0 release of SAX2-ext, an extension package for the
second generation of the Simple API for XML. Please send comments and
bug reports to sax@megginson.com before Monday 2 October 2000.
For more information about the package, please see docs/index.html.
A build.xml file is included for the Apache project's "ant" project
management tool.
David Megginson, david@megginson.com
2000-10-04
1.1 xml-commons/java/external/build-sax.xml
Index: build-sax.xml
===================================================================
<?xml version="1.0"?>
<!-- Proposed Minimal build script for combo of:
SAX 2.0 r2 prerelease
SAX2-ext 1.0
@author David Megginson, david@megginson.com
@author shane_curcuru@lotus.com
-->
<project name="sax2-and-ext" default="jar" basedir=".">
<property name="external-module" value="SAX 2.0 r2 prerelease and SAX2-ext 1.0" />
<property name="src.dir" value="src" />
<property name="docs.dir" value="xdocs/sax" />
<property name="build.dir" value="build" />
<property name="build.classes.dir" value="${build.dir}/classes" />
<property name="build.docs.dir" value="${build.dir}/docs" />
<property name="build.javadocs.dir" value="${build.docs.dir}/javadoc" />
<property name="sax.jar.location" value="${build.dir}" />
<property name="sax.jar.name" value="commons-sax.jar" />
<property name="sax.jar" value="${sax.jar.location}/${sax.jar.name}" />
<target name="prepare"
description="Create build output directories">
<mkdir dir="${build.classes.dir}" />
<mkdir dir="${build.docs.dir}" />
<mkdir dir="${build.javadocs.dir}" />
</target>
<target name="compile" depends="prepare"
description="Compile all SAX and helper classes">
<javac srcdir="${src.dir}" destdir="${build.classes.dir}" />
</target>
<target name="jar" depends="compile"
description="Jar all SAX and helper classes">
<jar jarfile="${sax.jar}" basedir="${build.classes.dir}" />
</target>
<target name="javadoc" depends="prepare"
description="Build javadocs and copy doc over">
<javadoc packagenames="org.xml.sax.*"
sourcepath="${src.dir}"
destdir="${build.javadocs.dir}"
version="yes"
windowtitle="${external-module}"
doctitle="${external-module}"
bottom="This document is in the PUBLIC DOMAIN and comes with NO WARRANTY of any kind."
/>
<!-- Just copy existing .html files over as well -->
<copy todir="${build.docs.dir}">
<fileset dir="${docs.dir}"/>
</copy>
</target>
<target name="clean"
description="Clean the output build area">
<delete file="${sax.jar}"/>
<delete dir="${build.dir}"/>
</target>
</project>
1.1 xml-commons/java/external/src/org/xml/sax/AttributeList.java
Index: AttributeList.java
===================================================================
// SAX Attribute List Interface.
// No warranty; no copyright -- use this as you will.
// $Id: AttributeList.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Interface for an element's attribute specifications.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This is the original SAX1 interface for reporting an element's
* attributes. Unlike the new {@link org.xml.sax.Attributes Attributes}
* interface, it does not support Namespace-related information.</p>
*
* <p>When an attribute list is supplied as part of a
* {@link org.xml.sax.DocumentHandler#startElement startElement}
* event, the list will return valid results only during the
* scope of the event; once the event handler returns control
* to the parser, the attribute list is invalid. To save a
* persistent copy of the attribute list, use the SAX1
* {@link org.xml.sax.helpers.AttributeListImpl AttributeListImpl}
* helper class.</p>
*
* <p>An attribute list includes only attributes that have been
* specified or defaulted: #IMPLIED attributes will not be included.</p>
*
* <p>There are two ways for the SAX application to obtain information
* from the AttributeList. First, it can iterate through the entire
* list:</p>
*
* <pre>
* public void startElement (String name, AttributeList atts) {
* for (int i = 0; i < atts.getLength(); i++) {
* String name = atts.getName(i);
* String type = atts.getType(i);
* String value = atts.getValue(i);
* [...]
* }
* }
* </pre>
*
* <p>(Note that the result of getLength() will be zero if there
* are no attributes.)
*
* <p>As an alternative, the application can request the value or
* type of specific attributes:</p>
*
* <pre>
* public void startElement (String name, AttributeList atts) {
* String identifier = atts.getValue("id");
* String label = atts.getValue("label");
* [...]
* }
* </pre>
*
* @deprecated This interface has been replaced by the SAX2
* {@link org.xml.sax.Attributes Attributes}
* interface, which includes Namespace support.
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.DocumentHandler#startElement startElement
* @see org.xml.sax.helpers.AttributeListImpl AttributeListImpl
*/
public interface AttributeList {
////////////////////////////////////////////////////////////////////
// Iteration methods.
////////////////////////////////////////////////////////////////////
/**
* Return the number of attributes in this list.
*
* <p>The SAX parser may provide attributes in any
* arbitrary order, regardless of the order in which they were
* declared or specified. The number of attributes may be
* zero.</p>
*
* @return The number of attributes in the list.
*/
public abstract int getLength ();
/**
* Return the name of an attribute in this list (by position).
*
* <p>The names must be unique: the SAX parser shall not include the
* same attribute twice. Attributes without values (those declared
* #IMPLIED without a value specified in the start tag) will be
* omitted from the list.</p>
*
* <p>If the attribute name has a namespace prefix, the prefix
* will still be attached.</p>
*
* @param i The index of the attribute in the list (starting at 0).
* @return The name of the indexed attribute, or null
* if the index is out of range.
* @see #getLength
*/
public abstract String getName (int i);
/**
* Return the type of an attribute in the list (by position).
*
* <p>The attribute type is one of the strings "CDATA", "ID",
* "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
* or "NOTATION" (always in upper case).</p>
*
* <p>If the parser has not read a declaration for the attribute,
* or if the parser does not report attribute types, then it must
* return the value "CDATA" as stated in the XML 1.0 Recommentation
* (clause 3.3.3, "Attribute-Value Normalization").</p>
*
* <p>For an enumerated attribute that is not a notation, the
* parser will report the type as "NMTOKEN".</p>
*
* @param i The index of the attribute in the list (starting at 0).
* @return The attribute type as a string, or
* null if the index is out of range.
* @see #getLength
* @see #getType(java.lang.String)
*/
public abstract String getType (int i);
/**
* Return the value of an attribute in the list (by position).
*
* <p>If the attribute value is a list of tokens (IDREFS,
* ENTITIES, or NMTOKENS), the tokens will be concatenated
* into a single string separated by whitespace.</p>
*
* @param i The index of the attribute in the list (starting at 0).
* @return The attribute value as a string, or
* null if the index is out of range.
* @see #getLength
* @see #getValue(java.lang.String)
*/
public abstract String getValue (int i);
////////////////////////////////////////////////////////////////////
// Lookup methods.
////////////////////////////////////////////////////////////////////
/**
* Return the type of an attribute in the list (by name).
*
* <p>The return value is the same as the return value for
* getType(int).</p>
*
* <p>If the attribute name has a namespace prefix in the document,
* the application must include the prefix here.</p>
*
* @param name The name of the attribute.
* @return The attribute type as a string, or null if no
* such attribute exists.
* @see #getType(int)
*/
public abstract String getType (String name);
/**
* Return the value of an attribute in the list (by name).
*
* <p>The return value is the same as the return value for
* getValue(int).</p>
*
* <p>If the attribute name has a namespace prefix in the document,
* the application must include the prefix here.</p>
*
* @param i The index of the attribute in the list.
* @return The attribute value as a string, or null if
* no such attribute exists.
* @see #getValue(int)
*/
public abstract String getValue (String name);
}
// end of AttributeList.java
1.1 xml-commons/java/external/src/org/xml/sax/Attributes.java
Index: Attributes.java
===================================================================
// Attributes.java - attribute list with Namespace support
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the public domain.
// $Id: Attributes.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Interface for a list of XML attributes.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This interface allows access to a list of attributes in
* three different ways:</p>
*
* <ol>
* <li>by attribute index;</li>
* <li>by Namespace-qualified name; or</li>
* <li>by qualified (prefixed) name.</li>
* </ol>
*
* <p>The list will not contain attributes that were declared
* #IMPLIED but not specified in the start tag. It will also not
* contain attributes used as Namespace declarations (xmlns*) unless
* the <code>http://xml.org/sax/features/namespace-prefixes</code>
* feature is set to <var>true</var> (it is <var>false</var> by
* default).</p>
*
* <p>If the namespace-prefixes feature (see above) is <var>false</var>,
* access by qualified name may not be available; if the
* <code>http://xml.org/sax/features/namespaces</code>
* feature is <var>false</var>, access by Namespace-qualified names
* may not be available.</p>
*
* <p>This interface replaces the now-deprecated SAX1 {@link
* org.xml.sax.AttributeList AttributeList} interface, which does not
* contain Namespace support. In addition to Namespace support, it
* adds the <var>getIndex</var> methods (below).</p>
*
* <p>The order of attributes in the list is unspecified, and will
* vary from implementation to implementation.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.helpers.AttributeListImpl
*/
public interface Attributes
{
////////////////////////////////////////////////////////////////////
// Indexed access.
////////////////////////////////////////////////////////////////////
/**
* Return the number of attributes in the list.
*
* <p>Once you know the number of attributes, you can iterate
* through the list.</p>
*
* @return The number of attributes in the list.
* @see #getURI(int)
* @see #getLocalName(int)
* @see #getQName(int)
* @see #getType(int)
* @see #getValue(int)
*/
public abstract int getLength ();
/**
* Look up an attribute's Namespace URI by index.
*
* @param index The attribute index (zero-based).
* @return The Namespace URI, or the empty string if none
* is available, or null if the index is out of
* range.
* @see #getLength
*/
public abstract String getURI (int index);
/**
* Look up an attribute's local name by index.
*
* @param index The attribute index (zero-based).
* @return The local name, or the empty string if Namespace
* processing is not being performed, or null
* if the index is out of range.
* @see #getLength
*/
public abstract String getLocalName (int index);
/**
* Look up an attribute's XML 1.0 qualified name by index.
*
* @param index The attribute index (zero-based).
* @return The XML 1.0 qualified name, or the empty string
* if none is available, or null if the index
* is out of range.
* @see #getLength
*/
public abstract String getQName (int index);
/**
* Look up an attribute's type by index.
*
* <p>The attribute type is one of the strings "CDATA", "ID",
* "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY", "ENTITIES",
* or "NOTATION" (always in upper case).</p>
*
* <p>If the parser has not read a declaration for the attribute,
* or if the parser does not report attribute types, then it must
* return the value "CDATA" as stated in the XML 1.0 Recommentation
* (clause 3.3.3, "Attribute-Value Normalization").</p>
*
* <p>For an enumerated attribute that is not a notation, the
* parser will report the type as "NMTOKEN".</p>
*
* @param index The attribute index (zero-based).
* @return The attribute's type as a string, or null if the
* index is out of range.
* @see #getLength
*/
public abstract String getType (int index);
/**
* Look up an attribute's value by index.
*
* <p>If the attribute value is a list of tokens (IDREFS,
* ENTITIES, or NMTOKENS), the tokens will be concatenated
* into a single string with each token separated by a
* single space.</p>
*
* @param index The attribute index (zero-based).
* @return The attribute's value as a string, or null if the
* index is out of range.
* @see #getLength
*/
public abstract String getValue (int index);
////////////////////////////////////////////////////////////////////
// Name-based query.
////////////////////////////////////////////////////////////////////
/**
* Look up the index of an attribute by Namespace name.
*
* @param uri The Namespace URI, or the empty string if
* the name has no Namespace URI.
* @param localName The attribute's local name.
* @return The index of the attribute, or -1 if it does not
* appear in the list.
*/
public int getIndex (String uri, String localName);
/**
* Look up the index of an attribute by XML 1.0 qualified name.
*
* @param qName The qualified (prefixed) name.
* @return The index of the attribute, or -1 if it does not
* appear in the list.
*/
public int getIndex (String qName);
/**
* Look up an attribute's type by Namespace name.
*
* <p>See {@link #getType(int) getType(int)} for a description
* of the possible types.</p>
*
* @param uri The Namespace URI, or the empty String if the
* name has no Namespace URI.
* @param localName The local name of the attribute.
* @return The attribute type as a string, or null if the
* attribute is not in the list or if Namespace
* processing is not being performed.
*/
public abstract String getType (String uri, String localName);
/**
* Look up an attribute's type by XML 1.0 qualified name.
*
* <p>See {@link #getType(int) getType(int)} for a description
* of the possible types.</p>
*
* @param qName The XML 1.0 qualified name.
* @return The attribute type as a string, or null if the
* attribute is not in the list or if qualified names
* are not available.
*/
public abstract String getType (String qName);
/**
* Look up an attribute's value by Namespace name.
*
* <p>See {@link #getValue(int) getValue(int)} for a description
* of the possible values.</p>
*
* @param uri The Namespace URI, or the empty String if the
* name has no Namespace URI.
* @param localName The local name of the attribute.
* @return The attribute value as a string, or null if the
* attribute is not in the list.
*/
public abstract String getValue (String uri, String localName);
/**
* Look up an attribute's value by XML 1.0 qualified name.
*
* <p>See {@link #getValue(int) getValue(int)} for a description
* of the possible values.</p>
*
* @param qName The XML 1.0 qualified name.
* @return The attribute value as a string, or null if the
* attribute is not in the list or if qualified names
* are not available.
*/
public abstract String getValue (String qName);
}
// end of Attributes.java
1.1 xml-commons/java/external/src/org/xml/sax/ContentHandler.java
Index: ContentHandler.java
===================================================================
// ContentHandler.java - handle main document content.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the public domain.
// $Id: ContentHandler.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Receive notification of the logical content of a document.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This is the main interface that most SAX applications
* implement: if the application needs to be informed of basic parsing
* events, it implements this interface and registers an instance with
* the SAX parser using the {@link org.xml.sax.XMLReader#setContentHandler
* setContentHandler} method. The parser uses the instance to report
* basic document-related events like the start and end of elements
* and character data.</p>
*
* <p>The order of events in this interface is very important, and
* mirrors the order of information in the document itself. For
* example, all of an element's content (character data, processing
* instructions, and/or subelements) will appear, in order, between
* the startElement event and the corresponding endElement event.</p>
*
* <p>This interface is similar to the now-deprecated SAX 1.0
* DocumentHandler interface, but it adds support for Namespaces
* and for reporting skipped entities (in non-validating XML
* processors).</p>
*
* <p>Implementors should note that there is also a Java class
* {@link java.net.ContentHandler ContentHandler} in the java.net
* package; that means that it's probably a bad idea to do</p>
*
* <blockquote>
* import java.net.*;
* import org.xml.sax.*;
* </blockquote>
*
* <p>In fact, "import ...*" is usually a sign of sloppy programming
* anyway, so the user should consider this a feature rather than a
* bug.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.XMLReader
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.ErrorHandler
*/
public interface ContentHandler
{
/**
* Receive an object for locating the origin of SAX document events.
*
* <p>SAX parsers are strongly encouraged (though not absolutely
* required) to supply a locator: if it does so, it must supply
* the locator to the application by invoking this method before
* invoking any of the other methods in the ContentHandler
* interface.</p>
*
* <p>The locator allows the application to determine the end
* position of any document-related event, even if the parser is
* not reporting an error. Typically, the application will
* use this information for reporting its own errors (such as
* character content that does not match an application's
* business rules). The information returned by the locator
* is probably not sufficient for use with a search engine.</p>
*
* <p>Note that the locator will return correct information only
* during the invocation of the events in this interface. The
* application should not attempt to use it at any other time.</p>
*
* @param locator An object that can return the location of
* any SAX document event.
* @see org.xml.sax.Locator
*/
public void setDocumentLocator (Locator locator);
/**
* Receive notification of the beginning of a document.
*
* <p>The SAX parser will invoke this method only once, before any
* other methods in this interface or in {@link org.xml.sax.DTDHandler
* DTDHandler} (except for {@link #setDocumentLocator
* setDocumentLocator}).</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #endDocument
*/
public void startDocument ()
throws SAXException;
/**
* Receive notification of the end of a document.
*
* <p>The SAX parser will invoke this method only once, and it will
* be the last method invoked during the parse. The parser shall
* not invoke this method until it has either abandoned parsing
* (because of an unrecoverable error) or reached the end of
* input.</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #startDocument
*/
public void endDocument()
throws SAXException;
/**
* Begin the scope of a prefix-URI Namespace mapping.
*
* <p>The information from this event is not necessary for
* normal Namespace processing: the SAX XML reader will
* automatically replace prefixes for element and attribute
* names when the <code>http://xml.org/sax/features/namespaces</code>
* feature is <var>true</var> (the default).</p>
*
* <p>There are cases, however, when applications need to
* use prefixes in character data or in attribute values,
* where they cannot safely be expanded automatically; the
* start/endPrefixMapping event supplies the information
* to the application to expand prefixes in those contexts
* itself, if necessary.</p>
*
* <p>Note that start/endPrefixMapping events are not
* guaranteed to be properly nested relative to each-other:
* all startPrefixMapping events will occur before the
* 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
* guaranteed.</p>
*
* <p>There should never be start/endPrefixMapping events for the
* "xml" prefix, since it is predeclared and immutable.</p>
*
* @param prefix The Namespace prefix being declared.
* @param uri The Namespace URI the prefix is mapped to.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
* @see #endPrefixMapping
* @see #startElement
*/
public void startPrefixMapping (String prefix, String uri)
throws SAXException;
/**
* End the scope of a prefix-URI mapping.
*
* <p>See {@link #startPrefixMapping startPrefixMapping} for
* details. This event will always occur after the corresponding
* {@link #endElement endElement} event, but the order of
* {@link #endPrefixMapping endPrefixMapping} events is not otherwise
* guaranteed.</p>
*
* @param prefix The prefix that was being mapping.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
* @see #startPrefixMapping
* @see #endElement
*/
public void endPrefixMapping (String prefix)
throws SAXException;
/**
* Receive notification of the beginning of an element.
*
* <p>The Parser will invoke this method at the beginning of every
* element in the XML document; there will be a corresponding
* {@link #endElement endElement} event for every startElement event
* (even when the element is empty). All of the element's content will be
* reported, in order, before the corresponding endElement
* event.</p>
*
* <p>This event allows up to three name components for each
* element:</p>
*
* <ol>
* <li>the Namespace URI;</li>
* <li>the local name; and</li>
* <li>the qualified (prefixed) name.</li>
* </ol>
*
* <p>Any or all of these may be provided, depending on the
* values of the <var>http://xml.org/sax/features/namespaces</var>
* and the <var>http://xml.org/sax/features/namespace-prefixes</var>
* properties:</p>
*
* <ul>
* <li>the Namespace URI and local name are required when
* the namespaces property is <var>true</var> (the default), and are
* optional when the namespaces property is <var>false</var> (if one is
* specified, both must be);</li>
* <li>the qualified name is required when the namespace-prefixes property
* is <var>true</var>, and is optional when the namespace-prefixes property
* is <var>false</var> (the default).</li>
* </ul>
*
* <p>Note that the attribute list provided will contain only
* attributes with explicit values (specified or defaulted):
* #IMPLIED attributes will be omitted. The attribute list
* will contain attributes used for Namespace declarations
* (xmlns* attributes) only if the
* <code>http://xml.org/sax/features/namespace-prefixes</code>
* property is true (it is false by default, and support for a
* true value is optional).</p>
*
* @param uri The Namespace URI, or the empty string if the
* element has no Namespace URI or if Namespace
* processing is not being performed.
* @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 #endElement
* @see org.xml.sax.Attributes
*/
public void startElement (String namespaceURI, String localName,
String qName, Attributes atts)
throws SAXException;
/**
* Receive notification of the end of an element.
*
* <p>The SAX parser will invoke this method at the end of every
* element in the XML document; there will be a corresponding
* {@link #startElement startElement} event for every endElement
* event (even when the element is empty).</p>
*
* <p>For information on the names, see startElement.</p>
*
* @param uri The Namespace URI, or the empty string if the
* element has no Namespace URI or if Namespace
* processing is not being performed.
* @param localName The local name (without prefix), or the
* empty string if Namespace processing is not being
* performed.
* @param qName The qualified XML 1.0 name (with prefix), or the
* empty string if qualified names are not available.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
*/
public void endElement (String namespaceURI, String localName,
String qName)
throws SAXException;
/**
* Receive notification of character data.
*
* <p>The Parser will call this method to report each chunk of
* character data. SAX parsers may return all contiguous character
* data in a single chunk, or they may split it into several
* chunks; however, all of the characters in any single event
* must come from the same external entity so that the Locator
* provides useful information.</p>
*
* <p>The application must not attempt to read from the array
* outside of the specified range.</p>
*
* <p>Note that some parsers will report whitespace in element
* content using the {@link #ignorableWhitespace ignorableWhitespace}
* method rather than this one (validating parsers <em>must</em>
* do so).</p>
*
* @param ch The characters from the XML document.
* @param start The start position in the array.
* @param length The number of characters to read from the array.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #ignorableWhitespace
* @see org.xml.sax.Locator
*/
public void characters (char ch[], int start, int length)
throws SAXException;
/**
* Receive notification of ignorable whitespace in element content.
*
* <p>Validating Parsers must use this method to report each chunk
* of whitespace in element content (see the W3C XML 1.0 recommendation,
* section 2.10): non-validating parsers may also use this method
* if they are capable of parsing and using content models.</p>
*
* <p>SAX parsers may return all contiguous whitespace in a single
* chunk, or they may split it into several chunks; however, all of
* the characters in any single event must come from the same
* external entity, so that the Locator provides useful
* information.</p>
*
* <p>The application must not attempt to read from the array
* outside of the specified range.</p>
*
* @param ch The characters from the XML document.
* @param start The start position in the array.
* @param length The number of characters to read from the array.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #characters
*/
public void ignorableWhitespace (char ch[], int start, int length)
throws SAXException;
/**
* Receive notification of a processing instruction.
*
* <p>The Parser will invoke this method once for each processing
* instruction found: note that processing instructions may occur
* before or after the main document element.</p>
*
* <p>A SAX parser must never report an XML declaration (XML 1.0,
* section 2.8) or a text declaration (XML 1.0, section 4.3.1)
* using this method.</p>
*
* @param target The processing instruction target.
* @param data The processing instruction data, or null if
* none was supplied. The data does not include any
* whitespace separating it from the target.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
*/
public void processingInstruction (String target, String data)
throws SAXException;
/**
* Receive notification of a skipped entity.
*
* <p>The Parser will invoke this method once for each entity
* 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
* may skip external entities, depending on the values of the
* <code>http://xml.org/sax/features/external-general-entities</code>
* and the
* <code>http://xml.org/sax/features/external-parameter-entities</code>
* properties.</p>
*
* @param name The name of the skipped entity. If it is a
* parameter entity, the name will begin with '%', and if
* it is the external DTD subset, it will be the string
* "[dtd]".
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
*/
public void skippedEntity (String name)
throws SAXException;
}
// end of ContentHandler.java
1.1 xml-commons/java/external/src/org/xml/sax/DTDHandler.java
Index: DTDHandler.java
===================================================================
// SAX DTD handler.
// No warranty; no copyright -- use this as you will.
// $Id: DTDHandler.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Receive notification of basic DTD-related events.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>If a SAX application needs information about notations and
* unparsed entities, then the application implements this
* interface and registers an instance with the SAX parser using
* the parser's setDTDHandler method. The parser uses the
* instance to report notation and unparsed entity declarations to
* the application.</p>
*
* <p>Note that this interface includes only those DTD events that
* the XML recommendation <em>requires</em> processors to report:
* notation and unparsed entity declarations.</p>
*
* <p>The SAX parser may report these events in any order, regardless
* of the order in which the notations and unparsed entities were
* declared; however, all DTD events must be reported after the
* document handler's startDocument event, and before the first
* startElement event.</p>
*
* <p>It is up to the application to store the information for
* future use (perhaps in a hash table or object tree).
* If the application encounters attributes of type "NOTATION",
* "ENTITY", or "ENTITIES", it can use the information that it
* obtained through this interface to find the entity and/or
* notation corresponding with the attribute value.</p>
*
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.Parser#setDTDHandler
* @see org.xml.sax.HandlerBase
*/
public interface DTDHandler {
/**
* Receive notification of a notation declaration event.
*
* <p>It is up to the application to record the notation for later
* reference, if necessary.</p>
*
* <p>At least one of publicId and systemId must be non-null.
* If a system identifier is present, and it is a URL, the SAX
* parser must resolve it fully before passing it to the
* application through this event.</p>
*
* <p>There is no guarantee that the notation declaration will be
* reported before any unparsed entities that use it.</p>
*
* @param name The notation name.
* @param publicId The notation's public identifier, or null if
* none was given.
* @param systemId The notation's system identifier, or null if
* none was given.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #unparsedEntityDecl
* @see org.xml.sax.AttributeList
*/
public abstract void notationDecl (String name,
String publicId,
String systemId)
throws SAXException;
/**
* Receive notification of an unparsed entity declaration event.
*
* <p>Note that the notation name corresponds to a notation
* reported by the {@link #notationDecl notationDecl} event.
* It is up to the application to record the entity for later
* reference, if necessary.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before passing it to the application.</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @param name The unparsed entity's name.
* @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.
* @see #notationDecl
* @see org.xml.sax.AttributeList
*/
public abstract void unparsedEntityDecl (String name,
String publicId,
String systemId,
String notationName)
throws SAXException;
}
// end of DTDHandler.java
1.1 xml-commons/java/external/src/org/xml/sax/DocumentHandler.java
Index: DocumentHandler.java
===================================================================
// SAX document handler.
// No warranty; no copyright -- use this as you will.
// $Id: DocumentHandler.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Receive notification of general document events.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This was the main event-handling interface for SAX1; in
* SAX2, it has been replaced by {@link org.xml.sax.ContentHandler
* ContentHandler}, which provides Namespace support and reporting
* of skipped entities. This interface is included in SAX2 only
* to support legacy SAX1 applications.</p>
*
* <p>The order of events in this interface is very important, and
* mirrors the order of information in the document itself. For
* example, all of an element's content (character data, processing
* instructions, and/or subelements) will appear, in order, between
* the startElement event and the corresponding endElement event.</p>
*
* <p>Application writers who do not want to implement the entire
* interface can derive a class from HandlerBase, which implements
* the default functionality; parser writers can instantiate
* HandlerBase to obtain a default handler. The application can find
* the location of any document event using the Locator interface
* supplied by the Parser through the setDocumentLocator method.</p>
*
* @deprecated This interface has been replaced by the SAX2
* {@link org.xml.sax.ContentHandler ContentHandler}
* interface, which includes Namespace support.
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.Parser#setDocumentHandler
* @see org.xml.sax.Locator
* @see org.xml.sax.HandlerBase
*/
public interface DocumentHandler {
/**
* Receive an object for locating the origin of SAX document events.
*
* <p>SAX parsers are strongly encouraged (though not absolutely
* required) to supply a locator: if it does so, it must supply
* the locator to the application by invoking this method before
* invoking any of the other methods in the DocumentHandler
* interface.</p>
*
* <p>The locator allows the application to determine the end
* position of any document-related event, even if the parser is
* not reporting an error. Typically, the application will
* use this information for reporting its own errors (such as
* character content that does not match an application's
* business rules). The information returned by the locator
* is probably not sufficient for use with a search engine.</p>
*
* <p>Note that the locator will return correct information only
* during the invocation of the events in this interface. The
* application should not attempt to use it at any other time.</p>
*
* @param locator An object that can return the location of
* any SAX document event.
* @see org.xml.sax.Locator
*/
public abstract void setDocumentLocator (Locator locator);
/**
* Receive notification of the beginning of a document.
*
* <p>The SAX parser will invoke this method only once, before any
* other methods in this interface or in DTDHandler (except for
* setDocumentLocator).</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
*/
public abstract void startDocument ()
throws SAXException;
/**
* Receive notification of the end of a document.
*
* <p>The SAX parser will invoke this method only once, and it will
* be the last method invoked during the parse. The parser shall
* not invoke this method until it has either abandoned parsing
* (because of an unrecoverable error) or reached the end of
* input.</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
*/
public abstract void endDocument ()
throws SAXException;
/**
* Receive notification of the beginning of an element.
*
* <p>The Parser will invoke this method at the beginning of every
* element in the XML document; there will be a corresponding
* endElement() event for every startElement() event (even when the
* element is empty). All of the element's content will be
* reported, in order, before the corresponding endElement()
* event.</p>
*
* <p>If the element name has a namespace prefix, the prefix will
* still be attached. Note that the attribute list provided will
* contain only attributes with explicit values (specified or
* defaulted): #IMPLIED attributes will be omitted.</p>
*
* @param name The element type name.
* @param atts The attributes attached to the element, if any.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #endElement
* @see org.xml.sax.AttributeList
*/
public abstract void startElement (String name, AttributeList atts)
throws SAXException;
/**
* Receive notification of the end of an element.
*
* <p>The SAX parser will invoke this method at the end of every
* element in the XML document; there will be a corresponding
* startElement() event for every endElement() event (even when the
* element is empty).</p>
*
* <p>If the element name has a namespace prefix, the prefix will
* still be attached to the name.</p>
*
* @param name The element type name
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
*/
public abstract void endElement (String name)
throws SAXException;
/**
* Receive notification of character data.
*
* <p>The Parser will call this method to report each chunk of
* character data. SAX parsers may return all contiguous character
* data in a single chunk, or they may split it into several
* chunks; however, all of the characters in any single event
* must come from the same external entity, so that the Locator
* provides useful information.</p>
*
* <p>The application must not attempt to read from the array
* outside of the specified range.</p>
*
* <p>Note that some parsers will report whitespace using the
* ignorableWhitespace() method rather than this one (validating
* parsers must do so).</p>
*
* @param ch The characters from the XML document.
* @param start The start position in the array.
* @param length The number of characters to read from the array.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #ignorableWhitespace
* @see org.xml.sax.Locator
*/
public abstract void characters (char ch[], int start, int length)
throws SAXException;
/**
* Receive notification of ignorable whitespace in element content.
*
* <p>Validating Parsers must use this method to report each chunk
* of ignorable whitespace (see the W3C XML 1.0 recommendation,
* section 2.10): non-validating parsers may also use this method
* if they are capable of parsing and using content models.</p>
*
* <p>SAX parsers may return all contiguous whitespace in a single
* chunk, or they may split it into several chunks; however, all of
* the characters in any single event must come from the same
* external entity, so that the Locator provides useful
* information.</p>
*
* <p>The application must not attempt to read from the array
* outside of the specified range.</p>
*
* @param ch The characters from the XML document.
* @param start The start position in the array.
* @param length The number of characters to read from the array.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see #characters
*/
public abstract void ignorableWhitespace (char ch[], int start, int length)
throws SAXException;
/**
* Receive notification of a processing instruction.
*
* <p>The Parser will invoke this method once for each processing
* instruction found: note that processing instructions may occur
* before or after the main document element.</p>
*
* <p>A SAX parser should never report an XML declaration (XML 1.0,
* section 2.8) or a text declaration (XML 1.0, section 4.3.1)
* using this method.</p>
*
* @param target The processing instruction target.
* @param data The processing instruction data, or null if
* none was supplied.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
*/
public abstract void processingInstruction (String target, String data)
throws SAXException;
}
// end of DocumentHandler.java
1.1 xml-commons/java/external/src/org/xml/sax/EntityResolver.java
Index: EntityResolver.java
===================================================================
// SAX entity resolver.
// No warranty; no copyright -- use this as you will.
// $Id: EntityResolver.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
import java.io.IOException;
/**
* Basic interface for resolving entities.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>If a SAX application needs to implement customized handling
* for external entities, it must implement this interface and
* register an instance with the SAX driver using the
* {@link org.xml.sax.XMLReader#setEntityResolver setEntityResolver}
* method.</p>
*
* <p>The XML reader will then allow the application to intercept any
* external entities (including the external DTD subset and external
* parameter entities, if any) before including them.</p>
*
* <p>Many SAX applications will not need to implement this interface,
* but it will be especially useful for applications that build
* XML documents from databases or other specialised input sources,
* or for applications that use URI types other than URLs.</p>
*
* <p>The following resolver would provide the application
* with a special character stream for the entity with the system
* identifier "http://www.myhost.com/today":</p>
*
* <pre>
* import org.xml.sax.EntityResolver;
* import org.xml.sax.InputSource;
*
* public class MyResolver implements EntityResolver {
* public InputSource resolveEntity (String publicId, String systemId)
* {
* if (systemId.equals("http://www.myhost.com/today")) {
* // return a special input source
* MyReader reader = new MyReader();
* return new InputSource(reader);
* } else {
* // use the default behaviour
* return null;
* }
* }
* }
* </pre>
*
* <p>The application can also use this interface to redirect system
* identifiers to local URIs or to look up replacements in a catalog
* (possibly by using the public identifier).</p>
*
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.Parser#setEntityResolver
* @see org.xml.sax.InputSource
*/
public interface EntityResolver {
/**
* Allow the application to resolve external entities.
*
* <p>The Parser will call this method before opening any external
* entity except the top-level document entity (including the
* external DTD subset, external entities referenced within the
* DTD, and external entities referenced within the document
* element): the application may request that the parser resolve
* the entity itself, that it use an alternative URI, or that it
* use an entirely different input source.</p>
*
* <p>Application writers can use this method to redirect external
* system identifiers to secure and/or local URIs, to look up
* public identifiers in a catalogue, or to read an entity from a
* database or other input source (including, for example, a dialog
* box).</p>
*
* <p>If the system identifier is a URL, the SAX parser must
* resolve it fully before reporting it to the application.</p>
*
* @param publicId The public identifier of the external entity
* being referenced, or null if none was supplied.
* @param systemId The system identifier of the external entity
* being referenced.
* @return An InputSource object describing the new input source,
* or null to request that the parser open a regular
* URI connection to the system identifier.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @exception java.io.IOException A Java-specific IO exception,
* possibly the result of creating a new InputStream
* or Reader for the InputSource.
* @see org.xml.sax.InputSource
*/
public abstract InputSource resolveEntity (String publicId,
String systemId)
throws SAXException, IOException;
}
// end of EntityResolver.java
1.1 xml-commons/java/external/src/org/xml/sax/ErrorHandler.java
Index: ErrorHandler.java
===================================================================
// SAX error handler.
// No warranty; no copyright -- use this as you will.
// $Id: ErrorHandler.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Basic interface for SAX error handlers.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>If a SAX application needs to implement customized error
* handling, it must implement this interface and then register an
* instance with the XML reader using the
* {@link org.xml.sax.XMLReader#setErrorHandler setErrorHandler}
* method. The parser will then report all errors and warnings
* through this interface.</p>
*
* <p><strong>WARNING:</strong> If an application does <em>not</em>
* register an ErrorHandler, XML parsing errors will go unreported
* and bizarre behaviour may result.</p>
*
* <p>For XML processing errors, a SAX driver must use this interface
* instead of throwing an exception: it is up to the application
* to decide whether to throw an exception for different types of
* errors and warnings. Note, however, that there is no requirement that
* the parser continue to provide useful information after a call to
* {@link #fatalError fatalError} (in other words, a SAX driver class
* could catch an exception and report a fatalError).</p>
*
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.Parser#setErrorHandler
* @see org.xml.sax.SAXParseException
*/
public interface ErrorHandler {
/**
* Receive notification of a warning.
*
* <p>SAX parsers will use this method to report conditions that
* are not errors or fatal errors as defined by the XML 1.0
* recommendation. The default behaviour is to take no action.</p>
*
* <p>The SAX parser must continue to provide normal parsing events
* after invoking this method: it should still be possible for the
* application to process the document through to the end.</p>
*
* <p>Filters may use this method to report other, non-XML warnings
* as well.</p>
*
* @param exception The warning information encapsulated in a
* SAX parse exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.SAXParseException
*/
public abstract void warning (SAXParseException exception)
throws SAXException;
/**
* Receive notification of a recoverable error.
*
* <p>This corresponds to the definition of "error" in section 1.2
* of the W3C XML 1.0 Recommendation. For example, a validating
* parser would use this callback to report the violation of a
* validity constraint. The default behaviour is to take no
* action.</p>
*
* <p>The SAX parser must continue to provide normal parsing events
* after invoking this method: it should still be possible for the
* application to process the document through to the end. If the
* application cannot do so, then the parser should report a fatal
* error even if the XML 1.0 recommendation does not require it to
* do so.</p>
*
* <p>Filters may use this method to report other, non-XML errors
* as well.</p>
*
* @param exception The error information encapsulated in a
* SAX parse exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.SAXParseException
*/
public abstract void error (SAXParseException exception)
throws SAXException;
/**
* Receive notification of a non-recoverable error.
*
* <p>This corresponds to the definition of "fatal error" in
* section 1.2 of the W3C XML 1.0 Recommendation. For example, a
* parser would use this callback to report the violation of a
* well-formedness constraint.</p>
*
* <p>The application must assume that the document is unusable
* after the parser has invoked this method, and should continue
* (if at all) only for the sake of collecting addition error
* messages: in fact, SAX parsers are free to stop reporting any
* other events once this method has been invoked.</p>
*
* @param exception The error information encapsulated in a
* SAX parse exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.SAXParseException
*/
public abstract void fatalError (SAXParseException exception)
throws SAXException;
}
// end of ErrorHandler.java
1.1 xml-commons/java/external/src/org/xml/sax/HandlerBase.java
Index: HandlerBase.java
===================================================================
// SAX default handler base class.
// No warranty; no copyright -- use this as you will.
// $Id: HandlerBase.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Default base class for handlers.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class implements the default behaviour for four SAX1
* interfaces: EntityResolver, DTDHandler, DocumentHandler,
* and ErrorHandler. It is now obsolete, but is included in SAX2 to
* support legacy SAX1 applications. SAX2 applications should use
* the {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
* class instead.</p>
*
* <p>Application writers can extend this class when they need to
* implement only part of an interface; parser writers can
* instantiate this class to provide default handlers when the
* application has not supplied its own.</p>
*
* <p>Note that the use of this class is optional.</p>
*
* @deprecated This class works with the deprecated
* {@link org.xml.sax.DocumentHandler DocumentHandler}
* interface. It has been replaced by the SAX2
* {@link org.xml.sax.helpers.DefaultHandler DefaultHandler}
* class.
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.EntityResolver
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.DocumentHandler
* @see org.xml.sax.ErrorHandler
*/
public class HandlerBase
implements EntityResolver, DTDHandler, DocumentHandler, ErrorHandler
{
////////////////////////////////////////////////////////////////////
// Default implementation of the EntityResolver interface.
////////////////////////////////////////////////////////////////////
/**
* Resolve an external entity.
*
* <p>Always return null, so that the parser will use the system
* identifier provided in the XML document. This method implements
* the SAX default behaviour: application writers can override it
* in a subclass to do special translations such as catalog lookups
* or URI redirection.</p>
*
* @param publicId The public identifer, or null if none is
* available.
* @param systemId The system identifier provided in the XML
* document.
* @return The new input source, or null to require the
* default behaviour.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.EntityResolver#resolveEntity
*/
public InputSource resolveEntity (String publicId, String systemId)
throws SAXException
{
return null;
}
////////////////////////////////////////////////////////////////////
// Default implementation of DTDHandler interface.
////////////////////////////////////////////////////////////////////
/**
* Receive notification of a notation declaration.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass if they wish to keep track of the notations
* declared in a document.</p>
*
* @param name The notation name.
* @param publicId The notation public identifier, or null if not
* available.
* @param systemId The notation system identifier.
* @see org.xml.sax.DTDHandler#notationDecl
*/
public void notationDecl (String name, String publicId, String systemId)
{
// no op
}
/**
* Receive notification of an unparsed entity declaration.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to keep track of the unparsed entities
* declared in a document.</p>
*
* @param name The entity name.
* @param publicId The entity public identifier, or null if not
* available.
* @param systemId The entity system identifier.
* @param notationName The name of the associated notation.
* @see org.xml.sax.DTDHandler#unparsedEntityDecl
*/
public void unparsedEntityDecl (String name, String publicId,
String systemId, String notationName)
{
// no op
}
////////////////////////////////////////////////////////////////////
// Default implementation of DocumentHandler interface.
////////////////////////////////////////////////////////////////////
/**
* Receive a Locator object for document events.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass if they wish to store the locator for use
* with other document events.</p>
*
* @param locator A locator for all SAX document events.
* @see org.xml.sax.DocumentHandler#setDocumentLocator
* @see org.xml.sax.Locator
*/
public void setDocumentLocator (Locator locator)
{
// no op
}
/**
* Receive notification of the beginning of the document.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the beginning
* of a document (such as allocating the root node of a tree or
* creating an output file).</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DocumentHandler#startDocument
*/
public void startDocument ()
throws SAXException
{
// no op
}
/**
* Receive notification of the end of the document.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the beginning
* of a document (such as finalising a tree or closing an output
* file).</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DocumentHandler#endDocument
*/
public void endDocument ()
throws SAXException
{
// no op
}
/**
* Receive notification of the start of an element.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the start of
* each element (such as allocating a new tree node or writing
* output to a file).</p>
*
* @param name The element type name.
* @param attributes The specified or defaulted attributes.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DocumentHandler#startElement
*/
public void startElement (String name, AttributeList attributes)
throws SAXException
{
// no op
}
/**
* Receive notification of the end of an element.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the end of
* each element (such as finalising a tree node or writing
* output to a file).</p>
*
* @param name The element type name.
* @param attributes The specified or defaulted attributes.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DocumentHandler#endElement
*/
public void endElement (String name)
throws SAXException
{
// no op
}
/**
* Receive notification of character data inside an element.
*
* <p>By default, do nothing. Application writers may override this
* method to take specific actions for each chunk of character data
* (such as adding the data to a node or buffer, or printing it to
* a file).</p>
*
* @param ch The characters.
* @param start The start position in the character array.
* @param length The number of characters to use from the
* character array.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DocumentHandler#characters
*/
public void characters (char ch[], int start, int length)
throws SAXException
{
// no op
}
/**
* Receive notification of ignorable whitespace in element content.
*
* <p>By default, do nothing. Application writers may override this
* method to take specific actions for each chunk of ignorable
* whitespace (such as adding data to a node or buffer, or printing
* it to a file).</p>
*
* @param ch The whitespace characters.
* @param start The start position in the character array.
* @param length The number of characters to use from the
* character array.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DocumentHandler#ignorableWhitespace
*/
public void ignorableWhitespace (char ch[], int start, int length)
throws SAXException
{
// no op
}
/**
* Receive notification of a processing instruction.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions for each
* processing instruction, such as setting status variables or
* invoking other methods.</p>
*
* @param target The processing instruction target.
* @param data The processing instruction data, or null if
* none is supplied.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DocumentHandler#processingInstruction
*/
public void processingInstruction (String target, String data)
throws SAXException
{
// no op
}
////////////////////////////////////////////////////////////////////
// Default implementation of the ErrorHandler interface.
////////////////////////////////////////////////////////////////////
/**
* Receive notification of a parser warning.
*
* <p>The default implementation does nothing. Application writers
* may override this method in a subclass to take specific actions
* for each warning, such as inserting the message in a log file or
* printing it to the console.</p>
*
* @param e The warning information encoded as an exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ErrorHandler#warning
* @see org.xml.sax.SAXParseException
*/
public void warning (SAXParseException e)
throws SAXException
{
// no op
}
/**
* Receive notification of a recoverable parser error.
*
* <p>The default implementation does nothing. Application writers
* may override this method in a subclass to take specific actions
* for each error, such as inserting the message in a log file or
* printing it to the console.</p>
*
* @param e The warning information encoded as an exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ErrorHandler#warning
* @see org.xml.sax.SAXParseException
*/
public void error (SAXParseException e)
throws SAXException
{
// no op
}
/**
* Report a fatal XML parsing error.
*
* <p>The default implementation throws a SAXParseException.
* Application writers may override this method in a subclass if
* they need to take specific actions for each fatal error (such as
* collecting all of the errors into a single report): in any case,
* the application must stop all regular processing when this
* method is invoked, since the document is no longer reliable, and
* the parser may no longer report parsing events.</p>
*
* @param e The error information encoded as an exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ErrorHandler#fatalError
* @see org.xml.sax.SAXParseException
*/
public void fatalError (SAXParseException e)
throws SAXException
{
throw e;
}
}
// end of HandlerBase.java
1.1 xml-commons/java/external/src/org/xml/sax/InputSource.java
Index: InputSource.java
===================================================================
// SAX input source.
// No warranty; no copyright -- use this as you will.
// $Id: InputSource.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
import java.io.Reader;
import java.io.InputStream;
/**
* A single input source for an XML entity.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class allows a SAX application to encapsulate information
* about an input source in a single object, which may include
* a public identifier, a system identifier, a byte stream (possibly
* with a specified encoding), and/or a character stream.</p>
*
* <p>There are two places that the application will deliver this
* input source to the parser: as the argument to the Parser.parse
* method, or as the return value of the EntityResolver.resolveEntity
* method.</p>
*
* <p>The SAX parser will use the InputSource object to determine how
* to read XML input. If there is a character stream available, the
* parser will read that stream directly; if not, the parser will use
* a byte stream, if available; if neither a character stream nor a
* byte stream is available, the parser will attempt to open a URI
* connection to the resource identified by the system
* identifier.</p>
*
* <p>An InputSource object belongs to the application: the SAX parser
* shall never modify it in any way (it may modify a copy if
* necessary).</p>
*
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.Parser#parse
* @see org.xml.sax.EntityResolver#resolveEntity
* @see java.io.InputStream
* @see java.io.Reader
*/
public class InputSource {
/**
* Zero-argument default constructor.
*
* @see #setPublicId
* @see #setSystemId
* @see #setByteStream
* @see #setCharacterStream
* @see #setEncoding
*/
public InputSource ()
{
}
/**
* Create a new input source with a system identifier.
*
* <p>Applications may use setPublicId to include a
* public identifier as well, or setEncoding to specify
* the character encoding, if known.</p>
*
* <p>If the system identifier is a URL, it must be full resolved.</p>
*
* @param systemId The system identifier (URI).
* @see #setPublicId
* @see #setSystemId
* @see #setByteStream
* @see #setEncoding
* @see #setCharacterStream
*/
public InputSource (String systemId)
{
setSystemId(systemId);
}
/**
* Create a new input source with a byte stream.
*
* <p>Application writers may use setSystemId to provide a base
* for resolving relative URIs, setPublicId to include a
* public identifier, and/or setEncoding to specify the object's
* character encoding.</p>
*
* @param byteStream The raw byte stream containing the document.
* @see #setPublicId
* @see #setSystemId
* @see #setEncoding
* @see #setByteStream
* @see #setCharacterStream
*/
public InputSource (InputStream byteStream)
{
setByteStream(byteStream);
}
/**
* Create a new input source with a character stream.
*
* <p>Application writers may use setSystemId() to provide a base
* for resolving relative URIs, and setPublicId to include a
* public identifier.</p>
*
* <p>The character stream shall not include a byte order mark.</p>
*
* @see #setPublicId
* @see #setSystemId
* @see #setByteStream
* @see #setCharacterStream
*/
public InputSource (Reader characterStream)
{
setCharacterStream(characterStream);
}
/**
* Set the public identifier for this input source.
*
* <p>The public identifier is always optional: if the application
* writer includes one, it will be provided as part of the
* location information.</p>
*
* @param publicId The public identifier as a string.
* @see #getPublicId
* @see org.xml.sax.Locator#getPublicId
* @see org.xml.sax.SAXParseException#getPublicId
*/
public void setPublicId (String publicId)
{
this.publicId = publicId;
}
/**
* Get the public identifier for this input source.
*
* @return The public identifier, or null if none was supplied.
* @see #setPublicId
*/
public String getPublicId ()
{
return publicId;
}
/**
* Set the system identifier for this input source.
*
* <p>The system identifier is optional if there is a byte stream
* or a character stream, but it is still useful to provide one,
* since the application can use it to resolve relative URIs
* and can include it in error messages and warnings (the parser
* will attempt to open a connection to the URI only if
* there is no byte stream or character stream specified).</p>
*
* <p>If the application knows the character encoding of the
* object pointed to by the system identifier, it can register
* the encoding using the setEncoding method.</p>
*
* <p>If the system ID is a URL, it must be fully resolved.</p>
*
* @param systemId The system identifier as a string.
* @see #setEncoding
* @see #getSystemId
* @see org.xml.sax.Locator#getSystemId
* @see org.xml.sax.SAXParseException#getSystemId
*/
public void setSystemId (String systemId)
{
this.systemId = systemId;
}
/**
* Get the system identifier for this input source.
*
* <p>The getEncoding method will return the character encoding
* of the object pointed to, or null if unknown.</p>
*
* <p>If the system ID is a URL, it will be fully resolved.</p>
*
* @return The system identifier, or null if none was supplied.
* @see #setSystemId
* @see #getEncoding
*/
public String getSystemId ()
{
return systemId;
}
/**
* Set the byte stream for this input source.
*
* <p>The SAX parser will ignore this if there is also a character
* stream specified, but it will use a byte stream in preference
* to opening a URI connection itself.</p>
*
* <p>If the application knows the character encoding of the
* byte stream, it should set it with the setEncoding method.</p>
*
* @param byteStream A byte stream containing an XML document or
* other entity.
* @see #setEncoding
* @see #getByteStream
* @see #getEncoding
* @see java.io.InputStream
*/
public void setByteStream (InputStream byteStream)
{
this.byteStream = byteStream;
}
/**
* Get the byte stream for this input source.
*
* <p>The getEncoding method will return the character
* encoding for this byte stream, or null if unknown.</p>
*
* @return The byte stream, or null if none was supplied.
* @see #getEncoding
* @see #setByteStream
*/
public InputStream getByteStream ()
{
return byteStream;
}
/**
* Set the character encoding, if known.
*
* <p>The encoding must be a string acceptable for an
* XML encoding declaration (see section 4.3.3 of the XML 1.0
* recommendation).</p>
*
* <p>This method has no effect when the application provides a
* character stream.</p>
*
* @param encoding A string describing the character encoding.
* @see #setSystemId
* @see #setByteStream
* @see #getEncoding
*/
public void setEncoding (String encoding)
{
this.encoding = encoding;
}
/**
* Get the character encoding for a byte stream or URI.
*
* @return The encoding, or null if none was supplied.
* @see #setByteStream
* @see #getSystemId
* @see #getByteStream
*/
public String getEncoding ()
{
return encoding;
}
/**
* Set the character stream for this input source.
*
* <p>If there is a character stream specified, the SAX parser
* will ignore any byte stream and will not attempt to open
* a URI connection to the system identifier.</p>
*
* @param characterStream The character stream containing the
* XML document or other entity.
* @see #getCharacterStream
* @see java.io.Reader
*/
public void setCharacterStream (Reader characterStream)
{
this.characterStream = characterStream;
}
/**
* Get the character stream for this input source.
*
* @return The character stream, or null if none was supplied.
* @see #setCharacterStream
*/
public Reader getCharacterStream ()
{
return characterStream;
}
////////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////////
private String publicId;
private String systemId;
private InputStream byteStream;
private String encoding;
private Reader characterStream;
}
// end of InputSource.java
1.1 xml-commons/java/external/src/org/xml/sax/Locator.java
Index: Locator.java
===================================================================
// SAX locator interface for document events.
// No warranty; no copyright -- use this as you will.
// $Id: Locator.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Interface for associating a SAX event with a document location.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>If a SAX parser provides location information to the SAX
* application, it does so by implementing this interface and then
* 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
* in the XML source document.</p>
*
* <p>Note that the results returned by the object will be valid only
* during the scope of each content handler method: the application
* will receive unpredictable results if it attempts to use the
* locator at any other time.</p>
*
* <p>SAX parsers are not required to supply a locator, but they are
* very strongly encouraged to do so. If the parser supplies a
* locator, it must do so before reporting any other document events.
* If no locator has been set by the time the application receives
* the {@link org.xml.sax.ContentHandler#startDocument startDocument}
* event, the application should assume that a locator is not
* available.</p>
*
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.ContentHandler#setDocumentLocator
*/
public interface Locator {
/**
* Return the public identifier for the current document event.
*
* <p>The return value is the public identifier of the document
* entity or of the external parsed entity in which the markup
* triggering the event appears.</p>
*
* @return A string containing the public identifier, or
* null if none is available.
* @see #getSystemId
*/
public abstract String getPublicId ();
/**
* Return the system identifier for the current document event.
*
* <p>The return value is the system identifier of the document
* entity or of the external parsed entity in which the markup
* triggering the event appears.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before passing it to the application.</p>
*
* @return A string containing the system identifier, or null
* if none is available.
* @see #getPublicId
*/
public abstract String getSystemId ();
/**
* Return the line number where the current document event ends.
*
* <p><strong>Warning:</strong> The return value from the method
* is intended only as an approximation for the sake of error
* reporting; it is not intended to provide sufficient information
* to edit the character content of the original XML document.</p>
*
* <p>The return value is an approximation of the line number
* in the document entity or external parsed entity where the
* markup triggering the event appears.</p>
*
* <p>If possible, the SAX driver should provide the line position
* of the first character after the text associated with the document
* event. The first line in the document is line 1.</p>
*
* @return The line number, or -1 if none is available.
* @see #getColumnNumber
*/
public abstract int getLineNumber ();
/**
* Return the column number where the current document event ends.
*
* <p><strong>Warning:</strong> The return value from the method
* is intended only as an approximation for the sake of error
* reporting; it is not intended to provide sufficient information
* to edit the character content of the original XML document.</p>
*
* <p>The return value is an approximation of the column number
* in the document entity or external parsed entity where the
* markup triggering the event appears.</p>
*
* <p>If possible, the SAX driver should provide the line position
* of the first character after the text associated with the document
* event.</p>
*
* <p>If possible, the SAX driver should provide the line position
* of the first character after the text associated with the document
* event. The first column in each line is column 1.</p>
*
* @return The column number, or -1 if none is available.
* @see #getLineNumber
*/
public abstract int getColumnNumber ();
}
// end of Locator.java
1.1 xml-commons/java/external/src/org/xml/sax/Parser.java
Index: Parser.java
===================================================================
// SAX parser interface.
// No warranty; no copyright -- use this as you will.
// $Id: Parser.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
import java.io.IOException;
import java.util.Locale;
/**
* Basic interface for SAX (Simple API for XML) parsers.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This was the main event supplier interface for SAX1; it has
* been replaced in SAX2 by {@link org.xml.sax.XMLReader XMLReader},
* which includes Namespace support and sophisticated configurability
* and extensibility.</p>
*
* <p>All SAX1 parsers must implement this basic interface: it allows
* applications to register handlers for different types of events
* and to initiate a parse from a URI, or a character stream.</p>
*
* <p>All SAX1 parsers must also implement a zero-argument constructor
* (though other constructors are also allowed).</p>
*
* <p>SAX1 parsers are reusable but not re-entrant: the application
* may reuse a parser object (possibly with a different input source)
* once the first parse has completed successfully, but it may not
* invoke the parse() methods recursively within a parse.</p>
*
* @deprecated This interface has been replaced by the SAX2
* {@link org.xml.sax.XMLReader XMLReader}
* interface, which includes Namespace support.
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.EntityResolver
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.DocumentHandler
* @see org.xml.sax.ErrorHandler
* @see org.xml.sax.HandlerBase
* @see org.xml.sax.InputSource
*/
public interface Parser
{
/**
* Allow an application to request a locale for errors and warnings.
*
* <p>SAX parsers are not required to provide localisation for errors
* and warnings; if they cannot support the requested locale,
* however, they must throw a SAX exception. Applications may
* not request a locale change in the middle of a parse.</p>
*
* @param locale A Java Locale object.
* @exception org.xml.sax.SAXException Throws an exception
* (using the previous or default locale) if the
* requested locale is not supported.
* @see org.xml.sax.SAXException
* @see org.xml.sax.SAXParseException
*/
public abstract void setLocale (Locale locale)
throws SAXException;
/**
* Allow an application to register a custom entity resolver.
*
* <p>If the application does not register an entity resolver, the
* SAX parser will resolve system identifiers and open connections
* to entities itself (this is the default behaviour implemented in
* HandlerBase).</p>
*
* <p>Applications may register a new or different entity resolver
* in the middle of a parse, and the SAX parser must begin using
* the new resolver immediately.</p>
*
* @param resolver The object for resolving entities.
* @see EntityResolver
* @see HandlerBase
*/
public abstract void setEntityResolver (EntityResolver resolver);
/**
* Allow an application to register a DTD event handler.
*
* <p>If the application does not register a DTD handler, all DTD
* events reported by the SAX parser will be silently
* ignored (this is the default behaviour implemented by
* HandlerBase).</p>
*
* <p>Applications may register a new or different
* handler in the middle of a parse, and the SAX parser must
* begin using the new handler immediately.</p>
*
* @param handler The DTD handler.
* @see DTDHandler
* @see HandlerBase
*/
public abstract void setDTDHandler (DTDHandler handler);
/**
* Allow an application to register a document event handler.
*
* <p>If the application does not register a document handler, all
* document events reported by the SAX parser will be silently
* ignored (this is the default behaviour implemented by
* HandlerBase).</p>
*
* <p>Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.</p>
*
* @param handler The document handler.
* @see DocumentHandler
* @see HandlerBase
*/
public abstract void setDocumentHandler (DocumentHandler handler);
/**
* Allow an application to register an error event handler.
*
* <p>If the application does not register an error event handler,
* all error events reported by the SAX parser will be silently
* ignored, except for fatalError, which will throw a SAXException
* (this is the default behaviour implemented by HandlerBase).</p>
*
* <p>Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.</p>
*
* @param handler The error handler.
* @see ErrorHandler
* @see SAXException
* @see HandlerBase
*/
public abstract void setErrorHandler (ErrorHandler handler);
/**
* Parse an XML document.
*
* <p>The application can use this method to instruct the SAX parser
* to begin parsing an XML document from any valid input
* source (a character stream, a byte stream, or a URI).</p>
*
* <p>Applications may not invoke this method while a parse is in
* progress (they should create a new Parser instead for each
* additional XML document). Once a parse is complete, an
* application may reuse the same Parser object, possibly with a
* different input source.</p>
*
* @param source The input source for the top-level of the
* XML document.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @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.InputSource
* @see #parse(java.lang.String)
* @see #setEntityResolver
* @see #setDTDHandler
* @see #setDocumentHandler
* @see #setErrorHandler
*/
public abstract void parse (InputSource source)
throws SAXException, IOException;
/**
* Parse an XML document from a system identifier (URI).
*
* <p>This method is a shortcut for the common case of reading a
* document from a system identifier. It is the exact
* equivalent of the following:</p>
*
* <pre>
* parse(new InputSource(systemId));
* </pre>
*
* <p>If the system identifier is a URL, it must be fully resolved
* by the application before it is passed to the parser.</p>
*
* @param systemId The system identifier (URI).
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @exception java.io.IOException An IO exception from the parser,
* possibly from a byte stream or character stream
* supplied by the application.
* @see #parse(org.xml.sax.InputSource)
*/
public abstract void parse (String systemId)
throws SAXException, IOException;
}
// end of Parser.java
1.1 xml-commons/java/external/src/org/xml/sax/SAXException.java
Index: SAXException.java
===================================================================
// SAX exception class.
// No warranty; no copyright -- use this as you will.
// $Id: SAXException.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Encapsulate a general SAX error or warning.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class can contain basic error or warning information from
* either the XML parser or the application: a parser writer or
* application writer can subclass it to provide additional
* functionality. SAX handlers may throw this exception or
* any exception subclassed from it.</p>
*
* <p>If the application needs to pass through other types of
* exceptions, it must wrap those exceptions in a SAXException
* or an exception derived from a SAXException.</p>
*
* <p>If the parser or application needs to include information about a
* specific location in an XML document, it should use the
* {@link org.xml.sax.SAXParseException SAXParseException} subclass.</p>
*
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.SAXParseException
*/
public class SAXException extends Exception {
/**
* Create a new SAXException.
*/
public SAXException ()
{
super();
this.exception = null;
}
/**
* Create a new SAXException.
*
* @param message The error or warning message.
* @see org.xml.sax.Parser#setLocale
*/
public SAXException (String message) {
super(message);
this.exception = null;
}
/**
* Create a new SAXException wrapping an existing exception.
*
* <p>The existing exception will be embedded in the new
* one, and its message will become the default message for
* the SAXException.</p>
*
* @param e The exception to be wrapped in a SAXException.
*/
public SAXException (Exception e)
{
super();
this.exception = e;
}
/**
* Create a new SAXException from an existing exception.
*
* <p>The existing exception will be embedded in the new
* one, but the new exception will have its own message.</p>
*
* @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)
{
super(message);
this.exception = e;
}
/**
* Return a detail message for this exception.
*
* <p>If there is an embedded exception, and if the SAXException
* has no detail message of its own, this method will return
* the detail message from the embedded exception.</p>
*
* @return The error or warning message.
* @see org.xml.sax.Parser#setLocale
*/
public String getMessage ()
{
String message = super.getMessage();
if (message == null && exception != null) {
return exception.getMessage();
} else {
return message;
}
}
/**
* Return the embedded exception, if any.
*
* @return The embedded exception, or null if there is none.
*/
public Exception getException ()
{
return exception;
}
/**
* Override toString to pick up any embedded exception.
*
* @return A string representation of this exception.
*/
public String toString ()
{
if (exception != null) {
return exception.toString();
} else {
return super.toString();
}
}
//////////////////////////////////////////////////////////////////////
// Internal state.
//////////////////////////////////////////////////////////////////////
/**
* @serial The embedded exception if tunnelling, or null.
*/
private Exception exception;
}
// end of SAXException.java
1.1 xml-commons/java/external/src/org/xml/sax/SAXNotRecognizedException.java
Index: SAXNotRecognizedException.java
===================================================================
// SAXNotRecognizedException.java - unrecognized feature or value.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the Public Domain.
// $Id: SAXNotRecognizedException.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Exception class for an unrecognized identifier.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>An XMLReader will throw this exception when it finds an
* unrecognized feature or property identifier; SAX applications and
* extensions may use this class for other, similar purposes.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.SAXNotSupportedException
*/
public class SAXNotRecognizedException extends SAXException
{
/**
* Default constructor.
*/
public SAXNotRecognizedException ()
{
super();
}
/**
* Construct a new exception with the given message.
*
* @param message The text message of the exception.
*/
public SAXNotRecognizedException (String message)
{
super(message);
}
}
// end of SAXNotRecognizedException.java
1.1 xml-commons/java/external/src/org/xml/sax/SAXNotSupportedException.java
Index: SAXNotSupportedException.java
===================================================================
// SAXNotSupportedException.java - unsupported feature or value.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the Public Domain.
// $Id: SAXNotSupportedException.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Exception class for an unsupported operation.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>An XMLReader will throw this exception when it recognizes a
* feature or property identifier, but cannot perform the requested
* operation (setting a state or value). Other SAX2 applications and
* extensions may use this class for similar purposes.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.SAXNotRecognizedException
*/
public class SAXNotSupportedException extends SAXException
{
/**
* Construct a new exception with no message.
*/
public SAXNotSupportedException ()
{
super();
}
/**
* Construct a new exception with the given message.
*
* @param message The text message of the exception.
*/
public SAXNotSupportedException (String message)
{
super(message);
}
}
// end of SAXNotSupportedException.java
1.1 xml-commons/java/external/src/org/xml/sax/SAXParseException.java
Index: SAXParseException.java
===================================================================
// SAX exception class.
// No warranty; no copyright -- use this as you will.
// $Id: SAXParseException.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Encapsulate an XML parse error or warning.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This exception will include information for locating the error
* in the original XML document. 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;
* instead, it can simply read the information in it and take a
* different action.</p>
*
* <p>Since this exception is a subclass of {@link org.xml.sax.SAXException
* SAXException}, it inherits the ability to wrap another exception.</p>
*
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.SAXException
* @see org.xml.sax.Locator
* @see org.xml.sax.ErrorHandler
*/
public class SAXParseException extends SAXException {
//////////////////////////////////////////////////////////////////////
// Constructors.
//////////////////////////////////////////////////////////////////////
/**
* Create a new SAXParseException from a message and a Locator.
*
* <p>This constructor is especially useful when an application is
* creating its own exception from within a {@link org.xml.sax.ContentHandler
* ContentHandler} callback.</p>
*
* @param message The error or warning message.
* @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);
if (locator != null) {
init(locator.getPublicId(), locator.getSystemId(),
locator.getLineNumber(), locator.getColumnNumber());
} else {
init(null, null, -1, -1);
}
}
/**
* Wrap an existing exception in a SAXParseException.
*
* <p>This constructor is especially useful when an application is
* creating its own exception from within a {@link org.xml.sax.ContentHandler
* ContentHandler} callback, and needs to wrap an existing exception that is not a
* subclass of {@link org.xml.sax.SAXException SAXException}.</p>
*
* @param message The error or warning message, or null to
* use the message from the embedded exception.
* @param locator The locator object for the error or warning (may be
* null).
* @param e Any exception.
* @see org.xml.sax.Locator
* @see org.xml.sax.Parser#setLocale
*/
public SAXParseException (String message, Locator locator,
Exception e) {
super(message, e);
if (locator != null) {
init(locator.getPublicId(), locator.getSystemId(),
locator.getLineNumber(), locator.getColumnNumber());
} else {
init(null, null, -1, -1);
}
}
/**
* Create a new SAXParseException.
*
* <p>This constructor is most useful for parser writers.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before creating the exception.</p>
*
* @param message The error or warning message.
* @param publicId The public identifer of the entity that generated
* the error or warning.
* @param systemId The system identifer of the entity that generated
* the error or warning.
* @param lineNumber The line number of the end of the text that
* 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)
{
super(message);
init(publicId, systemId, lineNumber, columnNumber);
}
/**
* Create a new SAXParseException with an embedded exception.
*
* <p>This constructor is most useful for parser writers who
* need to wrap an exception that is not a subclass of
* {@link org.xml.sax.SAXException SAXException}.</p>
*
* <p>If the system identifier is a URL, the parser must resolve it
* fully before creating the exception.</p>
*
* @param message The error or warning message, or null to use
* the message from the embedded exception.
* @param publicId The public identifer of the entity that generated
* the error or warning.
* @param systemId The system identifer of the entity that generated
* the error or warning.
* @param lineNumber The line number of the end of the text that
* caused the error or warning.
* @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)
{
super(message, e);
init(publicId, systemId, lineNumber, columnNumber);
}
/**
* Internal initialization method.
*
* @param publicId The public identifier of the entity which generated the exception,
* or null.
* @param systemId The system identifier of the entity which generated the exception,
* or null.
* @param lineNumber The line number of the error, or -1.
* @param columnNumber The column number of the error, or -1.
*/
private void init (String publicId, String systemId,
int lineNumber, int columnNumber)
{
this.publicId = publicId;
this.systemId = systemId;
this.lineNumber = lineNumber;
this.columnNumber = columnNumber;
}
/**
* Get the public identifier of the entity where the exception occurred.
*
* @return A string containing the public identifier, or null
* if none is available.
* @see org.xml.sax.Locator#getPublicId
*/
public String getPublicId ()
{
return this.publicId;
}
/**
* Get the system identifier of the entity where the exception occurred.
*
* <p>If the system identifier is a URL, it will be resolved
* fully.</p>
*
* @return A string containing the system identifier, or null
* if none is available.
* @see org.xml.sax.Locator#getSystemId
*/
public String getSystemId ()
{
return this.systemId;
}
/**
* The line number of the end of the text where the exception occurred.
*
* @return An integer representing the line number, or -1
* if none is available.
* @see org.xml.sax.Locator#getLineNumber
*/
public int getLineNumber ()
{
return this.lineNumber;
}
/**
* The column number of the end of the text where the exception occurred.
*
* <p>The first column in a line is position 1.</p>
*
* @return An integer representing the column number, or -1
* if none is available.
* @see org.xml.sax.Locator#getColumnNumber
*/
public int getColumnNumber ()
{
return this.columnNumber;
}
//////////////////////////////////////////////////////////////////////
// Internal state.
//////////////////////////////////////////////////////////////////////
/**
* @serial The public identifier, or null.
* @see #getPublicId
*/
private String publicId;
/**
* @serial The system identifier, or null.
* @see #getSystemId
*/
private String systemId;
/**
* @serial The line number, or -1.
* @see #getLineNumber
*/
private int lineNumber;
/**
* @serial The column number, or -1.
* @see #getColumnNumber
*/
private int columnNumber;
}
// end of SAXParseException.java
1.1 xml-commons/java/external/src/org/xml/sax/XMLFilter.java
Index: XMLFilter.java
===================================================================
// XMLFilter.java - filter SAX2 events.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the Public Domain.
// $Id: XMLFilter.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
/**
* Interface for an XML filter.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>An XML filter is like an XML reader, except that it obtains its
* events from another XML reader rather than a primary source like
* an XML document or database. Filters can modify a stream of
* events as they pass on to the final application.</p>
*
* <p>The XMLFilterImpl helper class provides a convenient base
* for creating SAX2 filters, by passing on all {@link org.xml.sax.EntityResolver
* EntityResolver}, {@link org.xml.sax.DTDHandler DTDHandler},
* {@link org.xml.sax.ContentHandler ContentHandler} and {@link org.xml.sax.ErrorHandler
* ErrorHandler} events automatically.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.helpers.XMLFilterImpl
*/
public interface XMLFilter extends XMLReader
{
/**
* Set the parent reader.
*
* <p>This method allows the application to link the filter to
* a parent reader (which may be another filter). The argument
* may not be null.</p>
*
* @param parent The parent reader.
*/
public abstract void setParent (XMLReader parent);
/**
* Get the parent reader.
*
* <p>This method allows the application to query the parent
* reader (which may be another filter). It is generally a
* bad idea to perform any operations on the parent reader
* directly: they should all pass through this filter.</p>
*
* @return The parent filter, or null if none has been set.
*/
public abstract XMLReader getParent ();
}
// end of XMLFilter.java
1.1 xml-commons/java/external/src/org/xml/sax/XMLReader.java
Index: XMLReader.java
===================================================================
// XMLReader.java - read an XML document.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the Public Domain.
// $Id: XMLReader.java,v 1.1 2001/05/20 03:12:56 curcuru Exp $
package org.xml.sax;
import java.io.IOException;
/**
* Interface for reading an XML document using callbacks.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p><strong>Note:</strong> despite its name, this interface does
* <em>not</em> extend the standard Java {@link java.io.Reader Reader}
* interface, because reading XML is a fundamentally different activity
* than reading character data.</p>
*
* <p>XMLReader is the interface that an XML parser's SAX2 driver must
* implement. This interface allows an application to set and
* query features and properties in the parser, to register
* event handlers for document processing, and to initiate
* a document parse.</p>
*
* <p>All SAX interfaces are assumed to be synchronous: the
* {@link #parse parse} methods must not return until parsing
* is complete, and readers must wait for an event-handler callback
* to return before reporting the next event.</p>
*
* <p>This interface replaces the (now deprecated) SAX 1.0 {@link
* org.xml.sax.Parser Parser} interface. The XMLReader interface
* contains two important enhancements over the old Parser
* interface:</p>
*
* <ol>
* <li>it adds a standard way to query and set features and
* properties; and</li>
* <li>it adds Namespace support, which is required for many
* higher-level XML standards.</li>
* </ol>
*
* <p>There are adapters available to convert a SAX1 Parser to
* a SAX2 XMLReader and vice-versa.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.XMLFilter
* @see org.xml.sax.helpers.ParserAdapter
* @see org.xml.sax.helpers.XMLReaderAdapter
*/
public interface XMLReader
{
////////////////////////////////////////////////////////////////////
// Configuration.
////////////////////////////////////////////////////////////////////
/**
* Look up the value of a feature.
*
* <p>The feature name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a feature name but
* to be unable to return its value; this is especially true
* in the case of an adapter for a SAX1 Parser, which has
* no way of knowing whether the underlying parser is
* performing validation or expanding external entities.</p>
*
* <p>All XMLReaders are required to recognize the
* http://xml.org/sax/features/namespaces and the
* http://xml.org/sax/features/namespace-prefixes feature names.</p>
*
* <p>Some feature values may be available only in specific
* contexts, such as before, during, or after a parse.</p>
*
* <p>Typical usage is something like this:</p>
*
* <pre>
* XMLReader r = new MySAXDriver();
*
* // try to activate validation
* try {
* r.setFeature("http://xml.org/sax/features/validation", true);
* } catch (SAXException e) {
* System.err.println("Cannot activate validation.");
* }
*
* // register event handlers
* r.setContentHandler(new MyContentHandler());
* r.setErrorHandler(new MyErrorHandler());
*
* // parse the first document
* try {
* r.parse("http://www.foo.com/mydoc.xml");
* } catch (IOException e) {
* System.err.println("I/O exception reading XML document");
* } catch (SAXException e) {
* System.err.println("XML exception reading document.");
* }
* </pre>
*
* <p>Implementors are free (and encouraged) to invent their own features,
* using names built on their own URIs.</p>
*
* @param name The feature name, which is a fully-qualified URI.
* @return The current state of the feature (true or false).
* @exception org.xml.sax.SAXNotRecognizedException When the
* XMLReader does not recognize the feature name.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the feature name but
* cannot determine its value at this time.
* @see #setFeature
*/
public boolean getFeature (String name)
throws SAXNotRecognizedException, SAXNotSupportedException;
/**
* Set the state of a feature.
*
* <p>The feature name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a feature name but
* to be unable to set its value; this is especially true
* in the case of an adapter for a SAX1 {@link org.xml.sax.Parser Parser},
* which has no way of affecting whether the underlying parser is
* validating, for example.</p>
*
* <p>All XMLReaders are required to support setting
* http://xml.org/sax/features/namespaces to true and
* http://xml.org/sax/features/namespace-prefixes to false.</p>
*
* <p>Some feature values may be immutable or mutable only
* in specific contexts, such as before, during, or after
* a parse.</p>
*
* @param name The feature name, which is a fully-qualified URI.
* @param state The requested state of the feature (true or false).
* @exception org.xml.sax.SAXNotRecognizedException When the
* XMLReader does not recognize the feature name.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the feature name but
* cannot set the requested value.
* @see #getFeature
*/
public void setFeature (String name, boolean value)
throws SAXNotRecognizedException, SAXNotSupportedException;
/**
* Look up the value of a property.
*
* <p>The property name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a property name but
* to be unable to return its state; this is especially true
* in the case of an adapter for a SAX1 {@link org.xml.sax.Parser
* Parser}.</p>
*
* <p>XMLReaders are not required to recognize any specific
* property names, though an initial core set is documented for
* SAX2.</p>
*
* <p>Some property values may be available only in specific
* contexts, such as before, during, or after a parse.</p>
*
* <p>Implementors are free (and encouraged) to invent their own properties,
* using names built on their own URIs.</p>
*
* @param name The property name, which is a fully-qualified URI.
* @return The current value of the property.
* @exception org.xml.sax.SAXNotRecognizedException When the
* XMLReader does not recognize the property name.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot determine its value at this time.
* @see #setProperty
*/
public Object getProperty (String name)
throws SAXNotRecognizedException, SAXNotSupportedException;
/**
* Set the value of a property.
*
* <p>The property name is any fully-qualified URI. It is
* possible for an XMLReader to recognize a property name but
* to be unable to set its value; this is especially true
* in the case of an adapter for a SAX1 {@link org.xml.sax.Parser
* Parser}.</p>
*
* <p>XMLReaders are not required to recognize setting
* any specific property names, though a core set is provided with
* SAX2.</p>
*
* <p>Some property values may be immutable or mutable only
* in specific contexts, such as before, during, or after
* a parse.</p>
*
* <p>This method is also the standard mechanism for setting
* extended handlers.</p>
*
* @param name The property name, which is a fully-qualified URI.
* @param state The requested value for the property.
* @exception org.xml.sax.SAXNotRecognizedException When the
* XMLReader does not recognize the property name.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the property name but
* cannot set the requested value.
*/
public void setProperty (String name, Object value)
throws SAXNotRecognizedException, SAXNotSupportedException;
////////////////////////////////////////////////////////////////////
// Event handlers.
////////////////////////////////////////////////////////////////////
/**
* Allow an application to register an entity resolver.
*
* <p>If the application does not register an entity resolver,
* the XMLReader will perform its own default resolution.</p>
*
* <p>Applications may register a new or different resolver in the
* middle of a parse, and the SAX parser must begin using the new
* resolver immediately.</p>
*
* @param resolver The entity resolver.
* @exception java.lang.NullPointerException If the resolver
* argument is null.
* @see #getEntityResolver
*/
public void setEntityResolver (EntityResolver resolver);
/**
* Return the current entity resolver.
*
* @return The current entity resolver, or null if none
* has been registered.
* @see #setEntityResolver
*/
public EntityResolver getEntityResolver ();
/**
* Allow an application to register a DTD event handler.
*
* <p>If the application does not register a DTD handler, all DTD
* events reported by the SAX parser will be silently ignored.</p>
*
* <p>Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.</p>
*
* @param handler The DTD handler.
* @exception java.lang.NullPointerException If the handler
* argument is null.
* @see #getDTDHandler
*/
public void setDTDHandler (DTDHandler handler);
/**
* Return the current DTD handler.
*
* @return The current DTD handler, or null if none
* has been registered.
* @see #setDTDHandler
*/
public DTDHandler getDTDHandler ();
/**
* Allow an application to register a content event handler.
*
* <p>If the application does not register a content handler, all
* content events reported by the SAX parser will be silently
* ignored.</p>
*
* <p>Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.</p>
*
* @param handler The content handler.
* @exception java.lang.NullPointerException If the handler
* argument is null.
* @see #getContentHandler
*/
public void setContentHandler (ContentHandler handler);
/**
* Return the current content handler.
*
* @return The current content handler, or null if none
* has been registered.
* @see #setContentHandler
*/
public ContentHandler getContentHandler ();
/**
* Allow an application to register an error event handler.
*
* <p>If the application does not register an error handler, all
* error events reported by the SAX parser will be silently
* ignored; however, normal processing may not continue. It is
* highly recommended that all SAX applications implement an
* error handler to avoid unexpected bugs.</p>
*
* <p>Applications may register a new or different handler in the
* middle of a parse, and the SAX parser must begin using the new
* handler immediately.</p>
*
* @param handler The error handler.
* @exception java.lang.NullPointerException If the handler
* argument is null.
* @see #getErrorHandler
*/
public void setErrorHandler (ErrorHandler handler);
/**
* Return the current error handler.
*
* @return The current error handler, or null if none
* has been registered.
* @see #setErrorHandler
*/
public ErrorHandler getErrorHandler ();
////////////////////////////////////////////////////////////////////
// Parsing.
////////////////////////////////////////////////////////////////////
/**
* Parse an XML document.
*
* <p>The application can use this method to instruct the XML
* reader to begin parsing an XML document from any valid input
* source (a character stream, a byte stream, or a URI).</p>
*
* <p>Applications may not invoke this method while a parse is in
* progress (they should create a new XMLReader instead for each
* nested XML document). Once a parse is complete, an
* application may reuse the same XMLReader object, possibly with a
* different input source.</p>
*
* <p>During the parse, the XMLReader will provide information
* about the XML document through the registered event
* handlers.</p>
*
* <p>This method is synchronous: it will not return until parsing
* has ended. If a client application wants to terminate
* parsing early, it should throw an exception.</p>
*
* @param source The input source for the top-level of the
* XML document.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @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.InputSource
* @see #parse(java.lang.String)
* @see #setEntityResolver
* @see #setDTDHandler
* @see #setContentHandler
* @see #setErrorHandler
*/
public void parse (InputSource input)
throws IOException, SAXException;
/**
* Parse an XML document from a system identifier (URI).
*
* <p>This method is a shortcut for the common case of reading a
* document from a system identifier. It is the exact
* equivalent of the following:</p>
*
* <pre>
* parse(new InputSource(systemId));
* </pre>
*
* <p>If the system identifier is a URL, it must be fully resolved
* by the application before it is passed to the parser.</p>
*
* @param systemId The system identifier (URI).
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @exception java.io.IOException An IO exception from the parser,
* possibly from a byte stream or character stream
* supplied by the application.
* @see #parse(org.xml.sax.InputSource)
*/
public void parse (String systemId)
throws IOException, SAXException;
}
// end of XMLReader.java
1.1 xml-commons/java/external/src/org/xml/sax/package.html
Index: package.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX 2.0 r2 prerelease interfaces</title>
</head>
<body>
<h1>SAX 2.0 r2 prerelease interfaces</h1>
<blockquote>
<p class="copyright">This document is in the <strong>PUBLIC
DOMAIN</strong> and comes with <strong>NO WARRANTY</strong> of any
kind.</p>
</blockquote>
<p>This is a prerelease of a bugfix release for SAX2, the second
generation of the Simple API for XML. For information, see
docs/index.html.</p>
</body>
</html>
1.1 xml-commons/java/external/src/org/xml/sax/ext/DeclHandler.java
Index: DeclHandler.java
===================================================================
// DeclHandler.java - Optional handler for DTD declaration events.
// Public Domain: no warranty.
// $Id: DeclHandler.java,v 1.1 2001/05/20 03:12:57 curcuru Exp $
package org.xml.sax.ext;
import org.xml.sax.SAXException;
/**
* SAX2 extension handler for DTD declaration events.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This is an optional extension handler for SAX2 to provide
* information about DTD declarations in an XML document. XML
* readers are not required to support this handler, and this
* handler is not included in the core SAX2 distribution.</p>
*
* <p>Note that data-related DTD declarations (unparsed entities and
* notations) are already reported through the {@link
* org.xml.sax.DTDHandler DTDHandler} interface.</p>
*
* <p>If you are using the declaration handler together with a lexical
* handler, all of the events will occur between the
* {@link org.xml.sax.ext.LexicalHandler#startDTD startDTD} and the
* {@link org.xml.sax.ext.LexicalHandler#endDTD endDTD} events.</p>
*
* <p>To set the DeclHandler for an XML reader, use the
* {@link org.xml.sax.XMLReader#setProperty setProperty} method
* with the propertyId "http://xml.org/sax/properties/declaration-handler".
* If the reader does not support declaration events, it will throw a
* {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
* or a
* {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException}
* when you attempt to register the handler.</p>
*
* @since 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 1.0
* @see org.xml.sax.XMLReader
*/
public interface DeclHandler
{
/**
* Report an element type declaration.
*
* <p>The content model will consist of the string "EMPTY", the
* string "ANY", or a parenthesised group, optionally followed
* by an occurrence indicator. The model will be normalized so
* that all parameter entities are fully resolved and all whitespace
* is removed,and will include the enclosing parentheses. Other
* normalization (such as removing redundant parentheses or
* simplifying occurrence indicators) is at the discretion of the
* parser.</p>
*
* @param name The element type name.
* @param model The content model as a normalized string.
* @exception SAXException The application may raise an exception.
*/
public abstract void elementDecl (String name, String model)
throws SAXException;
/**
* Report an attribute type declaration.
*
* <p>Only the effective (first) declaration for an attribute will
* be reported. The type will be one of the strings "CDATA",
* "ID", "IDREF", "IDREFS", "NMTOKEN", "NMTOKENS", "ENTITY",
* "ENTITIES", a parenthesized token group with
* the separator "|" and all whitespace removed, or the word
* "NOTATION" followed by a space followed by a parenthesized
* token group with all whitespace removed.</p>
*
* <p>Any parameter entities in the attribute value will be
* expanded, but general entities will not.</p>
*
* @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
* ("#IMPLIED", "#REQUIRED", or "#FIXED") or null if
* none of these applies.
* @param value A string representing the attribute's default value,
* or null if there is none.
* @exception SAXException The application may raise an exception.
*/
public abstract void attributeDecl (String eName,
String aName,
String type,
String valueDefault,
String value)
throws SAXException;
/**
* Report an internal entity declaration.
*
* <p>Only the effective (first) declaration for each entity
* will be reported. All parameter entities in the value
* will be expanded, but general entities will not.</p>
*
* @param name The name of the entity. If it is a parameter
* entity, the name will begin with '%'.
* @param value The replacement text of the entity.
* @exception SAXException The application may raise an exception.
* @see #externalEntityDecl
* @see org.xml.sax.DTDHandler#unparsedEntityDecl
*/
public abstract void internalEntityDecl (String name, String value)
throws SAXException;
/**
* Report a parsed external entity declaration.
*
* <p>Only the effective (first) declaration for each entity
* will be reported.</p>
*
* @param name The name of the entity. If it is a parameter
* entity, the name will begin with '%'.
* @param publicId The declared public identifier of the entity, or
* null if none was declared.
* @param systemId The declared system identifier of the entity.
* @exception SAXException The application may raise an exception.
* @see #internalEntityDecl
* @see org.xml.sax.DTDHandler#unparsedEntityDecl
*/
public abstract void externalEntityDecl (String name, String publicId,
String systemId)
throws SAXException;
}
// end of DeclHandler.java
1.1 xml-commons/java/external/src/org/xml/sax/ext/LexicalHandler.java
Index: LexicalHandler.java
===================================================================
// LexicalHandler.java - optional handler for lexical parse events.
// Public Domain: no warranty.
// $Id: LexicalHandler.java,v 1.1 2001/05/20 03:12:57 curcuru Exp $
package org.xml.sax.ext;
import org.xml.sax.SAXException;
/**
* SAX2 extension handler for lexical events.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This is an optional extension handler for SAX2 to provide
* lexical information about an XML document, such as comments
* and CDATA section boundaries; XML readers are not required to
* support this handler, and it is not part of the core SAX2
* distribution.</p>
*
* <p>The events in the lexical handler apply to the entire document,
* not just to the document element, and all lexical handler events
* must appear between the content handler's startDocument and
* endDocument events.</p>
*
* <p>To set the LexicalHandler for an XML reader, use the
* {@link org.xml.sax.XMLReader#setProperty setProperty} method
* with the propertyId "http://xml.org/sax/properties/lexical-handler".
* If the reader does not support lexical events, it will throw a
* {@link org.xml.sax.SAXNotRecognizedException SAXNotRecognizedException}
* or a
* {@link org.xml.sax.SAXNotSupportedException SAXNotSupportedException}
* when you attempt to register the handler.</p>
*
* @since 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 1.0
* @see org.xml.sax.XMLReader#setProperty
* @see org.xml.sax.SAXNotRecognizedException
* @see org.xml.sax.SAXNotSupportedException
*/
public interface LexicalHandler
{
/**
* Report the start of DTD declarations, if any.
*
* <p>This method is intended to report the beginning of the
* DOCTYPE declaration; if the document has no DOCTYPE declaration,
* this method will not be invoked.</p>
*
* <p>All declarations reported through
* {@link org.xml.sax.DTDHandler DTDHandler} or
* {@link org.xml.sax.ext.DeclHandler DeclHandler} events must appear
* between the startDTD and {@link #endDTD endDTD} events.
* Declarations are assumed to belong to the internal DTD subset
* unless they appear between {@link #startEntity startEntity}
* and {@link #endEntity endEntity} events. Comments and
* processing instructions from the DTD should also be reported
* between the startDTD and endDTD events, in their original
* order of (logical) occurrence; they are not required to
* appear in their correct locations relative to DTDHandler
* or DeclHandler events, however.</p>
*
* <p>Note that the start/endDTD events will appear within
* the start/endDocument events from ContentHandler and
* before the first
* {@link org.xml.sax.ContentHandler#startElement startElement}
* event.</p>
*
* @param name The document type name.
* @param publicId The declared public identifier for the
* 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.
* @exception SAXException The application may raise an
* exception.
* @see #endDTD
* @see #startEntity
*/
public abstract void startDTD (String name, String publicId,
String systemId)
throws SAXException;
/**
* Report the end of DTD declarations.
*
* <p>This method is intended to report the end of the
* DOCTYPE declaration; if the document has no DOCTYPE declaration,
* this method will not be invoked.</p>
*
* @exception SAXException The application may raise an exception.
* @see #startDTD
*/
public abstract void endDTD ()
throws SAXException;
/**
* Report the beginning of some internal and external XML entities.
*
* <p>The reporting of parameter entities (including
* the external DTD subset) is optional, and SAX2 drivers that
* support LexicalHandler may not support it; you can use the
* <code
* >http://xml.org/sax/features/lexical-handler/parameter-entities</code>
* feature to query or control the reporting of parameter entities.</p>
*
* <p>General entities are reported with their regular names,
* parameter entities have '%' prepended to their names, and
* the external DTD subset has the pseudo-entity name "[dtd]".</p>
*
* <p>When a SAX2 driver is providing these events, all other
* events must be properly nested within start/end entity
* events. There is no additional requirement that events from
* {@link org.xml.sax.ext.DeclHandler DeclHandler} or
* {@link org.xml.sax.DTDHandler DTDHandler} be properly ordered.</p>
*
* <p>Note that skipped entities will be reported through the
* {@link org.xml.sax.ContentHandler#skippedEntity skippedEntity}
* event, which is part of the ContentHandler interface.</p>
*
* <p>Because of the streaming event model that SAX uses, some
* entity boundaries cannot be reported under any
* circumstances:</p>
*
* <ul>
* <li>general entities within attribute values</li>
* <li>parameter entities within declarations</li>
* </ul>
*
* <p>These will be silently expanded, with no indication of where
* the original entity boundaries were.</p>
*
* <p>Note also that the boundaries of character references (which
* are not really entities anyway) are not reported.</p>
*
* <p>All start/endEntity events must be properly nested.
*
* @param name The name of the entity. If it is a parameter
* entity, the name will begin with '%', and if it is the
* external DTD subset, it will be "[dtd]".
* @exception SAXException The application may raise an exception.
* @see #endEntity
* @see org.xml.sax.ext.DeclHandler#internalEntityDecl
* @see org.xml.sax.ext.DeclHandler#externalEntityDecl
*/
public abstract void startEntity (String name)
throws SAXException;
/**
* Report the end of an entity.
*
* @param name The name of the entity that is ending.
* @exception SAXException The application may raise an exception.
* @see #startEntity
*/
public abstract void endEntity (String name)
throws SAXException;
/**
* Report the start of a CDATA section.
*
* <p>The contents of the CDATA section will be reported through
* the regular {@link org.xml.sax.ContentHandler#characters
* characters} event; this event is intended only to report
* the boundary.</p>
*
* @exception SAXException The application may raise an exception.
* @see #endCDATA
*/
public abstract void startCDATA ()
throws SAXException;
/**
* Report the end of a CDATA section.
*
* @exception SAXException The application may raise an exception.
* @see #startCDATA
*/
public abstract void endCDATA ()
throws SAXException;
/**
* Report an XML comment anywhere in the document.
*
* <p>This callback will be used for comments inside or outside the
* document element, including comments in the external DTD
* subset (if read). Comments in the DTD must be properly
* nested inside start/endDTD and start/endEntity events (if
* used).</p>
*
* @param ch An array holding the characters in the comment.
* @param start The starting position in the array.
* @param length The number of characters to use from the array.
* @exception SAXException The application may raise an exception.
*/
public abstract void comment (char ch[], int start, int length)
throws SAXException;
}
// end of LexicalHandler.java
1.1 xml-commons/java/external/src/org/xml/sax/ext/package.html
Index: package.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX2-ext: SAX2 Extension Handlers 1.0</title>
</head>
<body>
<h1>SAX2-ext: SAX2 Extension Handlers 1.0</h1>
<blockquote>
<p class="copyright">This document is in the <strong>PUBLIC
DOMAIN</strong> and comes with <strong>NO WARRANTY</strong> of any
kind.</p>
</blockquote>
<p>This package, SAX2-ext, is an extension package for SAX2. It is
designed both to allow SAX drivers to pass certain types of none-core
information to applications and to serve as a simple model for other
SAX2 extension packages.</p>
<p><strong>NOTE:</strong> this package alone does add any
functionality; it simply provides optional interfaces for SAX2 drivers
to use. You must find a SAX2 driver that supports these interfaces if
you actually want to have access to lexical and declaration
information.</p>
<p>The SAX2-ext package currently contains two extension handlers for
SAX2:</p>
<ol>
<li><a href="javadoc/org/xml/sax/ext/LexicalHandler.html"
>LexicalHandler</a>, which reports comments, the DOCTYPE declaration,
CDATA sections, and (some) entity boundaries; and</li>
<li><a href="javadoc/org/xml/sax/ext/DeclHandler.html"
>DeclHandler</a>, which reports element, attribute, and entity
declarations.</li>
</ol>
<p>This package is independent of the SAX2 core, and that independence
has several consequences:</p>
<ul>
<li>SAX2 drivers are <em>not</em> required to support these handlers,
and you cannot assume that the classes will be present in every SAX2
installation.</li>
<li>This package may be updated independently of SAX2 (i.e. new
handlers may be added without updating SAX2 itself).</li>
<li>The handlers are not supported explicitly by the SAX2
<var>XMLFilter</var> interface (i.e. events are not passed on by
default); you can subclass XMLFilter if you need such behaviour.</li>
<li>The handlers need to be registered differently than regular SAX2
handlers.</li>
</ul>
<p>To set a LexicalHandler, for example, you need to do something like
this:</p>
<blockquote><pre xml:space="preserve">
LexicalHandler lh = new MyLexicalHandler();
try {
xmlReader.setProperty("http://xml.org/sax/properties/lexical-handler",
lh);
} catch (SAXException e) {
System.out.println("LexicalHandler not supported by this SAX2 driver.");
}
</pre></blockquote>
<div>
<h2>SAX2-ext Properties</h2>
<p>Here is a full definition of the two new SAX2 properties introduced
in this version of SAX2-ext:</p>
<dl>
<dt><code>http://xml.org/sax/properties/lexical-handler</code></dt>
<dd><strong>data type:</strong>
<code>org.xml.sax.ext.LexicalHandler</code></dd>
<dd><strong>description:</strong> An optional extension handler for
lexical events like comments.</dd>
<dd><strong>access:</strong> read/write</dd>
<dt><code>http://xml.org/sax/properties/declaration-handler</code></dt>
<dd><strong>data type:</strong>
<code>org.xml.sax.ext.DeclHandler</code></dd>
<dd><strong>description:</strong> An optional extension handler for
DTD-related events other than notations and unparsed entities.</dd>
<dd><strong>access:</strong> read/write</dd>
</dl>
<p><strong>See also:</strong> the package's <a
href="javadoc/index.html">JavaDoc</a> documentation.</p>
<!-- end of "SAX2-ext Properties" -->
</div>
<hr />
<address>$Id: package.html,v 1.1 2001/05/20 03:12:57 curcuru Exp $</address>
</body>
</html>
1.1 xml-commons/java/external/src/org/xml/sax/helpers/AttributeListImpl.java
Index: AttributeListImpl.java
===================================================================
// SAX default implementation for AttributeList.
// No warranty; no copyright -- use this as you will.
// $Id: AttributeListImpl.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import org.xml.sax.AttributeList;
import java.util.Vector;
/**
* Default implementation for AttributeList.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>AttributeList implements the deprecated SAX1 {@link
* org.xml.sax.AttributeList AttributeList} interface, and has been
* replaced by the new SAX2 {@link org.xml.sax.helpers.AttributesImpl
* AttributesImpl} interface.</p>
*
* <p>This class provides a convenience implementation of the SAX
* {@link org.xml.sax.AttributeList AttributeList} interface. This
* implementation is useful both for SAX parser writers, who can use
* it to provide attributes to the application, and for SAX application
* writers, who can use it to create a persistent copy of an element's
* attribute specifications:</p>
*
* <pre>
* private AttributeList myatts;
*
* public void startElement (String name, AttributeList atts)
* {
* // create a persistent copy of the attribute list
* // for use outside this method
* myatts = new AttributeListImpl(atts);
* [...]
* }
* </pre>
*
* <p>Please note that SAX parsers are not required to use this
* class to provide an implementation of AttributeList; it is
* supplied only as an optional convenience. In particular,
* parser writers are encouraged to invent more efficient
* implementations.</p>
*
* @deprecated This class implements a deprecated interface,
* {@link org.xml.sax.AttributeList AttributeList};
* that interface has been replaced by
* {@link org.xml.sax.Attributes Attributes},
* which is implemented in the
* {@link org.xml.sax.helpers.AttributesImpl
* AttributesImpl} helper class.
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.AttributeList
* @see org.xml.sax.DocumentHandler#startElement
*/
public class AttributeListImpl implements AttributeList
{
/**
* Create an empty attribute list.
*
* <p>This constructor is most useful for parser writers, who
* will use it to create a single, reusable attribute list that
* can be reset with the clear method between elements.</p>
*
* @see #addAttribute
* @see #clear
*/
public AttributeListImpl ()
{
}
/**
* Construct a persistent copy of an existing attribute list.
*
* <p>This constructor is most useful for application writers,
* who will use it to create a persistent copy of an existing
* attribute list.</p>
*
* @param atts The attribute list to copy
* @see org.xml.sax.DocumentHandler#startElement
*/
public AttributeListImpl (AttributeList atts)
{
setAttributeList(atts);
}
////////////////////////////////////////////////////////////////////
// Methods specific to this class.
////////////////////////////////////////////////////////////////////
/**
* Set the attribute list, discarding previous contents.
*
* <p>This method allows an application writer to reuse an
* attribute list easily.</p>
*
* @param atts The attribute list to copy.
*/
public void setAttributeList (AttributeList atts)
{
int count = atts.getLength();
clear();
for (int i = 0; i < count; i++) {
addAttribute(atts.getName(i), atts.getType(i), atts.getValue(i));
}
}
/**
* Add an attribute to an attribute list.
*
* <p>This method is provided for SAX parser writers, to allow them
* to build up an attribute list incrementally before delivering
* it to the application.</p>
*
* @param name The attribute name.
* @param type The attribute type ("NMTOKEN" for an enumeration).
* @param value The attribute value (must not be null).
* @see #removeAttribute
* @see org.xml.sax.DocumentHandler#startElement
*/
public void addAttribute (String name, String type, String value)
{
names.addElement(name);
types.addElement(type);
values.addElement(value);
}
/**
* Remove an attribute from the list.
*
* <p>SAX application writers can use this method to filter an
* attribute out of an AttributeList. Note that invoking this
* method will change the length of the attribute list and
* some of the attribute's indices.</p>
*
* <p>If the requested attribute is not in the list, this is
* a no-op.</p>
*
* @param name The attribute name.
* @see #addAttribute
*/
public void removeAttribute (String name)
{
int i = names.indexOf(name);
if (i >= 0) {
names.removeElementAt(i);
types.removeElementAt(i);
values.removeElementAt(i);
}
}
/**
* Clear the attribute list.
*
* <p>SAX parser writers can use this method to reset the attribute
* list between DocumentHandler.startElement events. Normally,
* it will make sense to reuse the same AttributeListImpl object
* rather than allocating a new one each time.</p>
*
* @see org.xml.sax.DocumentHandler#startElement
*/
public void clear ()
{
names.removeAllElements();
types.removeAllElements();
values.removeAllElements();
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.AttributeList
////////////////////////////////////////////////////////////////////
/**
* Return the number of attributes in the list.
*
* @return The number of attributes in the list.
* @see org.xml.sax.AttributeList#getLength
*/
public int getLength ()
{
return names.size();
}
/**
* Get the name of an attribute (by position).
*
* @param i The position of the attribute in the list.
* @return The attribute name as a string, or null if there
* is no attribute at that position.
* @see org.xml.sax.AttributeList#getName(int)
*/
public String getName (int i)
{
if (i < 0) {
return null;
}
try {
return (String)names.elementAt(i);
} catch (ArrayIndexOutOfBoundsException e) {
return null;
}
}
/**
* Get the type of an attribute (by position).
*
* @param i The position of the attribute in the list.
* @return The attribute type as a string ("NMTOKEN" for an
* enumeration, and "CDATA" if no declaration was
* read), or null if there is no attribute at
* that position.
* @see org.xml.sax.AttributeList#getType(int)
*/
public String getType (int i)
{
if (i < 0) {
return null;
}
try {
return (String)types.elementAt(i);
} catch (ArrayIndexOutOfBoundsException e) {
return null;
}
}
/**
* Get the value of an attribute (by position).
*
* @param i The position of the attribute in the list.
* @return The attribute value as a string, or null if
* there is no attribute at that position.
* @see org.xml.sax.AttributeList#getValue(int)
*/
public String getValue (int i)
{
if (i < 0) {
return null;
}
try {
return (String)values.elementAt(i);
} catch (ArrayIndexOutOfBoundsException e) {
return null;
}
}
/**
* Get the type of an attribute (by name).
*
* @param name The attribute name.
* @return The attribute type as a string ("NMTOKEN" for an
* enumeration, and "CDATA" if no declaration was
* read).
* @see org.xml.sax.AttributeList#getType(java.lang.String)
*/
public String getType (String name)
{
return getType(names.indexOf(name));
}
/**
* Get the value of an attribute (by name).
*
* @param name The attribute name.
* @see org.xml.sax.AttributeList#getValue(java.lang.String)
*/
public String getValue (String name)
{
return getValue(names.indexOf(name));
}
////////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////////
Vector names = new Vector();
Vector types = new Vector();
Vector values = new Vector();
}
// end of AttributeListImpl.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/AttributesImpl.java
Index: AttributesImpl.java
===================================================================
// AttributesImpl.java - default implementation of Attributes.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the public domain.
// $Id: AttributesImpl.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import org.xml.sax.Attributes;
/**
* Default implementation of the Attributes interface.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class provides a default implementation of the SAX2
* {@link org.xml.sax.Attributes Attributes} interface, with the
* addition of manipulators so that the list can be modified or
* reused.</p>
*
* <p>There are two typical uses of this class:</p>
*
* <ol>
* <li>to take a persistent snapshot of an Attributes object
* in a {@link org.xml.sax.ContentHandler#startElement startElement} event; or</li>
* <li>to construct or modify an Attributes object in a SAX2 driver or filter.</li>
* </ol>
*
* <p>This class replaces the now-deprecated SAX1 {@link
* org.xml.sax.helpers.AttributeListImpl AttributeListImpl}
* class; in addition to supporting the updated Attributes
* interface rather than the deprecated {@link org.xml.sax.AttributeList
* AttributeList} interface, it also includes a much more efficient
* implementation using a single array rather than a set of Vectors.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
*/
public class AttributesImpl implements Attributes
{
////////////////////////////////////////////////////////////////////
// Constructors.
////////////////////////////////////////////////////////////////////
/**
* Construct a new, empty AttributesImpl object.
*/
public AttributesImpl ()
{
length = 0;
data = null;
}
/**
* Copy an existing Attributes object.
*
* <p>This constructor is especially useful inside a
* {@link org.xml.sax.ContentHandler#startElement startElement} event.</p>
*
* @param atts The existing Attributes object.
*/
public AttributesImpl (Attributes atts)
{
setAttributes(atts);
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.Attributes.
////////////////////////////////////////////////////////////////////
/**
* Return the number of attributes in the list.
*
* @return The number of attributes in the list.
* @see org.xml.sax.Attributes#getLength
*/
public int getLength ()
{
return length;
}
/**
* Return an attribute's Namespace URI.
*
* @param index The attribute's index (zero-based).
* @return The Namespace URI, the empty string if none is
* available, or null if the index is out of range.
* @see org.xml.sax.Attributes#getURI
*/
public String getURI (int index)
{
if (index >= 0 && index < length) {
return data[index*5];
} else {
return null;
}
}
/**
* Return an attribute's local name.
*
* @param index The attribute's index (zero-based).
* @return The attribute's local name, the empty string if
* none is available, or null if the index if out of range.
* @see org.xml.sax.Attributes#getLocalName
*/
public String getLocalName (int index)
{
if (index >= 0 && index < length) {
return data[index*5+1];
} else {
return null;
}
}
/**
* Return an attribute's qualified (prefixed) name.
*
* @param index The attribute's index (zero-based).
* @return The attribute's qualified name, the empty string if
* none is available, or null if the index is out of bounds.
* @see org.xml.sax.Attributes#getQName
*/
public String getQName (int index)
{
if (index >= 0 && index < length) {
return data[index*5+2];
} else {
return null;
}
}
/**
* Return an attribute's type by index.
*
* @param index The attribute's index (zero-based).
* @return The attribute's type, "CDATA" if the type is unknown, or null
* if the index is out of bounds.
* @see org.xml.sax.Attributes#getType(int)
*/
public String getType (int index)
{
if (index >= 0 && index < length) {
return data[index*5+3];
} else {
return null;
}
}
/**
* Return an attribute's value by index.
*
* @param index The attribute's index (zero-based).
* @return The attribute's value or null if the index is out of bounds.
* @see org.xml.sax.Attributes#getValue(int)
*/
public String getValue (int index)
{
if (index >= 0 && index < length) {
return data[index*5+4];
} else {
return null;
}
}
/**
* Look up an attribute's index by Namespace name.
*
* <p>In many cases, it will be more efficient to look up the name once and
* use the index query methods rather than using the name query methods
* repeatedly.</p>
*
* @param uri The attribute's Namespace URI, or the empty
* string if none is available.
* @param localName The attribute's local name.
* @return The attribute's index, or -1 if none matches.
* @see org.xml.sax.Attributes#getIndex(java.lang.String,java.lang.String)
*/
public int getIndex (String uri, String localName)
{
int max = length * 5;
for (int i = 0; i < max; i += 5) {
if (data[i].equals(uri) && data[i+1].equals(localName)) {
return i / 5;
}
}
return -1;
}
/**
* Look up an attribute's index by qualified (prefixed) name.
*
* @param qName The qualified name.
* @return The attribute's index, or -1 if none matches.
* @see org.xml.sax.Attributes#getIndex(java.lang.String)
*/
public int getIndex (String qName)
{
int max = length * 5;
for (int i = 0; i < max; i += 5) {
if (data[i+2].equals(qName)) {
return i / 5;
}
}
return -1;
}
/**
* Look up an attribute's type by Namespace-qualified name.
*
* @param uri The Namespace URI, or the empty string for a name
* with no explicit Namespace URI.
* @param localName The local name.
* @return The attribute's type, or null if there is no
* matching attribute.
* @see org.xml.sax.Attributes#getType(java.lang.String,java.lang.String)
*/
public String getType (String uri, String localName)
{
int max = length * 5;
for (int i = 0; i < max; i += 5) {
if (data[i].equals(uri) && data[i+1].equals(localName)) {
return data[i+3];
}
}
return null;
}
/**
* Look up an attribute's type by qualified (prefixed) name.
*
* @param qName The qualified name.
* @return The attribute's type, or null if there is no
* matching attribute.
* @see org.xml.sax.Attributes#getType(java.lang.String)
*/
public String getType (String qName)
{
int max = length * 5;
for (int i = 0; i < max; i += 5) {
if (data[i+2].equals(qName)) {
return data[i+3];
}
}
return null;
}
/**
* Look up an attribute's value by Namespace-qualified name.
*
* @param uri The Namespace URI, or the empty string for a name
* with no explicit Namespace URI.
* @param localName The local name.
* @return The attribute's value, or null if there is no
* matching attribute.
* @see org.xml.sax.Attributes#getValue(java.lang.String,java.lang.String)
*/
public String getValue (String uri, String localName)
{
int max = length * 5;
for (int i = 0; i < max; i += 5) {
if (data[i].equals(uri) && data[i+1].equals(localName)) {
return data[i+4];
}
}
return null;
}
/**
* Look up an attribute's value by qualified (prefixed) name.
*
* @param qName The qualified name.
* @return The attribute's value, or null if there is no
* matching attribute.
* @see org.xml.sax.Attributes#getValue(java.lang.String)
*/
public String getValue (String qName)
{
int max = length * 5;
for (int i = 0; i < max; i += 5) {
if (data[i+2].equals(qName)) {
return data[i+4];
}
}
return null;
}
////////////////////////////////////////////////////////////////////
// Manipulators.
////////////////////////////////////////////////////////////////////
/**
* Clear the attribute list for reuse.
*
* <p>Note that no memory is actually freed by this call:
* the current arrays are kept so that they can be
* reused.</p>
*/
public void clear ()
{
length = 0;
}
/**
* Copy an entire Attributes object.
*
* <p>It may be more efficient to reuse an existing object
* rather than constantly allocating new ones.</p>
*
* @param atts The attributes to copy.
*/
public void setAttributes (Attributes atts)
{
clear();
length = atts.getLength();
if (length > 0) {
data = new String[length*5];
for (int i = 0; i < length; i++) {
data[i*5] = atts.getURI(i);
data[i*5+1] = atts.getLocalName(i);
data[i*5+2] = atts.getQName(i);
data[i*5+3] = atts.getType(i);
data[i*5+4] = atts.getValue(i);
}
}
}
/**
* Add an attribute to the end of the list.
*
* <p>For the sake of speed, this method does no checking
* to see if the attribute is already in the list: that is
* the responsibility of the application.</p>
*
* @param uri The Namespace URI, or the empty string if
* none is available or Namespace processing is not
* being performed.
* @param localName The local name, or the empty string if
* Namespace processing is not being performed.
* @param qName The qualified (prefixed) name, or the empty string
* if qualified names are not available.
* @param type The attribute type as a string.
* @param value The attribute value.
*/
public void addAttribute (String uri, String localName, String qName,
String type, String value)
{
ensureCapacity(length+1);
data[length*5] = uri;
data[length*5+1] = localName;
data[length*5+2] = qName;
data[length*5+3] = type;
data[length*5+4] = value;
length++;
}
/**
* Set an attribute in the list.
*
* <p>For the sake of speed, this method does no checking
* for name conflicts or well-formedness: such checks are the
* responsibility of the application.</p>
*
* @param index The index of the attribute (zero-based).
* @param uri The Namespace URI, or the empty string if
* none is available or Namespace processing is not
* being performed.
* @param localName The local name, or the empty string if
* Namespace processing is not being performed.
* @param qName The qualified name, or the empty string
* if qualified names are not available.
* @param type The attribute type as a string.
* @param value The attribute value.
* @exception java.lang.ArrayIndexOutOfBoundsException When the
* supplied index does not point to an attribute
* in the list.
*/
public void setAttribute (int index, String uri, String localName,
String qName, String type, String value)
{
if (index >= 0 && index < length) {
data[index*5] = uri;
data[index*5+1] = localName;
data[index*5+2] = qName;
data[index*5+3] = type;
data[index*5+4] = value;
} else {
badIndex(index);
}
}
/**
* Remove an attribute from the list.
*
* @param index The index of the attribute (zero-based).
* @exception java.lang.ArrayIndexOutOfBoundsException When the
* supplied index does not point to an attribute
* in the list.
*/
public void removeAttribute (int index)
{
if (index >= 0 && index < length) {
if (index < length - 1) {
System.arraycopy(data, (index+1)*5, data, index*5,
(length-index)*5);
}
length--;
} else {
badIndex(index);
}
}
/**
* Set the Namespace URI of a specific attribute.
*
* @param index The index of the attribute (zero-based).
* @param uri The attribute's Namespace URI, or the empty
* string for none.
* @exception java.lang.ArrayIndexOutOfBoundsException When the
* supplied index does not point to an attribute
* in the list.
*/
public void setURI (int index, String uri)
{
if (index >= 0 && index < length) {
data[index*5] = uri;
} else {
badIndex(index);
}
}
/**
* Set the local name of a specific attribute.
*
* @param index The index of the attribute (zero-based).
* @param localName The attribute's local name, or the empty
* string for none.
* @exception java.lang.ArrayIndexOutOfBoundsException When the
* supplied index does not point to an attribute
* in the list.
*/
public void setLocalName (int index, String localName)
{
if (index >= 0 && index < length) {
data[index*5+1] = localName;
} else {
badIndex(index);
}
}
/**
* Set the qualified name of a specific attribute.
*
* @param index The index of the attribute (zero-based).
* @param qName The attribute's qualified name, or the empty
* string for none.
* @exception java.lang.ArrayIndexOutOfBoundsException When the
* supplied index does not point to an attribute
* in the list.
*/
public void setQName (int index, String qName)
{
if (index >= 0 && index < length) {
data[index*5+2] = qName;
} else {
badIndex(index);
}
}
/**
* Set the type of a specific attribute.
*
* @param index The index of the attribute (zero-based).
* @param type The attribute's type.
* @exception java.lang.ArrayIndexOutOfBoundsException When the
* supplied index does not point to an attribute
* in the list.
*/
public void setType (int index, String type)
{
if (index >= 0 && index < length) {
data[index*5+3] = type;
} else {
badIndex(index);
}
}
/**
* Set the value of a specific attribute.
*
* @param index The index of the attribute (zero-based).
* @param value The attribute's value.
* @exception java.lang.ArrayIndexOutOfBoundsException When the
* supplied index does not point to an attribute
* in the list.
*/
public void setValue (int index, String value)
{
if (index >= 0 && index < length) {
data[index*5+4] = value;
} else {
badIndex(index);
}
}
////////////////////////////////////////////////////////////////////
// Internal methods.
////////////////////////////////////////////////////////////////////
/**
* Ensure the internal array's capacity.
*
* @param n The minimum number of attributes that the array must
* be able to hold.
*/
private void ensureCapacity (int n) {
if (n <= 0) {
return;
}
int max;
if (data == null || data.length == 0) {
max = 25;
}
else if (data.length >= n * 5) {
return;
}
else {
max = data.length;
}
while (max < n * 5) {
max *= 2;
}
String newData[] = new String[max];
if (length > 0) {
System.arraycopy(data, 0, newData, 0, length*5);
}
data = newData;
}
/**
* Report a bad array index in a manipulator.
*
* @param index The index to report.
* @exception java.lang.ArrayIndexOutOfBoundsException Always.
*/
private void badIndex (int index)
throws ArrayIndexOutOfBoundsException
{
String msg =
"Attempt to modify attribute at illegal index: " + index;
throw new ArrayIndexOutOfBoundsException(msg);
}
////////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////////
int length;
String data [];
}
// end of AttributesImpl.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/DefaultHandler.java
Index: DefaultHandler.java
===================================================================
// DefaultHandler.java - default implementation of the core handlers.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the public domain.
// $Id: DefaultHandler.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import java.io.IOException;
import org.xml.sax.InputSource;
import org.xml.sax.Locator;
import org.xml.sax.Attributes;
import org.xml.sax.EntityResolver;
import org.xml.sax.DTDHandler;
import org.xml.sax.ContentHandler;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
/**
* Default base class for SAX2 event handlers.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class is available as a convenience base class for SAX2
* applications: it provides default implementations for all of the
* callbacks in the four core SAX2 handler classes:</p>
*
* <ul>
* <li>{@link org.xml.sax.EntityResolver EntityResolver}</li>
* <li>{@link org.xml.sax.DTDHandler DTDHandler}</li>
* <li>{@link org.xml.sax.ContentHandler ContentHandler}</li>
* <li>{@link org.xml.sax.ErrorHandler ErrorHandler}</li>
* </ul>
*
* <p>Application writers can extend this class when they need to
* implement only part of an interface; parser writers can
* instantiate this class to provide default handlers when the
* application has not supplied its own.</p>
*
* <p>This class replaces the deprecated SAX1
* {@link org.xml.sax.HandlerBase HandlerBase} class.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.EntityResolver
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.ContentHandler
* @see org.xml.sax.ErrorHandler
*/
public class DefaultHandler
implements EntityResolver, DTDHandler, ContentHandler, ErrorHandler
{
////////////////////////////////////////////////////////////////////
// Default implementation of the EntityResolver interface.
////////////////////////////////////////////////////////////////////
/**
* Resolve an external entity.
*
* <p>Always return null, so that the parser will use the system
* identifier provided in the XML document. This method implements
* the SAX default behaviour: application writers can override it
* in a subclass to do special translations such as catalog lookups
* or URI redirection.</p>
*
* @param publicId The public identifer, or null if none is
* available.
* @param systemId The system identifier provided in the XML
* document.
* @return The new input source, or null to require the
* default behaviour.
* @exception java.io.IOException If there is an error setting
* up the new input source.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.EntityResolver#resolveEntity
*/
public InputSource resolveEntity (String publicId, String systemId)
throws IOException, SAXException
{
return null;
}
////////////////////////////////////////////////////////////////////
// Default implementation of DTDHandler interface.
////////////////////////////////////////////////////////////////////
/**
* Receive notification of a notation declaration.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass if they wish to keep track of the notations
* declared in a document.</p>
*
* @param name The notation name.
* @param publicId The notation public identifier, or null if not
* available.
* @param systemId The notation system identifier.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DTDHandler#notationDecl
*/
public void notationDecl (String name, String publicId, String systemId)
throws SAXException
{
// no op
}
/**
* Receive notification of an unparsed entity declaration.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to keep track of the unparsed entities
* declared in a document.</p>
*
* @param name The entity name.
* @param publicId The entity public identifier, or null if not
* available.
* @param systemId The entity system identifier.
* @param notationName The name of the associated notation.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.DTDHandler#unparsedEntityDecl
*/
public void unparsedEntityDecl (String name, String publicId,
String systemId, String notationName)
throws SAXException
{
// no op
}
////////////////////////////////////////////////////////////////////
// Default implementation of ContentHandler interface.
////////////////////////////////////////////////////////////////////
/**
* Receive a Locator object for document events.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass if they wish to store the locator for use
* with other document events.</p>
*
* @param locator A locator for all SAX document events.
* @see org.xml.sax.ContentHandler#setDocumentLocator
* @see org.xml.sax.Locator
*/
public void setDocumentLocator (Locator locator)
{
// no op
}
/**
* Receive notification of the beginning of the document.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the beginning
* of a document (such as allocating the root node of a tree or
* creating an output file).</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#startDocument
*/
public void startDocument ()
throws SAXException
{
// no op
}
/**
* Receive notification of the end of the document.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the end
* of a document (such as finalising a tree or closing an output
* file).</p>
*
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#endDocument
*/
public void endDocument ()
throws SAXException
{
// no op
}
/**
* Receive notification of the start of a Namespace mapping.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the start of
* each Namespace prefix scope (such as storing the prefix mapping).</p>
*
* @param prefix The Namespace prefix being declared.
* @param uri The Namespace URI mapped to the prefix.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#startPrefixMapping
*/
public void startPrefixMapping (String prefix, String uri)
throws SAXException
{
// no op
}
/**
* Receive notification of the end of a Namespace mapping.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the end of
* each prefix mapping.</p>
*
* @param prefix The Namespace prefix being declared.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#endPrefixMapping
*/
public void endPrefixMapping (String prefix)
throws SAXException
{
// no op
}
/**
* Receive notification of the start of an element.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the start of
* each element (such as allocating a new tree node or writing
* output to a file).</p>
*
* @param name The element type name.
* @param attributes The specified or defaulted attributes.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#startElement
*/
public void startElement (String uri, String localName,
String qName, Attributes attributes)
throws SAXException
{
// no op
}
/**
* Receive notification of the end of an element.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions at the end of
* each element (such as finalising a tree node or writing
* output to a file).</p>
*
* @param name The element type name.
* @param attributes The specified or defaulted attributes.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#endElement
*/
public void endElement (String uri, String localName, String qName)
throws SAXException
{
// no op
}
/**
* Receive notification of character data inside an element.
*
* <p>By default, do nothing. Application writers may override this
* method to take specific actions for each chunk of character data
* (such as adding the data to a node or buffer, or printing it to
* a file).</p>
*
* @param ch The characters.
* @param start The start position in the character array.
* @param length The number of characters to use from the
* character array.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#characters
*/
public void characters (char ch[], int start, int length)
throws SAXException
{
// no op
}
/**
* Receive notification of ignorable whitespace in element content.
*
* <p>By default, do nothing. Application writers may override this
* method to take specific actions for each chunk of ignorable
* whitespace (such as adding data to a node or buffer, or printing
* it to a file).</p>
*
* @param ch The whitespace characters.
* @param start The start position in the character array.
* @param length The number of characters to use from the
* character array.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#ignorableWhitespace
*/
public void ignorableWhitespace (char ch[], int start, int length)
throws SAXException
{
// no op
}
/**
* Receive notification of a processing instruction.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions for each
* processing instruction, such as setting status variables or
* invoking other methods.</p>
*
* @param target The processing instruction target.
* @param data The processing instruction data, or null if
* none is supplied.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#processingInstruction
*/
public void processingInstruction (String target, String data)
throws SAXException
{
// no op
}
/**
* Receive notification of a skipped entity.
*
* <p>By default, do nothing. Application writers may override this
* method in a subclass to take specific actions for each
* processing instruction, such as setting status variables or
* invoking other methods.</p>
*
* @param name The name of the skipped entity.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ContentHandler#processingInstruction
*/
public void skippedEntity (String name)
throws SAXException
{
// no op
}
////////////////////////////////////////////////////////////////////
// Default implementation of the ErrorHandler interface.
////////////////////////////////////////////////////////////////////
/**
* Receive notification of a parser warning.
*
* <p>The default implementation does nothing. Application writers
* may override this method in a subclass to take specific actions
* for each warning, such as inserting the message in a log file or
* printing it to the console.</p>
*
* @param e The warning information encoded as an exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ErrorHandler#warning
* @see org.xml.sax.SAXParseException
*/
public void warning (SAXParseException e)
throws SAXException
{
// no op
}
/**
* Receive notification of a recoverable parser error.
*
* <p>The default implementation does nothing. Application writers
* may override this method in a subclass to take specific actions
* for each error, such as inserting the message in a log file or
* printing it to the console.</p>
*
* @param e The warning information encoded as an exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ErrorHandler#warning
* @see org.xml.sax.SAXParseException
*/
public void error (SAXParseException e)
throws SAXException
{
// no op
}
/**
* Report a fatal XML parsing error.
*
* <p>The default implementation throws a SAXParseException.
* Application writers may override this method in a subclass if
* they need to take specific actions for each fatal error (such as
* collecting all of the errors into a single report): in any case,
* the application must stop all regular processing when this
* method is invoked, since the document is no longer reliable, and
* the parser may no longer report parsing events.</p>
*
* @param e The error information encoded as an exception.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @see org.xml.sax.ErrorHandler#fatalError
* @see org.xml.sax.SAXParseException
*/
public void fatalError (SAXParseException e)
throws SAXException
{
throw e;
}
}
// end of DefaultHandler.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/LocatorImpl.java
Index: LocatorImpl.java
===================================================================
// SAX default implementation for Locator.
// No warranty; no copyright -- use this as you will.
// $Id: LocatorImpl.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import org.xml.sax.Locator;
/**
* Provide an optional convenience implementation of Locator.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class is available mainly for application writers, who
* can use it to make a persistent snapshot of a locator at any
* point during a document parse:</p>
*
* <pre>
* Locator locator;
* Locator startloc;
*
* public void setLocator (Locator locator)
* {
* // note the locator
* this.locator = locator;
* }
*
* public void startDocument ()
* {
* // save the location of the start of the document
* // for future use.
* Locator startloc = new LocatorImpl(locator);
* }
*</pre>
*
* <p>Normally, parser writers will not use this class, since it
* is more efficient to provide location information only when
* requested, rather than constantly updating a Locator object.</p>
*
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.Locator Locator
*/
public class LocatorImpl implements Locator
{
/**
* Zero-argument constructor.
*
* <p>This will not normally be useful, since the main purpose
* of this class is to make a snapshot of an existing Locator.</p>
*/
public LocatorImpl ()
{
}
/**
* Copy constructor.
*
* <p>Create a persistent copy of the current state of a locator.
* When the original locator changes, this copy will still keep
* the original values (and it can be used outside the scope of
* DocumentHandler methods).</p>
*
* @param locator The locator to copy.
*/
public LocatorImpl (Locator locator)
{
setPublicId(locator.getPublicId());
setSystemId(locator.getSystemId());
setLineNumber(locator.getLineNumber());
setColumnNumber(locator.getColumnNumber());
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.Locator
////////////////////////////////////////////////////////////////////
/**
* Return the saved public identifier.
*
* @return The public identifier as a string, or null if none
* is available.
* @see org.xml.sax.Locator#getPublicId
* @see #setPublicId
*/
public String getPublicId ()
{
return publicId;
}
/**
* Return the saved system identifier.
*
* @return The system identifier as a string, or null if none
* is available.
* @see org.xml.sax.Locator#getSystemId
* @see #setSystemId
*/
public String getSystemId ()
{
return systemId;
}
/**
* Return the saved line number (1-based).
*
* @return The line number as an integer, or -1 if none is available.
* @see org.xml.sax.Locator#getLineNumber
* @see #setLineNumber
*/
public int getLineNumber ()
{
return lineNumber;
}
/**
* Return the saved column number (1-based).
*
* @return The column number as an integer, or -1 if none is available.
* @see org.xml.sax.Locator#getColumnNumber
* @see #setColumnNumber
*/
public int getColumnNumber ()
{
return columnNumber;
}
////////////////////////////////////////////////////////////////////
// Setters for the properties (not in org.xml.sax.Locator)
////////////////////////////////////////////////////////////////////
/**
* Set the public identifier for this locator.
*
* @param publicId The new public identifier, or null
* if none is available.
* @see #getPublicId
*/
public void setPublicId (String publicId)
{
this.publicId = publicId;
}
/**
* Set the system identifier for this locator.
*
* @param systemId The new system identifier, or null
* if none is available.
* @see #getSystemId
*/
public void setSystemId (String systemId)
{
this.systemId = systemId;
}
/**
* Set the line number for this locator (1-based).
*
* @param lineNumber The line number, or -1 if none is available.
* @see #getLineNumber
*/
public void setLineNumber (int lineNumber)
{
this.lineNumber = lineNumber;
}
/**
* Set the column number for this locator (1-based).
*
* @param columnNumber The column number, or -1 if none is available.
* @see #getColumnNumber
*/
public void setColumnNumber (int columnNumber)
{
this.columnNumber = columnNumber;
}
////////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////////
private String publicId;
private String systemId;
private int lineNumber;
private int columnNumber;
}
// end of LocatorImpl.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/NamespaceSupport.java
Index: NamespaceSupport.java
===================================================================
// NamespaceSupport.java - generic Namespace support for SAX.
// Written by David Megginson, sax@megginson.com
// This class is in the Public Domain. NO WARRANTY!
// $Id: NamespaceSupport.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import java.util.EmptyStackException;
import java.util.Enumeration;
import java.util.Hashtable;
import java.util.Vector;
/**
* Encapsulate Namespace logic for use by SAX drivers.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class encapsulates the logic of Namespace processing:
* it tracks the declarations currently in force for each context
* and automatically processes qualified XML 1.0 names into their
* Namespace parts; it can also be used in reverse for generating
* XML 1.0 from Namespaces.</p>
*
* <p>Namespace support objects are reusable, but the reset method
* must be invoked between each session.</p>
*
* <p>Here is a simple session:</p>
*
* <pre>
* String parts[] = new String[3];
* NamespaceSupport support = new NamespaceSupport();
*
* support.pushContext();
* support.declarePrefix("", "http://www.w3.org/1999/xhtml");
* support.declarePrefix("dc", "http://www.purl.org/dc#");
*
* String 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);
* System.out.println("Namespace URI: " + parts[0]);
* System.out.println("Local name: " + parts[1]);
* System.out.println("Raw name: " + parts[2]);
* support.popContext();
* </pre>
*
* <p>Note that this class is optimized for the use case where most
* elements do not contain Namespace declarations: if the same
* prefix/URI mapping is repeated for each context (for example), this
* class will be somewhat less efficient.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
*/
public class NamespaceSupport
{
////////////////////////////////////////////////////////////////////
// Constants.
////////////////////////////////////////////////////////////////////
/**
* The XML Namespace as a constant.
*
* <p>This is the Namespace URI that is automatically mapped
* to the "xml" prefix.</p>
*/
public final static String XMLNS =
"http://www.w3.org/XML/1998/namespace";
/**
* An empty enumeration.
*/
private final static Enumeration EMPTY_ENUMERATION =
new Vector().elements();
////////////////////////////////////////////////////////////////////
// Constructor.
////////////////////////////////////////////////////////////////////
/**
* Create a new Namespace support object.
*/
public NamespaceSupport ()
{
reset();
}
////////////////////////////////////////////////////////////////////
// Context management.
////////////////////////////////////////////////////////////////////
/**
* Reset this Namespace support object for reuse.
*
* <p>It is necessary to invoke this method before reusing the
* Namespace support object for a new session.</p>
*/
public void reset ()
{
contexts = new Context[32];
contextPos = 0;
contexts[contextPos] = currentContext = new Context();
currentContext.declarePrefix("xml", XMLNS);
}
/**
* Start a new Namespace context.
*
* <p>Normally, you should push a new context at the beginning
* of each XML element: the new context will automatically inherit
* the declarations of its parent context, but it will also keep
* track of which declarations were made within this context.</p>
*
* <p>The Namespace support object always starts with a base context
* already in force: in this context, only the "xml" prefix is
* declared.</p>
*
* @see #popContext
*/
public void pushContext ()
{
int max = contexts.length;
contextPos++;
// Extend the array if necessary
if (contextPos >= max) {
Context newContexts[] = new Context[max*2];
System.arraycopy(contexts, 0, newContexts, 0, max);
max *= 2;
contexts = newContexts;
}
// Allocate the context if necessary.
currentContext = contexts[contextPos];
if (currentContext == null) {
contexts[contextPos] = currentContext = new Context();
}
// Set the parent, if any.
if (contextPos > 0) {
currentContext.setParent(contexts[contextPos - 1]);
}
}
/**
* Revert to the previous Namespace context.
*
* <p>Normally, you should pop the context at the end of each
* XML element. After popping the context, all Namespace prefix
* mappings that were previously in force are restored.</p>
*
* <p>You must not attempt to declare additional Namespace
* prefixes after popping a context, unless you push another
* context first.</p>
*
* @see #pushContext
*/
public void popContext ()
{
contextPos--;
if (contextPos < 0) {
throw new EmptyStackException();
}
currentContext = contexts[contextPos];
}
////////////////////////////////////////////////////////////////////
// Operations within a context.
////////////////////////////////////////////////////////////////////
/**
* Declare a Namespace prefix.
*
* <p>This method declares a prefix in the current Namespace
* context; the prefix will remain in force until this context
* is popped, unless it is shadowed in a descendant context.</p>
*
* <p>To declare a default Namespace, use the empty string. The
* prefix must not be "xml" or "xmlns".</p>
*
* <p>Note that you must <em>not</em> declare a prefix after
* you've pushed and popped another Namespace.</p>
*
* <p>Note that there is an asymmetry in this library: while {@link
* #getPrefix getPrefix} will not return the default "" prefix,
* even if you have declared one; to check for a default prefix,
* you have to look it up explicitly using {@link #getURI getURI}.
* This asymmetry exists to make it easier to look up prefixes
* for attribute names, where the default prefix is not allowed.</p>
*
* @param prefix The prefix to declare, or null for the empty
* string.
* @param uri The Namespace URI to associate with the prefix.
* @return true if the prefix was legal, false otherwise
* @see #processName
* @see #getURI
* @see #getPrefix
*/
public boolean declarePrefix (String prefix, String uri)
{
if (prefix.equals("xml") || prefix.equals("xmlns")) {
return false;
} else {
currentContext.declarePrefix(prefix, uri);
return true;
}
}
/**
* Process a raw XML 1.0 name.
*
* <p>This method processes a raw XML 1.0 name in the current
* context by removing the prefix and looking it up among the
* prefixes currently declared. The return value will be the
* array supplied by the caller, filled in as follows:</p>
*
* <dl>
* <dt>parts[0]</dt>
* <dd>The Namespace URI, or an empty string if none is
* in use.</dd>
* <dt>parts[1]</dt>
* <dd>The local name (without prefix).</dd>
* <dt>parts[2]</dt>
* <dd>The original raw name.</dd>
* </dl>
*
* <p>All of the strings in the array will be internalized. If
* the raw name has a prefix that has not been declared, then
* the return value will be null.</p>
*
* <p>Note that attribute names are processed differently than
* element names: an unprefixed element name will received the
* default Namespace (if any), while an unprefixed element name
* will not.</p>
*
* @param qName The raw XML 1.0 name to be processed.
* @param parts An array supplied by the caller, capable of
* holding at least three members.
* @param isAttribute A flag indicating whether this is an
* attribute name (true) or an element name (false).
* @return The supplied array holding three internalized strings
* representing the Namespace URI (or empty string), the
* local name, and the raw XML 1.0 name; or null if there
* is an undeclared prefix.
* @see #declarePrefix
* @see java.lang.String#intern */
public String [] processName (String qName, String parts[],
boolean isAttribute)
{
String myParts[] = currentContext.processName(qName, isAttribute);
if (myParts == null) {
return null;
} else {
parts[0] = myParts[0];
parts[1] = myParts[1];
parts[2] = myParts[2];
return parts;
}
}
/**
* Look up a prefix and get the currently-mapped Namespace URI.
*
* <p>This method looks up the prefix in the current context.
* Use the empty string ("") for the default Namespace.</p>
*
* @param prefix The prefix to look up.
* @return The associated Namespace URI, or null if the prefix
* is undeclared in this context.
* @see #getPrefix
* @see #getPrefixes
*/
public String getURI (String prefix)
{
return currentContext.getURI(prefix);
}
/**
* Return an enumeration of all prefixes currently declared.
*
* <p><strong>Note:</strong> if there is a default prefix, it will not be
* returned in this enumeration; check for the default prefix
* using the {@link #getURI getURI} with an argument of "".</p>
*
* @return An enumeration of all prefixes declared in the
* current context except for the empty (default)
* prefix.
* @see #getDeclaredPrefixes
* @see #getURI
*/
public Enumeration getPrefixes ()
{
return currentContext.getPrefixes();
}
/**
* Return one of the prefixes mapped to a Namespace URI.
*
* <p>If more than one prefix is currently mapped to the same
* URI, this method will make an arbitrary selection; if you
* want all of the prefixes, use the {@link #getPrefixes}
* method instead.</p>
*
* <p><strong>Note:</strong> this will never return the empty (default) prefix;
* to check for a default prefix, use the {@link #getURI getURI}
* method with an argument of "".</p>
*
* @param uri The Namespace URI.
* @param isAttribute true if this prefix is for an attribute
* (and the default Namespace is not allowed).
* @return One of the prefixes currently mapped to the URI supplied,
* or null if none is mapped or if the URI is assigned to
* the default Namespace.
* @see #getPrefixes(java.lang.String)
* @see #getURI
*/
public String getPrefix (String uri)
{
return currentContext.getPrefix(uri);
}
/**
* Return an enumeration of all prefixes currently declared for a URI.
*
* <p>This method returns prefixes mapped to a specific Namespace
* URI. The xml: prefix will be included. If you want only one
* prefix that's mapped to the Namespace URI, and you don't care
* which one you get, use the {@link #getPrefix getPrefix}
* method instead.</p>
*
* <p><strong>Note:</strong> the empty (default) prefix is <em>never</em> included
* in this enumeration; to check for the presence of a default
* Namespace, use the {@link #getURI getURI} method with an
* argument of "".</p>
*
* @param uri The Namespace URI.
* @return An enumeration of all prefixes declared in the
* current context.
* @see #getPrefix
* @see #getDeclaredPrefixes
* @see #getURI
*/
public Enumeration getPrefixes (String uri)
{
Vector prefixes = new Vector();
Enumeration allPrefixes = getPrefixes();
while (allPrefixes.hasMoreElements()) {
String prefix = (String)allPrefixes.nextElement();
if (uri.equals(getURI(prefix))) {
prefixes.addElement(prefix);
}
}
return prefixes.elements();
}
/**
* Return an enumeration of all prefixes declared in this context.
*
* <p>The empty (default) prefix will be included in this
* enumeration; note that this behaviour differs from that of
* {@link #getPrefix} and {@link #getPrefixes}.</p>
*
* @return An enumeration of all prefixes declared in this
* context.
* @see #getPrefixes
* @see #getURI
*/
public Enumeration getDeclaredPrefixes ()
{
return currentContext.getDeclaredPrefixes();
}
////////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////////
private Context contexts[];
private Context currentContext;
private int contextPos;
////////////////////////////////////////////////////////////////////
// Internal classes.
////////////////////////////////////////////////////////////////////
/**
* Internal class for a single Namespace context.
*
* <p>This module caches and reuses Namespace contexts, so the number allocated
* will be equal to the element depth of the document, not to the total
* number of elements (i.e. 5-10 rather than tens of thousands).</p>
*/
final class Context {
/**
* Create the root-level Namespace context.
*/
Context ()
{
copyTables();
}
/**
* (Re)set the parent of this Namespace context.
*
* @param context The parent Namespace context object.
*/
void setParent (Context parent)
{
this.parent = parent;
declarations = null;
prefixTable = parent.prefixTable;
uriTable = parent.uriTable;
elementNameTable = parent.elementNameTable;
attributeNameTable = parent.attributeNameTable;
defaultNS = parent.defaultNS;
tablesDirty = false;
}
/**
* Declare a Namespace prefix for this context.
*
* @param prefix The prefix to declare.
* @param uri The associated Namespace URI.
* @see org.xml.sax.helpers.NamespaceSupport#declarePrefix
*/
void declarePrefix (String prefix, String uri)
{
// Lazy processing...
if (!tablesDirty) {
copyTables();
}
if (declarations == null) {
declarations = new Vector();
}
prefix = prefix.intern();
uri = uri.intern();
if ("".equals(prefix)) {
if ("".equals(uri)) {
defaultNS = null;
} else {
defaultNS = uri;
}
} else {
prefixTable.put(prefix, uri);
uriTable.put(uri, prefix); // may wipe out another prefix
}
declarations.addElement(prefix);
}
/**
* Process a raw XML 1.0 name in this context.
*
* @param qName The raw XML 1.0 name.
* @param isAttribute true if this is an attribute name.
* @return An array of three strings containing the
* URI part (or empty string), the local part,
* and the raw name, all internalized, or null
* if there is an undeclared prefix.
* @see org.xml.sax.helpers.NamespaceSupport#processName
*/
String [] processName (String qName, boolean isAttribute)
{
String name[];
Hashtable table;
// Select the appropriate table.
if (isAttribute) {
table = elementNameTable;
} else {
table = attributeNameTable;
}
// Start by looking in the cache, and
// return immediately if the name
// is already known in this content
name = (String[])table.get(qName);
if (name != null) {
return name;
}
// We haven't seen this name in this
// context before.
name = new String[3];
int index = qName.indexOf(':');
// No prefix.
if (index == -1) {
if (isAttribute || defaultNS == null) {
name[0] = "";
} else {
name[0] = defaultNS;
}
name[1] = qName.intern();
name[2] = name[1];
}
// Prefix
else {
String prefix = qName.substring(0, index);
String local = qName.substring(index+1);
String uri;
if ("".equals(prefix)) {
uri = defaultNS;
} else {
uri = (String)prefixTable.get(prefix);
}
if (uri == null) {
return null;
}
name[0] = uri;
name[1] = local.intern();
name[2] = qName.intern();
}
// Save in the cache for future use.
table.put(name[2], name);
tablesDirty = true;
return name;
}
/**
* Look up the URI associated with a prefix in this context.
*
* @param prefix The prefix to look up.
* @return The associated Namespace URI, or null if none is
* declared.
* @see org.xml.sax.helpers.NamespaceSupport#getURI
*/
String getURI (String prefix)
{
if ("".equals(prefix)) {
return defaultNS;
} else if (prefixTable == null) {
return null;
} else {
return (String)prefixTable.get(prefix);
}
}
/**
* Look up one of the prefixes associated with a URI in this context.
*
* <p>Since many prefixes may be mapped to the same URI,
* the return value may be unreliable.</p>
*
* @param uri The URI to look up.
* @return The associated prefix, or null if none is declared.
* @see org.xml.sax.helpers.NamespaceSupport#getPrefix
*/
String getPrefix (String uri)
{
if (uriTable == null) {
return null;
} else {
return (String)uriTable.get(uri);
}
}
/**
* Return an enumeration of prefixes declared in this context.
*
* @return An enumeration of prefixes (possibly empty).
* @see org.xml.sax.helpers.NamespaceSupport#getDeclaredPrefixes
*/
Enumeration getDeclaredPrefixes ()
{
if (declarations == null) {
return EMPTY_ENUMERATION;
} else {
return declarations.elements();
}
}
/**
* Return an enumeration of all prefixes currently in force.
*
* <p>The default prefix, if in force, is <em>not</em>
* returned, and will have to be checked for separately.</p>
*
* @return An enumeration of prefixes (never empty).
* @see org.xml.sax.helpers.NamespaceSupport#getPrefixes
*/
Enumeration getPrefixes ()
{
if (prefixTable == null) {
return EMPTY_ENUMERATION;
} else {
return prefixTable.keys();
}
}
////////////////////////////////////////////////////////////////
// Internal methods.
////////////////////////////////////////////////////////////////
/**
* Copy on write for the internal tables in this context.
*
* <p>This class is optimized for the normal case where most
* elements do not contain Namespace declarations.</p>
*/
private void copyTables ()
{
if (prefixTable != null) {
prefixTable = (Hashtable)prefixTable.clone();
} else {
prefixTable = new Hashtable();
}
if (uriTable != null) {
uriTable = (Hashtable)uriTable.clone();
} else {
uriTable = new Hashtable();
}
elementNameTable = new Hashtable();
attributeNameTable = new Hashtable();
tablesDirty = true;
}
////////////////////////////////////////////////////////////////
// Protected state.
////////////////////////////////////////////////////////////////
Hashtable prefixTable;
Hashtable uriTable;
Hashtable elementNameTable;
Hashtable attributeNameTable;
String defaultNS = null;
////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////
private Vector declarations = null;
private boolean tablesDirty = false;
private Context parent = null;
}
}
// end of NamespaceSupport.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/ParserAdapter.java
Index: ParserAdapter.java
===================================================================
// ParserAdapter.java - adapt a SAX1 Parser to a SAX2 XMLReader.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the public domain.
// $Id: ParserAdapter.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import java.io.IOException;
import java.util.Enumeration;
import java.util.Vector;
import org.xml.sax.Parser; // deprecated
import org.xml.sax.InputSource;
import org.xml.sax.Locator;
import org.xml.sax.AttributeList; // deprecated
import org.xml.sax.EntityResolver;
import org.xml.sax.DTDHandler;
import org.xml.sax.DocumentHandler; // deprecated
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import org.xml.sax.XMLReader;
import org.xml.sax.Attributes;
import org.xml.sax.ContentHandler;
import org.xml.sax.SAXNotRecognizedException;
import org.xml.sax.SAXNotSupportedException;
/**
* Adapt a SAX1 Parser as a SAX2 XMLReader.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class wraps a SAX1 {@link org.xml.sax.Parser Parser}
* and makes it act as a SAX2 {@link org.xml.sax.XMLReader XMLReader},
* with feature, property, and Namespace support. Note
* that it is not possible to report {@link org.xml.sax.ContentHandler#skippedEntity
* skippedEntity} events, since SAX1 does not make that information available.</p>
*
* <p>This adapter does not test for duplicate Namespace-qualified
* attribute names.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.helpers.XMLReaderAdapter
* @see org.xml.sax.XMLReader
* @see org.xml.sax.Parser
*/
public class ParserAdapter implements XMLReader, DocumentHandler
{
////////////////////////////////////////////////////////////////////
// Constructors.
////////////////////////////////////////////////////////////////////
/**
* Construct a new parser adapter.
*
* <p>Use the "org.xml.sax.parser" property to locate the
* embedded SAX1 driver.</p>
*
* @exception org.xml.sax.SAXException If the embedded driver
* cannot be instantiated or if the
* org.xml.sax.parser property is not specified.
*/
public ParserAdapter ()
throws SAXException
{
super();
String driver = System.getProperty("org.xml.sax.parser");
try {
setup(ParserFactory.makeParser());
} catch (ClassNotFoundException e1) {
throw new
SAXException("Cannot find SAX1 driver class " +
driver, e1);
} catch (IllegalAccessException e2) {
throw new
SAXException("SAX1 driver class " +
driver +
" found but cannot be loaded", e2);
} catch (InstantiationException e3) {
throw new
SAXException("SAX1 driver class " +
driver +
" loaded but cannot be instantiated", e3);
} catch (ClassCastException e4) {
throw new
SAXException("SAX1 driver class " +
driver +
" does not implement org.xml.sax.Parser");
} catch (NullPointerException e5) {
throw new
SAXException("System property org.xml.sax.parser not specified");
}
}
/**
* Construct a new parser adapter.
*
* <p>Note that the embedded parser cannot be changed once the
* adapter is created; to embed a different parser, allocate
* a new ParserAdapter.</p>
*
* @param parser The SAX1 parser to embed.
* @exception java.lang.NullPointerException If the parser parameter
* is null.
*/
public ParserAdapter (Parser parser)
{
super();
setup(parser);
}
/**
* Internal setup method.
*
* @param parser The embedded parser.
* @exception java.lang.NullPointerException If the parser parameter
* is null.
*/
private void setup (Parser parser)
{
if (parser == null) {
throw new
NullPointerException("Parser argument must not be null");
}
this.parser = parser;
atts = new AttributesImpl();
nsSupport = new NamespaceSupport();
attAdapter = new AttributeListAdapter();
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.XMLReader.
////////////////////////////////////////////////////////////////////
//
// Internal constants for the sake of convenience.
//
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.
*
* <p>The only features supported are namespaces and
* namespace-prefixes.</p>
*
* @param name The feature name, as a complete URI.
* @param state The requested feature state.
* @exception org.xml.sax.SAXNotRecognizedException If the feature
* name is not known.
* @exception org.xml.sax.SAXNotSupportedException If the feature
* state is not supported.
* @see org.xml.sax.XMLReader#setFeature
*/
public void setFeature (String name, boolean state)
throws SAXNotRecognizedException, SAXNotSupportedException
{
if (name.equals(NAMESPACES)) {
checkNotParsing("feature", name);
namespaces = state;
if (!namespaces && !prefixes) {
prefixes = true;
}
} else if (name.equals(NAMESPACE_PREFIXES)) {
checkNotParsing("feature", name);
prefixes = state;
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);
}
}
/**
* Check a parser feature.
*
* <p>The only features supported are namespaces and
* namespace-prefixes.</p>
*
* @param name The feature name, as a complete URI.
* @return The current feature state.
* @exception org.xml.sax.SAXNotRecognizedException If the feature
* name is not known.
* @exception org.xml.sax.SAXNotSupportedException If querying the
* feature state is not supported.
* @see org.xml.sax.XMLReader#setFeature
*/
public boolean getFeature (String name)
throws SAXNotRecognizedException, SAXNotSupportedException
{
if (name.equals(NAMESPACES)) {
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);
}
}
/**
* Set a parser property.
*
* <p>No special properties are currently supported.</p>
*
* @param name The property name.
* @param value The property value.
* @exception org.xml.sax.SAXNotRecognizedException If the feature
* name is not known.
* @exception org.xml.sax.SAXNotSupportedException If the feature
* state is not supported.
* @see org.xml.sax.XMLReader#setProperty
*/
public void setProperty (String name, Object value)
throws SAXNotRecognizedException, SAXNotSupportedException
{
throw new SAXNotRecognizedException("Property: " + name);
}
/**
* Get a parser property.
*
* <p>No special properties are currently supported.</p>
*
* @param name The property name.
* @return The property value.
* @exception org.xml.sax.SAXNotRecognizedException If the feature
* name is not known.
* @exception org.xml.sax.SAXNotSupportedException If the feature
* state is not supported.
* @see org.xml.sax.XMLReader#getProperty
*/
public Object getProperty (String name)
throws SAXNotRecognizedException, SAXNotSupportedException
{
throw new SAXNotRecognizedException("Property: " + name);
}
/**
* 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;
}
/**
* Return the current entity resolver.
*
* @return The current entity resolver, or null if none was supplied.
* @see org.xml.sax.XMLReader#getEntityResolver
*/
public EntityResolver getEntityResolver ()
{
return entityResolver;
}
/**
* 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;
}
/**
* Return the current DTD handler.
*
* @return The current DTD handler, or null if none was supplied.
* @see org.xml.sax.XMLReader#getEntityResolver
*/
public DTDHandler getDTDHandler ()
{
return dtdHandler;
}
/**
* 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;
}
/**
* Return the current content handler.
*
* @return The current content handler, or null if none was supplied.
* @see org.xml.sax.XMLReader#getEntityResolver
*/
public ContentHandler getContentHandler ()
{
return contentHandler;
}
/**
* 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;
}
/**
* Return the current error handler.
*
* @return The current error handler, or null if none was supplied.
* @see org.xml.sax.XMLReader#getEntityResolver
*/
public ErrorHandler getErrorHandler ()
{
return errorHandler;
}
/**
* Parse an XML document.
*
* @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
* processing the document.
* @see #parse(org.xml.sax.InputSource)
* @see org.xml.sax.Parser#parse(java.lang.String)
*/
public void parse (String systemId)
throws IOException, SAXException
{
parse(new InputSource(systemId));
}
/**
* Parse an XML document.
*
* @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
* processing the document.
* @see #parse(java.lang.String)
* @see org.xml.sax.Parser#parse(org.xml.sax.InputSource)
*/
public void parse (InputSource input)
throws IOException, SAXException
{
if (parsing) {
throw new SAXException("Parser is already in use");
}
setupParser();
parsing = true;
try {
parser.parse(input);
} finally {
parsing = false;
}
parsing = false;
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.DocumentHandler.
////////////////////////////////////////////////////////////////////
/**
* Adapt a SAX1 document locator event.
*
* @param locator A document locator.
* @see org.xml.sax.ContentHandler#setDocumentLocator
*/
public void setDocumentLocator (Locator locator)
{
this.locator = locator;
if (contentHandler != null) {
contentHandler.setDocumentLocator(locator);
}
}
/**
* Adapt a SAX1 start document event.
*
* @exception org.xml.sax.SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#startDocument
*/
public void startDocument ()
throws SAXException
{
if (contentHandler != null) {
contentHandler.startDocument();
}
}
/**
* Adapt a SAX1 end document event.
*
* @exception org.xml.sax.SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#endDocument
*/
public void endDocument ()
throws SAXException
{
if (contentHandler != null) {
contentHandler.endDocument();
}
}
/**
* Adapt a SAX1 startElement event.
*
* <p>If necessary, perform Namespace processing.</p>
*
* @param qName The qualified (prefixed) name.
* @param qAtts The XML 1.0 attribute list (with qnames).
*/
public void startElement (String qName, AttributeList qAtts)
throws SAXException
{
// These are exceptions from the
// first pass; they should be
// ignored if there's a second pass,
// but reported otherwise.
Vector exceptions = null;
// If we're not doing Namespace
// processing, dispatch this quickly.
if (!namespaces) {
if (contentHandler != null) {
attAdapter.setAttributeList(qAtts);
contentHandler.startElement("", "", qName.intern(),
attAdapter);
}
return;
}
// 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();
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...
if (attQName.startsWith("xmlns")) {
String prefix;
int n = attQName.indexOf(':');
if (n == -1) {
prefix = "";
} 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(),
type, value);
}
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.add(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) {
for (int i = 0; i < exceptions.size(); i++)
errorHandler.error((SAXParseException)(exceptions.get(i)));
}
// OK, finally report the event.
if (contentHandler != null) {
String name[] = processName(qName, false, false);
contentHandler.startElement(name[0], name[1], name[2], atts);
}
}
/**
* Adapt a SAX1 end element event.
*
* @param qName The qualified (prefixed) name.
* @exception org.xml.sax.SAXException The client may raise a
* processing exception.
* @see org.xml.sax.DocumentHandler#endElement
*/
public void endElement (String qName)
throws SAXException
{
// If we're not doing Namespace
// processing, dispatch this quickly.
if (!namespaces) {
if (contentHandler != null) {
contentHandler.endElement("", "", qName.intern());
}
return;
}
// Split the name.
String names[] = processName(qName, false, false);
if (contentHandler != null) {
contentHandler.endElement(names[0], names[1], names[2]);
Enumeration prefixes = nsSupport.getDeclaredPrefixes();
while (prefixes.hasMoreElements()) {
String prefix = (String)prefixes.nextElement();
contentHandler.endPrefixMapping(prefix);
}
}
nsSupport.popContext();
}
/**
* 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
* processing exception.
* @see org.xml.sax.DocumentHandler#characters
*/
public void characters (char ch[], int start, int length)
throws SAXException
{
if (contentHandler != null) {
contentHandler.characters(ch, start, length);
}
}
/**
* 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
* processing exception.
* @see org.xml.sax.DocumentHandler#ignorableWhitespace
*/
public void ignorableWhitespace (char ch[], int start, int length)
throws SAXException
{
if (contentHandler != null) {
contentHandler.ignorableWhitespace(ch, start, length);
}
}
/**
* 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
* processing exception.
* @see org.xml.sax.DocumentHandler#processingInstruction
*/
public void processingInstruction (String target, String data)
throws SAXException
{
if (contentHandler != null) {
contentHandler.processingInstruction(target, data);
}
}
////////////////////////////////////////////////////////////////////
// Internal utility methods.
////////////////////////////////////////////////////////////////////
/**
* Initialize the parser before each run.
*/
private void setupParser ()
{
nsSupport.reset();
if (entityResolver != null) {
parser.setEntityResolver(entityResolver);
}
if (dtdHandler != null) {
parser.setDTDHandler(dtdHandler);
}
if (errorHandler != null) {
parser.setErrorHandler(errorHandler);
}
parser.setDocumentHandler(this);
locator = null;
}
/**
* Process a qualified (prefixed) name.
*
* <p>If the name has an undeclared prefix, use only the qname
* and make an ErrorHandler.error callback in case the app is
* interested.</p>
*
* @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
* an exception if there is an error callback.
*/
private String [] processName (String qName, boolean isAttribute,
boolean useException)
throws SAXException
{
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);
}
return parts;
}
/**
* Report a non-fatal error.
*
* @param message The error message.
* @exception org.xml.sax.SAXException The client may throw
* an exception.
*/
void reportError (String message)
throws SAXException
{
if (errorHandler != null)
errorHandler.error(makeException(message));
}
/**
* Construct an exception for the current context.
*
* @param message The error message.
*/
private SAXParseException makeException (String message)
{
SAXParseException e;
if (locator != null) {
return new SAXParseException(message, locator);
} else {
return new SAXParseException(message, null, null, -1, -1);
}
}
/**
* Throw an exception if we are parsing.
*
* <p>Use this method to detect illegal feature or
* property changes.</p>
*
* @param type The type of thing (feature or property).
* @param name The feature or property name.
* @exception org.xml.sax.SAXNotSupportedException If a
* document is currently being parsed.
*/
private void checkNotParsing (String type, String name)
throws SAXNotSupportedException
{
if (parsing) {
throw new SAXNotSupportedException("Cannot change " +
type + ' ' +
name + " while parsing");
}
}
////////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////////
private NamespaceSupport nsSupport;
private AttributeListAdapter attAdapter;
private boolean parsing = false;
private String nameParts[] = new String[3];
private Parser parser = null;
private AttributesImpl atts = null;
// Features
private boolean namespaces = true;
private boolean prefixes = false;
// Properties
// Handlers
Locator locator;
EntityResolver entityResolver = null;
DTDHandler dtdHandler = null;
ContentHandler contentHandler = null;
ErrorHandler errorHandler = null;
////////////////////////////////////////////////////////////////////
// Inner class to wrap an AttributeList when not doing NS proc.
////////////////////////////////////////////////////////////////////
/**
* Adapt a SAX1 AttributeList as a SAX2 Attributes object.
*
* <p>This class is in the Public Domain, and comes with NO
* WARRANTY of any kind.</p>
*
* <p>This wrapper class is used only when Namespace support
* is disabled -- it provides pretty much a direct mapping
* from SAX1 to SAX2, except that names and types are
* interned whenever requested.</p>
*/
final class AttributeListAdapter implements Attributes
{
/**
* Construct a new adapter.
*/
AttributeListAdapter ()
{
}
/**
* Set the embedded AttributeList.
*
* <p>This method must be invoked before any of the others
* can be used.</p>
*
* @param The SAX1 attribute list (with qnames).
*/
void setAttributeList (AttributeList qAtts)
{
this.qAtts = qAtts;
}
/**
* Return the length of the attribute list.
*
* @return The number of attributes in the list.
* @see org.xml.sax.Attributes#getLength
*/
public int getLength ()
{
return qAtts.getLength();
}
/**
* Return the Namespace URI of the specified attribute.
*
* @param The attribute's index.
* @return Always the empty string.
* @see org.xml.sax.Attributes#getURI
*/
public String getURI (int i)
{
return "";
}
/**
* Return the local name of the specified attribute.
*
* @param The attribute's index.
* @return Always the empty string.
* @see org.xml.sax.Attributes#getLocalName
*/
public String getLocalName (int i)
{
return "";
}
/**
* Return the qualified (prefixed) name of the specified attribute.
*
* @param The attribute's index.
* @return The attribute's qualified name, internalized.
*/
public String getQName (int i)
{
return qAtts.getName(i).intern();
}
/**
* Return the type of the specified attribute.
*
* @param The attribute's index.
* @return The attribute's type as an internalized string.
*/
public String getType (int i)
{
return qAtts.getType(i).intern();
}
/**
* Return the value of the specified attribute.
*
* @param The attribute's index.
* @return The attribute's value.
*/
public String getValue (int i)
{
return qAtts.getValue(i);
}
/**
* Look up an attribute index by Namespace name.
*
* @param uri The Namespace URI or the empty string.
* @param localName The local name.
* @return The attributes index, or -1 if none was found.
* @see org.xml.sax.Attributes#getIndex(java.lang.String,java.lang.String)
*/
public int getIndex (String uri, String localName)
{
return -1;
}
/**
* Look up an attribute index by qualified (prefixed) name.
*
* @param qName The qualified name.
* @return The attributes index, or -1 if none was found.
* @see org.xml.sax.Attributes#getIndex(java.lang.String)
*/
public int getIndex (String qName)
{
int max = atts.getLength();
for (int i = 0; i < max; i++) {
if (qAtts.getName(i).equals(qName)) {
return i;
}
}
return -1;
}
/**
* Look up the type of an attribute by Namespace name.
*
* @param uri The Namespace URI
* @param localName The local name.
* @return The attribute's type as an internalized string.
*/
public String getType (String uri, String localName)
{
return null;
}
/**
* Look up the type of an attribute by qualified (prefixed) name.
*
* @param qName The qualified name.
* @return The attribute's type as an internalized string.
*/
public String getType (String qName)
{
return qAtts.getType(qName).intern();
}
/**
* Look up the value of an attribute by Namespace name.
*
* @param uri The Namespace URI
* @param localName The local name.
* @return The attribute's value.
*/
public String getValue (String uri, String localName)
{
return null;
}
/**
* Look up the value of an attribute by qualified (prefixed) name.
*
* @param qName The qualified name.
* @return The attribute's value.
*/
public String getValue (String qName)
{
return qAtts.getValue(qName);
}
private AttributeList qAtts;
}
}
// end of ParserAdapter.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/ParserFactory.java
Index: ParserFactory.java
===================================================================
// SAX parser factory.
// No warranty; no copyright -- use this as you will.
// $Id: ParserFactory.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import java.lang.ClassNotFoundException;
import java.lang.IllegalAccessException;
import java.lang.InstantiationException;
import java.lang.SecurityException;
import java.lang.ClassCastException;
import org.xml.sax.Parser;
/**
* Java-specific class for dynamically loading SAX parsers.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p><strong>Note:</strong> This class is designed to work with the now-deprecated
* SAX1 {@link org.xml.sax.Parser Parser} class. SAX2 applications should use
* {@link org.xml.sax.helpers.XMLReaderFactory XMLReaderFactory} instead.</p>
*
* <p>ParserFactory is not part of the platform-independent definition
* of SAX; it is an additional convenience class designed
* specifically for Java XML application writers. SAX applications
* can use the static methods in this class to allocate a SAX parser
* dynamically at run-time based either on the value of the
* `org.xml.sax.parser' system property or on a string containing the class
* name.</p>
*
* <p>Note that the application still requires an XML parser that
* implements SAX1.</p>
*
* @deprecated This class works with the deprecated
* {@link org.xml.sax.Parser Parser}
* interface.
* @since SAX 1.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.Parser
* @see java.lang.Class
*/
public class ParserFactory {
/**
* Private null constructor.
*/
private ParserFactory ()
{
}
/**
* Create a new SAX parser using the `org.xml.sax.parser' system property.
*
* <p>The named class must exist and must implement the
* {@link org.xml.sax.Parser Parser} interface.</p>
*
* @exception java.lang.NullPointerException There is no value
* for the `org.xml.sax.parser' system property.
* @exception java.lang.ClassNotFoundException The SAX parser
* class was not found (check your CLASSPATH).
* @exception IllegalAccessException The SAX parser class was
* found, but you do not have permission to load
* it.
* @exception InstantiationException The SAX parser class was
* found but could not be instantiated.
* @exception java.lang.ClassCastException The SAX parser class
* was found and instantiated, but does not implement
* org.xml.sax.Parser.
* @see #makeParser(java.lang.String)
* @see org.xml.sax.Parser
*/
public static Parser makeParser ()
throws ClassNotFoundException,
IllegalAccessException,
InstantiationException,
NullPointerException,
ClassCastException
{
String className = System.getProperty("org.xml.sax.parser");
if (className == null) {
throw new NullPointerException("No value for sax.parser property");
} else {
return makeParser(className);
}
}
/**
* Create a new SAX parser object using the class name provided.
*
* <p>The named class must exist and must implement the
* {@link org.xml.sax.Parser Parser} interface.</p>
*
* @param className A string containing the name of the
* SAX parser class.
* @exception java.lang.ClassNotFoundException The SAX parser
* class was not found (check your CLASSPATH).
* @exception IllegalAccessException The SAX parser class was
* found, but you do not have permission to load
* it.
* @exception InstantiationException The SAX parser class was
* found but could not be instantiated.
* @exception java.lang.ClassCastException The SAX parser class
* was found and instantiated, but does not implement
* org.xml.sax.Parser.
* @see #makeParser()
* @see org.xml.sax.Parser
*/
public static Parser makeParser (String className)
throws ClassNotFoundException,
IllegalAccessException,
InstantiationException,
ClassCastException
{
return (Parser)(Class.forName(className).newInstance());
}
}
// end of ParserFactory.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/XMLFilterImpl.java
Index: XMLFilterImpl.java
===================================================================
// XMLFilterImpl.java - base SAX2 filter implementation.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the Public Domain.
// $Id: XMLFilterImpl.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import java.io.IOException;
import org.xml.sax.XMLReader;
import org.xml.sax.XMLFilter;
import org.xml.sax.InputSource;
import org.xml.sax.Locator;
import org.xml.sax.Attributes;
import org.xml.sax.EntityResolver;
import org.xml.sax.DTDHandler;
import org.xml.sax.ContentHandler;
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import org.xml.sax.SAXNotSupportedException;
import org.xml.sax.SAXNotRecognizedException;
/**
* Base class for deriving an XML filter.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class is designed to sit between an {@link org.xml.sax.XMLReader
* XMLReader} and the client application's event handlers. By default, it
* does nothing but pass requests up to the reader and events
* on to the handlers unmodified, but subclasses can override
* specific methods to modify the event stream or the configuration
* requests as they pass through.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.XMLFilter
* @see org.xml.sax.XMLReader
* @see org.xml.sax.EntityResolver
* @see org.xml.sax.DTDHandler
* @see org.xml.sax.ContentHandler
* @see org.xml.sax.ErrorHandler
*/
public class XMLFilterImpl
implements XMLFilter, EntityResolver, DTDHandler, ContentHandler, ErrorHandler
{
////////////////////////////////////////////////////////////////////
// Constructors.
////////////////////////////////////////////////////////////////////
/**
* Construct an empty XML filter, with no parent.
*
* <p>This filter will have no parent: you must assign a parent
* before you start a parse or do any configuration with
* setFeature or setProperty.</p>
*
* @see org.xml.sax.XMLReader#setFeature
* @see org.xml.sax.XMLReader#setProperty
*/
public XMLFilterImpl ()
{
super();
}
/**
* Construct an XML filter with the specified parent.
*
* @see #setParent
* @see #getParent
*/
public XMLFilterImpl (XMLReader parent)
{
super();
setParent(parent);
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.XMLFilter.
////////////////////////////////////////////////////////////////////
/**
* Set the parent reader.
*
* <p>This is the {@link org.xml.sax.XMLReader XMLReader} from which
* this filter will obtain its events and to which it will pass its
* configuration requests. The parent may itself be another filter.</p>
*
* <p>If there is no parent reader set, any attempt to parse
* or to set or get a feature or property will fail.</p>
*
* @param parent The parent XML reader.
* @exception java.lang.NullPointerException If the parent is null.
* @see #getParent
*/
public void setParent (XMLReader parent)
{
if (parent == null) {
throw new NullPointerException("Null parent");
}
this.parent = parent;
}
/**
* Get the parent reader.
*
* @return The parent XML reader, or null if none is set.
* @see #setParent
*/
public XMLReader getParent ()
{
return parent;
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.XMLReader.
////////////////////////////////////////////////////////////////////
/**
* Set the state of a feature.
*
* <p>This will always fail if the parent is null.</p>
*
* @param name The feature name.
* @param state The requested feature state.
* @exception org.xml.sax.SAXNotRecognizedException When the
* XMLReader does not recognize the feature name.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader recognizes the feature name but
* cannot set the requested value.
* @see org.xml.sax.XMLReader#setFeature
*/
public void setFeature (String name, boolean state)
throws SAXNotRecognizedException, SAXNotSupportedException
{
if (parent != null) {
parent.setFeature(name, state);
} else {
throw new SAXNotRecognizedException("Feature: " + name);
}
}
/**
* Look up the state of a feature.
*
* <p>This will always fail if the parent is null.</p>
*
* @param name The feature name.
* @return The current state of the feature.
* @exception org.xml.sax.SAXNotRecognizedException When the
* XMLReader does not recognize the feature name.
* @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
*/
public boolean getFeature (String name)
throws SAXNotRecognizedException, SAXNotSupportedException
{
if (parent != null) {
return parent.getFeature(name);
} else {
throw new SAXNotRecognizedException("Feature: " + name);
}
}
/**
* Set the value of a property.
*
* <p>This will always fail if the parent is null.</p>
*
* @param name The property name.
* @param state The requested property value.
* @exception org.xml.sax.SAXNotRecognizedException When the
* XMLReader does not recognize the property name.
* @exception org.xml.sax.SAXNotSupportedException When the
* XMLReader 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
{
if (parent != null) {
parent.setProperty(name, value);
} else {
throw new SAXNotRecognizedException("Property: " + name);
}
}
/**
* Look up the value of a property.
*
* @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.SAXNotSupportedException When the
* XMLReader 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
{
if (parent != null) {
return parent.getProperty(name);
} else {
throw new SAXNotRecognizedException("Property: " + name);
}
}
/**
* 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;
}
}
/**
* 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 ()
{
return entityResolver;
}
/**
* 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;
}
}
/**
* 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 ()
{
return dtdHandler;
}
/**
* 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;
}
}
/**
* 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 ()
{
return contentHandler;
}
/**
* 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;
}
}
/**
* 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 ()
{
return errorHandler;
}
/**
* Parse a document.
*
* @param input The input source for the document entity.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @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
{
setupParse();
parent.parse(input);
}
/**
* Parse a document.
*
* @param systemId The system identifier as a fully-qualified URI.
* @exception org.xml.sax.SAXException Any SAX exception, possibly
* wrapping another exception.
* @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
{
parse(new InputSource(systemId));
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.EntityResolver.
////////////////////////////////////////////////////////////////////
/**
* Filter an external entity resolution.
*
* @param publicId The entity's public identifier, or null.
* @param systemId The entity's system identifier.
* @return A new InputSource or null for the default.
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
* @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
{
if (entityResolver != null) {
return entityResolver.resolveEntity(publicId, systemId);
} else {
return null;
}
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.DTDHandler.
////////////////////////////////////////////////////////////////////
/**
* Filter a notation declaration event.
*
* @param name The notation name.
* @param publicId The notation's public identifier, or null.
* @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
{
if (dtdHandler != null) {
dtdHandler.notationDecl(name, publicId, systemId);
}
}
/**
* Filter an unparsed entity declaration event.
*
* @param name The entity name.
* @param publicId The entity's public identifier, or null.
* @param systemId The entity's system identifier, or null.
* @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)
throws SAXException
{
if (dtdHandler != null) {
dtdHandler.unparsedEntityDecl(name, publicId, systemId,
notationName);
}
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.ContentHandler.
////////////////////////////////////////////////////////////////////
/**
* Filter a new document locator event.
*
* @param locator The document locator.
* @see org.xml.sax.ContentHandler#setDocumentLocator
*/
public void setDocumentLocator (Locator locator)
{
this.locator = locator;
if (contentHandler != null) {
contentHandler.setDocumentLocator(locator);
}
}
/**
* Filter a start document event.
*
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
* @see org.xml.sax.ContentHandler#startDocument
*/
public void startDocument ()
throws SAXException
{
if (contentHandler != null) {
contentHandler.startDocument();
}
}
/**
* Filter an end document event.
*
* @exception org.xml.sax.SAXException The client may throw
* an exception during processing.
* @see org.xml.sax.ContentHandler#endDocument
*/
public void endDocument ()
throws SAXException
{
if (contentHandler != null) {
contentHandler.endDocument();
}
}
/**
* Filter a start Namespace prefix mapping event.
*
* @param prefix The Namespace prefix.
* @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
{
if (contentHandler != null) {
contentHandler.startPrefixMapping(prefix, uri);
}
}
/**
* Filter an end Namespace prefix mapping event.
*
* @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
{
if (contentHandler != null) {
contentHandler.endPrefixMapping(prefix);
}
}
/**
* Filter a start element event.
*
* @param uri The element's Namespace URI, or the empty string.
* @param localName The element's local name, or the empty string.
* @param qName The element's qualified (prefixed) name, or the empty
* string.
* @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)
throws SAXException
{
if (contentHandler != null) {
contentHandler.startElement(uri, localName, qName, atts);
}
}
/**
* Filter an end element event.
*
* @param uri The element's Namespace URI, or the empty string.
* @param localName The element's local name, or the empty string.
* @param qName The element's qualified (prefixed) name, or the empty
* 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
{
if (contentHandler != null) {
contentHandler.endElement(uri, localName, qName);
}
}
/**
* Filter a character data event.
*
* @param ch An array of characters.
* @param start The starting position in the array.
* @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
{
if (contentHandler != null) {
contentHandler.characters(ch, start, length);
}
}
/**
* Filter an 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 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
{
if (contentHandler != null) {
contentHandler.ignorableWhitespace(ch, start, length);
}
}
/**
* Filter a processing instruction event.
*
* @param target The processing instruction target.
* @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
{
if (contentHandler != null) {
contentHandler.processingInstruction(target, data);
}
}
/**
* Filter a skipped entity event.
*
* @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
{
if (contentHandler != null) {
contentHandler.skippedEntity(name);
}
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.ErrorHandler.
////////////////////////////////////////////////////////////////////
/**
* Filter a warning event.
*
* @param e The nwarning 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
{
if (errorHandler != null) {
errorHandler.warning(e);
}
}
/**
* Filter an error event.
*
* @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
{
if (errorHandler != null) {
errorHandler.error(e);
}
}
/**
* Filter a fatal error event.
*
* @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
{
if (errorHandler != null) {
errorHandler.fatalError(e);
}
}
////////////////////////////////////////////////////////////////////
// Internal methods.
////////////////////////////////////////////////////////////////////
/**
* Set up before a parse.
*
* <p>Before every parse, check whether the parent is
* non-null, and re-register the filter for all of the
* events.</p>
*/
private void setupParse ()
{
if (parent == null) {
throw new NullPointerException("No parent for filter");
}
parent.setEntityResolver(this);
parent.setDTDHandler(this);
parent.setContentHandler(this);
parent.setErrorHandler(this);
}
////////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////////
private XMLReader parent = null;
private Locator locator = null;
private EntityResolver entityResolver = null;
private DTDHandler dtdHandler = null;
private ContentHandler contentHandler = null;
private ErrorHandler errorHandler = null;
}
// end of XMLFilterImpl.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/XMLReaderAdapter.java
Index: XMLReaderAdapter.java
===================================================================
// XMLReaderAdapter.java - adapt an SAX2 XMLReader to a SAX1 Parser
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the public domain.
// $Id: XMLReaderAdapter.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import java.io.IOException;
import java.util.Locale;
import org.xml.sax.Parser; // deprecated
import org.xml.sax.Locator;
import org.xml.sax.InputSource;
import org.xml.sax.AttributeList; // deprecated
import org.xml.sax.EntityResolver;
import org.xml.sax.DTDHandler;
import org.xml.sax.DocumentHandler; // deprecated
import org.xml.sax.ErrorHandler;
import org.xml.sax.SAXException;
import org.xml.sax.XMLReader;
import org.xml.sax.Attributes;
import org.xml.sax.ContentHandler;
import org.xml.sax.SAXNotSupportedException;
/**
* Adapt a SAX2 XMLReader as a SAX1 Parser.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class wraps a SAX2 {@link org.xml.sax.XMLReader XMLReader}
* and makes it act as a SAX1 {@link org.xml.sax.Parser Parser}. The XMLReader
* must support a true value for the
* http://xml.org/sax/features/namespace-prefixes property or parsing will fail
* with a {@link org.xml.sax.SAXException SAXException}; if the XMLReader
* supports a false value for the http://xml.org/sax/features/namespaces
* property, that will also be used to improve efficiency.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.Parser
* @see org.xml.sax.XMLReader
*/
public class XMLReaderAdapter implements Parser, ContentHandler
{
////////////////////////////////////////////////////////////////////
// Constructor.
////////////////////////////////////////////////////////////////////
/**
* Create a new adapter.
*
* <p>Use the "org.xml.sax.driver" property to locate the SAX2
* driver to embed.</p>
*
* @exception org.xml.sax.SAXException If the embedded driver
* cannot be instantiated or if the
* org.xml.sax.driver property is not specified.
*/
public XMLReaderAdapter ()
throws SAXException
{
setup(XMLReaderFactory.createXMLReader());
}
/**
* Create a new adapter.
*
* <p>Create a new adapter, wrapped around a SAX2 XMLReader.
* The adapter will make the XMLReader act like a SAX1
* Parser.</p>
*
* @param xmlReader The SAX2 XMLReader to wrap.
* @exception java.lang.NullPointerException If the argument is null.
*/
public XMLReaderAdapter (XMLReader xmlReader)
{
setup(xmlReader);
}
/**
* Internal setup.
*
* @param xmlReader The embedded XMLReader.
*/
private void setup (XMLReader xmlReader)
{
if (xmlReader == null) {
throw new NullPointerException("XMLReader must not be null");
}
this.xmlReader = xmlReader;
qAtts = new AttributesAdapter();
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.Parser.
////////////////////////////////////////////////////////////////////
/**
* Set the locale for error reporting.
*
* <p>This is not supported in SAX2, and will always throw
* an exception.</p>
*
* @param The locale for error reporting.
* @see org.xml.sax.Parser#setLocale
*/
public void setLocale (Locale locale)
throws SAXException
{
throw new SAXNotSupportedException("setLocale not supported");
}
/**
* Register the entity resolver.
*
* @param resolver The new resolver.
* @see org.xml.sax.Parser#setEntityResolver
*/
public void setEntityResolver (EntityResolver resolver)
{
xmlReader.setEntityResolver(resolver);
}
/**
* Register the DTD event handler.
*
* @param handler The new DTD event handler.
* @see org.xml.sax.Parser#setDTDHandler
*/
public void setDTDHandler (DTDHandler handler)
{
xmlReader.setDTDHandler(handler);
}
/**
* Register the SAX1 document event handler.
*
* <p>Note that the SAX1 document handler has no Namespace
* support.</p>
*
* @param handler The new SAX1 document event handler.
* @see org.xml.sax.Parser#setDocumentHandler
*/
public void setDocumentHandler (DocumentHandler handler)
{
documentHandler = handler;
}
/**
* Register the error event handler.
*
* @param handler The new error event handler.
* @see org.xml.sax.Parser#setErrorHandler
*/
public void setErrorHandler (ErrorHandler handler)
{
xmlReader.setErrorHandler(handler);
}
/**
* Parse the document.
*
* <p>This method will throw an exception if the embedded
* XMLReader does not support the
* http://xml.org/sax/features/namespace-prefixes property.</p>
*
* @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
* processing the document.
* @see #parse(org.xml.sax.InputSource)
* @see org.xml.sax.Parser#parse(java.lang.String)
*/
public void parse (String systemId)
throws IOException, SAXException
{
parse(new InputSource(systemId));
}
/**
* Parse the document.
*
* <p>This method will throw an exception if the embedded
* XMLReader does not support the
* http://xml.org/sax/features/namespace-prefixes property.</p>
*
* @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
* processing the document.
* @see #parse(java.lang.String)
* @see org.xml.sax.Parser#parse(org.xml.sax.InputSource)
*/
public void parse (InputSource input)
throws IOException, SAXException
{
setupXMLReader();
xmlReader.parse(input);
}
/**
* Set up the XML reader.
*/
private void setupXMLReader ()
throws SAXException
{
xmlReader.setFeature("http://xml.org/sax/features/namespace-prefixes", true);
try {
xmlReader.setFeature("http://xml.org/sax/features/namespaces",
false);
} catch (SAXException e) {
// NO OP: it's just extra information, and we can ignore it
}
xmlReader.setContentHandler(this);
}
////////////////////////////////////////////////////////////////////
// Implementation of org.xml.sax.ContentHandler.
////////////////////////////////////////////////////////////////////
/**
* Set a document locator.
*
* @param locator The document locator.
* @see org.xml.sax.ContentHandler#setDocumentLocator
*/
public void setDocumentLocator (Locator locator)
{
if (documentHandler != null)
documentHandler.setDocumentLocator(locator);
}
/**
* Start document event.
*
* @exception org.xml.sax.SAXException The client may raise a
* processing exception.
* @see org.xml.sax.ContentHandler#startDocument
*/
public void startDocument ()
throws SAXException
{
if (documentHandler != null)
documentHandler.startDocument();
}
/**
* End document event.
*
* @exception org.xml.sax.SAXException The client may raise a
* processing exception.
* @see org.xml.sax.ContentHandler#endDocument
*/
public void endDocument ()
throws SAXException
{
if (documentHandler != null)
documentHandler.endDocument();
}
/**
* Adapt a SAX2 start prefix mapping event.
*
* @param prefix The prefix being mapped.
* @param uri The Namespace URI being mapped to.
* @see org.xml.sax.ContentHandler#startPrefixMapping
*/
public void startPrefixMapping (String prefix, String uri)
{
}
/**
* Adapt a SAX2 end prefix mapping event.
*
* @param prefix The prefix being mapped.
* @see org.xml.sax.ContentHandler#endPrefixMapping
*/
public void endPrefixMapping (String prefix)
{
}
/**
* Adapt a SAX2 start element event.
*
* @param uri The Namespace URI.
* @param localName The Namespace local name.
* @param qName The qualified (prefixed) name.
* @param atts The SAX2 attributes.
* @exception org.xml.sax.SAXException The client may raise a
* processing exception.
* @see org.xml.sax.ContentHandler#endDocument
*/
public void startElement (String uri, String localName,
String qName, Attributes atts)
throws SAXException
{
if (documentHandler != null) {
qAtts.setAttributes(atts);
documentHandler.startElement(qName, qAtts);
}
}
/**
* Adapt a SAX2 end element event.
*
* @param uri The Namespace URI.
* @param localName The Namespace local name.
* @param qName The qualified (prefixed) name.
* @exception org.xml.sax.SAXException The client may raise a
* processing exception.
* @see org.xml.sax.ContentHandler#endElement
*/
public void endElement (String uri, String localName,
String qName)
throws SAXException
{
if (documentHandler != null)
documentHandler.endElement(qName);
}
/**
* Adapt a SAX2 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
* processing exception.
* @see org.xml.sax.ContentHandler#characters
*/
public void characters (char ch[], int start, int length)
throws SAXException
{
if (documentHandler != null)
documentHandler.characters(ch, start, length);
}
/**
* Adapt a SAX2 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
* processing exception.
* @see org.xml.sax.ContentHandler#ignorableWhitespace
*/
public void ignorableWhitespace (char ch[], int start, int length)
throws SAXException
{
if (documentHandler != null)
documentHandler.ignorableWhitespace(ch, start, length);
}
/**
* Adapt a SAX2 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
* processing exception.
* @see org.xml.sax.ContentHandler#processingInstruction
*/
public void processingInstruction (String target, String data)
throws SAXException
{
if (documentHandler != null)
documentHandler.processingInstruction(target, data);
}
/**
* Adapt a SAX2 skipped entity event.
*
* @param name The name of the skipped entity.
* @see org.xml.sax.ContentHandler#skippedEntity
*/
public void skippedEntity (String name)
throws SAXException
{
}
////////////////////////////////////////////////////////////////////
// Internal state.
////////////////////////////////////////////////////////////////////
XMLReader xmlReader;
DocumentHandler documentHandler;
AttributesAdapter qAtts;
////////////////////////////////////////////////////////////////////
// Internal class.
////////////////////////////////////////////////////////////////////
/**
* Internal class to wrap a SAX2 Attributes object for SAX1.
*/
final class AttributesAdapter implements AttributeList
{
AttributesAdapter ()
{
}
/**
* Set the embedded Attributes object.
*
* @param The embedded SAX2 Attributes.
*/
void setAttributes (Attributes attributes)
{
this.attributes = attributes;
}
/**
* Return the number of attributes.
*
* @return The length of the attribute list.
* @see org.xml.sax.AttributeList#getLength
*/
public int getLength ()
{
return attributes.getLength();
}
/**
* Return the qualified (prefixed) name of an attribute by position.
*
* @return The qualified name.
* @see org.xml.sax.AttributeList#getName
*/
public String getName (int i)
{
return attributes.getQName(i);
}
/**
* Return the type of an attribute by position.
*
* @return The type.
* @see org.xml.sax.AttributeList#getType(int)
*/
public String getType (int i)
{
return attributes.getType(i);
}
/**
* Return the value of an attribute by position.
*
* @return The value.
* @see org.xml.sax.AttributeList#getValue(int)
*/
public String getValue (int i)
{
return attributes.getValue(i);
}
/**
* Return the type of an attribute by qualified (prefixed) name.
*
* @return The type.
* @see org.xml.sax.AttributeList#getType(java.lang.String)
*/
public String getType (String qName)
{
return attributes.getType(qName);
}
/**
* Return the value of an attribute by qualified (prefixed) name.
*
* @return The value.
* @see org.xml.sax.AttributeList#getValue(java.lang.String)
*/
public String getValue (String qName)
{
return attributes.getValue(qName);
}
private Attributes attributes;
}
}
// end of XMLReaderAdapter.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/XMLReaderFactory.java
Index: XMLReaderFactory.java
===================================================================
// XMLReaderFactory.java - factory for creating a new reader.
// Written by David Megginson, sax@megginson.com
// NO WARRANTY! This class is in the Public Domain.
// $Id: XMLReaderFactory.java,v 1.1 2001/05/20 03:12:58 curcuru Exp $
package org.xml.sax.helpers;
import org.xml.sax.Parser;
import org.xml.sax.XMLReader;
import org.xml.sax.SAXException;
/**
* Factory for creating an XML reader.
*
* <blockquote>
* <em>This module, both source code and documentation, is in the
* Public Domain, and comes with <strong>NO WARRANTY</strong>.</em>
* </blockquote>
*
* <p>This class contains static methods for creating an XML reader
* from an explicit class name, or for creating an XML reader based
* on the value of the <code>org.xml.sax.driver</code> system
* property:</p>
*
* <pre>
* try {
* XMLReader myReader = XMLReaderFactory.createXMLReader();
* } catch (SAXException e) {
* System.err.println(e.getMessage());
* }
* </pre>
*
* <p>Note that these methods will not be usable in environments where
* system properties are not accessible or where the application or
* applet is not permitted to load classes dynamically.</p>
*
* <p><strong>Note to implementors:</strong> SAX implementations in specialized
* environments may replace this class with a different one optimized for the
* environment, as long as its method signatures remain the same.</p>
*
* @since SAX 2.0
* @author David Megginson,
* <a href="mailto:sax@megginson.com">sax@megginson.com</a>
* @version 2.0r2pre
* @see org.xml.sax.XMLReader
*/
final public class XMLReaderFactory
{
/**
* Private constructor.
*
* <p>This constructor prevents the class from being instantiated.</p>
*/
private XMLReaderFactory ()
{
}
/**
* Attempt to create an XML reader from a system property.
*
* <p>This method uses the value of the system property
* "org.xml.sax.driver" as the full name of a Java class
* and tries to instantiate that class as a SAX2
* XMLReader.</p>
*
* <p>Note that many Java interpreters allow system properties
* to be specified on the command line.</p>
*
* @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.
* @see #createXMLReader(java.lang.String)
*/
public static synchronized XMLReader createXMLReader ()
throws SAXException
{
String className = System.getProperty("org.xml.sax.driver");
if (className == null) {
Parser parser;
try {
parser = ParserFactory.makeParser();
} 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);
}
}
/**
* Attempt to create an XML reader from a class name.
*
* <p>Given a class name, this method attempts to load
* and instantiate the class as an XML reader.</p>
*
* @return A new XML reader.
* @exception org.xml.sax.SAXException If the class cannot be
* loaded, instantiated, and cast to XMLReader.
* @see #createXMLReader()
*/
public static synchronized XMLReader createXMLReader (String className)
throws SAXException
{
try {
return (XMLReader)(Class.forName(className).newInstance());
} catch (ClassNotFoundException e1) {
throw new SAXException("SAX2 driver class " + className +
" not found", e1);
} catch (IllegalAccessException e2) {
throw new SAXException("SAX2 driver class " + className +
" 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?)",
e3);
} catch (ClassCastException e4) {
throw new SAXException("SAX2 driver class " + className +
" does not implement XMLReader", e4);
}
}
}
// end of XMLReaderFactory.java
1.1 xml-commons/java/external/src/org/xml/sax/helpers/package.html
Index: package.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX 2.0 r2 prerelease helper interfaces</title>
</head>
<body>
<h1>SAX 2.0 r2 prerelease helper interfaces</h1>
<blockquote>
<p class="copyright">This document is in the <strong>PUBLIC
DOMAIN</strong> and comes with <strong>NO WARRANTY</strong> of any
kind.</p>
</blockquote>
<p>This is a prerelease of a bugfix release for SAX2, the second
generation of the Simple API for XML. For information, see
docs/index.html.</p>
</body>
</html>
1.1 xml-commons/java/external/xdocs/sax/changes.html
Index: changes.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX2: Changes</title>
<link rel="stylesheet" type="text/css" href="sax-style.css" />
</head>
<body>
<h1>SAX2: Changes</h1>
<blockquote>
<p class="copyright">This document is in the Public Domain.</p>
</blockquote>
<div>
<h2>Changes from SAX 2.0 to SAX 2.0 r2 prerelease</h2>
<p>(See the ChangeLog in the distribution for more details.)</p>
<ul>
<li>Added simple test program src/SAXTest.java</li>
<li>Synchronized static methods in XMLReaderFactory for thread
safety.</li>
<li>Fixed bug in ParserAdapter that reported an incorrect error when
an attribute using a Namespace prefix appeared before the Namespace
declaration.</li>
<li>Fixed bugs in AttributesImpl that caused infinite loops or
prevented removing attributes.</li>
<li>Specified that InputSource.getSystemId should return null (not an
empty string) when no system ID is available.</li>
<li>Modified DefaultHandler.resolveEntity to throw IOException, as in
the interface specification.</li>
<li>Added default constructors to SAXException,
SAXNotRecognizedException, and SAXNotSupportedException.</li>
</ul>
</div>
<div>
<h2>Changes from SAX 2.0prerelease to SAX 2.0</h2>
<ul>
<li>Documented the fact that parse() and event handlers are
synchronous.</li>
<li>Documented the fact that xml: prefix never has
start/endPrefixMapping events.</li>
</ul>
</div>
<div>
<h2>Changes from SAX 2.0beta2 to SAX 2.0prerelease</h2>
<p>(See the <code>ChangeLog</code> included in the distribution for
more detailed information.)</p>
<ul>
<li>If the <code>org.xml.sax.driver property</code> is not specified
but the SAX <code>org.xml.sax.parser</code> property is specified, <a
href="javadoc/org/xml/sax/helpers/XMLReaderFactory.html#createXMLReader()"
>XMLReaderFactory.createXMLReader()</a> will
attempt to create an XML1 <a
href="javadoc/org/xml/sax/Parser.html">Parser</a> and then wrap it in
a <a
href="javadoc/org/xml/sax/helpers/ParserAdapter.html">ParserAdapter</a>.</li>
<li><a
href="javadoc/org/xml/sax/helpers/DefaultHandler.html">DefaultHandler</a>
now throws a <a
href="javadoc/org/xml/sax/SAXException.html">SAXException</a> for its
<var>notationDecl</var> and <var>unparsedEntityDecl</var> methods, so
that they can be subclassed properly.</li>
<li>Bug fixed in <a
href="javadoc/org/xml/sax/helpers/AttributesImpl.html"
>AttributesImpl</a>; last attribute can now be removed.</li>
<li>Added <var>setAttributes</var> method <a
href="javadoc/org/xml/sax/helpers/AttributesImpl.html">AttributesImpl</a>
to simplify reusing an object.</li>
<li><a
href="javadoc/org/xml/sax/SAXParseException.html">SAXParseException</a>
now allows a null <var>locator</var> argument in its
constructors.</li>
<li>Specified that the <a
href="javadoc/org/xml/sax/ContentHandler.html">ContentHandler</a>
<var>skippedEntity</var> method will have an entity name of "[dtd]"
for the external DTD subset.</li>
<li>Specified that the <a
href="javadoc/org/xml/sax/ContentHandler.html">ContentHandler</a>
<var>processingInstruction</var> method will exclude whitespace
between the target and data.</li>
<li>In <a
href="javadoc/org/xml/sax/helpers/NamespaceSupport.html">NamespaceSupport</a>,
setting the "" prefix to "" removes any default mapping, and changed
<var>getPrefix</var>, <var>getPrefixes</var> so that they will not
return the default prefix.</li>
<li>In <a href="javadoc/org/xml/sax/Attributes.html">Attributes</a>,
renamed <var>getRawName</var> to <var>getQName</var>. Likewise, in <a
href="javadoc/org/xml/sax/helpers/AttributesImpl.html">AttributesImpl</a>,
renamed <var>setRawName</var> to <var>setQName</var>.</li>
<li>Removed the <code>org.xml.sax.ext</code> package into a separate
distribution, SAX2-ext. The <var>DeclHandler</var> and
<var>LexicalHandler</var> classes are no longer part of the core SAX2
distribution.</li>
<li>Added docs/quick-start.html</li>
<li>Modified <a
href="javadoc/org/xml/sax/helpers/XMLReaderAdapter.html">XMLReaderAdapter</a>,
<a
href="javadoc/org/xml/sax/helpers/ParserAdapter.html">ParserAdapter</a>,
and <a
href="javadoc/org/xml/sax/helpers/XMLFilterImpl.html">XMLFilterImpl</a>
so that <var>parse(String)</var> actually invokes
<var>parse(InputSource)</var>: this way, only
<var>parse(InputSource)</var> needs to be overridden in
subclasses.</li>
<li>Added <var>getPrefix(String)</var> and
<var>getPrefixes(String)</var> methods to <a
href="javadoc/org/xml/sax/helpers/NamespaceSupport.html">NamespaceSupport</a>
to look up currently-mapped prefixes.</li>
</ul>
<!-- end of "Changes from SAX2.0beta2 to SAX2.0prerelease" -->
</div>
<div>
<h2>Changes from SAX 2.0beta to SAX 2.0beta2</h2>
<ul>
<li>Corrected "raw-names" to "namespace-prefixes" throughout.</li>
<li>Removed a JDK 1.2 dependency in <a
href="javadoc/org/xml/sax/helpers/NamespaceSupport.html"
>org.xml.sax.helpers.NamespaceSupport</a>.</li>
<li>Fixed <a href="javadoc/org/xml/sax/helpers/ParserAdapter.html"
>org.xml.sax.helpers.ParserAdapter</a> so that the object can be
reused after a previous parse has thrown an exception.</li>
<li>Added <a href="javadoc/org/xml/sax/helpers/XMLReaderFactory.html"
>org.xml.sax.helpers.XMLReaderFactory</a>.</li>
<li>Documented limitations of start/endEntity in
<var>org.xml.sax.ext.LexicalHandler</var>, and added documentation
that LexicalHandler applies to the whole document and that all events
must appear between start/endDocument (including start/endDTD).</li>
<li><a href="javadoc/org/xml/sax/helpers/ParserAdapter.html"
>org.xml.sax.helpers.ParserAdapter</a> and
<a href="javadoc/org/xml/sax/helpers/XMLReaderAdapter.html"
>org.xml.sax.helpers.XMLReaderAdapter</a> now have a default
constructors that use the "org.xml.sax.parser" and
"org.xml.sax.driver" properties to locate the embedded SAX1 and
SAX2 drivers respectively.</li>
</ul>
</div>
<div>
<h2>Changes from SAX 1.0 to SAX 2.0beta</h2>
<p>The following interfaces and classes have been deprecated, and will
be removed from a future version of SAX; they should be used only for
interaction with SAX1 drivers or applications:</p>
<ul>
<li><a
href="javadoc/org/xml/sax/Parser.html">org.xml.sax.Parser</a></li>
<li><a href="javadoc/org/xml/sax/DocumentHandler.html"
>org.xml.sax.DocumentHandler</a></li>
<li><a href="javadoc/org/xml/sax/AttributeList.html"
>org.xml.sax.AttributeList</a></li>
<li><a href="javadoc/org/xml/sax/HandlerBase.html"
>org.xml.sax.HandlerBase</a></li>
<li><a href="javadoc/org/xml/sax/helpers/ParserFactory.html"
>org.xml.sax.helpers.ParserFactory</a></li>
<li><a href="javadoc/org/xml/sax/helpers/AttributeListImpl.html"
>org.xml.sax.helpers.AttributeListImpl</a></li>
</ul>
<p>The following interfaces and classes have been added to SAX2:</p>
<ul>
<li><a href="javadoc/org/xml/sax/XMLReader.html"
>org.xml.sax.XMLReader</a> (replaces <a
href="javadoc/org/xml/sax/Parser.html">Parser</a>)</li>
<li><a href="javadoc/org/xml/sax/XMLFilter.html"
>org.xml.sax.XMLFilter</a></li>
<li><a href="javadoc/org/xml/sax/ContentHandler.html">org.xml.sax.ContentHandler</a> (replaces <a
href="javadoc/org/xml/sax/DocumentHandler.html"
>DocumentHandler</a>)</li>
<li><a href="javadoc/org/xml/sax/Attributes.html"
>org.xml.sax.Attributes</a> (replaces <a
href="javadoc/org/xml/sax/AttributeList.html">AttributeList</a>)</li>
<li><a href="javadoc/org/xml/sax/SAXNotSupportedException.html"
>org.xml.sax.SAXNotSupportedException</a></li>
<li><a href="javadoc/org/xml/sax/SAXNotRecognizedException.html"
>org.xml.sax.SAXNotRecognizedException</a></li>
<li><a href="javadoc/org/xml/sax/helpers/AttributesImpl.html"
>org.xml.sax.helpers.AttributesImpl</a> (replaces
AttributeListImpl)</li>
<li><a href="javadoc/org/xml/sax/helpers/NamespaceSupport.html"
>org.xml.sax.helpers.NamespaceSupport</a></li>
<li><a href="javadoc/org/xml/sax/helpers/XMLFilterImpl.html"
>org.xml.sax.helpers.XMLFilterImpl</a></li>
<li><a href="javadoc/org/xml/sax/helpers/ParserAdapter.html"
>org.xml.sax.helpers.ParserAdapter</a></li>
<li><a href="javadoc/org/xml/sax/helpers/XMLReaderAdapter.html"
>org.xml.sax.helpers.XMLReaderAdapter</a></li>
<li><a href="javadoc/org/xml/sax/helpers/DefaultHandler.html"
>org.xml.sax.helpers.DefaultHandler</a> (replaces <a
href="javadoc/org/xml/sax/HandlerBase.html">HandlerBase</a>)</li>
<li><var>org.xml.sax.ext.LexicalHandler</var> (since removed)</li>
<li><var>org.xml.sax.ext.DeclHandler</var> (since removed)</li>
</ul>
<p>SAX2 contains complete Namespace support, which is available by
default from any <a
href="javadoc/org/xml/sax/XMLReader.html">XMLReader</a>. An XML
reader can also optionally supply raw XML 1.0 names. See <a
href="namespaces.html">SAX2: Namespaces</a> for more details.</p>
<p>An XML reader is fully configurable: it is possible to attempt to
query or change the current value of any feature or property.
Features and properties are identified by fully-qualified URIs, and
parties are free to invent their own names for new extensions. See <a
href="features.html">SAX2: Features and Properties</a> for more
details.</p>
<p>The <a href="javadoc/org/xml/sax/ContentHandler.html"
shape="rect">ContentHandler</a> and <a
href="javadoc/org/xml/sax/Attributes.html">Attributes</a> interfaces
are similar to the deprecated <a
href="javadoc/org/xml/sax/DocumentHandler.html">DocumentHandler</a>
and <a href="javadoc/org/xml/sax/AttributeList.html">AttributeList</a>
interfaces, but they add support for Namespace-related information.
ContentHandler also adds a callback for skipped entities, and
Attributes adds the ability to look up an attribute's index by
name.</p>
<p>The <a
href="javadoc/org/xml/sax/helpers/ParserAdapter.html">ParserAdapter</a>
class makes a SAX1 <a
href="javadoc/org/xml/sax/Parser.html">Parser</a> behave as a SAX2 <a
href="javadoc/org/xml/sax/XMLReader.html">XMLReader</a>. The <a
href="javadoc/org/xml/sax/helpers/XMLReaderAdapter.html">XMLReaderAdapter</a>
class makes a SAX2 XML reader behave as a SAX1 parser. These two
classes should ease the transition from SAX1 to SAX2 by allowing SAX1
drivers and clients to co-exist with SAX2 drivers and clients in the
same application.</p>
<div>
<h3>SAX1 Bugs Fixed</h3>
<dl>
<dt><a href="javadoc/org/xml/sax/SAXException.html">SAXException</a></dt>
<dd>Overrode java.lang.Object.toString so that an embedded exception
will give a proper String representation for debugging.</dd>
<dt><a href="javadoc/org/xml/sax/helpers/ParserFactory.html"
>ParserFactory</a></dt>
<dd>Added missing closing comment so that private constructor is not
commented out.</dd>
</dl>
</div>
</div>
<hr />
<address>$Id: changes.html,v 1.1 2001/05/20 03:12:59 curcuru Exp $</address>
</body>
</html>
1.1 xml-commons/java/external/xdocs/sax/features.html
Index: features.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX2: Features and Properties</title>
<link rel="stylesheet" type="text/css" href="sax-style.css" />
</head>
<body>
<h1>SAX2: Features and Properties</h1>
<blockquote>
<p class="copyright">This document is in the Public Domain.</p>
</blockquote>
<p>SAX2 adds standard methods to query and set features and properties
in an <a href="javadoc/org/xml/sax/XMLReader.html">XMLReader</a>. It
is now possible to request an XML reader to validate (or not to
validate) a document, or to internalize (or not to internalize) all
names, using the <var>getFeature</var>, <var>setFeature</var>,
<var>getProperty</var>, and <var>setProperty</var> methods:</p>
<blockquote><pre xml:space="preserve">
try {
if (xmlReader.getFeature("http://xml.org/sax/features/validation")) {
System.out.println("Parser is validating.");
} else {
System.out.println("Parser is not validating.");
}
} catch (SAXException e) {
System.out.println("Parser may or may not be validating.");
}
</pre></blockquote>
<p>There is no fixed set of features or properties available for SAX2:
implementors are free to define new features and properties as needed.
All feature and property names are fully-qualified URIs (often URLs),
such as "http://www.acme.com/features/foo"; as with Namespace URIs,
people should always define feature and property names based on URIs
that they control.</p>
<p>If an application attempts to query or set a feature that the XML
reader does not recognize, the XML reader throws a <a
href="javadoc/org/xml/sax/SAXNotRecognizedException.html"
>SAXNotRecognizedException</a>; if the application attempts to set a
feature state or property value that the XML reader cannot support at
that time, or attempts to modify a feature or property when it is
read-only, the XML reader throws a <a
href="javadoc/org/xml/sax/SAXNotSupportedException.html"
>SAXNotSupportedException</a>.</p>
<p>One important application for properties is getting and setting
extension event handlers, for event types not supported by the four
core SAX2 handlers, <a
href="javadoc/org/xml/sax/EntityResolver.html">EntityResolver</a>, <a
href="javadoc/org/xml/sax/DTDHandler.html">DTDHandler</a>, <a
href="javadoc/org/xml/sax/ContentHandler.html">ContentHandler</a>, and
<a href="javadoc/org/xml/sax/ErrorHandler.html">ErrorHandler</a>.
Outside parties are free to define handlers for any kinds of events,
and to create properties for setting and querying them.</p>
<p>All XML readers are required to recognize the
"http://xml.org/sax/features/namespaces" and the
"http://xml.org/sax/features/namespace-prefixes" features (see below),
and to support a <var>true</var> value for the namespaces property and
a false value for the <var>namespace-prefixes</var> property: these
requirements ensure that all SAX2 XML readers can provide the minimal
required Namespace support for higher-level specs such as RDF, XSL,
XML Schemas, and XLink. XML readers are not required to recognize or
support any other features or any properties, even the core ones
listed below.</p>
<div>
<h2>Core Features</h2>
<p>While anyone is free to define new SAX2 features, there is a core
reference set of features that are application to a wide range of
applications, and that many SAX2 XML readers may choose to support.
Note that features may be read-only or read/write, and that they may
be modifiable only when parsing, or only when not parsing.</p>
<dl>
<dt><code>http://xml.org/sax/features/namespaces</code></dt>
<dd><strong>true:</strong> Perform Namespace processing.</dd>
<dd><strong>false:</strong> Optionally do not perform Namespace processing (implies
<var>namespace-prefixes</var>). See <a href="namespaces.html">SAX2:
Namespaces</a> for further information.</dd>
<dd><strong>access:</strong> (parsing) read-only; (not parsing)
read/write</dd>
<dt><code>http://xml.org/sax/features/namespace-prefixes</code></dt>
<dd><strong>true:</strong> Report the original prefixed names and
attributes used for Namespace declarations.</dd>
<dd><strong>false:</strong> Do not report attributes used for
Namespace declarations, and optionally do not report original prefixed
names.</dd>
<dd><strong>access:</strong> (parsing) read-only; (not parsing)
read/write</dd>
<dt><code>http://xml.org/sax/features/string-interning</code></dt>
<dd><strong>true:</strong> All element names, prefixes, attribute
names, Namespace URIs, and local names are internalized using
java.lang.String.intern.</dd>
<dd><strong>false:</strong> Names are not necessarily
internalized.</dd>
<dd><strong>access:</strong> (parsing) read-only; (not parsing)
read/write</dd>
<dt><code>http://xml.org/sax/features/validation</code></dt>
<dd><strong>true:</strong> Report all validation errors (implies
<var>external-general-entities</var> and
<var>external-parameter-entities</var>).</dd>
<dd><strong>false:</strong> Do not report validation errors.</dd>
<dd><strong>access:</strong> (parsing) read-only; (not parsing)
read/write</dd>
<dt><code>http://xml.org/sax/features/external-general-entities</code></dt>
<dd><strong>true:</strong> Include all external general (text)
entities.</dd>
<dd><strong>false:</strong> Do not include external general
entities.</dd>
<dd><strong>access:</strong> (parsing) read-only; (not parsing)
read/write</dd>
<dt><code>http://xml.org/sax/features/external-parameter-entities</code></dt>
<dd><strong>true:</strong> Include all external parameter entities,
including the external DTD subset.</dd>
<dd><strong>false:</strong> Do not include any external parameter
entities, even the external DTD subset.</dd>
<dd><strong>access:</strong> (parsing) read-only; (not parsing)
read/write</dd>
</dl>
<!-- end of "Core Features" -->
</div>
<div>
<h2>Core Properties</h2>
<p>While anyone is free to define new SAX2 properties, there is a core
reference set of properties that are application to a wide range of
applications, and that many SAX2 XML readers may choose to support.
Note that properties may be read-only or read/write, and that they may
be modifiable only when parsing, or only when not parsing.</p>
<dl>
<dt><code>http://xml.org/sax/properties/dom-node</code></dt>
<dd><strong>data type:</strong> <code>org.w3c.dom.Node</code></dd>
<dd><strong>description:</strong> When parsing, the current DOM node
being visited if this is a DOM iterator; when not parsing, the root
DOM node for iteration.</dd>
<dd><strong>access:</strong> (parsing) read-only; (not parsing)
read/write</dd>
<dt><code>http://xml.org/sax/properties/xml-string</code></dt>
<dd><strong>data type:</strong> <code>java.lang.String</code></dd>
<dd><strong>description:</strong> The literal string of characters
that was the source for the current event.</dd>
<dd><strong>access:</strong> read-only</dd>
</dl>
<!-- end of "Core Properties" -->
</div>
<hr />
<address>$Id: features.html,v 1.1 2001/05/20 03:12:59 curcuru Exp $</address>
</body>
</html>
1.1 xml-commons/java/external/xdocs/sax/filters.html
Index: filters.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX2: Filters</title>
<link rel="stylesheet" type="text/css" href="sax-style.css" />
</head>
<body>
<h1>SAX2: Filters</h1>
<blockquote>
<p class="copyright">This document is in the Public Domain.</p>
</blockquote>
<p>The SAX interface assumes two basic streams:</p>
<ol>
<li>a stream of requests flowing from the application to the SAX
driver; and</li>
<li>a stream of events (and other information) flowing from the SAX
driver to the application.</li>
</ol>
<p>With SAX1, programmers quickly realized that it was possible to
extend this model to support a processing chain, where requests could
flow through several different components, or filters, before arriving
at the original SAX driver, and events could flow through the same
filters before arriving at the application. Each filter can make
changes to the stream of events as it passes through, but the whole
chain of filters still appears to be a single SAX driver to the
application.</p>
<p>SAX2 formalizes this design technique by adding a new interface, <a
href="javadoc/org/xml/sax/XMLFilter.html">org.xml.sax.XMLFilter</a>,
and a new helper class, <a
href="javadoc/org/xml/sax/helpers/XMLFilterImpl.html"
>org.xml.sax.XMLFilterImpl</a>.</p>
<p>The <var>XMLFilter</var> interface itself is very simple, extending
the basic <var>XMLReader</var> interface with two additional
methods:</p>
<blockquote><pre xml:space="preserve">
public interface XMLFilter extends XMLReader
{
public abstract void setParent (XMLReader parent);
public abstract XMLReader getParent ();
}
</pre></blockquote>
<p>In other words, a SAX2 filter is simply an XMLReader that has
another XMLReader as its parent.</p>
<p>In normal use, a filter will implement not only the
<var>XMLFilter</var> interface but also one or all of the various
resolver and handler interfaces (<var>EntityResolver</var>,
<var>DTDHandler</var>, <var>ContentHandler</var>, and
<var>ErrorHandler</var>). To the parent XML reader, the filter is the
client application receiving the events; to the client application,
the filter is the SAX driver producing the events.</p>
<p>The <var>XMLFilterImpl</var> helper class provides a convenient
base for deriving SAX2 filters. This class implements the
<var>XMLFilter</var>, <var>EntityResolver</var>,
<var>DTDHandler</var>, <var>ContentHandler</var>, and
<var>ErrorHandler</var> interfaces. By default, it passes all events
on unmodified, but the derived filter can override specific
methods.</p>
<p>Here's an example of a very simple filter that changes the
Namespace URI <code>http://www.foo.com/ns/</code> to
<code>http://www.bar.com/</code> wherever it appears in an element
name (but not an attribute name):</p>
<blockquote><pre xml:space="preserve">
public class FooFilter extends XMLFilterImpl
{
public FooFilter ()
{
}
public FooFilter (XMLReader parent)
{
super(parent);
}
/**
* Filter the Namespace URI for start-element events.
*/
public void startElement (String uri, String localName,
String qName, Attributes atts)
throws SAXException
{
if (uri.equals("http://www.foo.com/ns/")) {
uri = "http://www.bar.com/ns/";
}
super.startElement(uri, localName, qName, atts);
}
/**
* Filter the Namespace URI for end-element events.
*/
public void endElement (String uri, String localName, String qName)
throws SAXException
{
if (uri.equals("http://www.foo.com/ns/")) {
uri = "http://www.bar.com/ns/";
}
super.endElement(uri, localName, qName);
}
}
</pre></blockquote>
<p>Note the use of <var>super.startElement</var> and
<var>super.endElement</var> to send the event on to the client. In a
real filter, it would be good to override the
<var>ContentHandler.startPrefixMapping</var> and
<var>ContentHandler.endPrefixMapping</var> methods as well.</p>
<p>Long filter chains are not always the best approach, but you will
find that it is sometimes easier to build complex XML applications if
you can break them down into a collection of simple SAX filters, each
one reading the events from its parent.</p>
<hr />
<address>$Id: filters.html,v 1.1 2001/05/20 03:12:59 curcuru Exp $</address>
</body>
</html>
1.1 xml-commons/java/external/xdocs/sax/namespaces.html
Index: namespaces.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX2 Namespace Support</title>
<link rel="stylesheet" type="text/css" href="sax-style.css" />
</head>
<body>
<h1>SAX2 Namespace Support</h1>
<blockquote>
<p class="copyright">This document is in the Public Domain.</p>
</blockquote>
<p>SAX2 adds <a href="[FIXME]">XML Namespace</a> support, which is
required for higher-level standards like <a href="[FIXME]">XSL</a>, <a
href="[FIXME]">XML Schemas</a>, <a
href="http://www.w3.org/TR/REC-rdf-syntax">RDF</a>, and <a
href="[FIXME]">XLink</a>. Every implementation of the SAX2 <a
href="javadoc/org/xml/sax/XMLReader.html" >XMLReader</a> interface is
required to support Namespace processing as its default state; some
XML readers may also allow Namespace processing to be disabled or
modified (note to SAX driver writers: there is a helper class, <a
href="javadoc/org/xml/sax/helpers/NamespaceSupport.html">NamespaceSupport</a>,
that can do most of the work of Namespace processing for you).</p>
<p>Namespace processing affects only element and attribute names.
Without Namespace processing, each XML element and attribute has a
single, local name (called the <em>qName</em>), which may contain a
colon; with Namespace processing, each element and attribute has a
two-part name, consisting of an optional URI (equivalent to a Java or
Perl package name) followed by a local name which may not contain a
colon.</p>
<p>SAX is capable of supporting either of these views or both
simultaneously, though XML readers are required to support only the
Namespaces view, and most applications will not need anything
further.</p>
<div>
<h2>1. Namespaces in SAX Events</h2>
<p>Namespace support affects the <a
href="javadoc/org/xml/sax/ContentHandler.html" >ContentHandler</a> and
<a href="javadoc/org/xml/sax/Attributes.html" >Attributes</a>
interfaces.</p>
<div>
<h3>1.1. Element names</h3>
<p>In SAX2, the <a
href="javadoc/org/xml/sax/ContentHandler.html#startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)"
>startElement</a> and <a
href="javadoc/org/xml/sax/ContentHandler.html#endElement(java.lang.String, java.lang.String, java.lang.String)"
>endElement</a> callbacks in a content handler look like this:</p>
<blockquote><pre xml:space="preserve">
public void startElement (String uri, String localName,
String qName, Attributes atts)
throws SAXException;
public void endElement (String uri, String localName, String qName)
throws SAXException;
</pre></blockquote>
<p>By default, an XML reader will report a Namespace URI and a local
name for every element, in both the start and end handler. Consider
the following example:</p>
<blockquote><pre xml:space="preserve">
<html:hr xmlns:html="http://www.w3.org/1999/xhtml"/>
</pre></blockquote>
<p>With the default SAX2 Namespace processing, the XML reader would
report a start and end element event with the Namespace URI
"http://www.w3.org/1999/xhtml" and the local name "hr". The XML
reader might also report the original qName "html:hr", but that
parameter might simply be an empty string.</p>
<!-- end of "Element Names" -->
</div>
<div>
<h3>1.2. Attribute Names</h3>
<p>For attributes, you can look up the value of a named attribute
using the <a
href="javadoc/org/xml/sax/Attributes.html#getValue(java.lang.String, java.lang.String"
>getValue</a> method, and you can look up the Namespace URI or local
name of an attribute by its index using the <a href="javadoc/org/xml/sax/Attributes.html#getURI(int)">getURI</a> and
<a href="javadoc/org/xml/sax/Attributes.html#getLocalName(int)"
>getLocalName</a> methods (usually when you're iterating
through the entire attribute list):</p>
<blockquote><pre xml:space="preserve">
String rdfns = "http://www.w3.org/1999/02/22-rdf-syntax-ns#";
String resource = atts.getValue(rdfns, "resource");
for (int i = 0; i < atts.getLength(); i++) {
String uri = atts.getURI(i);
String localName = atts.getLocalName(i);
String value = atts.getValue(i);
/* ... */
}
</pre></blockquote>
<!-- end of "Attribute Names" -->
</div>
<div>
<h3>1.3. Prefix Mappings</h3>
<p>In addition to those events, SAX2 reports the scope of Namespace
declarations using the <a
href="javadoc/org/xml/sax/ContentHandler.html#startPrefixMapping(java.lang.String, java.lang.String)"
>startPrefixMapping</a> and <a
href="javadoc/org/xml/sax/ContentHandler.html#endPrefixMapping(java.lang.String)"
>endPrefixMapping</a> methods, so that applications can resolve
prefixes in attribute values or character data if necessary. The
callbacks look like this:</p>
<blockquote><pre xml:space="preserve">
public void startPrefixMapping (String prefix, String uri)
throws SAXException;
public void endPrefixMapping (String prefix)
throws SAXException;
</pre></blockquote>
<p>For the above example, the XML reader would make the following
callback <em>before</em> the start-element event:</p>
<blockquote><pre xml:space="preserve">
startPrefixMapping("html", "http://www.w3.org/1999/xhtml")
</pre></blockquote>
<p>The XML reader would make the following callback <em>after</em> the
end-element event:</p>
<blockquote><pre xml:space="preserve">
endPrefixMapping("html")
</pre></blockquote>
<p>The rest of this document applies only to SAX2 applications with
special requirements, such as text editors.</p>
</div>
</div>
<div>
<h2>2. Configuration</h3>
<div>
<h3>2.1. Configuring Namespace Support</h3>
<p>The "http://xml.org/features/namespaces" feature controls general
Namespace processing: when this feature is true (the default),
Namespace URIs and local names must be available through the
<var>startElement</var> and <var>endElement</var> callbacks in the <a
href="javadoc/org/xml/sax/ContentHandler.html">ContentHandler</a>
interface, and through the various methods in the <a
href="javadoc/org/xml/sax/Attributes.html">Attributes</a> interface,
and start/endPrefixMapping events must be reported.</p>
<p>The "http://xml.org/features/namespace-prefixes" feature controls
the reporting of qNames and Namespace declarations (xmlns*
attributes): when this feature is false (the default), qNames may
optionally be reported, and xmlns* attributes must not be
reported.</p>
<p>The following table summarizes the interaction of these two
features (for general information on using features, see <a
href="features.html">SAX2: Features and Properties</a>):</p>
<table border="3">
<thead>
<tr>
<th>namespaces</th>
<th>namespace-prefixes</th>
<th>Namespace names</th>
<th>start/endPrefixMapping</th>
<th>qNames</th>
<th>xmlns* attributes</th>
</tr>
</thead>
<tbody>
<tr>
<td>true</td>
<td>false</td>
<td>YES</td>
<td>YES</td>
<td>unknown</td>
<td>NO</td>
</tr>
<tr>
<td>true</td>
<td>true</td>
<td>YES</td>
<td>YES</td>
<td>YES</td>
<td>YES</td>
</tr>
<tr>
<td>false</td>
<td>false</td>
<td colspan="4" align="center">(ILLEGAL COMBINATION)</td>
</tr>
<tr>
<td>false</td>
<td>true</td>
<td>unknown</td>
<td>unknown</td>
<td>YES</td>
<td>YES</td>
</tr>
</table>
<p>Note <var>xmlns*</var> attributes will <strong>not</strong> be
reported unless the <var>namespace-prefixes</var> feature is true (it
is false by default).</p>
<!-- end of "Configuring Namespace Support" -->
</div>
<div>
<h3>2.2. Configuration Example</h3>
<p>Consider the following simple sample document:</p>
<blockquote><pre xml:space="preserve">
<?xml version="1.0"?>
<h:hello xmlns:h="http://www.greeting.com/ns/" id="a1" h:person="David"/>
</pre></blockquote>
<p>If <var>namespaces</var> is true and <var>namespace-prefixes</var>
is false (the default), then a SAX2 XML reader will report the
following:</p>
<ul>
<li>an element with the Namespace URI "http://www.greeting.com/ns/" and
the local name "hello";</li>
<li>an attribute with no Namespace URI (empty string) and the local
name "id"; and</li>
<li>an attribute with the Namespace URI "http://www.greeting.com/ns/"
and the local name "person".</li>
</ul>
<p>If <var>namespaces</var> is true and <var>namespace-prefixes</var>
is true, then a SAX2 XML reader will report the following:</p>
<ul>
<li>an element with the Namespace URI "http://www.greeting.com/ns/",
the local name "hello", and the qName "h:hello";</li>
<li>an attribute with no Namespace URI (empty string), no local name
(empty string), and the qName "xmlns:h";</li>
<li>an attribute with no Namespace URI (empty string), the local
name "id", and the qName "id"; and</li>
<li>an attribute with the Namespace URI "http://www.greeting.com/ns/",
the local name "person", and the qName "h:person".</li>
</ul>
<p>If <var>namespaces</var> is false and <var>namespace-prefixes</var>
is true, then a SAX2 XML reader will report the following:</p>
<ul>
<li>an element with the qName "h:hello";</li>
<li>an attribute with the qName "xmlns:h";</li>
<li>an attribute with the qName "id"; and</li>
<li>an attribute with the qName "h:person".</li>
</ul>
<!-- end of "Configuration Example" -->
</div>
<!-- end of "Configuration" -->
</div>
<hr />
<address>$Id: namespaces.html,v 1.1 2001/05/20 03:12:59 curcuru Exp $</address>
</body>
</html>
1.1 xml-commons/java/external/xdocs/sax/quick-start.html
Index: quick-start.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX2: Quick Start</title>
<link rel="stylesheet" type="text/css" href="sax-style.css" />
</head>
<body>
<h1>SAX2: Quick Start</h1>
<blockquote>
<p class="copyright">This document is in the Public Domain.</p>
</blockquote>
<p>This document provides a quick-start tutorial for Java programmers
who wish to use SAX2 in their programs.</p>
<div>
<h2>Requirements</h2>
<p>SAX is not an XML parser.</p>
<p>SAX is a common interface implemented for many different XML
parsers (and things that pose as XML parsers), just as the JDBC is a
common interface implemented for many different relational databases
(and things that pose as relational databases). If you want to use
SAX, you'll need all of the following:</p>
<ul>
<li><p>Java 1.1 or higher.</p></li>
<li><p>The SAX2 distribution installed on your Java
classpath.</p></li>
<li><p>A SAX2-compatible XML parser installed on your Java
classpath.</p></li>
<li><p>The name of the SAX2 driver class in your XML parser (read the
documentation that came with the parser, and <em>write down the class
name</em>).</p></li>
</ul>
<!-- end of "Requirements" -->
</div>
<div>
<h2>Parsing a document</h2>
<p>Start by creating a class that extends <a
href="javadoc/org/xml/sax/helpers/DefaultHandler.html"
>DefaultHandler</a>:</p>
<blockquote><pre xml:space="preserve">
import org.xml.sax.helpers.DefaultHandler;
public class MySAXApp extends DefaultHandler
{
public MySAXApp ()
{
super();
}
}
</pre></blockquote>
<p>Now, let's assume that the SAX driver for your XML parser is named
"com.acme.xml.SAXDriver" (this does not really exist: you
<em>must</em> find out the name of the real driver for your parser).
Since this is a Java application, we'll create a static
<var>main</var> method that creates a new instance of this driver
(note the "throws Exception" wimp-out):</p>
<blockquote><pre xml:space="preserve">
public static void main (String args[])
throws Exception
{
XMLReader xr = new com.acme.xml.SAXDriver();
}
</pre></blockquote>
<p>Alternatively, if you don't want to tie your application to a
specific SAX driver, you can use the <a
href="javadoc/org/xml/sax/helpers/XMLReaderFactory.html#createXMLReader()">createXMLReader</a>
method from the <a
href="javadoc/org/xml/sax/helpers/XMLReaderFactory.html"
>XMLReaderFactory</a> class to choose a SAX driver dynamically:</p>
<blockquote><pre>
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
}
</pre></blockquote>
<p>In this case, it will be necessary at runtime to set the
org.xml.sax.driver Java system property to the full classname of the
SAX driver, as in</p>
<blockquote><pre xml:space="preserve">
java -Dorg.xml.sax.driver=com.acme.xml.SAXDriver MySAXApp sample.xml
</pre></blockquote>
<p>We can use this object to parse XML documents, but first, we have
to register event handlers that the parser can use for reporting
information, using the <a
href="javadoc/org/xml/sax/XMLReader.html#setContentHandler(org.xml.sax.ContentHandler)"
>setContentHandler</a> and <a
href="javadoc/org/xml/sax/XMLReader.html#setErrorHandler(org.xml.sax.ErrorHandler)"
>setErrorHandler</a> methods from the <a
href="javadoc/org/xml/sax/XMLReader.html">XMLReader</a> interface. In
a real-world application, the handlers will usually be separate
objects, but for this simple demo, we've bundled the handlers into the
top-level class, so we just have to instantiate the class and register
it with the XML reader:</p>
<blockquote><pre xml:space="preserve">
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
MySAXApp handler = new MySAXApp();
xr.setContentHandler(handler);
xr.setErrorHandler(handler);
}
</pre></blockquote>
<p>This code creates an instance of MySAXApp to receive XML parsing
events, and registers it with the XML reader for regular content
events and error events (there are other kinds, but they're rarely
used). Now, let's assume that all of the command-line args are file
names, and we'll try to parse them one-by-one using the <a
href="javadoc/org/xml/sax/XMLReader.html#parse(org.xml.sax.InputSource)"
>parse</a> method from the <a
href="javadoc/org/xml/sax/XMLReader.html"
>XMLReader</a> interface:</p>
<blockquote><pre xml:space="preserve">
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
MySAXApp handler = new MySAXApp();
xr.setContentHandler(handler);
xr.setErrorHandler(handler);
// Parse each file provided on the
// command line.
for (int i = 0; i < args.length; i++) {
FileReader r = new FileReader(args[i]);
xr.parse(new InputSource(r));
}
}
</pre></blockquote>
<p>Note that each reader must be wrapped in an <a
href="javadoc/org/xml/sax/InputSource.html"
>InputSource</a> object to be parsed. Here's the whole demo class
together (so far):</p>
<blockquote><pre xml:space="preserve">
import java.io.FileReader;
import org.xml.sax.XMLReader;
import org.xml.sax.InputSource;
import org.xml.sax.helpers.XMLReaderFactory;
import org.xml.sax.helpers.DefaultHandler;
public class MySAXApp extends DefaultHandler
{
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
MySAXApp handler = new MySAXApp();
xr.setContentHandler(handler);
xr.setErrorHandler(handler);
// Parse each file provided on the
// command line.
for (int i = 0; i < args.length; i++) {
FileReader r = new FileReader(args[i]);
xr.parse(new InputSource(r));
}
}
public MySAXApp ()
{
super();
}
}
</pre></blockquote>
<p>You can compile this code and run it (make sure you specify the SAX
driver class in the org.xml.sax.driver property), but nothing much
will happen unless the document contains malformed XML, because you
have not yet set up your application to handle SAX events.</p>
<!-- end of "Parsing a document" -->
</div>
<div>
<h2>Handling events</h2>
<p>Things get interesting when you start implementing methods to
respond to XML parsing events (remember that we registered our class
to receive XML parsing events in the previous section). The most
important events are the start and end of the document, the start and
end of elements, and character data.</p>
<p>To find out about the start and end of the document, the client
application implements the <a
href="javadoc/org/xml/sax/ContentHandler.html#startDocument()"
>startDocument</a> and <a
href="javadoc/org/xml/sax/ContentHandler.html#endDocument()"
>endDocument</a> methods:</p>
<blockquote><pre xml:space="preserve">
public void startDocument ()
{
System.out.println("Start document");
}
public void endDocument ()
{
System.out.println("End document");
}
</pre></blockquote>
<p>The start/endDocument event handlers take no arguments. When the
SAX driver finds the beginning of the document, it will invoke the
<var>startDocument</var> method once; when it finds the end, it will
invoke the <var>endDocument</var> method once (if there have been
errors, endDocument may not be invoked).</p>
<p>These examples simply print a message to standard output, but your
application can contain any arbitrary code in these handlers: most
commonly, the code will build some kind of an in-memory tree, produce
output, populate a database, or extract information from the XML
stream.</p>
<p>The SAX driver will signal the start and end of elements in much
the same way, except that it will also pass some parameters to the <a
href="javadoc/org/xml/sax/ContentHandler.html#startElement(java.lang.String, java.lang.String, java.lang.String, org.xml.sax.Attributes)">startElement</a> and <a
href="javadoc/org/xml/sax/ContentHandler.html#endElement(java.lang.String, java.lang.String, java.lang.String)">endElement</a> methods:</p>
<blockquote><pre xml:space="preserve">
public void startElement (String uri, String name,
String qName, Attributes atts)
{
System.out.println("Start element: {" + uri + "}" + name);
}
public void endElement (String uri, String name, String qName)
{
System.out.println("End element: {" + uri + "}" + name);
}
</pre></blockquote>
<p>These methods print a message every time an element starts or ends,
with the Namespace URI in braces before the element's local name. The
<var>qName</var> contains the raw XML 1.0 name, and since not all
SAX drivers will report it, it is best to ignore that parameter for
now.</p>
<p>Finally, SAX2 reports regular character data through the <a
href="javadoc/org/xml/sax/ContentHandler.html#characters(char[], int, int)"
>characters</a> method; the following implementation will print all
character data to the screen; it is a little longer because it
pretty-prints the output by escaping special characters:</p>
<blockquote><pre xml:space="preserve">
public void characters (char ch[], int start, int length)
{
System.out.print("Characters: \"");
for (int i = start; i < start + length; i++) {
switch (ch[i]) {
case '\\':
System.out.print("\\\\");
break;
case '"':
System.out.print("\\\"");
break;
case '\n':
System.out.print("\\n");
break;
case '\r':
System.out.print("\\r");
break;
case '\t':
System.out.print("\\t");
break;
default:
System.out.print(ch[i]);
break;
}
}
System.out.print("\"\n");
}
</pre></blockquote>
<p>Note that a SAX driver is free to chunk the character data any way
it wants, so you cannot count on all of the character data content of
an element arriving in a single <var>characters</var> event.</p>
<!-- end of "Handling events" -->
</div>
<div>
<h2>Sample SAX2 application</h2>
<p>Here is the complete sample application (again, in a serious app
the event handlers would probably be implemented in a separate
class):</p>
<blockquote><pre>
import java.io.FileReader;
import org.xml.sax.XMLReader;
import org.xml.sax.Attributes;
import org.xml.sax.InputSource;
import org.xml.sax.helpers.XMLReaderFactory;
import org.xml.sax.helpers.DefaultHandler;
public class MySAXApp extends DefaultHandler
{
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
MySAXApp handler = new MySAXApp();
xr.setContentHandler(handler);
xr.setErrorHandler(handler);
// Parse each file provided on the
// command line.
for (int i = 0; i < args.length; i++) {
FileReader r = new FileReader(args[i]);
xr.parse(new InputSource(r));
}
}
public MySAXApp ()
{
super();
}
////////////////////////////////////////////////////////////////////
// Event handlers.
////////////////////////////////////////////////////////////////////
public void startDocument ()
{
System.out.println("Start document");
}
public void endDocument ()
{
System.out.println("End document");
}
public void startElement (String uri, String name,
String qName, Attributes atts)
{
System.out.println("Start element: {" + uri + "}" + name);
}
public void endElement (String uri, String name, String qName)
{
System.out.println("End element: {" + uri + "}" + name);
}
public void characters (char ch[], int start, int length)
{
System.out.print("Characters: \"");
for (int i = start; i < start + length; i++) {
switch (ch[i]) {
case '\\':
System.out.print("\\\\");
break;
case '"':
System.out.print("\\\"");
break;
case '\n':
System.out.print("\\n");
break;
case '\r':
System.out.print("\\r");
break;
case '\t':
System.out.print("\\t");
break;
default:
System.out.print(ch[i]);
break;
}
}
System.out.print("\"\n");
}
}
</pre></blockquote>
<!-- end of "Sample SAX2 application" -->
</div>
<div>
<h2>Sample Output</h2>
<p>Consider the following XML document:</p>
<blockquote><pre xml:space="preserve">
<?xml version="1.0"?>
<poem xmlns="http://www.megginson.com/ns/exp/poetry">
<title>Roses are Red</title>
<l>Roses are red,</l>
<l>Violets are blue;</l>
<l>Sugar is sweet,</l>
<l>And I love you.</l>
</poem>
</pre></blockquote>
<p>If this document is named <code>roses.xml</code> and there is a
SAX2 driver on your classpath named
<code>com.acme.xml.SAXDriver</code> (this driver does not actually
exist), you can invoke the sample application like this:</p>
<blockquote><pre xml:space="preserve">
java -Dcom.acme.xml.SAXDriver MySAXApp roses.xml
</pre></blockquote>
<p>When you run this, you'll get output something like this:</p>
<blockquote><pre xml:space="preserve">
Start document
Start element: {http://www.megginson.com/ns/exp/poetry}poem
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}title
Characters: "Roses are Red"
End element: {http://www.megginson.com/ns/exp/poetry}title
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "Roses are red,"
End element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "Violets are blue;"
End element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "Sugar is sweet,"
End element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "And I love you."
End element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "\n"
End element: {http://www.megginson.com/ns/exp/poetry}poem
End document
</pre></blockquote>
<p>Note that even a short document generates (at least) 25 events: one
for the start and end of each of the six elements used (or, if you
prefer, one for each start tag and one for each end tag), one of each
of the eleven chunks of character data (including whitespace between
elements), one for the start of the document, and one for the end.</p>
<!-- end of "Sample Output" -->
</div>
<hr />
<address>$Id: quick-start.html,v 1.1 2001/05/20 03:12:59 curcuru Exp $</address>
</body>
</html>
1.1 xml-commons/java/external/xdocs/sax/sax-style.css
Index: sax-style.css
===================================================================
body {
background: white;
}
h1, h2, h3 {
font-family: arial, sans-serif;
font-weight: bold;
}
h1 {
font-size: 207%;
}
h2 {
font-size: 173%;
}
h3 {
font-size: 144%;
}
p.copyright {
color: green;
font-style: italic;
}
1.1 xml-commons/java/external/xdocs/sax/sax.html
Index: sax.html
===================================================================
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>SAX 2.0/Java</title>
<link rel="stylesheet" type="text/css" href="sax-style.css" />
</head>
<body>
<h1>SAX 2.0/Java</h1>
<blockquote>
<p class="copyright">This document is in the Public Domain.</p>
</blockquote>
<p>SAX2 is a new Java-based release of SAX, the <cite>Simple API for
XML</cite>. A C++ version (at least) is planned as well. SAX2
introduces configurable features and properties and adds support for
XML Namespaces; it includes adapters so that SAX1 parsers and
applications can interoperate with SAX2.</p>
<ul>
<li><a href="quick-start.html">Quick start</a></li>
<li><a href="changes.html">Changes from SAX 1.0</a></li>
<li><a href="features.html">Features and Properties</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="filters.html">Filters</a></li>
<li><a href="javadoc/index.html">API Documentation</a></li>
<li><a href="http://www.megginson.com/SAX/Java/sax2.zip"
>Download SAX 2.0 final release for Java</a></li>
</ul>
<hr />
<address>$Id: sax.html,v 1.1 2001/05/20 03:12:59 curcuru Exp $</address>
</body>
</html>