org.apache.xml.dtm.ref

## Class DTMNodeIterator

- java.lang.Object
- - org.apache.xml.dtm.ref.DTMNodeIterator

All Implemented Interfaces:
  NodeIterator

    public class DTMNodeIterator
    extends java.lang.Object
    implements NodeIterator

`DTMNodeIterator` gives us an implementation of the DTMNodeIterator which returns DOM nodes. Please note that this is not necessarily equivlaent to a DOM NodeIterator operating over the same document. In particular:

- If there are several Text nodes in logical succession (ie, across CDATASection and EntityReference boundaries), we will return only the first; the caller is responsible for stepping through them. (%REVIEW% Provide a convenience routine here to assist, pending proposed DOM Level 3 getAdjacentText() operation?)
- Since the whole XPath/XSLT architecture assumes that the source document is not altered while we're working with it, we do not promise to implement the DOM NodeIterator's "maintain current position" response to document mutation.
- Since our design for XPath NodeIterators builds a stateful filter directly into the traversal object, getNodeFilter() is not supported.

State: In progress!!

### Constructor Summary

Constructors
Constructor and Description
`DTMNodeIterator(DTMIterator dtmIterator)` Public constructor: Wrap a DTMNodeIterator around an existing and preconfigured DTMIterator

### Method Summary

Methods
`void` `detach()` Detaches the NodeIterator from the set which it iterated over, releasing any computational resources and placing the iterator in the INVALID state.
`DTMIterator` `getDTMIterator()` Access the wrapped DTMIterator.
`boolean` `getExpandEntityReferences()` The value of this flag determines whether the children of entity reference nodes are visible to the iterator.
`NodeFilter` `getFilter()` Return a handle to the filter used to screen nodes.
`Node` `getRoot()` The root node of the `NodeIterator`, as specified when it was created.
`int` `getWhatToShow()` Return a mask describing which node types are presented via the iterator.
`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.

### Methods inherited from class java.lang.Object

`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### DTMNodeIterator

    public DTMNodeIterator(DTMIterator dtmIterator)

Public constructor: Wrap a DTMNodeIterator around an existing and preconfigured DTMIterator

### Method Detail

#### getDTMIterator

    public DTMIterator getDTMIterator()

Access the wrapped DTMIterator. I'm not sure whether anyone will need this or not, but let's write it and think about it.

#### detach

    public void detach()

Detaches the NodeIterator from the set which it iterated over, releasing any computational resources and placing the iterator in the INVALID state.

Specified by:
  `detach` in interface `NodeIterator`

#### getExpandEntityReferences

    public boolean getExpandEntityReferences()

The value of this flag determines whether the children of entity reference nodes are visible to the iterator.

Specified by:
  `getExpandEntityReferences` in interface `NodeIterator`
Returns:
  false, always (the DTM model flattens entity references)

#### getFilter

    public NodeFilter getFilter()

Return a handle to the filter used to screen nodes. This is ill-defined in Xalan's usage of Nodeiterator, where we have built stateful XPath-based filtering directly into the traversal object. We could return something which supports the NodeFilter interface and allows querying whether a given node would be permitted if it appeared as our next node, but in the current implementation that would be very complex -- and just isn't all that useful.

Specified by:
  `getFilter` in interface `NodeIterator`
Throws:
  `DOMException` - -- NOT_SUPPORTED_ERROR because I can't think of anything more useful to do in this case

#### getRoot

    public Node getRoot()

Description copied from interface: `NodeIterator`
The root node of the `NodeIterator`, as specified when it was created.

Specified by:
  `getRoot` in interface `NodeIterator`
Returns:
  The root node of the NodeIterator, as specified when it was created.

#### getWhatToShow

    public int getWhatToShow()

Return a mask describing which node types are presented via the iterator.

Specified by:
  `getWhatToShow` in interface `NodeIterator`

#### nextNode

    public Node nextNode()
                  throws DOMException

Description copied from interface: `NodeIterator`
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.

Specified by:
  `nextNode` in interface `NodeIterator`
Returns:
  the next node in the set and advance the position of the iterator in the set.
Throws:
  `DOMException` - - INVALID_STATE_ERR Raised if this method is called after the detach method was invoked.

#### previousNode

    public Node previousNode()

Description copied from interface: `NodeIterator`
Returns the previous node in the set and moves the position of the `NodeIterator` backwards in the set.

Specified by:
  `previousNode` in interface `NodeIterator`
Returns:
  the next previous in the set and advance the position of the iterator in the set.
Throws:
  `DOMException` - - INVALID_STATE_ERR Raised if this method is called after the detach method was invoked.