home | O'Reilly's CD bookshelfs | FreeBSD | Linux | Cisco | Cisco Exam  


Book HomeXML in a NutshellSearch this book

25.4. The org.xml.sax.ext Package

The org.xml.sax.ext package provides optional interfaces that parsers may use to provide further functionality. Not all parsers support these interfaces, though most major ones do.

The LexicalHandler Interface

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

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;

}


Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.