org.apache.crimson.tree
Class TreeWalker

java.lang.Object
  org.apache.crimson.tree.TreeWalker

public class TreeWalker

extends Object

This class implements a preorder depth first walk over the tree rooted at a given DOM node. The traversal is "live", and terminates either when that given node is reached when climbing back up, or when a null parent node is reached. It may be restarted via reset().

The way this remains live is to have a "current" node to which the walk is tied. If the tree is modified, that current node will always still be valid ... even if it is no longer connected to the rest of the document, or if it's reconnected at a different location. The behavior of tree modifications is specified by DOM, and the interaction with a walker's current node is specified entirely by knowing that only the getNextSibling, getParentNode, and getFirstChild methods are used for walking the tree.

For example, if the current branch is cut off, the walk will stop when it tries to access what were parents or siblings of that node. (That is, the walk will continue over the branch that was cut.) If that is not the intended behaviour, one must change the "current" branch before cutting ... much like avoiding trimming a branch off a real tree if someone is sitting on it. The removeCurrent() method encapsulates that logic.

Author:

David Brownell

Field Summary

private org.w3c.dom.Node	current
private org.w3c.dom.Node	startPoint

Constructor Summary

TreeWalker(org.w3c.dom.Node initial)
Constructs a tree walker starting at the given node.

Method Summary

org.w3c.dom.Node	getCurrent() Returns the current node.
org.w3c.dom.Node	getNext() Advances to the next node, and makes that current.
org.w3c.dom.Element	getNextElement(String tag) Convenience method to walk only through elements with the specified tag name.
org.w3c.dom.Element	getNextElement(String nsURI, String localName) Namespace version
org.w3c.dom.Node	removeCurrent() Removes the current node; reassigns the current node to be the next one in the current walk that isn't a child of the (removed) current node, and returns that new current node.
void	reset() Resets the walker to the state in which it was created: the current node will be the node given to the constructor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

startPoint

private org.w3c.dom.Node startPoint

current

private org.w3c.dom.Node current

Constructor Detail

TreeWalker

public TreeWalker(org.w3c.dom.Node initial)

Constructs a tree walker starting at the given node.

Method Detail

getCurrent

public org.w3c.dom.Node getCurrent()

Returns the current node.

getNext

public org.w3c.dom.Node getNext()

Advances to the next node, and makes that current. Returns null if there are no more nodes through which to walk, because the initial node was reached or because a null parent was reached.

Returns:

the next node (which becomes current), or else null

getNextElement

public org.w3c.dom.Element getNextElement(String tag)

Convenience method to walk only through elements with the specified tag name. This just calls getNext() and filters out the nodes which aren't desired. It returns null when the iteration completes.

Parameters:

tag - the tag to match, or null to indicate all elements

Returns:

the next matching element, or else null

getNextElement

public org.w3c.dom.Element getNextElement(String nsURI,
                                          String localName)

Namespace version

reset

public void reset()

Resets the walker to the state in which it was created: the current node will be the node given to the constructor. If the tree rooted at that node has been modified from the previous traversal, the sequence of nodes returned by getNext() will differ accordingly.

removeCurrent

public org.w3c.dom.Node removeCurrent()

Removes the current node; reassigns the current node to be the next one in the current walk that isn't a child of the (removed) current node, and returns that new current node. In a loop, this could be used instead of a getNext().

Returns:

the next node (which becomes current), or else null

Throws:

IllegalStateException - if the current node is null or has no parent (it is a Document or DocumentFragment)