Most of the time when you’re dealing with XML, one standards body or another developed the various technologies. With SAX, that isn’t the case. SAX was developed by members of the xml-dev mailing list in order to provide XML developers with a way to deal with XML documents in a simple and straightforward manner. One of the lead developers in this mailing list was Dave Megginson, whose name often comes up in discussions related to SAX, and who has resumed maintaining SAX after a hiatus. You can find out more about SAX at http://www.saxproject.org/.

The original version of SAX, 1.0, was released in May 1998. The most recent version is SAX 2.0.2, which was released in April 2004. Earlier versions of the SAX API were implemented initially as Java interfaces. However, you can write a SAX parser in any language, and indeed, there are SAX parsers available for most popular programming languages. However, I’m going to talk about the features that were made available in the Java version—you can assume they’ll also be available under whatever implementation you choose to use. Let’s look at the specifics of these two releases.

SAX 1.0 provides support for triggering events on all of the standard content in an XML document. Rather than telling you everything it does support, it’s easier to tell you that SAX 1.0 does not support namespaces. A program that uses a SAX 1.0 parser must support the following methods, which are automatically invoked when events occur during the parsing of a document:

SAX 1.0 also handles attributes of elements by providing them through its interface when the startElement() method of the document handler is called. SAX 1.0 has been deprecated now that SAX 2.0 has been implemented. In the Java world, most SAX 2.0 libraries (such as Xerces) still support SAX 1.0 so that they’ll work with legacy SAX 1.0 applications. But if you’re writing a new application that uses SAX, you should use SAX 2.0.

SAX 2.0 is an extension of SAX 1.0 that provides support for namespaces. As such, programs that communicate with a SAX 2.0 parser must support the following methods:

Xerces is the XML parser from the Apache Software Foundation. It’s used as part of several other Apache XML and Java-related projects and can be used by itself as well. In addition to supporting SAX, it also supports DOM Level 2, which you learned about in the previous hour, as well as XML Schema validation.

You can obtain Xerces, along with lots of other open source XML-related software, at http://xml.apache.org/. Xerces is completely free as it is open source software released under the Apache Software License.

The Xerces library is available in both .tar.gz and .zip formats—download the one that’s appropriate for your platform. Included in the package are xercesImpl.jar and xml-apis.jar, which contain the compiled class files for the Xerces library itself, and xercesSamples.jar, compiled versions of the sample programs that come with Xerces. The package also includes documentation, source code for the sample programs, and some sample data files.

In order to use the Xerces library, you just need to include the two aforementioned .JAR files (xercesImpl.jar and xml-apis.jar) in your class path when compiling and running programs that use it.

libxml is a package of Perl modules that contains a number of XML processing libraries. One of these is XML::Parser::PerlSAX. The easiest way to install it is to download it from CPAN (http://www.cpan.org/) and follow the instructions to install it on your local system. The methods provided by the PerlSAX module are basically identical to those in the Java version of SAX—they both implement the same interface in ways appropriate to Perl and Java, respectively.

If you’re a Python programmer, things are particularly easy for you. Recent versions of Python (from 2.0 on) provide built-in support for SAX without any additional software. To use the SAX library in your programs, you just need to include the line

from xml.sax import saxutils

Every command-line Java application begins its life with the main() method. In the Java world, the main method indicates that a class is a standalone program, as opposed to one that just provides functionality used by other classes. Perhaps more importantly, it’s the method that gets run when you start the program. The purpose of this method is to set up the parser and get the name of the document to be parsed from the arguments passed in to the program. Here’s the code:

  public static void main(String[] args) {
    if (args.length == 0) {
      System.out.println("No XML document path specified.");
      System.exit(1);
    }

    DocumentPrinter dp = new DocumentPrinter();
    XMLReader parser;
    try {
      parser = (XMLReader)Class.forName(PARSER_NAME).newInstance();
      parser.setContentHandler(dp);
      parser.setErrorHandler(dp);
      parser.parse(args[0]);
    }
    // Normally it's a bad idea to catch generic exceptions like this.
    catch (Exception ex) {
      System.out.println(ex.getMessage());
      ex.printStackTrace();
    }
  }

This program expects that the user will specify the path to an XML document as its only command-line argument. If no such argument is submitted, the program will exit and instruct the user to supply that argument when running the program.

Next, the program creates an instance of the DocumentPrinter object and assigns it to the variable dp. You’ll need this object later when you tell the parser which ContentHandler and ErrorHandler to use. After instantiating dp, a try...catch block is opened to house the parsing code. This is necessary because some of the methods called to carry out the parsing can throw exceptions that must be caught within the program. All of the real work in the program takes place inside the try block.

Within the try...catch block, the first order of business is creating a parser object. This object is actually an instance of the class named in the variable PARSER_NAME. The fact that you’re using it through the XMLReader interface means that you can call only those methods included in that interface. For this application, that’s fine. The class specified in the PARSER_NAME variable is then loaded and assigned to the variable parser. Because SAX 2.0 parsers must implement XMLReader, you can refer to the interface as an object of that type rather than referring to the class by its own name—SAXParser.

After the parser has been created, you can start setting its properties. Before actually parsing the document, however, you have to specify the content and error handlers that the parser will use. Because the DocumentPrinter class can play both of those roles, you simply set both of those properties to dp (the DocumentPrinter object you just created). At this point, all you have to do is call the parse() method on the URI passed in on the command line, which is exactly what the code does.

The skeleton for the program is now in place. The rest of the program consists of methods that fulfill the requirements of the ContentHandler and ErrorHandler interfaces. More specifically, these methods respond to events that are triggered during the parsing of an XML document. In this program, the methods just print out the content that they receive.

The first of these methods is the characters() method, which is called whenever content is parsed in a document. Following is the code for this method:

  public void characters(char[] ch, int start, int length) {
    String chars = "";
    for (int i = start; i < start + length; i++)
      chars = chars + ch[i];

      if ((chars.trim()).length() > 0)
        System.out.println("Received characters: " + chars);
  }

The characters() method receives content found within elements. It accepts three arguments: an array of characters, the position in the array where the content starts, and the amount of content received. In this method, a for loop is used to extract the content from the array, starting at the position in the array where the content starts, and iterating over each element until the position of the last element is reached. When all of the characters are gathered, the code checks to make sure they aren’t just empty spaces, and then prints the results if not.

The next two methods, startDocument() and endDocument(), are called when the beginning and end of the document are encountered, respectively. They accept no arguments and are called only once each during document parsing, for obvious reasons. Here’s the code for these methods:

  public void startDocument() {
    System.out.println("Start document.");
  }
  public void endDocument() {
    System.out.println("End of document reached.");
  }

Next let’s look at the startElement() and endElement() methods, which accept the most complex set of arguments of any of the methods that make up a ContentHandler:

  public void startElement(String namespaceURI, String localName,
    String qName, Attributes atts) {
    System.out.println("Start element: " + localName);
  }

  public void endElement(String namespaceURI, String localName,
    String qName) {
    System.out.println("End of element: " + localName);
  }

The startElement() method accepts four arguments from the parser. The first is the namespace URI, which you’ll see elsewhere as well. The namespace URI is the URI for the namespace associated with the element. If a namespace is used in the document, the URI for the namespace is provided in a namespace declaration. The local name is the name of the element without the namespace prefix. The qualified name is the name of the element including the namespace prefix if there is one. Finally, the attributes are provided as an instance of the Attributes object. The endElement() method accepts the same first three arguments but not the final attributes argument.

Let’s look at attribute processing specifically. Attributes are supplied to the startElement() method as an instance of the Attributes object. In the sample code, you use three methods of the Attributes object: getLength(), getLocalName(), and getValue(). The getLength() method is used to iterate over the attributes supplied to the method call, while getLocalName() and getValue() accept the index of the attribute being retrieved as arguments. The code retrieves each attribute and prints out its name and value. In case you’re curious, the full list of methods for the Attributes object appears in Table 17.1.

Getting back to the endElement() method, its operation is basically the same as that of startElement() except that it doesn’t accept the attributes of the element as an argument.

The next two methods, startPrefixMapping() and endPrefixMapping(), have to do with prefix mappings for namespaces:

  public void startPrefixMapping(String prefix, String uri) {
    System.out.println("Prefix mapping: " + prefix);
    System.out.println("URI: " + uri);
  }

  public void endPrefixMapping(String prefix) {
    System.out.println("End of prefix mapping: " + prefix);
  }

These methods are used to report the beginning and end of namespace prefix mappings when they are encountered in a document.

The next method, ignorableWhitespace(), is similar to characters(), except that it returns whitespace from element content that can be ignored.

  public void ignorableWhitespace(char[] ch, int start, int length) {
    System.out.println("Received whitespace.");
  }

Next on the method agenda is processingInstruction(), which reports processing instructions to the content handler. For example, a stylesheet can be associated with an XML document using the following processing instruction:

<?xml-stylesheet href="mystyle.css" type="text/css"?>

The method that handles such instructions is

  public void processingInstruction(String target, String data) {
    System.out.println("Received processing instruction:");
    System.out.println("Target: " + target);
    System.out.println("Data: " + data);
  }

The last method you need to be concerned with is setDocumentLocator(), which is called when each and every event is processed. Nothing is output by this method in this program, but I’ll explain what its purpose is anyway. Whenever an entity in a document is processed, the parser calls setDocumentLocator() with a Locator object. The Locator object contains information about where in the document the entity currently being processed is located. Here’s the “do nothing” source code for the method:

    public void setDocumentLocator(Locator locator) { }

The methods of a Locator object are described in Table 17.2.

Because the sample program doesn’t concern itself with the specifics of locators, none of these methods are actually used. However, it’s good for you to know about them in case you need to develop a program that somehow is interested in locators.

I mentioned earlier that the DocumentPrinter class implements two interfaces, ContentHandler and ErrorHandler. Let’s look at the methods that are used to implement the ErrorHandler interface. There are three types of errors that a SAX parser can generate—errors, fatal errors, and warnings. Classes that implement the ErrorHandler interface must provide methods to handle all three types of errors. Here’s the source code for the three methods:

  public void error(SAXParseException exception) { }

  public void fatalError(SAXParseException exception) { }

  public void warning(SAXParseException exception) { }

As you can see, each of the three methods accepts the same argument—a SAXParseException object. The only difference between them is that they are called under different circumstances. To keep things simple, the sample program doesn’t output any error notifications. For the sake of completeness, the full list of methods supported by SAXParseException appears in Table 17.3.

Similar to the Locator methods, these methods aren’t used in the Document Printer sample program, so you don’t have to worry about the ins and outs of how they work.

Now that you understand how the code works in the Document Printer sample program, let’s take it for a test drive one more time. This time around, you’re running the program to parse the condos.xml sample document from the previous hour. Here’s an excerpt from that document in case it’s already gotten a bit fuzzy in your memory:

  <proj status="active">
    <location lat="36.122238" long="-86.845028" />
    <description>
      <name>Woodmont Close</name>
      <address>131 Woodmont Blvd.</address>
      <address2>Nashville, TN 37205</address2>
      <img>condowc.jpg</img>
    </description>
  </proj>

And here’s the command required to run this document through the Document Printer program:

java -classpath xercesImpl.jar;xml-apis.jar;. DocumentPrinter condos.xml

Finally, Listing 17.2 contains the output of the Document Printer program after feeding it the condominium map data stored in the condos.xml document.

 1:  Start document.
 2:  Start element: projects
 3:  Start element: proj
 4:  Start element: location
 5:  End of element: location
 6:  Start element: description
 7:  Start element: name
 8:  Received characters: Woodmont Close
 9:  End of element: name
10:  Start element: address
11:  Received characters: 131 Woodmont Blvd.
12:  End of element: address
13:  Start element: address2
14:  Received characters: Nashville, TN 37205
15:  End of element: address2
16:  Start element: img
17:  Received characters: condowc.jpg
18:  End of element: img
19:  End of element: description
20:  End of element: proj
21:  ...
22:  Start element: proj
23:  Start element: location
24:  End of element: location
25:  Start element: description
26:  Start element: name
27:  Received characters: Harding Hall
28:  End of element: name
29:  Start element: address
30:  Received characters: 2120 Harding Pl.
31:  End of element: address
32:  Start element: address2
33:  Received characters: Nashville, TN 37215
34:  End of element: address2
35:  Start element: img
36:  Received characters: condohh.jpg
37:  End of element: img
38:  End of element: description
39:  End of element: proj
40:  End of element: projects
41:  End of document reached.

The excerpt from the condos.xml document that you saw a moment ago corresponds to the first proj element in the XML document. Lines 3 through 20 show how the Document Printer program parses and displays detailed information for this element and all of its content.