An Introduction to DOM Parser (with JAXP)

by K. Yue
Created: June 2002
copyright 2002-4

0. Resources

• http://java.sun.com/xml/xml_jaxp.html: Sun's JAXP page.
• http://java.sun.com/xml/jaxp/dist/1.1/docs/tutorial/index.html: Sun's JAXP tutorial; dated.
• http://java.sun.com/webservices/docs/2.0/api/index.html: Sun's Java Web Service Developer (JWSD) pack. JAXP 1.2 is included in JWSD 1.4. JAXP 1.3 included in JWSD 2.0 and J2SE 5.0.
• http://java.sun.com/j2ee/1.4/docs/api/index.html: J2EE 1.4 doc.
• http://java.sun.com/j2se/1.5.0/docs/api/index.html: J2SE 1.5 doc.
• http://www.w3.org/DOM/: W3C DOM page.
• http://www.w3.org/DOM/DOMTR: DOM technical reports at W3C.
• http://www.w3schools.com/dom/default.asp: W3school's DOM page.

1. Introduction

• XML SAX parsers tend to be of lower level and may be difficult to program for some developers.
• An important alternative is the DOM parser, where a DOM tree will be built.
• DOM (Document Object Model) is "a platform- and language-neutral interface that allows programs and scripts to dynamically access and update the content, structure and style of documents." (from W3C specification)
• There are currently three levels of DOM. All of them have reached recommendation status.
  • Level 1:
    • Core: our focus; define basic entities such as Node, Element, Document, etc.
    • HTML: for accessing objects of HTML document; for dynamic HTML, for example.
  • Level 2:
    • Core, Views, Events, Style, Traversal and Range, HTML.
  • Level 3:
    • Core, Load and Save, HTML
• Level 1 Core DOM is designed to be general: platform-neutral, language-neutral and applicable to many document types, including XML and HTML.
• DOM does not define language bindings. It is up to the language to define its binding to DOM, which is largely the language's DOM API.

2. The JAXP DOM API

• To use JAXP DOM parsers to parse XML documents, the basic steps include:
  1. Create a DOM parser (DocumentBuilder obejct) using the newDocumentBuilder() method of a javax.xml.parsers.DomBuilderFactory object.
  2. Parse the XML document using the parse() method of the parser, which returns a Document object, representing the XML tree.
  3. Use DOM API classes and methods for traversing and processing the document tree.

Example:

RootElementName.java: print out the name of the root element of the XML document.

import javax.xml.parsers.*;

import org.xml.sax.SAXException; 
import org.xml.sax.SAXParseException; 

import java.io.*;
import org.w3c.dom.*;

public class RootElementName{
    static Document document;

    public static void main(String argv[])
    {
        if (argv.length != 1) {
            System.err.println("Usage: java RootElementName xmlfilename");
            System.exit(1);
        }

        DocumentBuilderFactory factory =
            DocumentBuilderFactory.newInstance();
        try {
           DocumentBuilder builder = factory.newDocumentBuilder();
           document = builder.parse(new File(argv[0]));
           System.out.println("Root element: " +
              document.getDocumentElement().getTagName() + "\n");
        } catch (Throwable e) {
           e.printStackTrace();
        }
    } // main
}

Try it on:

<?xml version="1.0" encoding="UTF-8"?>
<root a="1" b="2" c="3">
   <!-- Some comments -->
   <?somePi ?>
   <p x="1">
      Hello
      <q />
      <r />
      <s x="1" y="2"><u x="1">ok</u></s>
      Good bye
   </p>
   <p x="1" y="2" z="3" w="4" />
</root>

2.1 The DOM parser

• The class javax.xml.parsers.DocumentBuilderFactory is used to create DOM parser instances.
• DocumentBuilderFactory implementation does not need to guarantee to be thread safe. It may not be reentrant.
• The two most frequently used methods for DocumentBuilderFactory are:
  • static DocumentBuilderFactory newInstance(): create a DocumentBuilderFactory object ; and
  • DocumentBuilder newDocumentBuilder(): create a Document Builder, which is a DOM parser.
• There are six properties for reading and setting:
• For reading:
  • isValidating
  • isCoalescing
  • isIgnoringElementContentWhitespace
  • isExpandEntityReferences
  • isIgnoringComments
  • isNamespaceAware
• For setting:
  • setValidating
  • setCoalescing
  • setIgnoringElementContentWhitespace
  • setExpandEntityReferences
  • setIgnoringComments
  • setNamespaceAware
• Note that the XML parser may select not to coalesce adjacent text.
• The most important methods of DocumentBuilder are the five overloaded parse methods, which parse an XML document from various sources of XML document and build the corresponding DOM tree.
• The newDocument() method can also be used to create an DOM document object.

Example:

Using properties of DocumentBuilderFactory and DocumentBuilder. (This is not a complete program.)

public static void main(String argv[])
{
   if (argv.length < 1) {
      System.err.println("Usage: Java yourprogram xmlfilename");
      System.exit(1);
   }

   try {
      DocumentBuilderFactory factory =
         DocumentBuilderFactory.newInstance();

      // Set builder properties.
      factory.setCoalescing(true);
      factory.setIgnoringElementContentWhitespace(true);

      DocumentBuilder builder = factory.newDocumentBuilder();

      // Set Error Handler
      builder.setErrorHandler(new yourprogram());

      document = builder.parse(new File(argv[0]));
      System.out.println("XML contents ==> \n\n");
      // process the document.
      process(document.getDocumentElement(), 0);
    } catch (Throwable e) {
      e.printStackTrace();
   }
} // main

Example:

To create a DOM parser that is validating:

public class MyProg extends DefaultHandler {
   static Document document;

   public static void main(String argv[]) {
   // ...
   try {
      DocumentBuilderFactory factory =
      DocumentBuilderFactory.newInstance();
      // ...
      // Set builder property.
      factory.setValidating(true);

      DocumentBuilder builder = factory.newDocumentBuilder();
      // Set Error Handler
      builder.setErrorHandler(new MyProg());
      // ...

2.2 Document and DocumentFragment

• The Document interface represents the entire document.
• It is the root of the document tree (not the root element).
• To get the root element, use the method getDocumentElement().
• Document extends the interface Node.
• Therefore, it inherits all methods of Node.
• It has methods to find elements similar to the Element interface. Examples:
  • Element getElementById(java.lang.String elementId)
  • NodeList getElementsByTagName(java.lang.String tagname)
  • NodeList getElementsByTagNameNS(java.lang.String namespaceURI, java.lang.String localName)
• It also has a set of methods for creating nodes of different types, such as Element, Attr, Comment, etc.

DocumentFragment

• DocumentFragment is a lightweight object similar to Document.
• However, DocumentFragment is not required to be completely well-formed.
• It is used to hold subtrees for temporary manipulation.
• When a DocumentFragement node is inserted into another node, its children, not the DocumentFragment node itself, will be inserted.

Example:

Running

DocumentRoot.java: display the children of the document root.

import javax.xml.parsers.*;

import org.xml.sax.*; 
import org.xml.sax.helpers.*; 

import java.io.*;
import org.w3c.dom.*;

public class DocumentRoot extends DefaultHandler {
   static Document document;

   public static void main(String argv[])
   {
      if (argv.length != 1) {
         System.err.println("Usage: Java DocumentRoot xmlfilename");
         System.exit(1);
      }

      try {
           DocumentBuilderFactory factory =
              DocumentBuilderFactory.newInstance();

         DocumentBuilder builder = factory.newDocumentBuilder();

         //   Set Error Handler
         builder.setErrorHandler(new DocumentRoot());
           document = builder.parse(new File(argv[0]));
         System.out.println("Number of children of the document root ==> " +
            document.getChildNodes().getLength());

         NodeList nodes = document.getChildNodes();
         for (int i=0; i<nodes.getLength() ; i++)
         {   System.out.println("Child " + i + " type " + nodes.item(i).getNodeType() + " => " + nodes.item(i));
         }
       } catch (Throwable e) {

        e.printStackTrace();
      }
   } // main
}

on

<?xml version="1.0"?>
<!DOCTYPE familytree SYSTEM "ft.dtd">
<!-- This xml has comments and pi before root node. -->
<?br ?>

<familytree>
<!-- other contents -->
</familytree>

gives:

Number of children of the document root ==> 4
Child 0 type 10 => [familytree: null]
Child 1 type 8 => [#comment: This xml has comments and pi before root node. ]
Child 2 type 7 => [br: ]
Child 3 type 1 => [familytree: null]

2.3 The Node Interface

• The Node interface is the primary interface of DOM datatype.
• The short constants are used to indicate the type of Node:
  • ATTRIBUTE_NODE
  • CDATA_SECTION_NODE
  • COMMENT_NODE
  • DOCUMENT_FRAGMENT_NODE
  • DOCUMENT_NODE
  • DOCUMENT_TYPE_NODE
  • ELEMENT_NODE
  • ENTITY_NODE
  • ENTITY_REFERENCE_NODE
  • NOTATION_NODE
  • PROCESSING_INSTRUCTION_NODE
  • TEXT_NODE
• The method getNodeType() gets the type of the node.
  

Example:

short nodeType = node.getNodeType();
if (nodeType == Node.ELEMENT_NODE) {
   // ...

• There are many methods provided by the interface Node.
• As an example, the following methods are for manipulating child nodes:
  • Node appendChild(Node newChild)
  • NodeList getChildNodes()
  • Node getFirstChild()
  • boolean hasChildNodes()
  • Node insertBefore(Node newChild, Node refChild)
  • Node removeChild(Node oldChild)
  • Node replaceChild(Node newChild, Node oldChild)
• The NodeList interface represents a list of nodes and has two methods:
  • int getLength(): the number of nodes in the list.
  • Node item(int index): the node at the position index (start from 0).
    
• As another example, to get all attributes of a node, use:
  • NamedNodeMap getAttributes().
• The NamedNodeMap is similar to the NodeList interface, except that it is a map, meaning that an item can be retrieved and manipulated by names. For example:
  • Node getNamedItem(java.lang.String name)
  • Node removeNamedItem(java.lang.String name)
  • Node setNamedItem(Node arg)

Example

Use Document and DocumentFragment to create a DOM document.

import javax.xml.parsers.*;

import org.xml.sax.*; 
import org.xml.sax.helpers.*; 

import java.io.*;
import org.w3c.dom.*;

public class DocumentFragmentTest extends DefaultHandler {
    static Document document;

    public static void main(String argv[])
    {
        try {
           DocumentBuilderFactory factory =
              DocumentBuilderFactory.newInstance();

         //   Set builder property.
         factory.setValidating(true);
         factory.setCoalescing(true);
         factory.setIgnoringElementContentWhitespace(true);

         DocumentBuilder builder = factory.newDocumentBuilder();

         //   Set Error Handler
           document = builder.newDocument();
         DocumentFragment df = document.createDocumentFragment();
         Element root = document.createElement("examples");
         for (int i=0; i<5; i++)
         {   Element node = document.createElement("exam");
            Text text = document.createTextNode("quotation #" + (i+1));
            node.appendChild(text);
            df.appendChild(node);
         }
           root.appendChild(df);
         document.appendChild(root);
         //  print contents
         printNode(document, 0);

      } catch (Throwable e) {
           //
           e.printStackTrace();
        }
    } // main

   // print the content of a node.
   private static void printNode(Node node, int level)
   {   short nodeType = node.getNodeType();
      if (nodeType == Node.ELEMENT_NODE)
      {   int i;
         printSpaces(level * 3);
         System.out.print("ELement: " + ((Element) node).getTagName() + "\n");

         NamedNodeMap attributes = node.getAttributes();
         int numAttributes = attributes.getLength();
         for (i=0; i<numAttributes; i++)
         {
            printSpaces((level+1) * 3);
            Attr attr = (Attr) attributes.item(i);
            System.out.println("Attribute: " + attr.getName() + ": " + attr.getValue());
         }  

         NodeList childNodes = node.getChildNodes();
         int numChildNodes = childNodes.getLength();
         for (i=0; i< numChildNodes; i++)
         {  
            printNode(childNodes.item(i), level+1);
         }
      }
      else if (nodeType == Node.TEXT_NODE || nodeType == Node.CDATA_SECTION_NODE || nodeType == Node.COMMENT_NODE)
      {   printSpaces(level * 3);
         String data = ((CharacterData) node).getData();
         System.out.print((nodeType == Node.TEXT_NODE) ? "text" : ((nodeType == node.CDATA_SECTION_NODE) ? "cdata" : "comment"));
         System.out.println("(" + data.length() + "): \"" + data + "\"");
      }
      else if (nodeType == Node.PROCESSING_INSTRUCTION_NODE)
      {   printSpaces(level * 3);
         System.out.print("Processing Instruction: " + ((ProcessingInstruction) node).getTarget() + " => " +
               ((ProcessingInstruction) node).getData() + "\n");
      }
      else if (nodeType == Node.DOCUMENT_NODE)
      {   //   Document Root
         System.out.println("Document Root.");
         NodeList childNodes = node.getChildNodes();
         int numChildNodes = childNodes.getLength();
         for (int i=0; i< numChildNodes; i++)
         {  
            printNode(childNodes.item(i), level+1);
         }
      }
      else if (nodeType == Node.DOCUMENT_TYPE_NODE)
      {   //   Document Root
         printSpaces(level * 3);
         System.out.println("DocType: " + ((DocumentType) node).getName() +
            ", public id: " + ((DocumentType) node).getPublicId() +
            ", system id: " + ((DocumentType) node).getSystemId());
      }
      else if (nodeType == Node.ENTITY_NODE)
      {   //   Document Root
         printSpaces(level * 3);
         System.out.print("Entity: " + ((Entity) node).getNotationName() + "\n");
      }
      else if (nodeType == Node.ENTITY_REFERENCE_NODE)
      {   //   Document Root
         printSpaces(level * 3);
         System.out.print("Entity: " + ((EntityReference) node).getNodeName() + "\n");
      }

   }   //   printNode

   private static void printSpaces(int count) {
      int i;
      for (i=0; i<count; i++)
      {
         System.out.print(" ");
      }
   }
}

Example:

NumberOfRootChildren.java:

The following version to count the number of children (text and element) of the root nodes may not work correctly. Why?

import javax.xml.parsers.*;

import org.xml.sax.*; 
import org.xml.sax.helpers.*; 

import java.io.*;
import org.w3c.dom.*;

//  
public class NumberOfRootChildren extends DefaultHandler {
    static Document document;

    public static void main(String argv[])
    {
        if (argv.length != 1) {
            System.err.println("Usage: Java NumberOfRootChildren xmlfilename");
            System.exit(1);
        }

        try {
           DocumentBuilderFactory factory =
              DocumentBuilderFactory.newInstance();

         //   Set builder property.
         factory.setValidating(false);
         factory.setCoalescing(true);

         factory.setIgnoringElementContentWhitespace(true);

         DocumentBuilder builder = factory.newDocumentBuilder();

         //   Set Error Handler
         builder.setErrorHandler(new NumberOfRootChildren());
           document = builder.parse(new File(argv[0]));
         Element root = document.getDocumentElement();

         System.out.println("Number of children of the root element => " +
            root.getChildNodes().getLength());
        } catch (Throwable e) {
           //
           e.printStackTrace();
        }
    } // main
}

Can you spot the problems and correct it?

2.4 The Element interface

• The Element interface represents an XML (or HTML) element.
• The Element interface is a subinterface of Node and thus inherits all its methods.
• The Element interface contains many methods appropriate only for element nodes.
  
• Examples:
  • java.lang.String getTagName()
  • java.lang.String getAttribute(java.lang.String name)
    
• The Element interface contains many convenience methods.
• As an example, element nodes with the subtree can be searched using tag names:
  • NodeList getElementsByTagName(java.lang.String name)
  • NodeList getElementsByTagNameNS(java.lang.String namespaceURI, java.lang.String localName)
• Note that many methods have live effect: updating the data structure has an immediate effect.

2.5 Other interfaces

• There is an interface for each node type.
• For example, the Attr interface represents an attribute with these methods.
  • java.lang.String getName()
  • Element getOwnerElement()
  • java.lang.String getValue()
  • void setValue(java.lang.String value)
  • Boolean getSpecified(): whether the attribute was explicitly given a value in the original document.

Example:

NumberOfElement.java: counts the number of elements in an XML document. Can you write a version to count the number of attributes?

import org.w3c.dom.*;
import org.xml.sax.*;
import javax.xml.parsers.*;

import java.io.*;
import org.apache.xml.serialize.*;

/**

   Show the number of elements in an XML document
*/
public class NumberOfElements {
   static Document document;

   //   main body
   public static void main(String argv[])
   {
      if (argv.length != 1) {
         System.err.println("Usage: Java NumberOfElements inputxmlfilename");
         System.exit(1);
      }

      DocumentBuilderFactory factory =
         DocumentBuilderFactory.newInstance();
      try {
         //  Parse input XML file.
         DocumentBuilder builder = factory.newDocumentBuilder();
         document = builder.parse(new File(argv[0]));

         System.out.println("Number of elements in " + argv[0] +
               " = " +   numElements(document.getDocumentElement()));
      } catch (Throwable e) {
         //   Print error messages.
         System.err.println("Sorry, cannot parse the input XML file " + argv[0] + ".");
         e.printStackTrace();
      }
   } // main

   //  
   private static int numElements(org.w3c.dom.Element element) {
      if (element == null) return 0;

      int result = 1;      //   self
      NodeList childNodes = element.getChildNodes();
      for (int i=0; i < childNodes.getLength(); i++) {
         if (childNodes.item(i).getNodeType() == Node.ELEMENT_NODE) {
            result += numElements((Element) childNodes.item(i));
         }   //   if
      }   //   for
      return result;
   }   //   numElements
}   //   NumberOfElements

Example:

Insert a B element before every A element then print out the total number of elements in the result XML tree.

import org.w3c.dom.*;
import org.xml.sax.*;
import javax.xml.parsers.*;

import java.io.*;
import org.apache.xml.serialize.*;

/**

   Show the number of elements in an XML document
*/
public class AddBBeforeA {
   static Document document;

   //   main body
   public static void main(String argv[])
   {
      if (argv.length != 1) {
         System.err.println("Usage: Java NumberOfElements inputxmlfilename");
         System.exit(1);
      }

      DocumentBuilderFactory factory =
         DocumentBuilderFactory.newInstance();
      try {
         //  Parse input XML file.
         DocumentBuilder builder = factory.newDocumentBuilder();
         document = builder.parse(new File(argv[0]));

         Element root = document.getDocumentElement();
         System.out.println("Number of elements in " + argv[0] +
               " initially = " +   numElements(root));
         addBBeforeA(root);
         System.out.println("Number of elements in " + argv[0] +
               " Before adding <B> Before <A> = " +   numElements(root));
      } catch (Throwable e) {
         //   Print error messages.
         System.err.println("Sorry, cannot parse the input XML file " + argv[0] + ".");
         e.printStackTrace();
      }
   } // main

   //  
   private static int numElements(org.w3c.dom.Element element) {
      if (element == null) return 0;

      int result = 1;      //   self
      NodeList childNodes = element.getChildNodes();
      for (int i=0; i < childNodes.getLength(); i++) {
         if (childNodes.item(i).getNodeType() == Node.ELEMENT_NODE) {
            result += numElements((Element) childNodes.item(i));
         }   //   if
      }   //   for
      return result;
   }   //   numElements

   //
   private static void addBBeforeA (org.w3c.dom.Element element) {
      if (element == null) return;
      NodeList childNodes = element.getChildNodes();
      Element bNode = document.createElement("B");

      int numChildren = childNodes.getLength();
           
      for (int i=0; i < numChildren; i++) {
         if (childNodes.item(i).getNodeType() == Node.ELEMENT_NODE &&
            "A".equals(((Element) childNodes.item(i)).getNodeName())) {
            element.insertBefore(bNode, childNodes.item(i));
         }   //   if
      }   //   for
   }   //   addBBeforeA
  
}   //   AddBBeforeA

For input file:

<?xml version="1.0" ?>
<root>
   <C />
   <A />
   <C />
   <D />
</root>

The output is:

Number of elements in AddBBeforeAtest1.xml initially = 5
Number of elements in AddBBeforeAtest1.xml Before adding <B> Before <A> = 6

Can you spot any potential problems?

3. Other DOM Topics

3.1 Namespace Support

• DOM Level 2 supports namespace.
• Many methods related to elements have a namespace version. Examples:
  • getElementsByTagNameNS(java.lang.String namespaceURI, java.lang.String localName).
  • hasAttributeNS(java.lang.String namespaceURI, java.lang.String localName).
  • createElementNS(java.lang.String namespaceURI, java.lang.String qualifiedName), in Document.
• The node interface also has the following methods for accessing namespace information:
  • getPrefix()
  • getNamespaceURI()

Dr. Kwok-Bun Yue
Professor, Computer Science and Computer Information Systems
Chair, Division of Computing and Mathematics
University of Houston-Clear Lake
2700 Bay Area Boulevard
Houston, TX 77058
  Yue's home page      yue@uhcl.edu       281-283-3864