Java SAX DefaultHandler
Jakob Jenkov |
The org.xml.sax.helpers.DefaultHandler class is the base class for "listeners" in SAX 2.0.
As shown briefly in the first text on SAX in this tutorial, you create a subclass of DefaultHandler
and override certain inherited methods in this subclass. In this text I will show a very simple
example of a DefaultHandler subclass, which just prints out detail about the XML file.
Here is the code:
public class SaxHandler extends DefaultHandler {
public void startDocument() throws SAXException {
System.out.println("start document : ");
}
public void endDocument() throws SAXException {
System.out.println("end document : ");
}
public void startElement(String uri, String localName,
String qName, Attributes attributes)
throws SAXException {
System.out.println("start element : " + qName);
}
public void endElement(String uri, String localName, String qName)
throws SAXException {
System.out.println("end element : " + qName);
}
public void characters(char ch[], int start, int length)
throws SAXException {
System.out.println("start characters : " +
new String(ch, start, length));
}
}
When you run this code, with this file as input:
<root>
<child>
<grandchild>text 1</grandchild>
</child>
<child>
<grandchild>text 2</grandchild>
</child>
</root>
... you get the following output printed to the System.out:
start document :
start element : root
characters :
start element : child
characters :
start element : grandchild
characters : text 1
end element : grandchild
characters :
end element : child
characters :
start element : child
characters :
start element : grandchild
characters : text 2
end element : grandchild
characters :
end element : child
characters :
end element : root
end document :
This is the sequence in which the SAXParser calls the corresponding
methods in the SaxHandler instance, when processing the XML file shown
above.
You may have noticed that sometimes the characters() method prints out a line break.
This is because the characters() method is called by the SAXParser
with the whitespace characters that are located between the end of the parent element begin
tag, and the child begin tag. In other words, the white space characters marked here using
dots (...):
<root>...
....<child>
</child>
There are also sometimes whitespace characters located after the end of an element end tag, and until the beginning of the next sibling tag, or the beginning of the end tag of the parent element.
Processing Instructions
The DefaultHandler class also has a method for when XML processing
instructions are found in the XML file. Here is how that method looks:
public void processingInstruction(String target, String data)
throws SAXException {
}
You don't very often use processing instructions, so I won't get into more detail about it here. Now that you know it is here, you can play with it yourself.
Exceptions
The DefaultHandler class has three methods you can override to
handle exceptions encountered during the XML parsing. Here they are:
public void warning(SAXParseException e) throws SAXException {
}
public void error(SAXParseException e) throws SAXException {
}
public void fatalError(SAXParseException e) throws SAXException {
}
Let's say that the parser encounters an illegal XML entity (like ¬Legal;).
The SAXParser will then call the fatalError() method, before
breaking the parsing.
If a less dangerous error occurs, the SAXParser may just call the
error() or warning() method. That way you can collect
all the errors in a list, and return them all at once, instead of one by one,
as they are met.
Additional Methods
The DefaultHandler has more methods you can override. Check out
the JavaDoc for more details on those methods.
| Tweet | |
Jakob Jenkov | |
