Java SAX DefaultHandler

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 thecharacters() 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 {
}

Java SAX DefaultHandler

 
By Jakob Jenkov

 Connect with me: 

Rate article:

Share article:

Tweet

Table of Contents

• Processing Instructions
• Exceptions
• Additional Methods

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 DefaultHandlersubclass, 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 thecharacters() 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 &notLegal;). The SAXParser will then call thefatalError() 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.