org.w3c.dom.traversal.NodeIterator Maven / Gradle / Ivy
/*
* Copyright (c) 2000 World Wide Web Consortium,
* (Massachusetts Institute of Technology, Institut National de
* Recherche en Informatique et en Automatique, Keio University). All
* Rights Reserved. This program is distributed under the W3C's Software
* Intellectual Property License. This program is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY; without even
* the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
* PURPOSE.
* See W3C License http://www.w3.org/Consortium/Legal/ for more details.
*/
package org.w3c.dom.traversal;
import org.w3c.dom.Node;
import org.w3c.dom.DOMException;
/**
* 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 DOM Level 2
*/
public interface NodeIterator {
/**
* The root node of the NodeIterator, as specified when it
* was created.
*/
public Node getRoot();
/**
* 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.
*/
public int getWhatToShow();
/**
* The NodeFilter used to screen nodes.
*/
public NodeFilter getFilter();
/**
* 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.
*/
public boolean getExpandEntityReferences();
/**
* 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.
* @return The next Node in the set being iterated over, or
* null if there are no more members in that set.
* @exception DOMException
* INVALID_STATE_ERR: Raised if this method is called after the
* detach method was invoked.
*/
public Node nextNode()
throws DOMException;
/**
* Returns the previous node in the set and moves the position of the
* NodeIterator backwards in the set.
* @return The previous Node in the set being iterated over,
* or null if there are no more members in that set.
* @exception DOMException
* INVALID_STATE_ERR: Raised if this method is called after the
* detach method was invoked.
*/
public Node previousNode()
throws DOMException;
/**
* 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.
*/
public void detach();
}