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:
- The Internal DTD Subset is not currently exposed
through this interface; applications requiring literal recreation of
a document's doctype can't do this with SAX2. (Examples of such
applications include the filtering proxies that many secure message
distribution networks require.)
- Sun's parser lets you insert the results of executing the
JavaScript within an HTML <script> tag into the input
stream as it is parsed, permitting complete XHTML support.
- SAX2 discards some semantic attribute declaration information,
namely the list of just which NOTATIONs an attribute may use.
- At this time, the SAX 1.0 handlers are not exposed as parser
properties in the way that the SAX2 ones are exposed. (These could
be defined as such properties, however.)
- The com.sun.xml.parser.AttributeListEx information is
still visible through the startElement() callback; this information
is useful to support some DOM Level 1 features relating to defaulting
of attributes, without requiring applications to replicate the
parser's handling of DTD information.
Features which might affect conformance with the SAX2 draft include:
- While validation may be enabled or disabled, that can't be done
while parsing. The SAX2 draft should perhaps say this, since any
nonvalidating parser is likely to have discarded information needed
to validate by the time validation would be enabled.
- Like other SAX handlers, the declaration and lexical handlers may
be set at any time ... though the SAX2 draft says that shouldn't be
permitted.
- Expansion of entities within attributes is not exposed. It was
observed during initial implementation of Sun's parser that such
reports look like the entities precede the element, giving
applications an incorrect model of the document content.
- As noted above, Sun's parsers will not report expansion of
parameter entities. The rationale is, in short, that seeing such
boundaries is all but useless since they're normally used as parts
of larger components, and construction-by-parts isn't exposed.
- 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 |
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.
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()