Not all DOM implementations are guaranteed to support the traversal module, though most do. You can check this with hasFeature("traversal", "2.0") in the DOMImplementation class. For example,

if (!impl.hasFeature("traversal", "2.0")) {
  System.err.println( 
   "A DOM implementation that supports traversal is required.");  
  return;
}

Assuming the implementation does support traversal, the Document implementation class also implements the DocumentTraversal interface. This factory interface, shown in Example 12.2, allows you to create new NodeIterator and TreeWalker objects which traverse the nodes in that document.

package org.w3c.dom.traversal;

public interface DocumentTraversal {
  
  public NodeIterator createNodeIterator(Node root, 
   int whatToShow, NodeFilter filter, 
   boolean entityReferenceExpansion) throws DOMException;

  public TreeWalker createTreeWalker(Node root,
   int whatToShow, NodeFilter filter,
   boolean entityReferenceExpansion) throws DOMException;

}

Thus, to create a NodeIterator you cast the Document object you want to iterate over to DocumentTraversal, and then invoke its createNodeIterator() method. This method takes four arguments:

For example, the last chapter demonstrated a comment reader program that recursively descended an XML tree, printing out all the comment nodes that were found. A NodeIterator makes it possible to write the program non-recursively. When creating the iterator, the root argument is the document node, whatToShow is NodeFilter.SHOW_COMMENT, the node filter is null, and entityReferenceExpansion is true. Example 12.3 demonstrates.

import javax.xml.parsers.*;
import org.w3c.dom.*;
import org.w3c.dom.traversal.*;
import org.xml.sax.SAXException;
import java.io.IOException;


public class CommentIterator {

  public static void main(String[] args) {

    if (args.length <= 0) {
      System.out.println("Usage: java DOMCommentReader URL");
      return;
    }
    
    String url = args[0];
    
    try {
      DocumentBuilderFactory factory 
       = DocumentBuilderFactory.newInstance();
      DocumentBuilder parser = factory.newDocumentBuilder();
      
      // Check for the traversal module
      DOMImplementation impl = parser.getDOMImplementation();
      if (!impl.hasFeature("traversal", "2.0")) {
        System.out.println(
         "A DOM implementation that supports traversal is required."
        );  
        return;
      }
      
      // Read the document
      Document doc = parser.parse(url); 
      
      // Create the NodeIterator
      DocumentTraversal traversable = (DocumentTraversal) doc;
      NodeIterator iterator = traversable.createNodeIterator(
       doc, NodeFilter.SHOW_COMMENT, null, true);

      // Iterate over the comments
      Node node;
      while ((node = iterator.nextNode()) != null) {
        System.out.println(node.getNodeValue());
      }
       
    }
    catch (SAXException e) {
      System.out.println(e);
      System.out.println(url + " is not well-formed.");
    }
    catch (IOException e) { 
      System.out.println(
       "Due to an IOException, the parser could not check " + url
      ); 
    }
    catch (FactoryConfigurationError e) { 
      System.out.println("Could not locate a factory class"); 
    }
    catch (ParserConfigurationException e) { 
      System.out.println("Could not locate a JAXP parser"); 
    }
     
  } // end main  
  
}

You can decide for yourself whether or not you prefer the explicit recursion and tree-walking of Example 11.20 in the last chapter or the hidden recursion of CommentIterator here. With a decent implementation, there really shouldn’t be any noticeable performance penalty, so feel free to use whichever feels more natural to you.

Node iterators are live. That is, if the document changes while the program is walking the tree, the iterator retains its state. For instance, let’s suppose the program is at node C of a node iterator that’s walking through nodes A, B, C, D, and E in that order. If you delete node D, and then call nextNode(), you’ll get node E. If you add node Z in between B and C and then call previousNode(), you’ll get node Z. The iterator’s current position is always between two nodes (or before the first node or after the last node) but never on a node. Thus it is not invalidated by deleting the current node.

For example, this method deletes all the comments in its Document argument. When the method returns all the comments have been removed.

  public static void deleteComments(Document doc) {
  
    // Create the NodeIterator
    DocumentTraversal traversable = (DocumentTraversal) doc;
    NodeIterator iterator = traversable.createNodeIterator(
     doc, NodeFilter.SHOW_COMMENT, null, true);

    // Iterate over the comments
    Node comment;
    while ((comment = iterator.nextNode()) != null) {
      Node parent = comment.getParentNode();
      parent.removeChild(comment);
    }
    
  }

This method changes the original Document object. It does not change the XML file from which the Document object was created unless you specifically write the changed document back out into the original file after the comments have been deleted.

You can combine the various flags for whatToShow with the bitwise or operator. For example, the previous chapter used a rather convoluted recursive getText() method in the ExampleExtractor program to accumulate all the text from both text and CDATA section nodes within an element. Example 12.4 shows how NodeIterator can be used to accomplish this task in a much more straightforward fashion.

import org.w3c.dom.*;
import org.w3c.dom.traversal.*;


public class TextExtractor {

  public static String getText(Node node) {
    
    if (node == null) return "";
    
    // Set up the iterator
    Document doc = node.getOwnerDocument();
    DocumentTraversal traversable = (DocumentTraversal) doc;
    int whatToShow 
     = NodeFilter.SHOW_TEXT | NodeFilter.SHOW_CDATA_SECTION;
    NodeIterator iterator = traversable.createNodeIterator(node, 
     whatToShow, null, true);
     
    // Extract the text
    StringBuffer result = new StringBuffer();
    Node current;
    while ((current = iterator.nextNode()) != null) {
      result.append(current.getNodeValue());
    }
    return result.toString();
    
  }

}

I’ll be reusing this class a little later on. Something like this should definitely be in your toolbox for whenever you need to extract the text content of an element.