Title: XML in Applications II DOM - the Document Object Model

After a few drafts, the DOM Level 1 Specification became a W3C recommendation in October 1998. So what does the "Level 1" bit mean? The DOM working group plan to release their work in stages. Level one concentrates on the actual core, HTML, and XML document models. It contains functionality for document navigation and manipulation.

Level two will include a style sheet object model, and define functionality for manipulating the style information attached to a document. It will also allow rich queries of the document and define some event models, and provide support for XML namespaces.

Further levels will specify some interface with the possibly underlying window system, including some ways to prompt the user. They will also contain functions to manipulate the document's DTD. Finally, they will include some security models.

On 23 September 1999, the working group released the first version of the working draft of the level 2 specification.

I originally designed DOMManager to be a super class for DOM manipulating classes to inherit from. After consideration, I've realised that it is more useful to have your class to implement DOMManager as a private member variable, and delegate calls to it. This changes the nature of DOMManager from being a behaviour "template" to being a helper object. I can identify two very good reasons to make this change of viewpoint:

We don't mix the loading/saving interface into our property management interface.

Delegating to our member variable allows our class to manage the lifetime of the DOM. This would allow us to implement alternative memory management policies such as lazy evaluation or saving on a separate thread behind the scenes.

A very simple Property manager class that echoes the document back to the standard output has its relevant functionality shown here.

import java.io.*;
public class PropertiesViewer {
  private DOMManager settings;
  private Document doc;
  private String inFile;
  ...
  public void printToSystemOut()
  {
    try
    {
      doc = settings.loadDocument(inFile);  // inherited
// change our output to be the System.out
      settings.setOutputTarget(new PrintWriter(System.out));
      settings.saveDocument(doc);             // inherited
    }
    catch (IOException ioe)
    {
      System.out.println("I/O Problem with " + inFile);
    }
  }
}

Now that we have a basic framework in place for loading / saving our XML documents, we can proceed to a less trivial example. Consider an application that has the following property file:

<?xml version="1.0"?>
<domapp>
    <display>
        <default_scheme>normal</default_scheme>
        <scheme name="normal">
            <normal>black</normal>
            <error>red</error>
            <background>white</background>
            <highlight>blue</highlight>
            <highlight_background>green</highlight_background>
        </scheme>
        <scheme name="weird">
            <normal>yellow</normal>
            <error>red</error>
            <background>black</background>
            <highlight>purple</highlight>
            <highlight_background>grey</highlight_background>
        </scheme>
    </display>
</domapp>

Our application wants to encapsulate the properties as a Java object. As an example of showing how to edit the DOM, we will change the highlight_background of the "normal" scheme from green to yellow.

First, we create our DomAppProperties class.

package org.accu.cornish.xml.dom;
import org.accu.cornish.xml.*;
import org.w3c.dom.*;
import java.io.*;
import java.util.Vector;

public class DomAppProperties {
    private String propertiesFile = "D:\\xml\\domapp.properties";
    private DOMManager domManager;
    private Document doc;

    public DomAppProperties()
    {
        domManager = new DOMManager();
    }
    public void load()   { … }
    public void save()  { … }

    public boolean changeDisplaySchemeValue(String scheme,String name,String value)
    {
        if (doc == null)
        {
            System.err.println("Error:  no document node");
            return false;
        }
        try
        {
            Node schemeNode = this.getDisplaySchemeNode(scheme);
            Node node = this.findElement(schemeNode, name);
            this.setElementValue(node, value);
        }
        catch (BadXMLException bXML)
        {
            System.err.println(bXML.message());
        }
        return true;
    }

    private Node getRootElementNode() throws BadXMLException
    {
// start at the document node
// get the root element <domapp>
        Node node = doc.getDocumentElement();
        if ( !node.getNodeName().equals("domapp") )
        {
            throw new BadXMLException("Unexpected root node <"
                                    + node.getNodeName()
                                    + ">, was expecting <domapp>");
        }
        return node;
    }

    private Node getDisplayNode(Node rootElementNode) throws BadXMLException
    {
        Node node = null;
// verified node = <domapp>
// get the child element <display>
        NodeList children = rootElementNode.getChildNodes();
        for (int i = 0; i < children.getLength(); ++i)
        {
            if (children.item(i).getNodeName().equals("display"))
            {
                node = children.item(i);
            }
        }
        if (! node.getNodeName().equals("display") )
        {
            throw new BadXMLException("Unexpected structure, was expecting "
                            + "<display> after <domapp>");
        }
        return node;
    }

    private Node getDisplaySchemeNode(String schemeName) throws BadXMLException
    {
        Node node = getDisplayNode( getRootElementNode() );

// verified node = <display>
// get the children - can be <default_scheme> or <scheme>
        boolean bFound = false;
        NodeList children = node.getChildNodes();
        for (int i = 0; i < children.getLength() && !bFound; ++i)
        {
            if (children.item(i).getNodeName().equals("scheme"))
            {
// we are in a <scheme> node - is it the right one?
//
// it's the one with with name attribute equal to the schemeName passed into this method
                NamedNodeMap attrs = children.item(i).getAttributes();
                Node attNode = null;

                if ( (attNode = attrs.getNamedItem("name")) == null)
                {
                    throw new BadXMLException("<scheme> node has no name attribute");
                }
                else
                {
// we're in the <scheme name=" node - check the value

                    if (attNode.getNodeValue().equals(schemeName))
                    {
                        // BINGO!
                        bFound = true;
                        node = children.item(i);
                    }
                }
            }   //if scheme
        }   // children of <display>
        children = null;
        if (! bFound )
        {
            throw new BadXMLException("Cannot find <scheme name=\""
                                        + schemeName + "\">");
        }
// return the node
        return node;
    }

    private Node findElement(Node node, String name)
    {
        Node returnNode = null;

        if (node.getNodeType() == Node.ELEMENT_NODE)
        {
            if (node.getNodeName().equals(name))
            {
                returnNode = node;
            }
            else
            {
// go through all the children

                NodeList children = node.getChildNodes();
                if (children != null)
                {
                    int len = children.getLength();
                    Node tempNode;

                    found: for (int i = 0; i < len; ++i)
                    {
                        returnNode = findElement(children.item(i), name);
                        if (returnNode != null)
                        {
                            break found;  // from this for loop
                        }
                    }
                }
            }
        }
        return returnNode;
    }
    private void setElementValue(Node element, String newValue) {
        NodeList children = element.getChildNodes();
        if (children != null)
        {
            int len = children.getLength();
            for (int i = 0; i < len; ++i)
            {
                if (children.item(i).getNodeType() == Node.TEXT_NODE)
                {
                    children.item(i).setNodeValue(newValue);
                }
            }
        }
    }
}

First note that there is no parser specific code in this class - this is because we've hidden it all away in the DomManager class. The load() and save() methods are trivial enough not to detail them. The important public method is the ChangeDisplaySchemeValue(scheme, element, value) method. This method performs three distinct tasks (each as private methods - highlighted in bold). First it finds the appropriate <scheme> node (recall that our XML file can contain more than one scheme). Next, the correct element in the scheme is identified. Finally, the new value is set.

The private methods of the class give some useful examples of processing with the DOM tree. Note that because I'm using elements and values (tags and text) in my XML to represent the settings, this shapes the setElementValue() method. If I had used tags with attributes, this method would need to be implemented differently.

Now we need a harness to show the DomAppProperties in action. For convenience, I'll define a main method on the class.

    public static void main(String[] args)
    {
        DomAppProperties editor = new DomAppProperties();
        editor.load();
        editor.changeDisplaySchemeValue("normal", "highlight_background", "yellow");
        editor.changeDisplaySchemeValue("weird", "normal", "orange");
        editor.save();
    }

This is all we need to make our changes.

Of course, the DomAppProperties is a class of dubious usefulness - it doesn't even have methods to report existing values. I hope it fulfills its intended purpose - to demonstrate how to use DOM and DOM compliant parsers to manipulate XML documents.

DOM provides quite a rich API for manipulating documents. Most users would likely wrap it with an interface more useful to the task at hand (e.g. property files). DOM parsers are best suited to processing XML documents that need to be read (possibly more than once) and may be subject to a non-trivial amount of manipulation. DOM is definitely suited to recreating the XML document at a later time. As you may recall from the previous article, SAX is better suited to read-once, process immediately usage.