Availability

DOM Level 2 Traversal

Properties

readonly boolean expandEntityReferences

Whether this NodeIterator traverses the children of EntityReference nodes (in XML documents). The value is specified as an argument to Document.createNodeIterator( ) when the NodeIterator is first created.

readonly NodeFilter filter

The node filter function that was specified for this NodeIterator in the call to Document.createNodeIterator( ).

readonly Node root

The root node at which the NodeIterator begins iterating. The value of this property is specified in the call to Document.createNodeIterator( ).

readonly unsigned long whatToShow

A set of bit flags (see NodeFilter for a list of valid flags) that specifies what types of Document nodes this NodeIterator will consider. If a bit is not set in this property, the corresponding node type will always be ignored by this NodeIterator. Note that the value of this property is specified in the call to Document.createNodeIterator( ).

Methods

detach( )

"Detaches" this NodeIterator from its document so that the implementation no longer needs to modify the NodeIterator when the document is modified. Call this method when you are done using a NodeIterator. After detach( ) has been called, any calls to other NodeIterator methods will cause exceptions.

nextNode( )

Returns the next node in the filtered sequence of nodes represented by this NodeIterator, or null if the NodeIterator has already returned the last node.

previousNode( )

Returns the previous node in the filtered sequence of nodes represented by this NodeIterator, or null if there is no previous node.

Description

A NodeIterator represents the sequence of Document nodes that results from traversing a document subtree in document source order and filtering the nodes using a two-stage process. Create a NodeIterator object with Document.createNodeIterator( ). Use the nextNode( ) and previousNode( ) methods to iterate forward and backward through the sequence of nodes. Call detach( ) when you are done with a NodeIterator, unless you are sure that the NodeIterator will be garbage collected before the document is modified. Note that the properties of this interface are all read-only copies of the arguments passed to Document.createNodeIterator( ).

To be returned by the nextNode( ) or previousNode( ) methods, a node must pass two filtration steps. First, the node type must be one of the types specified by the whatToShow property. See NodeFilter for a list of constants that can be combined to specify the whatToShow argument to Document.createNodeIterator( ). Next, if the filter property is not null, each node that passes the whatToShow test is passed to the filter function specified by the filter property. If this function returns NodeFilter.FILTER_ACCEPT, the node is returned. If it returns NodeFilter.FILTER_REJECT or NodeFilter.FILTER_SKIP, the NodeIterator skips the node. Note that when a node is rejected by either of these filtration steps, it is only the node itself that is rejected; the children of the node are not automatically rejected and are subject to the same filtration steps.

NodeIterator objects remain valid even if the document tree they are traversing is modified. The nextNode( ) and previousNode( ) methods return nodes based on the current state of the document, not the state of the document that existed when the NodeIterator was created.

See Also

NodeFilter, TreeWalker; Chapter 17

Returned by

Document.createNodeIterator( )