org.brownell.xml
Class Parser2

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

public class Parser2
extends java.lang.Object
implements org.xml.sax.Configurable, org.xml.sax.Parser

This is a wrapper around the com.sun.xml.parser.* SAX 1.0 parsers, implementing 1-June-1999 draft SAX2 interfaces. The standardized SAX2 facilities exposed by this parser include all SAX 1.0 features, as well as a number of additional features and properties identified by standardized URIs. Those features (but not the associated URIs) are summarized below.

Name Type Notes
validation Feature Defaults to false; may be set to true
external-general-entities Feature Value is fixed at true
external-parameter-entities Feature Value is fixed at true
namespaces Feature Value is fixed at false
normalize-text Feature Value is fixed at false
use-locator Feature Value is fixed at true
 
DeclHandler Property 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 "%".
LexicalHandler Property 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, which may be significant by their current absence in the draft SAX2 APIs, include:

Features which might affect conformance with the SAX2 draft include:

Version:
1.1 (23 June 1999)
Author:
David Brownell (db@post.harvard.edu)

Constructor Summary
Parser2()
          Constructs an unitialized SAX2 parser.
 
Method Summary
 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(org.xml.sax.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 setDocumentHandler(org.xml.sax.DocumentHandler handler)
          SAX1: Provides an object which receives callbacks for the most significant document information.
 void setDTDHandler(org.xml.sax.DTDHandler handler)
          SAX1: Provides an object which may be used to intercept declarations related to notations and unparsed entities.
 void setEntityResolver(org.xml.sax.EntityResolver resolver)
          SAX1: Provides an object which may be used when resolving external entities during parsing (both general and parameter entities).
 void setErrorHandler(org.xml.sax.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

setErrorHandler

public void setErrorHandler(org.xml.sax.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 org.xml.sax.Parser

setDocumentHandler

public void setDocumentHandler(org.xml.sax.DocumentHandler handler)
SAX1: Provides an object which receives callbacks for the most significant document information.
Specified by:
setDocumentHandler in interface org.xml.sax.Parser

setDTDHandler

public void setDTDHandler(org.xml.sax.DTDHandler handler)
SAX1: Provides an object which may be used to intercept declarations related to notations and unparsed entities.
Specified by:
setDTDHandler in interface org.xml.sax.Parser

setEntityResolver

public void setEntityResolver(org.xml.sax.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 org.xml.sax.Parser

setLocale

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

parse

public void parse(java.lang.String uri)
           throws org.xml.sax.SAXException,
                  java.io.IOException
SAX1: Parse the XML text at the given input URI.
Specified by:
parse in interface org.xml.sax.Parser
Throws:
org.xml.sax.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(org.xml.sax.InputSource input)
           throws org.xml.sax.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 org.xml.sax.Parser
Throws:
org.xml.sax.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 org.xml.sax.SAXException
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 SAX 1.0 parsers).
Specified by:
getFeature in interface org.xml.sax.Configurable
Throws:
org.xml.sax.SAXException - as defined in the specification for org.xml.sax.Configurable.getFeature()

getProperty

public java.lang.Object getProperty(java.lang.String propertyId)
                             throws org.xml.sax.SAXException
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 org.xml.sax.Configurable
Throws:
org.xml.sax.SAXException - as defined in the specification for org.xml.sax.Configurable.getProperty()

setFeature

public void setFeature(java.lang.String featureId,
                       boolean state)
                throws org.xml.sax.SAXException
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 org.xml.sax.Configurable
Throws:
org.xml.sax.SAXException - as defined in the specification for org.xml.sax.Configurable.setFeature()

setProperty

public void setProperty(java.lang.String propertyId,
                        java.lang.Object property)
                 throws org.xml.sax.SAXException
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 org.xml.sax.Configurable
Throws:
org.xml.sax.SAXException - as defined in the specification for org.xml.sax.Configurable.setProperty()