This interface is the key one for XML parsing with the SAX API. An XMLReader tells your application about the content of the XML document it is parsing by invoking the various methods of the ContentHandler interface. In order to parse documents with SAX, you must implement this interface to define methods that take whatever actions are necessary when they are invoked by the parser. Because this interface is so critical to the SAX API, the methods are explained individually below:

setDocumentLocator( )

The parser usually calls this method (but is not required to do so) before calling any others to pass a Locator object to the ContentHandler. Locator defines methods that return the current line and column number of the document being parsed, and if the parser supplies a Locator object, it guarantees that its methods will return valid values during any other ContentHandler invocations that follow. A ContentHandler can call the methods of this object when printing error messages, for example.

startDocument( ), endDocument( )

The parser calls these methods once, at the beginning and end of parsing. startDocument( ) is the first method called except for the optional setDocumentLocator( ) call, and endDocument( ) is always the last method call on a ContentHandler.

startElement( ), endElement( )

The parser calls these methods for each start tag and end tag it encounters. Both are passed three arguments describing the name of the tag: if the parser is doing namespace processing, then the first two arguments of both methods return the URI that uniquely identifies the namespace, and the local name of the tag within that namespace. If the parser is not doing namespace parsing, then the third argument provides the full name of the tag. In addition to these tag name arguments, startElement( ) is also passed an Attributes object that describes the attributes of the tag.

characters( )

This method is invoked to tell the application that the parser has found a string of text in the XML document. The text is contained within the specified character array, at the specified start position, and continuing for the specified number of characters.

ignorableWhitespace( )

This method is like characters( ), but parsers may use it to tell the application about "ignorable whitespace" in XML element content.

processingInstruction( )

The parser calls this method to tell the application that it has encountered an XML Processing Instruction (or PI) with the specified target and data strings.

skippedEntity( )

If the XML parser does encounters an entity in the document, but does not expand and parse its content, then it tells the application about it by passing the name of the entity to this method.

startPrefixMapping( ), endPrefixMapping( )

These methods to tell the application about a namespace mapping from the specified prefix to the specified namespace URI.

DTDHandler is another interface like ContentHandler. An application can implement this interface to receive notification of DTD-related events from the parser. Similarly, the org.xml.sax.ext package defines two "extension" interfaces that can be used (if the parser supports these extensions) to obtain even more information about the document (such as comments and CDATA sections) and about the DTD (including the full set of element, attribute and entity declarations). The org.xml.sax.helpers.DefaultHandler class is a useful one. It implements ContentHandler and three other interfaces that are commonly used with the XMLReader class and provides empty implementations of all their methods. Applications can subclass DefaultHandler only need to override the methods they care about. This is usually more convenient that implementing the interfaces directly.

public interface ContentHandler {
// Public Instance Methods
     void characters(char[ ] ch, int start, int length) 
       throws SAXException;  
     void endDocument( ) throws SAXException;  
     void endElement(String uri, String localName, String qName) 
        throws SAXException;  
     void endPrefixMapping(String prefix) throws SAXException;  
     void ignorableWhitespace(char[ ] ch, int start, int length) 
        throws SAXException;  
     void processingInstruction(String target, String data) 
        throws SAXException;  
     void setDocumentLocator(Locator locator);  
     void skippedEntity(String name) throws SAXException;  
     void startDocument( ) throws SAXException;  
     void startElement(String uri, String localName, String qName, 
        org.xml.sax.Attributes atts) throws SAXException;  
     void startPrefixMapping(String prefix, String uri) 
        throws SAXException;  
}

Implementations

javax.xml.transform.sax.TemplatesHandler, javax.xml.transform.sax.TransformerHandler, javax.xml.validation.ValidatorHandler, org.xml.sax.helpers.DefaultHandler, org.xml.sax.helpers.XMLFilterImpl, org.xml.sax.helpers.XMLReaderAdapter

Passed To

javax.xml.transform.sax.SAXResult.{SAXResult( ), setHandler( )}, javax.xml.validation.ValidatorHandler.setContentHandler( ), XMLReader.setContentHandler( ), org.xml.sax.helpers.ParserAdapter.setContentHandler( ), org.xml.sax.helpers.XMLFilterImpl.setContentHandler( )

Returned By

javax.xml.transform.sax.SAXResult.getHandler( ), javax.xml.validation.ValidatorHandler.getContentHandler( ), XMLReader.getContentHandler( ), org.xml.sax.helpers.ParserAdapter.getContentHandler( ), org.xml.sax.helpers.XMLFilterImpl.getContentHandler( )