Using the org.jdom.input.SAXBuilder class to create a JDOM document from an existing XML input source is fairly simple. The SAXBuilder constructor can take in two optional parameters: the name of the SAX parser class to use (which should implement org.xml.sax.XMLReader), and a flag indicating whether validation should occur. If neither is supplied, the default parser is used (currently Apache Xerces), and validation does not occur. We can create a simple SAXTest class to allow entry of a file on the command line, and then create a JDOM Document object using the SAXBuilder class and the supplied filename:

import java.io.File;

import org.jdom.Document;
import org.jdom.Element;
import org.jdom.JDOMException;
import org.jdom.input.Builder;
import org.jdom.input.SAXBuilder;

public class SAXTest {

    public static void main(String[] args) {
        if (args.length != 1) {
            System.out.println("Usage: SAXTest [filename to parse]");
            return;
        }

        try {
            // Request document building without validation
            Builder builder = new SAXBuilder(false);
            Document doc = builder.build(new File(args[0]));
            System.out.println("Document successfully read");
        } catch (JDOMException e) {
            e.printStackTrace(  );
        }
    }
}

Seems simple, doesn’t it? This is because the SAXBuilder handles the chores of creating the various SAX handler classes, registering those with the XMLReader implementation, and building the JDOM Document. This is similar to how many DOM parsers might build a DOM Document object using SAX; however, to keep things simple, JDOM’s SAXBuilder handles all SAXExceptions and converts them to JDOMExceptions. This isolates the SAX code from your Document building, and JDOM ensures the converted exceptions contain information about the specific problems that occurred in parsing and the line on which they occurred.

The org.jdom.input.DOMBuilder class is almost identical in function to the SAXBuilder class. Like SAXBuilder, it provides a means of producing a JDOM Document, but uses DOM and DOM parsers to accomplish the task. Because DOM does not define a standard parser interface, the org.jdom.adapters package supplies an abstraction level over vendor-specific parsers, providing a standard means of obtaining a DOM Document object. The constructor of a DOMBuilder takes in a flag indicating whether validation should occur, as well as the name of the adapter class to use. This can be any class (including user-defined ones), as long as it implements the DOMAdapter interface defined in org.jdom.adapters.

Once the DOMBuilder has been created, it functions exactly the same as the SAXBuilder. The following example shows how to build a Document using DOM:

import java.io.File;

import org.jdom.Document;
import org.jdom.Element;
import org.jdom.JDOMException;
import org.jdom.input.Builder;
import org.jdom.input.DOMBuilder;

public class DOMTest {

    public static void main(String[] args) {
        if (args.length != 1) {
            System.out.println("Usage: DOMTest [filename to parse]");
            return;
        }

        try {
            // Request document building without validation, using Oracle parser
            Builder builder =
                new DOMBuilder("org.jdom.adapters.OracleV2DOMAdapter");
            Document doc = builder.build(new File(args[0]));
            System.out.println("Document successfully read");
        } catch (JDOMException e) {
            e.printStackTrace(  );
        }
    }
}

This uses the Oracle V2 XML parser to create a DOM tree, and then build a JDOM Document object from that DOM tree. To use the default parser, simply call Builder builder = new DOMBuilder( ).

Once the JDOM Document object has been created, there is no difference in the Document operation and functionality between varying builders.