uk.ac.starlink.util

## Class NodeDescendants

- java.lang.Object
- - uk.ac.starlink.util.NodeDescendants

-     public class NodeDescendants
      extends java.lang.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

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `NodeDescendants.Visitor` The `Visitor` processes a single node in a tree.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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

    Constructors
    Constructor and Description
    `NodeDescendants(org.w3c.dom.Node node)` Creates a new `NodeDescendant` object.
    `NodeDescendants(org.w3c.dom.Node node, int whatToShow)` Creates a new `NodeDescendant` object.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.Iterator<org.w3c.dom.Node>` | `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.
    `java.lang.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(org.w3c.dom.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(org.w3c.dom.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 java.lang.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 java.util.Iterator<org.w3c.dom.Node> 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.