The org.xml.sax.ext Package (XML in a Nutshell, 2nd Edition)

The DeclHandler Interface

DeclHandler is a callback interface that provides information about the ELEMENT, ATTLIST, and parsed ENTITY declarations in the document's DTD. To configure an XMLReader with a DeclHandler, pass the name http://xml.org/sax/properties/DeclHandler and an instance of your handler to the reader's setProperty( ) method:

try {
  parser.setProperty(
   "http://xml.org/sax/properties/DeclHandler",
    new YourDeclHandlerImplementationClass( ));
}
catch(SAXException e) {
  System.out.println("This parser does not provide declarations.");
}

If the parser does not provide declaration events, it throws a SAXNotRecognizedException. If the parser cannot install a DeclHandler at this moment (generally because it's in the middle of parsing a document), then it throws a SAXNotSupportedException. If it doesn't throw one of these exceptions, it will call back to the methods in your DeclHandler as it parses the DTD:

package org.xml.sax.ext;

public interface DeclHandler {

  public void elementDecl(String name, String model) throws SAXException;
  public void attributeDecl(String elementName, String attributeName,
   String type, String defaultValue, String value) throws SAXException;
  public void internalEntityDecl(String name, String value)
   throws SAXException;
  public void externalEntityDecl(String name, String publicID,
   String systemID) throws SAXException;

}

The LexicalHandler Interface

LexicalHandler is a callback interface that provides information about aspects of the document that are not normally relevant, specifically:

CDATA sections
Entity boundaries
DTD boundaries
Comments

Without a LexicalHandler, the parser simply ignores comments and expands entity references and CDATA sections. By using the LexicalHandler interface, however, you can read the comments and learn which text came from regular character data, which came from a CDATA section, and which came from which entity reference.

To configure an XMLReader with a LexicalHandler, pass an instance of your handler to the reader's setProperty( ) method with the name http://xml.org/sax/properties/LexicalHandler:

try {
  parser.setProperty(
    "http://xml.org/sax/properties/LexicalHandler",
    new YourLexicalHandlerClass( )
  );
}
catch(SAXException e) {
  System.out.println("This parser does not provide lexical events.");
}

If the parser does not provide lexical events, it throws a SAXNotRecognizedException. If the parser cannot install a LexicalHandler at this moment (generally because it's in the middle of parsing a document), then it throws a SAXNotSupportedException. If it doesn't throw one of these exceptions, it calls back to the methods in your LexicalHandler as it encounters entity references, comments, and CDATA sections. The basic content of the resolved entities and CDATA sections are still reported through the ContentHandler interface, as normal:

package org.xml.sax.ext;

public interface LexicalHandler {

  public void startDTD(String name, String publicID, String systemID)
   throws SAXException;
  public void endDTD( ) throws SAXException;
  public void startEntity(String name) throws SAXException;
  public void endEntity(String name) throws SAXException;
  public void startCDATA( ) throws SAXException;
  public void endCDATA( ) throws SAXException;
  public void comment(char[] text, int start, int length)
   throws SAXException;

}

25.4. The org.xml.sax.ext Package