A concrete example should help make this clearer. I’m going to write a very simple program that extracts all the text content from an XML document while stripping out all the tags, comments, and processing instructions. This will be divided into two parts, a class that implements ContentHandler and a class that feeds the document into the parser.

Example 6.3, TextExtractor, is the class that implements ContentHandler. It has to provide all eleven methods declared in ContentHandler. However, the only one that’s actually needed is characters(). The other ten are do-nothing methods. They have empty method bodies, and nothing happens when the parser invokes them.

import org.xml.sax.*;
import java.io.*;


public class TextExtractor implements ContentHandler {

  private Writer out;
  
  public TextExtractor(Writer out) {
    this.out = out;   
  }
    
  public void characters(char[] text, int start, int length)
   throws SAXException {
     
    try {
      out.write(text, start, length); 
    }
    catch (IOException e) {
      throw new SAXException(e);   
    }
    
  }  
    
  // do-nothing methods
  public void setDocumentLocator(Locator locator) {}
  public void startDocument() {}
  public void endDocument() {}
  public void startPrefixMapping(String prefix, String uri) {}
  public void endPrefixMapping(String prefix) {}
  public void startElement(String namespaceURI, String localName,
   String qualifiedName, Attributes atts) {}
  public void endElement(String namespaceURI, String localName,
   String qualifiedName) {}
  public void ignorableWhitespace(char[] text, int start, 
   int length) throws SAXException {}
  public void processingInstruction(String target, String data){}
  public void skippedEntity(String name) {}

} // end TextExtractor

Besides the eleven methods declared in ContentHandler, TextExtractor has a constructor and an out field. The constructor sets this field to the Writer on which the parsed text will be output. You can always add as many additional methods, fields, and constructors as you need. You’re not limited to just those declared in the interface.

All the real work of this class happens inside characters(). When the parser reads content between tags, it passes this text to the characters() method inside an array of chars. The index of the first character of the text inside that array is given by the start argument. The number of characters is given by the length argument. In this class, the characters() method writes the sub-array of text from start to start+length onto the Writer stored in the out field.

The characters() method in this class invokes the write() method in java.io.Writer. It happens that the write() method is declared to throw an IOException. The ContentHandler interface does not declare that characters() throws IOException. Therefore this exception must be caught. However, rather than simply ignoring it or printing a pointless message on System.err, we can wrap the IOException inside SAXException, which characters() is declared to throw, and then throw that exception. This signals the parser that something went wrong, and the parser will pass the exception along to the client application. If the client application wants to know what originally went wrong, it can find out by invoking SAXException’s getException() method.

In contrast, none of the do-nothing methods such as startElement() and processingInstruction() will ever throw any exceptions. Therefore, they are not declared to throw SAXException even though ContentHandler would support this declaration. There’s no need to clutter up the code with unnecessary throws clauses, nor is it good programming practice to advertise a possible exception in the method signature when you know that exception will never occur.

By itself the TextExtractor class does nothing. There’s no code in the class to actually invoke any of the methods or parse a document. Although code to do this could be placed in a main() method in TextExtractor, I prefer to place it in a class of its own called ExtractorDriver which is shown in Example 6.4.

import org.xml.sax.*;
import org.xml.sax.helpers.XMLReaderFactory;
import java.io.*;


public class ExtractorDriver {

  public static void main(String[] args) {
      
    if (args.length <= 0) {
      System.out.println(
       "Usage: java ExtractorDriver url"
      );
      return;
    }
          
    try {
      XMLReader parser = XMLReaderFactory.createXMLReader();
      
      // Since this just writes onto the console, it's best
      // to use the system default encoding, which is what
      // we get by not specifying an explicit encoding here.
      Writer out = new OutputStreamWriter(System.out);
      ContentHandler handler = new TextExtractor(out);
      parser.setContentHandler(handler);
    
      parser.parse(args[0]);
      
      out.flush();
    }
    catch (Exception e) {
      System.err.println(e); 
    }
  
  } 

}

The main() method in this class performs the following steps:

One thing to note: there’s still no code that actually invokes the characters() or any other method in the TextExtractor class! This is for the same reason that you never see any code to invoke actionPerformed() or mouseClicked() when writing GUI programs in Java. The code that actually calls these methods is hidden deep inside the class library. You rarely need to concern yourself with it directly. Here the relevant code that calls characters() is hiding somewhere inside the parser-specific implementation of the XMLReader interface.

Let’s suppose you run this program over the original XML order document, Example 1.2 from Chapter 1. The results look like this:

C:\>java ExtractorDriver order.xml

  Chez Fred

    Birdsong Clock
    244
    12
    21.95


    135 Airline Highway
    Narragansett RI 02882

  263.40
  18.44
  8.95
  290.79

The text of the original document, including white space, has been preserved. However, the markup has all been stripped. This is exactly what we asked for.

In the next few sections, we’ll explore the individual methods of the ContentHandler interface and their behavior in more detail.

TextExtractor only really used one of the eleven methods declared in ContentHandler. The other ten methods were all do-nothing methods with empty bodies. In fact, few SAX programs actually use all eleven methods. Most of the time about half suffice. To take advantage of this, SAX includes the org.xml.sax.helpers.DefaultHandler convenience class that implements the ContentHandler interface (and several other callback interfaces discussed in upcoming chapters) with do-nothing methods:

public class DefaultHandler implements ContentHandler, 
 DTDHandler, EntityResolver, ErrorHandler

Instead of implementing, ContentHandler directly and cluttering up your code with irrelevant methods, you can instead extend DefaultHandler. Then you only have to override those methods you actually care about, not all eleven.

For example, if TextExtractor was built on top of DefaultHandler, it would be the smaller and simpler class shown in Example 6.5.

import org.xml.sax.*;
import org.xml.sax.helpers.DefaultHandler;
import java.io.*;


public class TextExtractor extends DefaultHandler {

  private Writer out;
  
  public TextExtractor(Writer out) {
    this.out = out;   
  }
    
  public void characters(char[] text, int start, int length)
   throws SAXException {
    try {
      out.write(text, start, length); 
    }
    catch (IOException e) {
      throw new SAXException(e);   
    }
  }

}

Programs in this book use content handlers that implement ContentHandler directly and content handlers that extend DefaultHandler, mostly depending on which subjectively feels more natural to the problem at hand. You should feel free to use whichever variation you prefer.