Download PDF Home History |  | API Search Feedback FAQ

> ## 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
>       ...
>       >

>       <!-- PROCESSING INSTRUCTION -->
>       <?my.presentation.Program QUERY="exec, tech, all"?>

>       <!-- TITLE SLIDE -->

> 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.

Download PDF Home History |  | API Search Feedback FAQ

All of the material in The J2EE(TM) 1.4 Tutorial is copyright-protected and may not be published in other works without express written permission from Sun Microsystems.