The Java API for XML Parsing (JAXP)

As stated earlier, there are two common ways for a computer program to ingest and use an XML document: either as a stream of SAX events or as a Document Object Model (DOM). There are many implementations of these two de facto standards available from numerous vendors; however, there was no way to write code that would work with all vendors'implementa tions in a plug-and-play manner until now. That is the problem that the Java Community process set out to solve with the Java API for XML Parsing. The package javax.xml defines two Factory and Wrapper class combinations—one for SAX Parsers and one for Document (Object Model) Builders. The following are the four classes in the javax.xml.parser:

• SAXParserFactory An abstract class whose subclasses represent specific implementations capable of instantiating a compliant SAX Parser. An example of using this class is presented later in this section.

• SAXParser A convenience wrapper class that represents a SAX Parser. This class adds some overloaded parse() methods that parse common Java IO objects like java.io.File and java.io.InputStream.

• DocumentBuilderFactory An abstract class whose subclasses represent specific implementations capable of instantiating a compliant Document Builder (another name for a parser capable of producing an org.w3c.dom.Document object). An example of using this class is presented later in this section.

• DocumentBuilder A convenience wrapper class that represents a Document Builder parser. There are several overloaded parse() methods that all produce an org.w3c.dom.Document object. Additionally, there is a method to obtain a new Document object for creating in-memory representations from scratch.

Next we will examine an example using a SAXParserFactory object.

The SAX Parser Factory

The SAX Parser Factory is an abstract class designed to allow you to access a SAX Parser implementation and check or set certain facilities of the implementation. The SAXParseFactory comes with a default implementation (com.sun.xml.parser.*) that can be overridden by setting the System property javax.xml.parsers.SAXParserFactory with the name of a class that is a concrete subclass of SAXParserFactory.

The Java API for XML parsing is extremely simple and consistent. Listing 2.16 is a rewrite of Listing 2.3 (SaxTester.java) that uses a SAXParserFactory instead. The class TestHandler has been separated out and repackaged as the public class EchoHandler (the code is identical to the class TestHandler in Listing 2.3, so it is not repeated here).

Code Listing 2.16. Example of the SAX Parser Factory

/* SaxFactoryExample.java */
package sams.chp2;

import javax.xml.parsers.*;
import java.io.*;
public class SAXFactoryExample
{
    public static void main(String args[])
    {
        if (args.length < 1)
        {
            System.out.println("USAGE: java sams.chp2.SAXFactoryExample xmlfile");
System.exit(1);
        }

        try
        {
            SAXParserFactory factory = SAXParserFactory.newInstance();
            SAXParser sp = factory.newSAXParser();
            sp.parse(new File(args[0]), new EchoHandler());                   
        } catch (Throwable t)
          {
            t.printStackTrace();
          }
    }
}

A run of Listing 2.16 produces the same output as Listing 2.3.

The Document Builder Factory

The Document Builder Factory is an abstract class designed to allow you to access a Document Builder implementation and check or set certain facilities of the implementation. The Document Builder Factory comes with a default implementation (com.sun.xml.tree.*) that can be overridden by setting the System property javax.xml.parsers. DocumentBuilderFactory with the name of a class that is a concrete subclass of DocumentBuilderFactory.

Listing 2.17 demonstrates the use of a DocumentBuilderFactory. We will not elaborate on the Document Object Model in this chapter because it is covered in detail in the next chapter. Listing 2.17 is provided here to provide complete coverage of the Java API for XML Parsing. The usage of the Document Builder Factory follows the same pattern as the SAX Parser Factory. We first obtain an instance of the factory. We then obtain an instance of the builder (or parser). We then build (or parse) some document. To complete the example, Listing 2.17 includes a method to recursively print out the nodes of the document, which is a tree data structure.

Code Listing 2.17. Example of the Document Builder Factory

/* DocumentBuilderFactoryExample.java */
package sams.chp2;

import javax.xml.parsers.*;
import java.io.*;

import org.w3c.dom.*;

public class DocumentBuilderFactoryExample
{
    public static void main(String args[])
    {
        if (args.length < 1)
        {
            System.out.println("USAGE: java sams.chp2.DocumentBuilderFactoryExample xmlfile");
System.exit(1);
        }

        try
        {
            DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = factory.newDocumentBuilder();
            Document doc = builder.parse(new File(args[0]));
            Element root = doc.getDocumentElement();
            root.normalize();
            printNodes(root, System.out);
        } catch (Throwable t)
          {
            t.printStackTrace();
          }
    }
    

    private static void printNodes(Node n, OutputStream out) throws IOException
    {
        if (n == null)
            return;

        out.write(("Node name: " + n.getNodeName() + ", value: " + n.getNodeValue() + "

").getBytes());
NodeList list = n.getChildNodes();
        if (list == null)
            return;
        else
        {
            int len = list.getLength();
            for (int i=0; i < len; i++)
            {
                printNodes(list.item(i), out);
            }
        }
    }
}

When run, Listing 2.17 produces the following output (abridged for brevity):

E:synergysolutionsXml-in-Javasamschp2>java sams.chp2.DocumentBuilderFactoryExample
 myaddresses.xml

Node name: ADDRESS_BOOK, value: null
Node name: #text, value:
Node name: ADDRESS, value: null
Node name: #text, value:
Node name: NAME, value: null
Node name: #text, value: Michael Daconta
Node name: #text, value:
Node name: STREET, value: null
Node name: #text, value: 4296 Razor Hill Road
Node name: #text, value:
Node name: CITY, value: null
Node name: #text, value: Bealeton
Node name: #text, value:
Node name: STATE, value: null
Node name: #text, value: VA
Node name: #text, value:
Node name: ZIP, value: null
Node name: #text, value: 22712

So, as demonstrated in this section, the Java API for XML parsing provides the key standardized bootstrapping mechanisms for a plug-and-play parsing architecture. Java developers now have simple, standard access to both a DOM or SAX event stream.