gnu.xml.aelfred2
Class SAXDriver

java.lang.Object
  extended bygnu.xml.aelfred2.SAXDriver
All Implemented Interfaces:
AttributeList, Attributes, Attributes2, Locator, Parser, XMLReader

public final class SAXDriver
extends Object
implements Locator, Attributes2, XMLReader, Parser, AttributeList

An enhanced SAX2 version of Microstar's Ælfred XML parser. The enhancements primarily relate to significant improvements in conformance to the XML specification, and SAX2 support. Performance has been improved. See the package level documentation for more information.

Name Notes
Features ... URL prefix is http://xml.org/sax/features/
(URL)/external-general-entities Value defaults to true
(URL)/external-parameter-entities Value defaults to true
(URL)/is-standalone (PRELIMINARY) Returns true iff the document's parsing has started (some non-error event after startDocument() was reported) and the document's standalone flag is set.
(URL)/namespace-prefixes Value defaults to false (but XML 1.0 names are always reported)
(URL)/lexical-handler/parameter-entities Value is fixed at true
(URL)/namespaces Value defaults to true
(URL)/resolve-dtd-uris (PRELIMINARY) Value defaults to true
(URL)/string-interning Value is fixed at true
(URL)/use-attributes2 (PRELIMINARY) Value is fixed at true
(URL)/use-entity-resolver2 (PRELIMINARY) Value defaults to true
(URL)/validation Value is fixed at false
Handler Properties ... URL prefix is http://xml.org/sax/properties/
(URL)/declaration-handler A declaration handler may be provided.
(URL)/lexical-handler A lexical handler may be provided.

This parser currently implements the SAX1 Parser API, but it may not continue to do so in the future.

Version:
$Date: 2001/11/19 18:27:20 $
Author:
Written by David Megginson (version 1.2a from Microstar), Updated by David Brownell <dbrownell@users.sourceforge.net>
See Also:
Parser

Constructor Summary
SAXDriver()
          Constructs a SAX Parser.
 
Method Summary
 int getColumnNumber()
          SAX Locator method (don't invoke on parser);
 ContentHandler getContentHandler()
          SAX2: Returns the object used to report the logical content of an XML document.
 DTDHandler getDTDHandler()
          SAX2: Returns the object used to process declarations related to notations and unparsed entities.
 EntityResolver getEntityResolver()
          SAX2: Returns the object used when resolving external entities during parsing (both general and parameter entities).
 ErrorHandler getErrorHandler()
          SAX2: Returns the object used to receive callbacks for XML errors of all levels (fatal, nonfatal, warning); this is never null;
 boolean getFeature(String featureId)
          SAX2: Tells the value of the specified feature flag.
 int getIndex(String xmlName)
          SAX2 Attributes method (don't invoke on parser);
 int getIndex(String uri, String local)
          SAX2 Attributes method (don't invoke on parser);
 int getLength()
          SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);
 int getLineNumber()
          SAX Locator method (don't invoke on parser);
 String getLocalName(int index)
          SAX2 Attributes method (don't invoke on parser);
 String getName(int i)
          SAX1 AttributeList method (don't invoke on parser);
 Object getProperty(String propertyId)
          SAX2: Returns the specified property.
 String getPublicId()
          SAX Locator method (don't invoke on parser);
 String getQName(int i)
          SAX2 Attributes method (don't invoke on parser);
 String getSystemId()
          SAX Locator method (don't invoke on parser);
 String getType(int i)
          SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);
 String getType(String xmlName)
          SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);
 String getType(String uri, String local)
          SAX2 Attributes method (don't invoke on parser);
 String getURI(int index)
          SAX2 Attributes method (don't invoke on parser);
 String getValue(int i)
          SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);
 String getValue(String xmlName)
          SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);
 String getValue(String uri, String local)
          SAX Attributes method (don't invoke on parser);
 boolean isSpecified(int index)
          SAX-ext Attributes2 method (don't invoke on parser);
 boolean isSpecified(String xmlName)
          SAX-ext Attributes2 method (don't invoke on parser);
 boolean isSpecified(String uri, String local)
          SAX-ext Attributes2 method (don't invoke on parser);
 void parse(InputSource source)
          SAX1, SAX2: Auxiliary API to parse an XML document, used mostly when no URI is available.
 void parse(String systemId)
          SAX1, SAX2: Preferred API to parse an XML document, using a system identifier (URI).
 void setContentHandler(ContentHandler handler)
          SAX2: Assigns the object used to report the logical content of an XML document.
 void setDocumentHandler(DocumentHandler handler)
          Deprecated. SAX2 programs should use the XMLReader interface and a ContentHandler.
 void setDTDHandler(DTDHandler handler)
          SAX1, SAX2: Set the DTD handler for this parser.
 void setEntityResolver(EntityResolver resolver)
          SAX1, SAX2: Set the entity resolver for this parser.
 void setErrorHandler(ErrorHandler handler)
          SAX1, SAX2: Set the error handler for this parser.
 void setFeature(String featureId, boolean value)
          SAX2: Sets the state of feature flags in this parser.
 void setLocale(Locale locale)
          SAX1: Sets the locale used for diagnostics; currently, only locales using the English language are supported.
 void setProperty(String propertyId, Object value)
          SAX2: Assigns the specified property.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SAXDriver

public SAXDriver()
Constructs a SAX Parser.

Method Detail

setLocale

public void setLocale(Locale locale)
               throws SAXException
SAX1: Sets the locale used for diagnostics; currently, only locales using the English language are supported.

Specified by:
setLocale in interface Parser
Parameters:
locale - The locale for which diagnostics will be generated
Throws:
SAXException - Throws an exception (using the previous or default locale) if the requested locale is not supported.
See Also:
SAXException, SAXParseException

getEntityResolver

public EntityResolver getEntityResolver()
SAX2: Returns the object used when resolving external entities during parsing (both general and parameter entities).

Specified by:
getEntityResolver in interface XMLReader
Returns:
The current entity resolver, or null if none has been registered.
See Also:
XMLReader.setEntityResolver(org.xml.sax.EntityResolver)

setEntityResolver

public void setEntityResolver(EntityResolver resolver)
SAX1, SAX2: Set the entity resolver for this parser.

Specified by:
setEntityResolver in interface XMLReader
Parameters:
resolver - The entity resolver.
See Also:
XMLReader.getEntityResolver()

getDTDHandler

public DTDHandler getDTDHandler()
SAX2: Returns the object used to process declarations related to notations and unparsed entities.

Specified by:
getDTDHandler in interface XMLReader
Returns:
The current DTD handler, or null if none has been registered.
See Also:
XMLReader.setDTDHandler(org.xml.sax.DTDHandler)

setDTDHandler

public void setDTDHandler(DTDHandler handler)
SAX1, SAX2: Set the DTD handler for this parser.

Specified by:
setDTDHandler in interface XMLReader
Parameters:
handler - The object to receive DTD events.
See Also:
XMLReader.getDTDHandler()

setDocumentHandler

public void setDocumentHandler(DocumentHandler handler)
Deprecated. SAX2 programs should use the XMLReader interface and a ContentHandler.

SAX1: Set the document handler for this parser. If a content handler was set, this document handler will supplant it. The parser is set to report all XML 1.0 names rather than to filter out "xmlns" attributes (the "namespace-prefixes" feature is set to true).

Specified by:
setDocumentHandler in interface Parser
Parameters:
handler - The object to receive document events.
See Also:
DocumentHandler, HandlerBase

getContentHandler

public ContentHandler getContentHandler()
SAX2: Returns the object used to report the logical content of an XML document.

Specified by:
getContentHandler in interface XMLReader
Returns:
The current content handler, or null if none has been registered.
See Also:
XMLReader.setContentHandler(org.xml.sax.ContentHandler)

setContentHandler

public void setContentHandler(ContentHandler handler)
SAX2: Assigns the object used to report the logical content of an XML document. If a document handler was set, this content handler will supplant it (but XML 1.0 style name reporting may remain enabled).

Specified by:
setContentHandler in interface XMLReader
Parameters:
handler - The content handler.
See Also:
XMLReader.getContentHandler()

setErrorHandler

public void setErrorHandler(ErrorHandler handler)
SAX1, SAX2: Set the error handler for this parser.

Specified by:
setErrorHandler in interface XMLReader
Parameters:
handler - The object to receive error events.
See Also:
XMLReader.getErrorHandler()

getErrorHandler

public ErrorHandler getErrorHandler()
SAX2: Returns the object used to receive callbacks for XML errors of all levels (fatal, nonfatal, warning); this is never null;

Specified by:
getErrorHandler in interface XMLReader
Returns:
The current error handler, or null if none has been registered.
See Also:
XMLReader.setErrorHandler(org.xml.sax.ErrorHandler)

parse

public void parse(InputSource source)
           throws SAXException,
                  IOException
SAX1, SAX2: Auxiliary API to parse an XML document, used mostly when no URI is available. If you want anything useful to happen, you should set at least one type of handler.

Specified by:
parse in interface XMLReader
Parameters:
source - The XML input source. Don't set 'encoding' unless you know for a fact that it's correct.
Throws:
SAXException - The handlers may throw any SAXException, and the parser normally throws SAXParseException objects.
IOException - IOExceptions are normally through through the parser if there are problems reading the source document.
See Also:
setEntityResolver(org.xml.sax.EntityResolver), setDTDHandler(org.xml.sax.DTDHandler), setContentHandler(org.xml.sax.ContentHandler), setErrorHandler(org.xml.sax.ErrorHandler)

parse

public void parse(String systemId)
           throws SAXException,
                  IOException
SAX1, SAX2: Preferred API to parse an XML document, using a system identifier (URI).

Specified by:
parse in interface XMLReader
Parameters:
systemId - The system identifier (URI).
Throws:
SAXException - Any SAX exception, possibly wrapping another exception.
IOException - An IO exception from the parser, possibly from a byte stream or character stream supplied by the application.
See Also:
XMLReader.parse(org.xml.sax.InputSource)

getFeature

public boolean getFeature(String featureId)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
SAX2: Tells the value of the specified feature flag.

Specified by:
getFeature in interface XMLReader
Parameters:
featureId - The feature name, which is a fully-qualified URI.
Returns:
The current value of the feature (true or false).
Throws:
SAXNotRecognizedException - thrown if the feature flag is neither built in, nor yet assigned.
SAXNotSupportedException - When the XMLReader recognizes the feature name but cannot determine its value at this time.
See Also:
XMLReader.setFeature(java.lang.String, boolean)

getProperty

public Object getProperty(String propertyId)
                   throws SAXNotRecognizedException
SAX2: Returns the specified property.

Specified by:
getProperty in interface XMLReader
Parameters:
propertyId - The property name, which is a fully-qualified URI.
Returns:
The current value of the property.
Throws:
SAXNotRecognizedException - thrown if the property value is neither built in, nor yet stored.
See Also:
XMLReader.setProperty(java.lang.String, java.lang.Object)

setFeature

public void setFeature(String featureId,
                       boolean value)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException
SAX2: Sets the state of feature flags in this parser. Some built-in feature flags are mutable.

Specified by:
setFeature in interface XMLReader
Parameters:
featureId - The feature name, which is a fully-qualified URI.
value - The requested value of the feature (true or false).
Throws:
SAXNotSupportedException - When the XMLReader recognizes the feature name but cannot set the requested value.
SAXNotRecognizedException - If the feature value can't be assigned or retrieved.
See Also:
XMLReader.getFeature(java.lang.String)

setProperty

public void setProperty(String propertyId,
                        Object value)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
SAX2: Assigns the specified property. Like SAX1 handlers, these may be changed at any time.

Specified by:
setProperty in interface XMLReader
Parameters:
propertyId - The property name, which is a fully-qualified URI.
value - The requested value for the property.
Throws:
SAXNotSupportedException - When the XMLReader recognizes the property name but cannot set the requested value.
SAXNotRecognizedException - If the property value can't be assigned or retrieved.

getLength

public int getLength()
SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);

Specified by:
getLength in interface Attributes
Returns:
The number of attributes in the list.
See Also:
Attributes.getURI(int), Attributes.getLocalName(int), Attributes.getQName(int), Attributes.getType(int), Attributes.getValue(int)

getURI

public String getURI(int index)
SAX2 Attributes method (don't invoke on parser);

Specified by:
getURI in interface Attributes
Parameters:
index - The attribute index (zero-based).
Returns:
The Namespace URI, or the empty string if none is available, or null if the index is out of range.
See Also:
Attributes.getLength()

getLocalName

public String getLocalName(int index)
SAX2 Attributes method (don't invoke on parser);

Specified by:
getLocalName in interface Attributes
Parameters:
index - The attribute index (zero-based).
Returns:
The local name, or the empty string if Namespace processing is not being performed, or null if the index is out of range.
See Also:
Attributes.getLength()

getQName

public String getQName(int i)
SAX2 Attributes method (don't invoke on parser);

Specified by:
getQName in interface Attributes
Parameters:
i - The attribute index (zero-based).
Returns:
The XML 1.0 qualified name, or the empty string if none is available, or null if the index is out of range.
See Also:
Attributes.getLength()

getName

public String getName(int i)
SAX1 AttributeList method (don't invoke on parser);

Specified by:
getName in interface AttributeList
Parameters:
i - The index of the attribute in the list (starting at 0).
Returns:
The name of the indexed attribute, or null if the index is out of range.
See Also:
AttributeList.getLength()

getType

public String getType(int i)
SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);

Specified by:
getType in interface Attributes
Parameters:
i - The attribute index (zero-based).
Returns:
The attribute's type as a string, or null if the index is out of range.
See Also:
Attributes.getLength()

getValue

public String getValue(int i)
SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);

Specified by:
getValue in interface Attributes
Parameters:
i - The attribute index (zero-based).
Returns:
The attribute's value as a string, or null if the index is out of range.
See Also:
Attributes.getLength()

getIndex

public int getIndex(String uri,
                    String local)
SAX2 Attributes method (don't invoke on parser);

Specified by:
getIndex in interface Attributes
Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
local - The attribute's local name.
Returns:
The index of the attribute, or -1 if it does not appear in the list.

getIndex

public int getIndex(String xmlName)
SAX2 Attributes method (don't invoke on parser);

Specified by:
getIndex in interface Attributes
Parameters:
xmlName - The qualified (prefixed) name.
Returns:
The index of the attribute, or -1 if it does not appear in the list.

getType

public String getType(String uri,
                      String local)
SAX2 Attributes method (don't invoke on parser);

Specified by:
getType in interface Attributes
Parameters:
uri - The Namespace URI, or the empty String if the name has no Namespace URI.
local - The local name of the attribute.
Returns:
The attribute type as a string, or null if the attribute is not in the list or if Namespace processing is not being performed.

getType

public String getType(String xmlName)
SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);

Specified by:
getType in interface Attributes
Parameters:
xmlName - The XML 1.0 qualified name.
Returns:
The attribute type as a string, or null if the attribute is not in the list or if qualified names are not available.

getValue

public String getValue(String uri,
                       String local)
SAX Attributes method (don't invoke on parser);

Specified by:
getValue in interface Attributes
Parameters:
uri - The Namespace URI, or the empty String if the name has no Namespace URI.
local - The local name of the attribute.
Returns:
The attribute value as a string, or null if the attribute is not in the list.

getValue

public String getValue(String xmlName)
SAX1 AttributeList, SAX2 Attributes method (don't invoke on parser);

Specified by:
getValue in interface Attributes
Parameters:
xmlName - The XML 1.0 qualified name.
Returns:
The attribute value as a string, or null if the attribute is not in the list or if qualified names are not available.

isSpecified

public boolean isSpecified(int index)
SAX-ext Attributes2 method (don't invoke on parser);

Specified by:
isSpecified in interface Attributes2
Parameters:
index - The attribute index (zero-based).
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.

isSpecified

public boolean isSpecified(String uri,
                           String local)
SAX-ext Attributes2 method (don't invoke on parser);

Specified by:
isSpecified in interface Attributes2
Parameters:
uri - The Namespace URI, or the empty string if the name has no Namespace URI.
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.

isSpecified

public boolean isSpecified(String xmlName)
SAX-ext Attributes2 method (don't invoke on parser);

Specified by:
isSpecified in interface Attributes2
Returns:
true if the value was found in the XML text, false if the value was provided by DTD defaulting.

getPublicId

public String getPublicId()
SAX Locator method (don't invoke on parser);

Specified by:
getPublicId in interface Locator
Returns:
A string containing the public identifier, or null if none is available.
See Also:
Locator.getSystemId()

getSystemId

public String getSystemId()
SAX Locator method (don't invoke on parser);

Specified by:
getSystemId in interface Locator
Returns:
A string containing the system identifier, or null if none is available.
See Also:
Locator.getPublicId()

getLineNumber

public int getLineNumber()
SAX Locator method (don't invoke on parser);

Specified by:
getLineNumber in interface Locator
Returns:
The line number, or -1 if none is available.
See Also:
Locator.getColumnNumber()

getColumnNumber

public int getColumnNumber()
SAX Locator method (don't invoke on parser);

Specified by:
getColumnNumber in interface Locator
Returns:
The column number, or -1 if none is available.
See Also:
Locator.getLineNumber()


Source code is under GPL (with library exception) in the JAXP project at http://www.gnu.org/software/classpathx/jaxp
This documentation was derived from that source code on 2007-02-12.