Note: This tip uses JAXP. The classes are also part of the Java 2 SDK 1.4, so if you have 1.4 installed, you don't need any additional software. You can download the source file for this article (see Resources).

How a SAX parser works

The Simple API for XML (SAX) is an event-based API. It examines an XML file, character by character, and translates it into a series of events, such as startDocument() and endElement(). A ContentHandler object processes these events, taking appropriate action. An ErrorHandler object takes care of any warnings or errors that arise during the parsing. The main application (see Listing 1) assigns these objects to the XMLReader object:

The parse() method simply sends the events to the content object, which then deals with them.

Back to top

The handlers

For this application, all of the work will be done by the WeblogHandler object, which processes the XML file. The changes.xml file itself is fairly simple, with all of the actual data contained in attributes:

<?xml version="1.0"?>
<weblogUpdates version="1" 
              updated="Sat, 15 Jun 2002 22:25:06 GMT" 
              count="592697">
  <weblog name="Enigmatic Mermaid" 
             url="http://pombostrans.blogspot.com" 
             when="28"/>
  <weblog name="The Vanguard Science Fiction Report" 
             url="http://www.vanguardreport.com" when="852"/>
  <weblog name="Flummox.com" 
             url="http://www.flummox.com/" when="10713"/>
</weblogUpdates>

This is just a snippet of the actual file, but it shows the structure: Attributes include the name, the URL, and the time since the weblog was updated, in seconds. The content handler takes some of that information and outputs it to the window:

import org.xml.sax.helpers.DefaultHandler;
import org.xml.sax.Attributes;

public class WeblogHandler extends DefaultHandler
{
  public WeblogHandler ()
  {
      super();
  }

  int numLogs = 0;
  public void startElement (String namespaceUri, String localName, 
          String qualifiedName, Attributes attributes) {
      
      if (localName.equals("weblog")) {
          String logName = attributes.getValue("name");
          String secsAgo = attributes.getValue("when");
          numLogs = numLogs + 1;
          System.out.println(numLogs + ") " + logName 
                  + " updated " + secsAgo + " seconds ago.");
      }
  }

  public void endDocument(){
       System.out.println();
       System.out.println("All recorded logs displayed.");
       System.out.println("More may have been updated within"
                  + " the appropriate timeframe.");
  }

}

In this case the error handler is trivial, simply alerting you to the presence of an error or warning. The source files include the file in its entirety.

Back to top

Running the application

When you actually run MainSaxApp, all of the data in changes.xml is passed through to content, which outputs the appropriate information, as seen in Figure 1.

Notice that the entire file has been parsed, as evidenced by the execution of the endDocument() method.

Back to top

Stopping the parser

As you can see, a significant number of weblogs have been updated in the three-hour period that changes.xml tracks. Suppose that you want to allow the user to enter a number of seconds representing the interval in which he or she is interested. To do that, you'll look at the first argument on the command line, passing it in to the content object. (You'll look at the corresponding changes to WeblogHandler.java in a moment.)

...
   String parserClass = "org.apache.crimson.parser.XMLReaderImpl";
   XMLReader reader = XMLReaderFactory.createXMLReader(parserClass);

   WeblogHandler content = new WeblogHandler();
   int numSecs = new Integer(args[0]).intValue();
   content.setNumSecs(numSecs);

   ErrorProcessor errors = new ErrorProcessor(); 

   reader.setContentHandler(content);
   reader.setErrorHandler(errors);
...

Of course, these changes won't mean anything unless you change the WeblogHandler class:

import org.xml.sax.helpers.DefaultHandler;
import org.xml.sax.Attributes;
import org.xml.sax.SAXException;

public class WeblogHandler extends DefaultHandler
{
 public WeblogHandler ()
 { super(); }

 //-------------
 //UTILITY METHODS
 //-------------
 int numSecs = 0;
 public void setNumSecs(int arg) {
      numSecs = arg;
 }

 //-------------
 //EVENT METHODS
 //-------------
 int numLogs = 0;
 public void startElement (String namespaceUri, String localName,
                           String qualifiedName, Attributes attributes)
                        throws SAXException {

  if (localName.equals("weblog")) {
   String logName = attributes.getValue("name");
   String logURL = attributes.getValue("url");

    int secsAgo = new Integer(attributes.getValue("when")).intValue();
                
   if (secsAgo > numSecs) {
    throw new SAXException("\nLimit reached after "+numLogs+" entries.");
   } else {
       numLogs = numLogs + 1;
       System.out.println(numLogs + ") " + logName + 
                             " updated " + secsAgo + " seconds ago.");
        }
    }
 }

 public void endDocument(){
      System.out.println();
      System.out.println("All recorded logs displayed.");
      System.out.println("More may have been updated within"
                            + " the appropriate timeframe.");
 }

}

First, add the setNumSecs() method for the argument. Next, retrieve the when attribute as an int rather than as a String. Fortunately, changes.xml is sorted based on the when attribute, so all you have to do is compare the current secsAgo to numSecs; if secsAgo exceeds numSecs, you want to stop parsing.

In order to stop parsing, you throw a new SAXException, creating it with a message that includes the number of logs processed so far. So what happens when you run it?

Back to top

Running the new application

Now, if you run the new application with an argument of, say, five minutes (for example, using java MainSaxApp 300) you can see the difference, as shown in Figure 2.

So what is actually happening here? You entered an argument of 300 seconds, so when the first weblog that was updated more than 300 seconds ago is reached, the startElement() method throws the SAXException. Because there's no try-catch block to catch that exception, startElement() throws it to the calling environment, which is the reader's parse() method called in MainSaxApp. There's nothing to catch it there either, so it goes to the MainSaxApp's main() method, where that try-catch block outputs the passed message.

The main point is this: Because the application threw the exception, the parser stopped -- as evidenced by the fact that the endDocument() method was never executed -- but you still had all of the information it had already encountered.

Back to top

Next steps

This tip demonstrates a simple application that includes a SAX parser that stops when it encounters a particular condition. Here, you have simply used a generic SAXException, but there's nothing to stop you from creating your own exceptions for different business conditions and building their use into your logic. (You'd also want to perform a lot more error checking when using the command-line argument!)

Back to top

Download

Information about download methods

Resources

• Download the source files for this tip.
  
  
• Get more information on the Simple API for XML (SAX).
  
  
• Read the developerWorks Understanding SAX tutorial (developerWorks, September 2001).
  
  
• Find more XML resources on the developerWorks XML zone.
  
  
• IBM trial software: Build your next development project with trial software available for download directly from developerWorks.
  
  
• Find out how you can become an IBM Certified Developer in XML and related technologies.
  
  
• Want us to send you useful XML tips like this every week? Sign up for the developerWorks XML Tips newsletter.
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• How a SAX parser works
• The handlers
• Running the application
• Stopping the parser
• Running the new application
• Next steps
• Download
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

My developerWorks community

Dig deeper into XML on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers