This document is in the Public Domain.
This document provides a quick-start tutorial for Java programmers who wish to use SAX2 in their programs.
SAX is not an XML parser.
SAX is a common interface implemented for many different XML parsers (and things that pose as XML parsers), just as the JDBC is a common interface implemented for many different relational databases (and things that pose as relational databases). If you want to use SAX, you'll need all of the following:
Java 1.1 or higher.
The SAX2 distribution installed on your Java classpath.
A SAX2-compatible XML parser installed on your Java classpath.
The name of the SAX2 driver class in your XML parser (read the documentation that came with the parser, and write down the class name).
Start by creating a class that extends DefaultHandler:
import org.xml.sax.helpers.DefaultHandler;
public class MySAXApp extends DefaultHandler
{
public MySAXApp ()
{
super();
}
}
Now, let's assume that the SAX driver for your XML parser is named "com.acme.xml.SAXDriver" (this does not really exist: you must find out the name of the real driver for your parser). Since this is a Java application, we'll create a static main method that creates a new instance of this driver (note the "throws Exception" wimp-out):
public static void main (String args[])
throws Exception
{
XMLReader xr = new com.acme.xml.SAXDriver();
}
Alternatively, if you don't want to tie your application to a specific SAX driver, you can use the createXMLReader method from the XMLReaderFactory class to choose a SAX driver dynamically:
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
}
In this case, it will be necessary at runtime to set the org.xml.sax.driver Java system property to the full classname of the SAX driver, as in
java -Dorg.xml.sax.driver=com.acme.xml.SAXDriver MySAXApp sample.xml
We can use this object to parse XML documents, but first, we have to register event handlers that the parser can use for reporting information, using the setContentHandler and setErrorHandler methods from the XMLReader interface. In a real-world application, the handlers will usually be separate objects, but for this simple demo, we've bundled the handlers into the top-level class, so we just have to instantiate the class and register it with the XML reader:
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
MySAXApp handler = new MySAXApp();
xr.setContentHandler(handler);
xr.setErrorHandler(handler);
}
This code creates an instance of MySAXApp to receive XML parsing events, and registers it with the XML reader for regular content events and error events (there are other kinds, but they're rarely used). Now, let's assume that all of the command-line args are file names, and we'll try to parse them one-by-one using the parse method from the XMLReader interface:
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
MySAXApp handler = new MySAXApp();
xr.setContentHandler(handler);
xr.setErrorHandler(handler);
// Parse each file provided on the
// command line.
for (int i = 0; i < args.length; i++) {
FileReader r = new FileReader(args[i]);
xr.parse(new InputSource(r));
}
}
Note that each reader must be wrapped in an InputSource object to be parsed. Here's the whole demo class together (so far):
import java.io.FileReader;
import org.xml.sax.XMLReader;
import org.xml.sax.InputSource;
import org.xml.sax.helpers.XMLReaderFactory;
import org.xml.sax.helpers.DefaultHandler;
public class MySAXApp extends DefaultHandler
{
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
MySAXApp handler = new MySAXApp();
xr.setContentHandler(handler);
xr.setErrorHandler(handler);
// Parse each file provided on the
// command line.
for (int i = 0; i < args.length; i++) {
FileReader r = new FileReader(args[i]);
xr.parse(new InputSource(r));
}
}
public MySAXApp ()
{
super();
}
}
You can compile this code and run it (make sure you specify the SAX driver class in the org.xml.sax.driver property), but nothing much will happen unless the document contains malformed XML, because you have not yet set up your application to handle SAX events.
Things get interesting when you start implementing methods to respond to XML parsing events (remember that we registered our class to receive XML parsing events in the previous section). The most important events are the start and end of the document, the start and end of elements, and character data.
To find out about the start and end of the document, the client application implements the startDocument and endDocument methods:
public void startDocument ()
{
System.out.println("Start document");
}
public void endDocument ()
{
System.out.println("End document");
}
The start/endDocument event handlers take no arguments. When the SAX driver finds the beginning of the document, it will invoke the startDocument method once; when it finds the end, it will invoke the endDocument method once (if there have been errors, endDocument may not be invoked).
These examples simply print a message to standard output, but your application can contain any arbitrary code in these handlers: most commonly, the code will build some kind of an in-memory tree, produce output, populate a database, or extract information from the XML stream.
The SAX driver will signal the start and end of elements in much the same way, except that it will also pass some parameters to the startElement and endElement methods:
public void startElement (String uri, String name,
String qName, Attributes atts)
{
System.out.println("Start element: {" + uri + "}" + name);
}
public void endElement (String uri, String name, String qName)
{
System.out.println("End element: {" + uri + "}" + name);
}
These methods print a message every time an element starts or ends, with the Namespace URI in braces before the element's local name. The qName contains the raw XML 1.0 name, and since not all SAX drivers will report it, it is best to ignore that parameter for now.
Finally, SAX2 reports regular character data through the characters method; the following implementation will print all character data to the screen; it is a little longer because it pretty-prints the output by escaping special characters:
public void characters (char ch[], int start, int length)
{
System.out.print("Characters: \"");
for (int i = start; i < start + length; i++) {
switch (ch[i]) {
case '\\':
System.out.print("\\\\");
break;
case '"':
System.out.print("\\\"");
break;
case '\n':
System.out.print("\\n");
break;
case '\r':
System.out.print("\\r");
break;
case '\t':
System.out.print("\\t");
break;
default:
System.out.print(ch[i]);
break;
}
}
System.out.print("\"\n");
}
Note that a SAX driver is free to chunk the character data any way it wants, so you cannot count on all of the character data content of an element arriving in a single characters event.
Here is the complete sample application (again, in a serious app the event handlers would probably be implemented in a separate class):
import java.io.FileReader;
import org.xml.sax.XMLReader;
import org.xml.sax.Attributes;
import org.xml.sax.InputSource;
import org.xml.sax.helpers.XMLReaderFactory;
import org.xml.sax.helpers.DefaultHandler;
public class MySAXApp extends DefaultHandler
{
public static void main (String args[])
throws Exception
{
XMLReader xr = XMLReaderFactory.createXMLReader();
MySAXApp handler = new MySAXApp();
xr.setContentHandler(handler);
xr.setErrorHandler(handler);
// Parse each file provided on the
// command line.
for (int i = 0; i < args.length; i++) {
FileReader r = new FileReader(args[i]);
xr.parse(new InputSource(r));
}
}
public MySAXApp ()
{
super();
}
////////////////////////////////////////////////////////////////////
// Event handlers.
////////////////////////////////////////////////////////////////////
public void startDocument ()
{
System.out.println("Start document");
}
public void endDocument ()
{
System.out.println("End document");
}
public void startElement (String uri, String name,
String qName, Attributes atts)
{
System.out.println("Start element: {" + uri + "}" + name);
}
public void endElement (String uri, String name, String qName)
{
System.out.println("End element: {" + uri + "}" + name);
}
public void characters (char ch[], int start, int length)
{
System.out.print("Characters: \"");
for (int i = start; i < start + length; i++) {
switch (ch[i]) {
case '\\':
System.out.print("\\\\");
break;
case '"':
System.out.print("\\\"");
break;
case '\n':
System.out.print("\\n");
break;
case '\r':
System.out.print("\\r");
break;
case '\t':
System.out.print("\\t");
break;
default:
System.out.print(ch[i]);
break;
}
}
System.out.print("\"\n");
}
}
Consider the following XML document:
<?xml version="1.0"?> <poem xmlns="http://www.megginson.com/ns/exp/poetry"> <title>Roses are Red</title> <l>Roses are red,</l> <l>Violets are blue;</l> <l>Sugar is sweet,</l> <l>And I love you.</l> </poem>
If this document is named roses.xml and there is a
SAX2 driver on your classpath named
com.acme.xml.SAXDriver (this driver does not actually
exist), you can invoke the sample application like this:
java -Dcom.acme.xml.SAXDriver MySAXApp roses.xml
When you run this, you'll get output something like this:
Start document
Start element: {http://www.megginson.com/ns/exp/poetry}poem
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}title
Characters: "Roses are Red"
End element: {http://www.megginson.com/ns/exp/poetry}title
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "Roses are red,"
End element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "Violets are blue;"
End element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "Sugar is sweet,"
End element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "\n"
Start element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "And I love you."
End element: {http://www.megginson.com/ns/exp/poetry}l
Characters: "\n"
End element: {http://www.megginson.com/ns/exp/poetry}poem
End document
Note that even a short document generates (at least) 25 events: one for the start and end of each of the six elements used (or, if you prefer, one for each start tag and one for each end tag), one of each of the eleven chunks of character data (including whitespace between elements), one for the start of the document, and one for the end.