This interface defines the methods that must be implemented by a SAX2 XML parser. Since it is an interface, XMLReader cannot define a constructor for creating an XMLReader. To obtain an XMLReader, object, you can instantiate some implementation-specific class that implements this interface. Alternatively, you can keep your code independent of any specific parser implementation by using the SAXParserFactory and SAXParser classes of the javax.xml.parsers package. See those classes for more details. Note that the XMLReader interface has no relationship to the java.io.Reader class or any other character stream classes.

Once you have obtained an XMLReader instance, you must register handler objects on it, so that it can invoke methods on those handlers to notify your application of the results of its parsing. All applications should register a ContentHandler and an ErrorHandler with setContentHandler( ) and setErrorHandler( ). Some applications may also want to register an EntityResolver and/or a DTDHandler. Applications can also register DeclHandler and LexicalHandler objects from the org.xml.sax.ext package, if the parser implementation supports these extension handler interfaces. DeclHandler and LexicalHandler objects are registered with setProperty( ), as explained below.

In addition to registering handler objects for an XMLReader, you may also want to configure the behavior of the parser using setFeature( ) and setProperty( ). Features and properties are both name/value pairs. For uniqueness, the names of features and properties are expressed as URLs (the URLs usually do not have any web content associated with them: they are merely unique identifiers). Features have boolean values, and properties have arbitrary object values. Features and properties are an extension mechanism, allowing an application to specify implementation-specific details about how the parser should behave. But there are also several "standard" features and properties that are supported by many (or all) SAX parsers. They are listed below. If a parser does not recognize the name of a feature or property, the setFeature( ) and setProperty( ) methods (as well as the corresponding getFeature( ) and getProperty( ) query methods) throw a SAXNotRecognizedException. If the parser recognizes the name of a feature or property, but does not support the feature or property, the methods instead throw a SAXNotSupportedException. This exception is also thrown by the set methods when the parser allows the feature or property to be queried but not set.

The standard features are the following. Their names are all URLs that begin with the prefix "http://www.xml.org/sax/features/". For brevity, this prefix has been omitted below. Note that only two of these features must be supported by all parsers. The others may or may not be supported in any given implementation:

namespaces

If true (the default), then the parser supports namespaces and provides the namespace URI and localname for element and attribute names. Support for this feature is required in all parser implementations .

namespace-prefixes

If true, then the parser provides the qualified name (or "qName") that for element and attribute names. A qName consists of a namespace prefix, a colon, and the local name. The default value of this feature is false, and support for the feature is required in all parser implementations.

validation

If true, then the parser will validate XML documents, and will read all external entities.

external-general-entities

If true, then the parser handles external general entities. This is always TRue if the validation feature is TRue.

external-parameter-entities

If true, then the parser handles external parameter entities. This is always TRue if the validation feature is true.

lexical-handler/parameter-entities

If true, then the parser will report the begining and end of parameter entities to the LexicalHandler extension interface.

string-interning

If TRue, then the parser will use the String.intern( ) method for all strings (element, attribute, entity and notation names, and namespace prefixes and URIs) it returns. If the application does the same, it can use = = equality testing for these strings rather than using the more expensive equals( ) method.

The standard properties are the following. Like the features, their names are all URLs that begin with the prefix (omitted below) "http://www.xml.org/sax/properties/". Note that support for all of these properties is optional.

declaration-handler

An org.xml.sax.ext.DeclHandler object to which the parser will report the contents of the DTD.

lexical-handler

An org.xml.sax.ext.LexicalHandler object on which the parser will make method calls to describe the lexical structure (such as comments and CDATA sections) of the XML document.

xml-string

This is a read-only property, and can only be queried from within a handler method invoked by the parser. The value of this property is a String that contains the document content that triggered the current handler invocation.

dom-node

An XMLReader that "parses" a DOM tree rather than the textual form of an XML document uses the value of this property as the org.w3c.dom.Node object at which it should begin parsing.

Finally, after you have obtained an XMLReader object, have queried and configured its features and properties, and have set a ContentHandler, ErrorHandler, and any other required handler objects, you are ready to parse an XML document. Do this by calling one of the parse( ) methods, specifying the document to parse either as a system identifier (a URL) or as an InputSource object (which allows the use of streams as well).

public interface XMLReader {
// Public Instance Methods
     org.xml.sax.ContentHandler getContentHandler( );  
     DTDHandler getDTDHandler( );  
     EntityResolver getEntityResolver( );  
     ErrorHandler getErrorHandler( );  
     boolean getFeature(String name) throws SAXNotRecognizedException, 
        SAXNotSupportedException;  
     Object getProperty(String name) throws SAXNotRecognizedException, 
        SAXNotSupportedException;  
     void parse(String systemId) throws java.io.IOException, SAXException;  
     void parse(InputSource input) throws java.io.IOException, SAXException;  
     void setContentHandler(org.xml.sax.ContentHandler handler);  
     void setDTDHandler(DTDHandler handler);  
     void setEntityResolver(EntityResolver resolver);  
     void setErrorHandler(ErrorHandler handler);  
     void setFeature(String name, boolean value) 
        throws SAXNotRecognizedException, SAXNotSupportedException;  
     void setProperty(String name, Object value) 
        throws SAXNotRecognizedException, SAXNotSupportedException;  
}

Implementations

XMLFilter, org.xml.sax.helpers.ParserAdapter

Passed To

javax.xml.transform.sax.SAXSource.{SAXSource( ), setXMLReader( )}, XMLFilter.setParent( ), org.xml.sax.helpers.XMLFilterImpl.{setParent( ), XMLFilterImpl( )}, org.xml.sax.helpers.XMLReaderAdapter.XMLReaderAdapter( )

Returned By

javax.xml.parsers.SAXParser.getXMLReader( ), javax.xml.transform.sax.SAXSource.getXMLReader( ), XMLFilter.getParent( ), org.xml.sax.helpers.XMLFilterImpl.getParent( ), org.xml.sax.helpers.XMLReaderFactory.createXMLReader( )