Java SAX Parser

SAX is an abbreviation and means "Simple API for XML". A Java SAX XML parser is a stream oriented XML parser. It works by iterating over the XML and call certain methods on a "listener" object when it meets certain structural elements of the XML. For instance, it will call the listener object for the following "events":

- startDocument
- startElement
- characters
- comments
- processing instructions
- endElement
- endDocument

This list is probably not complete, but it is long enough to give you an idea of how it works. Let's move on to see how you create and use a Java SAX Parser.

SAXParserFactory factory = SAXParserFactory.newInstance();
try {

    InputStream    xmlInput  = new FileInputStream("theFile.xml");
    SAXParser      saxParser = factory.newSAXParser();

    DefaultHandler handler   = new SaxHandler();
    saxParser.parse(xmlInput, handler);

} catch (Throwable err) {
    err.printStackTrace ();
}

When you call the SAXParser.parse() method the SAX parser starts the XML processing. The xmlInput InputStream passed as parameter to the parse() method is where the XML is read from.Notice the SaxHandler instance being created, and passed as parameter to the parse() method. The SaxHandler class is a subclass of the class org.xml.sax.helpers.DefaultHandler. The DefaultHandler class comes with the JDK.

While processing the XML the SAXParser calls methods in the DefaultHandler subclass (here, the SaxHandler) instance corresponding to what the parser finds in the XML file. To react to those method calls you override the corresponding methods in the DefaultHandler subclass. Here is an example:

public class SaxHandler extends DefaultHandler {

    public void startDocument() throws SAXException {
    }

    public void endDocument() throws SAXException {
    }

    public void startElement(String uri, String localName,
            String qName, Attributes attributes)
    throws SAXException {

    }

    public void endElement(String uri, String localName, String qName)
    throws SAXException {
    }

    public void characters(char ch[], int start, int length)
    throws SAXException {
    }

    public void ignorableWhitespace(char ch[], int start, int length)
    throws SAXException {
    }

}   

It is the responsibility of the DefaultHandler subclass to extract any necessary information from the XML via these methods. If you need to build an object graph based on an XML file, you will have to build that object graph inside the DefaultHandler subclass.

import java.io.FileInputStream;
import java.io.InputStream;

import javax.xml.parsers.SAXParser;
import javax.xml.parsers.SAXParserFactory;

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

public class TestSAXParser {
    public static void test() {
        SAXParserFactory factory = SAXParserFactory.newInstance();
        try {

            InputStream xmlInput = new FileInputStream("theFile.xml");
            SAXParser saxParser = factory.newSAXParser();

            DefaultHandler handler = new SaxHandler();
            saxParser.parse(xmlInput, handler);

        } catch (Throwable err) {
            err.printStackTrace();
        }
    }
    public static void main(String[] args) {
        TestSAXParser.test();
    }
}

class SaxHandler extends DefaultHandler {

    public void startDocument() throws SAXException {
    }

    public void endDocument() throws SAXException {
    }

    public void startElement(String uri, String localName, String qName,
            Attributes attributes) throws SAXException {
        System.out.println(uri + ":" + localName + ":" + qName);        
    }

    public void endElement(String uri, String localName, String qName)
            throws SAXException {
        System.out.println(uri + ":" + localName + ":" + qName);
    }

    public void characters(char ch[], int start, int length)
            throws SAXException {
    }

    public void ignorableWhitespace(char ch[], int start, int length)
            throws SAXException {
    }

}