uk.ac.starlink.util
Class NodeDescendants

java.lang.Object
  extended by uk.ac.starlink.util.NodeDescendants

public class NodeDescendants
extends Object

Represents the set of Nodes in the tree rooted at a particular DOM Node. The tree includes the root node.

This supports two ways of traversing the tree, either using an iterator, or providing an object which visits each node in the tree in turn.

Note that the iterator() and visitTree(uk.ac.starlink.util.NodeDescendants.Visitor) methods below share state -- namely the state which this object represents -- so you should not use simultaneously the result of two such method calls on the same object.


Nested Class Summary
static interface NodeDescendants.Visitor
          The Visitor processes a single node in a tree.
 
Field Summary
static int SHOW_ALL
          Indicates that all nodes should be included in a traversal of, or iteration through, a tree.
static int SHOW_ATTRIBUTE
           
static int SHOW_CDATA_SECTION
           
static int SHOW_COMMENT
           
static int SHOW_DOCUMENT
           
static int SHOW_DOCUMENT_FRAGMENT
           
static int SHOW_DOCUMENT_TYPE
           
static int SHOW_ELEMENT
           
static int SHOW_ENTITY
           
static int SHOW_ENTITY_REFERENCE
           
static int SHOW_NOTATION
           
static int SHOW_PROCESSING_INSTRUCTION
           
static int SHOW_TEXT
           
 
Constructor Summary
NodeDescendants(Node node)
          Creates a new NodeDescendant object.
NodeDescendants(Node node, int whatToShow)
          Creates a new NodeDescendant object.
 
Method Summary
 Iterator iterator()
          Obtains an iterator which iterates over the nodes in the set of descendants.
 void reset()
          Sets the object back to its initial state.
 void reset(int whatToShow)
          Sets the object back to its initial state, but with a (possibly) different constraint on which nodes are included in the set.
 Object visitTree(NodeDescendants.Visitor v)
          Visits each of the nodes in the tree.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SHOW_ALL

public static final int SHOW_ALL
Indicates that all nodes should be included in a traversal of, or iteration through, a tree. To visit only certain nodes, use one of the other SHOW... constants.

Note: this mechanism is taken from the DOM2 Traversal specification, though it is not an implementation of that set of interfaces. As noted there, not all of the SHOW... values are useful, since not all of the associated Node types can appear as descendants of a Node, othe than in rather special circumstances. The constants are included here for completeness, however.

See Also:
NodeDescendants(Node,int), Constant Field Values

SHOW_ELEMENT

public static final int SHOW_ELEMENT
See Also:
Constant Field Values

SHOW_ATTRIBUTE

public static final int SHOW_ATTRIBUTE
See Also:
Constant Field Values

SHOW_TEXT

public static final int SHOW_TEXT
See Also:
Constant Field Values

SHOW_CDATA_SECTION

public static final int SHOW_CDATA_SECTION
See Also:
Constant Field Values

SHOW_ENTITY_REFERENCE

public static final int SHOW_ENTITY_REFERENCE
See Also:
Constant Field Values

SHOW_ENTITY

public static final int SHOW_ENTITY
See Also:
Constant Field Values

SHOW_PROCESSING_INSTRUCTION

public static final int SHOW_PROCESSING_INSTRUCTION
See Also:
Constant Field Values

SHOW_COMMENT

public static final int SHOW_COMMENT
See Also:
Constant Field Values

SHOW_DOCUMENT

public static final int SHOW_DOCUMENT
See Also:
Constant Field Values

SHOW_DOCUMENT_TYPE

public static final int SHOW_DOCUMENT_TYPE
See Also:
Constant Field Values

SHOW_DOCUMENT_FRAGMENT

public static final int SHOW_DOCUMENT_FRAGMENT
See Also:
Constant Field Values

SHOW_NOTATION

public static final int SHOW_NOTATION
See Also:
Constant Field Values
Constructor Detail

NodeDescendants

public NodeDescendants(Node node)
Creates a new NodeDescendant object. Equivalent to NodeDescendant(node, SHOW_ALL).

Parameters:
node - the node which is to be the root of the tree

NodeDescendants

public NodeDescendants(Node node,
                       int whatToShow)
Creates a new NodeDescendant object. This represents the set of Nodes in the tree rooted at the given Node.

You can configure the set to include only certain nodes. If the whatToShow parameter is given as SHOW_ALL, then all nodes are returned. If the parameter has one of the other SHOW_... values, or more than one or'ed together (using |), then only the indicated node types are included in the set, and returned by any iterator or examined by any visitor.

For example, if you create the NodeDescendant using the constructor:

 NodeDescendants tree = new NodeDescendants
     (mynode, NodeDescendants.SHOW_ALL);
 
(which is equivalent to the NodeDescendants(Node) constructor), then the set represents all the nodes in the tree which are reachable from the node mynode by the getFirstChild and similar methods. If, however, the object was constructed with
 NodeDescendants tree = new NodeDescendants
     (mynode, 
     NodeDescendants.SHOW_TEXT|NodeDescendants.SHOW_CDATA_SECTION);
 
then all Text and CDATA nodes would be included in the set, and only these would be returned by the iterator or visited by the visitor.

Parameters:
node - the node which is to be the root of the tree
whatToShow - code indicating which node types should be included in the set
Method Detail

reset

public void reset()
Sets the object back to its initial state. This allows you to extract a second iterator either after an earlier one has finished, or before.


reset

public void reset(int whatToShow)
Sets the object back to its initial state, but with a (possibly) different constraint on which nodes are included in the set.

Parameters:
whatToShow - code indicating which node types should be included in the set. See NodeDescendants(Node,int)

visitTree

public Object visitTree(NodeDescendants.Visitor v)
Visits each of the nodes in the tree. This method iterates through all the descendants of the given node, starting with that node, and presents each of them to the given NodeVisitor. If that object's visitNode method returns non-null, then the traversal is stopped and the returned object immediately returned as the value of this method. If the visitNode method always returns null and so the traversal completes, then the method returns null also.

Parameters:
v - a visitor which has each node presented to it in turn

iterator

public Iterator iterator()
Obtains an iterator which iterates over the nodes in the set of descendants. The traversal happens in depth-first order.

Returns:
an iterator which returns in turn the given node, then all of its descendants.

Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.