Adding Additional Event Handlers - The J2EE 1.4 Tutorial

Adding Additional Event Handlers

In addition to ignorableWhitespace, there are two other ContentHandler methods that can find uses in even simple applications: setDocumentLocator and processingInstruction. In this section, you'll implement those two event handlers.

Identifying the Document's Location

A locator is an object that contains the information necessary to find a document. The Locator class encapsulates a system ID (URL) or a public identifier (URN) or both. You would need that information if you wanted to find something relative to the current document--in the same way, for example, that an HTML browser processes an href="anotherFile" attribute in an anchor tag. The browser uses the location of the current document to find anotherFile.

You could also use the locator to print good diagnostic messages. In addition to the document's location and public identifier, the locator contains methods that give the column and line number of the most recently processed event. The setDocumentLocator method, however, is called only once: at the beginning of the parse. To get the current line or column number, you would save the locator when setDocumentLocator is invoked and then use it in the other event-handling methods.

Note: The code discussed in this section is in Echo04.java. Its output is in Echo04-01.txt. (The browsable version is Echo04-01.html.)

Start by removing the extra character-echoing code you added for the last example:
public void characters(char buf[], int offset, int len)
throws SAXException
{
  if (textBuffer != null) {
    echoText();
    textBuffer = null;
  }
  String s = new String(buf, offset, len);
  ...
} 
Next, add the following highlighted method to the Echo program to get the document locator and use it to echo the document's system ID.
...
private String indentString = "    "; // Amount to indent
private int indentLevel = 0; 
public void setDocumentLocator(Locator l)
{
  try {
    out.write("LOCATOR");
    out.write("SYS ID: " + l.getSystemId() );
    out.flush();
  } catch (IOException e) {
    // Ignore errors
  }
} 
public void startDocument()
... 
Notes:

This method, in contrast to every other ContentHandler method, does not return a SAXException. So rather than use emit for output, this code writes directly to System.out. (This method is generally expected to simply save the Locator for later use rather than do the kind of processing that generates an exception, as here.)

The spelling of these methods is Id, not ID. So you have getSystemId and getPublicId.

When you compile and run the program on slideSample01.xml, here is the significant part of the output:
LOCATOR
SYS ID: file:<path>/../samples/slideSample01.xml 
START DOCUMENT
<?xml version='1.0' encoding='UTF-8'?>
... 
Here, it is apparent that setDocumentLocator is called before startDocument. That can make a difference if you do any initialization in the event-handling code.

Handling Processing Instructions

It sometimes makes sense to code application-specific processing instructions in the XML data. In this exercise, you'll modify the Echo program to display a processing instruction contained in slideSample02.xml.

Note: The code discussed in this section is in Echo05.java. The file it operates on is slideSample02.xml, as described in Writing Processing Instructions . The output is in Echo05-02.txt. (The browsable versions are slideSample02-xml.html and Echo05-02.html.)

As you saw in Writing Processing Instructions, the format for a processing instruction is <?target data?>, where target is the application that is expected to do the processing, and data is the instruction or information for it to process. The sample file slideSample02.xml contains a processing instruction for a mythical slide presentation program that queries the user to find out which slides to display (technical, executive-level, or all):
<slideshow 
  ...
  >

  
  <?my.presentation.Program QUERY="exec, tech, all"?>

   
To display that processing instruction, add the following highlighted code to the Echo application:
public void characters(char buf[], int offset, int len)
...
} 
public void processingInstruction(String target, String data)
throws SAXException
{
  nl(); 
  emit("PROCESS: ");
  emit("<?"+target+" "+data+"?>");
} 
private void echoText()
... 
When your edits are complete, compile and run the program. The relevant part of the output should look like this:
ELEMENT: <slideshow
  ...
>
PROCESS: <?my.presentation.Program QUERY="exec, tech, all"?>
CHARS: 
... 
Summary

With the minor exception of ignorableWhitespace, you have used most of the ContentHandler methods that you need to handle the most commonly useful SAX events. You'll see ignorableWhitespace a little later. Next, though, you'll get deeper insight into how you handle errors in the SAX parsing process.