org.brownell.xml
Class Parser2

java.lang.Object
  |
  +--org.brownell.xml.Parser2

public class Parser2
extends java.lang.Object
implements XMLReader

This is a wrapper around the com.sun.xml.parser.* SAX1 parsers, implementing SAX2 interfaces. The standardized SAX2 facilities exposed by this parser include all SAX1 features, as well as a number of additional features and properties identified by standardized URIs. Those features are summarized below.

Name Notes
Features ... URL prefix is http://xml.org/sax/features/
(URI)/external-general-entities Value is fixed at true
(URI)/external-parameter-entities Value is fixed at true
(URI)/namespaces Value is fixed at false (temporary -- SAX2 demands default of 'true')
(URI)/namespace-prefixes Value is fixed at true (temporary -- SAX2 demands default of 'false')
(URI)/string-interning Value is fixed at true
(URI)/validation Defaults to false; may be set to true
Handler properties ... URL prefix is http://xml.org/sax/properties/
(URI)/declaration-handler A declaration handler may be provided. Declaration of general entities is exposed, but not parameter entities; none of the entity names reported here will begin with "%".
(URI)/lexical-handler A lexical handler may be provided. While the start and end of any external subset are reported, expansion of other parameter entities (e.g. inside attribute list declarations) is not exposed. Expansion of general entities within attributes is also not exposed (see below).

Other features of the Sun parser, some of which may be significant by their current lack of support in SAX2, include:

Expansion of entities is not exposed, although the final version of SAX2 does now address the reporting issues noted in response to the implementation of the first (1998) SAX2 API proposals.

Version:
$Date: 2000/05/29 12:12:04 $
Author:
David Brownell

Constructor Summary
Parser2()
          Constructs an unitialized SAX2 parser.
 
Method Summary
 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).
 boolean getFeature(java.lang.String featureId)
          SAX2: Tells whether this parser supports the specified feature.
 java.lang.Object getProperty(java.lang.String propertyId)
          SAX2: Returns the specified property.
 void parse(InputSource input)
          SAX1: parse the XML text in the given input source.
 void parse(java.lang.String uri)
          SAX1: Parse the XML text at the given input URI.
 void setContentHandler(ContentHandler handler)
          SAX2: Assigns the object used to report the logical content of an XML document.
 void setDTDHandler(DTDHandler handler)
          SAX1: Provides an object which may be used to intercept declarations related to notations and unparsed entities.
 void setEntityResolver(EntityResolver resolver)
          SAX1: Provides an object which may be used when resolving external entities during parsing (both general and parameter entities).
 void setErrorHandler(ErrorHandler handler)
          SAX1: Provides an object which receives callbacks for XML errors of all levels (fatal, nonfatal, warning).
 void setFeature(java.lang.String featureId, boolean state)
          SAX2: Sets the state of features supported in this parser.
 void setLocale(java.util.Locale locale)
          SAX1: Identifies the locale which the parser should use for the diagnostics it provides.
 void setProperty(java.lang.String propertyId, java.lang.Object property)
          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

Parser2

public Parser2()
Constructs an unitialized SAX2 parser. By default, this will not validate; validation may be manually enabled. If it is enabled, you should probably set an error handler accordingly.
Method Detail

getErrorHandler

public ErrorHandler getErrorHandler()
SAX2: Returns the object used to receive callbacks for XML errors of all levels (fatal, nonfatal, warning).
Specified by:
getErrorHandler in interface XMLReader
Tags copied from interface: XMLReader
Returns:
The current error handler, or null if none has been registered.
See Also:
XMLReader.setErrorHandler(org.xml.sax.ErrorHandler)

setErrorHandler

public void setErrorHandler(ErrorHandler handler)
SAX1: Provides an object which receives callbacks for XML errors of all levels (fatal, nonfatal, warning).

NOTE: When using a validating parser, the SAX default error handler almost certainly does not do what you expected. Unless you specified validation on a lark, you probably wanted to do something more with validity errors than discard them. You should provide a handler which does something useful with nonfatal errors, probably reporting them (perhaps by treating them like fatal errors).

Specified by:
setErrorHandler in interface XMLReader
Tags copied from interface: XMLReader
Parameters:
handler - The error handler.
Throws:
java.lang.NullPointerException - If the handler argument is null.
See Also:
XMLReader.getErrorHandler()

getContentHandler

public ContentHandler getContentHandler()
SAX2: Returns the object used to report the logical content of an XML document.
Specified by:
getContentHandler in interface XMLReader
Tags copied from 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.
Specified by:
setContentHandler in interface XMLReader
Tags copied from interface: XMLReader
Parameters:
handler - The content handler.
Throws:
java.lang.NullPointerException - If the handler argument is null.
See Also:
XMLReader.getContentHandler()

getDTDHandler

public DTDHandler getDTDHandler()
SAX2: Returns the object used to process declarations related to notations and unparsed entities.
Specified by:
getDTDHandler in interface XMLReader
Tags copied from 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: Provides an object which may be used to intercept declarations related to notations and unparsed entities.
Specified by:
setDTDHandler in interface XMLReader
Tags copied from interface: XMLReader
Parameters:
handler - The DTD handler.
Throws:
java.lang.NullPointerException - If the handler argument is null.
See Also:
XMLReader.getDTDHandler()

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
Tags copied from 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: Provides an object which may be used when resolving external entities during parsing (both general and parameter entities).
Specified by:
setEntityResolver in interface XMLReader
Tags copied from interface: XMLReader
Parameters:
resolver - The entity resolver.
Throws:
java.lang.NullPointerException - If the resolver argument is null.
See Also:
XMLReader.getEntityResolver()

setLocale

public void setLocale(java.util.Locale locale)
               throws SAXException
SAX1: Identifies the locale which the parser should use for the diagnostics it provides.
Throws:
SAXException - as defined in the specification for org.xml.sax.Parser.setLocale()

parse

public void parse(java.lang.String uri)
           throws SAXException,
                  java.io.IOException
SAX1: Parse the XML text at the given input URI.
Specified by:
parse in interface XMLReader
Throws:
SAXException - as defined in the specification for org.xml.sax.Parser.parse()
java.io.IOException - as defined in the specification for org.xml.sax.Parser.parse()

parse

public void parse(InputSource input)
           throws SAXException,
                  java.io.IOException
SAX1: parse the XML text in the given input source. Note that if no system identifier is available for the input stream, then the parse will not be able to interpret any relative URIs in that XML source text; provide the system identifier, if you know it.
Specified by:
parse in interface XMLReader
Throws:
SAXException - as defined in the specification for org.xml.sax.Parser.parse()
java.io.IOException - as defined in the specification for org.xml.sax.Parser.parse()

getFeature

public boolean getFeature(java.lang.String featureId)
                   throws SAXNotRecognizedException,
                          SAXNotSupportedException
SAX2: Tells whether this parser supports the specified feature. At this time, this directly parallels the underlying parser, except that the use of validation can be enabled or disabled (since Sun's package has two separate SAX1 parsers).
Specified by:
getFeature in interface XMLReader
Tags copied from interface: XMLReader
Parameters:
name - The feature name, which is a fully-qualified URI.
Returns:
The current state of the feature (true or false).
Throws:
SAXNotRecognizedException - When the XMLReader does not recognize the feature name.
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 java.lang.Object getProperty(java.lang.String propertyId)
                             throws SAXNotRecognizedException,
                                    SAXNotSupportedException
SAX2: Returns the specified property. At this time only declaration and lexical handlers are supported (Sun's parser exposes this state already).
Specified by:
getProperty in interface XMLReader
Tags copied from interface: XMLReader
Parameters:
name - The property name, which is a fully-qualified URI.
Returns:
The current value of the property.
Throws:
SAXNotRecognizedException - When the XMLReader does not recognize the property name.
SAXNotSupportedException - When the XMLReader recognizes the property name but cannot determine its value at this time.
See Also:
XMLReader.setProperty(java.lang.String, java.lang.Object)

setFeature

public void setFeature(java.lang.String featureId,
                       boolean state)
                throws SAXNotRecognizedException,
                       SAXNotSupportedException
SAX2: Sets the state of features supported in this parser. At this writing, only one feature's state is mutable: validation can be enabled or disabled, though not in the middle of a parse.
Specified by:
setFeature in interface XMLReader
Tags copied from interface: XMLReader
Parameters:
name - The feature name, which is a fully-qualified URI.
state - The requested state of the feature (true or false).
Throws:
SAXNotRecognizedException - When the XMLReader does not recognize the feature name.
SAXNotSupportedException - When the XMLReader recognizes the feature name but cannot set the requested value.
See Also:
XMLReader.getFeature(java.lang.String)

setProperty

public void setProperty(java.lang.String propertyId,
                        java.lang.Object property)
                 throws SAXNotRecognizedException,
                        SAXNotSupportedException
SAX2: Assigns the specified property. At this time only declaration and lexical handlers are supported, and these must not be changed to values of the wrong type. Like SAX1 handlers, these may be changed at any time.
Specified by:
setProperty in interface XMLReader
Tags copied from interface: XMLReader
Parameters:
name - The property name, which is a fully-qualified URI.
state - The requested value for the property.
Throws:
SAXNotRecognizedException - When the XMLReader does not recognize the property name.
SAXNotSupportedException - When the XMLReader recognizes the property name but cannot set the requested value.