Summary

The SAX XMLReader interface represents an XML parser. The actual implementation class will vary from one parser to the next, but generally you’ll only interact with it through the parser-independent methods in XMLReader. Parser-specific instances of this interface are built by the XMLReaderFactory factory class.

The XMLReader’s parse() method actually reads the XML document. One parser object can read multiple documents in series. However, parsers are not thread safe or reentrant and should not be used to read documents in parallel. The source from which the XML document is read, be it an InputStream, Reader, or URI, is wrapped inside an org.xml.sax.InputSource object. An EntityResolver can be used to replace one InputSource with a different InputSource behind the parser’s back. If anything goes wrong during the parse process, this method throws a SAXException or an IOException

The parser is configured by setting features and properties. Both features and properties have names given by absolute URIs. Features have boolean values, true or false. Properties have object values. Standard features have names beginning with http://xml.org/sax/features/ and include http://xml.org/sax/features/external-general-entities, http://xml.org/sax/features/external-parameter-entities, http://xml.org/sax/features/string-interning, and http://xml.org/sax/features/validation. Standard properties have names beginning with http://xml.org/sax/properties/ and include http://xml.org/sax/properties/declaration-handler, http://xml.org/sax/properties/dom-node, http://xml.org/sax/properties/lexical-handler, and http://xml.org/sax/properties/xml-string.

This is not an exhaustive list. Parser vendors add custom features and properties with names in their own domain such as http://apache.org/xml/features/validation/schema and http://apache.org/xml/properties/schema/external-schemaLocation to configure functionality unique to their parser. Of course, not all features and properties, not even all standard features and properties, are supported by any one parser. If you try to set a feature or property that the parser is unfamiliar with and never allows under any circumstances, setFeature()/setProperty() throws a SAXNotRecognizedException. If you try to set a feature or property that the parser recognizes but cannot set at the current time, setFeature()/setProperty() throws a SAXNotSupportedException.

The parser reports the content of the XML document to methods in one or more callback interfaces. The most basic such callback interface and the one that accounts for 90% of what you need is ContentHandler. Other callback interfaces for special needs include ErrorHandler for reporting fatal errors, errors, and warnings and DTDHandler for keeping track of unparsed entity and notation declarations. In addition there are two optional callback interfaces registered by setting properties, LexicalHandler for reporting comments, parsed entities, and CDATA sections; and DeclHandler for reporting ELEMENT, ATTLIST, and ENTITY declarations.


Copyright 2001, 2002 Elliotte Rusty Haroldelharo@metalab.unc.eduLast Modified September 09, 2002
Up To Cafe con Leche