Module java.xml
Package org.w3c.dom.traversal

# Interface NodeIterator

public interface NodeIterator
`NodeIterators` are used to step through a set of nodes, e.g. the set of nodes in a `NodeList`, the document subtree governed by a particular `Node`, the results of a query, or any other set of nodes. The set of nodes to be iterated is determined by the implementation of the `NodeIterator`. DOM Level 2 specifies a single `NodeIterator` implementation for document-order traversal of a document subtree. Instances of these `NodeIterators` are created by calling `DocumentTraversal``.createNodeIterator()`.

See also the Document Object Model (DOM) Level 2 Traversal and Range Specification.

Since:
  9, DOM Level 2

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `detach()`
  Detaches the `NodeIterator` from the set which it iterated over, releasing any computational resources and placing the `NodeIterator` in the INVALID state.
  `boolean`
  `getExpandEntityReferences()`
  The value of this flag determines whether the children of entity reference nodes are visible to the `NodeIterator`.
  `NodeFilter`
  `getFilter()`
  The `NodeFilter` used to screen nodes.
  `Node`
  `getRoot()`
  The root node of the `NodeIterator`, as specified when it was created.
  `int`
  `getWhatToShow()`
  This attribute determines which node types are presented via the `NodeIterator`.
  `Node`
  `nextNode()`
  Returns the next node in the set and advances the position of the `NodeIterator` in the set.
  `Node`
  `previousNode()`
  Returns the previous node in the set and moves the position of the `NodeIterator` backwards in the set.

- ## Method Details

  - ### getRoot

    Node getRoot()
    The root node of the `NodeIterator`, as specified when it was created.

  - ### getWhatToShow

    int getWhatToShow()
    This attribute determines which node types are presented via the `NodeIterator`. The available set of constants is defined in the `NodeFilter` interface. Nodes not accepted by `whatToShow` will be skipped, but their children may still be considered. Note that this skip takes precedence over the filter, if any.

  - ### getFilter

    NodeFilter getFilter()
    The `NodeFilter` used to screen nodes.

  - ### getExpandEntityReferences

    boolean getExpandEntityReferences()
    The value of this flag determines whether the children of entity reference nodes are visible to the `NodeIterator`. If false, these children and their descendants will be rejected. Note that this rejection takes precedence over `whatToShow` and the filter. Also note that this is currently the only situation where `NodeIterators` may reject a complete subtree rather than skipping individual nodes.
    To produce a view of the document that has entity references expanded and does not expose the entity reference node itself, use the `whatToShow` flags to hide the entity reference node and set `expandEntityReferences` to true when creating the `NodeIterator`. To produce a view of the document that has entity reference nodes but no entity expansion, use the `whatToShow` flags to show the entity reference node and set `expandEntityReferences` to false.

  - ### nextNode

    Node nextNode() throws DOMException
    Returns the next node in the set and advances the position of the `NodeIterator` in the set. After a `NodeIterator` is created, the first call to `nextNode()` returns the first node in the set.
    Returns:
      The next `Node` in the set being iterated over, or `null` if there are no more members in that set.
    Throws:
      `DOMException` - INVALID_STATE_ERR: Raised if this method is called after the `detach` method was invoked.

  - ### previousNode

    Node previousNode() throws DOMException
    Returns the previous node in the set and moves the position of the `NodeIterator` backwards in the set.
    Returns:
      The previous `Node` in the set being iterated over, or `null` if there are no more members in that set.
    Throws:
      `DOMException` - INVALID_STATE_ERR: Raised if this method is called after the `detach` method was invoked.

  - ### detach

    void detach()
    Detaches the `NodeIterator` from the set which it iterated over, releasing any computational resources and placing the `NodeIterator` in the INVALID state. After `detach` has been invoked, calls to `nextNode` or `previousNode` will raise the exception INVALID_STATE_ERR.