XML Reference Guide

The Document Object Model Level 3 Load and Save Recommendation has two main features that don't exist in earlier versions of the DOM:

• The ability to easily create a parser and load a document
• The ability to easily create a writer and output a document

That doesn't sound like much, but it does come with a whole host of other goodies, such as the ability to filter the data as it goes by, control validation, and handle events and errors. So let's take a look at just how this works.

The general idea is that in the earlier versions of the Document Object Model, everything was defined as an interface, and the actual creation of a parser (or a Document for that matter) was left up to the implementer. That led to a mess of jumbled bindings. DOM Level 3 Load and Save creates a standard way to create a parser (and an outputter), and throws in a great deal of control, to boot. Let's start by creating a parser.

import org.w3c.dom.bootstrap.DOMImplementationRegistry;
import org.w3c.dom.DOMImplementationList;
import org.w3c.dom.ls.DOMImplementationLS;
import org.w3c.dom.ls.LSParser;
import org.w3c.dom.Document;

public class Level3Dom {

   public static void main (String args[]){

      try {
        System.setProperty(DOMImplementationRegistry.PROPERTY,
             "org.apache.xerces.dom.DOMImplementationSourceImpl");
        DOMImplementationRegistry registry = 
             DOMImplementationRegistry.newInstance();
        DOMImplementationLS impl = 
            (DOMImplementationLS)registry.getDOMImplementation("LS");

        LSParser builder = impl.createLSParser(
                         DOMImplementationLS.MODE_SYNCHRONOUS, null);

        Document document = builder.parseURI("http://www.nicholaschase.com/personal.xml");

      } catch (Exception e){
        System.out.println(e.toString());
      }
   }
}

Now, the first part of this class is the creation of a DOM implementation; this new DOMImplementationRegistry is part of the DOM Level 3 Core, but for now understand that it enables you to choose a DOMImplementation with particular features and characteristics. In this case, we're choosing an implementation that supports the LS feature.

Next, we're using the DOMImplementationLS to create the a synchronous parser -- in other words, it waits until it's done parsing before allowing the application to move on -- and, finally, parsing the data to create a Document object. Note that we have three choices for parsing the data:

• parse(LSInput input): This method takes an LSInput as an argument. An LSInput can represent a public identifier, a system identifier (such as a file name), a byte stream, a URL, or a character stream.
• parseURI(String url): This method takes a relative or absolute URL -- well, to be strictly accurate, a URI -- and parses the information at that location.
• parseWithContext(LSInput input, Node context, short action): This method actually enables you to parse one document into another. Depending on the value of the action parameter, the new data may follow, preceed, or even replace existing data.

One of the advantages of using this method of parsing is the ability to control aspects of the parse. For example, you can specify that the document should be validated based on a schema:

...
public class Level3Dom {

   public static void main (String args[]){

      try {
        System.setProperty(DOMImplementationRegistry.PROPERTY,
             "org.apache.xerces.dom.DOMImplementationSourceImpl");
        DOMImplementationRegistry registry = 
             DOMImplementationRegistry.newInstance();
        DOMImplementationLS impl = 
            (DOMImplementationLS)registry.getDOMImplementation("LS");

        LSParser builder = impl.createLSParser(
                         DOMImplementationLS.MODE_SYNCHRONOUS, null);

        DOMConfiguration config = builder.getDomConfig();
        config.setParameter("validate", Boolean.TRUE);
        config.setParameter("schema-type", "http://www.w3.org/2001/XMLSchema");
        config.setParameter("schema-location",
                         "http://www.nicholaschase.com/informit/personal.xsd");

        Document document = builder.parseURI("http://www.nicholaschase.com/personal.xml");

      } catch (Exception e){
        System.out.println(e.toString());
      }
   }
}

The DOMConfiguration object is part of the Core, but for now understand that it enables you to set parameters such as whether or not to include comments, normalize namespaces, and so on. You can apply it to a Document, but the DOMConfiguration you create for the LSParser doesn't carry over to the actual Document object the parser creates.

You can also filter the data that gets passed through, in a manner similar to the one that first appeared in the DOM Level 2 Traversal Recommendation. First you create a filter class:

import org.w3c.dom.ls.LSParserFilter;
import org.w3c.dom.Element;
import org.w3c.dom.Node;
import org.w3c.dom.traversal.NodeFilter;

public class InputFilter implements LSParserFilter{

	public short acceptNode(Node enode) {
        return NodeFilter.FILTER_ACCEPT;
	}

	public int getWhatToShow() {
		return NodeFilter.SHOW_ELEMENT;
	}

	public short startElement(Element elt) {
		return LSParserFilter.FILTER_ACCEPT;
	}

}

This filter passes everything through, but you can create your own custom filter that determines what information should and should not be part of your document. You can also use the filter to change the data as it goes by. Once you've created your filter, you can add it to the parser:

...
import org.w3c.dom.DOMConfiguration;
import org.w3c.dom.ls.LSParserFilter;

public class Level3Dom {

   public static void main (String args[]){

      try {
...
        LSParser builder = impl.createLSParser(
                         DOMImplementationLS.MODE_SYNCHRONOUS, null);

        DOMConfiguration config = builder.getDomConfig();
        config.setParameter("validate", Boolean.TRUE);
        config.setParameter("schema-type", "http://www.w3.org/2001/XMLSchema");
        config.setParameter("schema-location",
                         "http://www.nicholaschase.com/informit/personal.xsd");

        LSParserFilter filter = new InputFilter();
        builder.setFilter(filter);

        Document document = builder.parseURI("http://www.nicholaschase.com/personal.xml");

      } catch (Exception e){
        System.out.println(e.toString());
      }
   }
}

You can use a similar method to add an error handler to the parser. First, create the error handler:

import org.w3c.dom.DOMErrorHandler;
import org.w3c.dom.DOMError;

public class HandleErrors implements DOMErrorHandler {

    public boolean handleError(DOMError error){
        short severity = error.getSeverity();
        if (severity == error.SEVERITY_ERROR) {
            System.out.println("[our-dom3-error]: "+error.getMessage());
        }

        if (severity == error.SEVERITY_WARNING) {
            System.out.println("[our-dom3-warning]: "+error.getMessage());
        }
        return true;
    }

}

This class, borrowed slightly from the Xerces samples, simply outputs the message, along with some idea of the severity. Adding it to the parser is strightforward, using the DOMConfiguration:

...
public class Level3Dom {

   public static void main (String args[]){

      try {
...
        LSParser builder = impl.createLSParser(
                         DOMImplementationLS.MODE_SYNCHRONOUS, null);

        DOMConfiguration config = builder.getDomConfig();
...

        config.setParameter("error-handler", new HandleErrors());

        Document document = builder.parseURI("http://www.nicholaschase.com/personal.xml");

      } catch (Exception e){
        System.out.println(e.toString());
      }
   }
}

OK, so what about output? Output follows the same general mode as input. For example, we can write the document out to a file:

...
import org.w3c.dom.ls.LSSerializer;
import org.w3c.dom.ls.LSOutput;

public class Level3Dom {

   public static void main (String args[]){

      try {
...
        Document document = builder.parseURI("http://www.nicholaschase.com/personal.xml");

        LSSerializer writer = impl.createLSSerializer();
        LSOutput output = impl.createLSOutput();
        output.setSystemId("file:///personalout.xml");

        writer.write(document, output);
 
      } catch (Exception e){
        System.out.println(e.toString());
      }
   }
}

You create the output, specify where the data should go, and then feed the Document (or any Node, actually) to the LSSerializer with that output, and it's done. Note that here you also have three options:

• write(Document document, LSOutput output): This method sends the data to the specified location, be it a URL (or URI) or character or byte stream.
• writeToString(Node node): Perhaps the most eagerly awaited new fuction, this method simply serializes a Node to a string, a function that should have been trivially easy from the start, but wasn't.
• writeToURI(String uri): This method simply outputs the XML to a specified location. It's a convenience method that is the same as using write() to send the data to an LSOutput that has the systemId property set.

Note that you can use filters and error handlers when you output the data just as you can when you input it. For example, you can specify that you don't want to pass on any comments:

...
public class Level3Dom {

   public static void main (String args[]){

      try {
...
        Document document = builder.parseURI("http://www.nicholaschase.com/personal.xml");

        LSSerializer writer = impl.createLSSerializer();
        LSOutput output = impl.createLSOutput();
        output.setSystemId("file:///personalout.xml");

        config = writer.getDomConfig();
        config.setParameter("comments", Boolean.FALSE);

        writer.write(document, output);
 
      } catch (Exception e){
        System.out.println(e.toString());
      }
   }
}

Overall, while it might take a little bit of getting used to, DOM Level 3 Load and Save makes it simpler and easier to load and serielize data.