ACCU Home page ACCU Conference Page
Search Contact us ACCU at Flickr ACCU at GitHib ACCU at Google+ ACCU at Facebook ACCU at Linked-in ACCU at Twitter Skip Navigation

pinXML in Applications II DOM - the Document Object Model

Overload Journal #36 - Mar 2000 + Design of applications and programs   Author: Steve Cornish

In the first part of this series, I introduced SAX, the Simple API for XML. SAX is an event based API, and is best suited for reading XML once only (our example was a data import). But what if you want to read, alter and save your XML in the course of your application? This is where the DOM fits in. This article will describe DOM, how it came to be and how to use it.

A brief history of DOM

The Document Object Model is a platform- and language-neutral interface that will allow programs and scripts to dynamically access and update the content, structure and style of documents. The document can be further processed and the results of that processing can be incorporated back into the presented page. This is an overview of DOM-related materials here at W3C and around the web.

DOM started life in September 1997 as a W3C (World Wide Web Consortium) requirements publication. From an XML parsing perspective, the most important requirements are:

General

  • The Object Model can be used to construct and deconstruct the document.

  • It must be possible to read in a document and write out a structurally identical document to disk (both documents can be represented by the same raw structural model).

Document Manipulation

  • There will be a way to add, remove and change elements and/or tags (if permitted by the Document Type Definition and not precluded by security or validity considerations) in the document structure.

  • There will be a way to add, remove and change attributes (if permitted by the Document Type Definition and not precluded by security or validity considerations) in the document structure.

  • Operations must restore consistency before they return.

Content Manipulation

  • There will be a way to determine the containing element from any text part of the document.

  • There will be a way to manipulate (add, change, delete) content.

  • There will be a way to navigate content.

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.

org.w3c.dom

Like SAX, DOM is only an interface specification. It is up to vendors to provide implementations of the interfaces. Fortunately, many of the SAX based XML parser implementations also provide a DOM interface. I will be using the XML4J from IBM Alphaworks for the examples in this article.

Access to the DOM is through the Document interface. The Document object represents the root of the document tree. The Document interface contains a number of factory method for creating elements, attributes, comments and processing instructions. The object model is often implied to have a tree structure. Although W3C were very cautious not to use the word tree (in case they were seen to be mandating implementation details), DOM does imply a logical tree structure even if the implementer has chosen a different structure.

All nodes on the document tree implement the Node interface (Document inherits from the Node interface). The Node interface provides for navigation between child, parent and sibling nodes, as well as a direct link to the owning Document object via the getOwnerDocument() method. A Node object can be made to reveal the type of node it represents via the getNodeType() method. The table on the next page provides a mapping from XML terminology to the node types defined on the Node interface.

Each of the node types has a corresponding class type whose interface extends Node. The Node object can be cast to its corresponding type class. For example:

<colgroup> <col> <col></colgroup> <thead> </thead> <tbody> </tbody>
XML entity org.w3c.dom.Node type
Root element DOCUMENT_NODE
Tag / element <..> or </..> ELEMENT_NODE
Element Attributes ATTRIBUTE_NODE
Text CDATA_SECTION_NODE or TEXT_NODE
XML processinginstruction <? … ?> PROCESSING_INSTRUCTION_NODE
Entity references ENTITY_REFERENCE_NODE
public Document getDocument(Node node)
{
  Document doc = null;
  if (node.getType() == Node.DOCUMENT_NODE)
  {
    // if we call getOwnerDocument on the document object it returns null
  doc = (Document) node;
  }
  else
  {
    doc = node.getOwnerDocument();
  }
  return doc;
}

Using DOM to handle XML

As I stated at the beginning of the article, DOM is better suited to read / alter / write XML than SAX is. The example we will be using is that of an application's properties file written in XML.

Since there are numerous XML parsers that support the DOM interfaces, we're going to use IBM Alphaworks' XML4J parser to construct the object model, and write our own code to manipulate and write back our model to XML. Since parsing/loading and saving back XML files is common behaviour for a DOM application, it makes sense to factor that behaviour out to a common class. I've written such a class, called DOMManager:

package org.accu.cornish.xml.dom;

import org.w3c.dom.*;
import com.ibm.xml.dom.*;
import com.ibm.xml.parsers.DOMParser;
import java.io.IOException;
import java.io.PrintWriter;
import org.xml.sax.SAXException;

public class DOMManager
{
  private PrintWriter out = null;

  public DOMManager() {}

  public Document loadDocument(String uri)
    throws IOException
  {
//  this is all the code necessary to get the Document object from the URI
    DOMParser domParser = new DOMParser();
    Document doc;
    try {
      domParser.parse( uri );
      doc = domParser.getDocument(); 
  }
    catch (SAXException badCall) 
    {
// convert it into an IOException
      throw new IOException("Error parsing XML: " + uri);
    }
    return doc;
  }

  public void setOutputTarget(PrintWriter output)
  {
    this.out = output;
  }
  public void saveDocument(Node node) throws java.io.IOException
  {
    if (this.out == null)
    {
      throw new IOException("No target identified for save");
    }
    print( node );
  }
  private void print(Node node) { /* see dom.DOMWriter in the IBM Samples */ }
}

The method print(Node node) was pinched in whole from IBM's sample application DOMWriter, along with helper methods (normalize and sortAttributes). The source code for DOMWriter is available from the installation for XML4J.

Now, to write any application that needs to import and export XML, you can have your Property manager class delegate your Document class management to a DOMManager member.

Inheritance vs. Delegation

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);
    }
  }
}

Editing documents with DOM

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.

Free DOM parsers

There are a number of free XML Parsers that support the DOM Level 1. Here are the main players:

Further References

DOMit is an online utility for checking the validity of your XML files. The idea is you paste your document into the text pane, then hit the button to create a DOM representation of your XML. Very useful http://www.networking.ibm.com/xml/XmlValidatorForm.html

The World Wide Web Consortium DOM site - http://www.w3.org/DOM/

XML-Dev mailing list - and a good XML site from Seybold and O'Reilly - www.xml.com

Another XML site (close links with OASIS) - www.xml.org

Overload Journal #36 - Mar 2000 + Design of applications and programs