Java in a Nutshell, 5th Edition [Electronic resources] نسخه متنی

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(
)