| /******************************************************************************* |
| * Copyright (c) 2001, 2004 IBM Corporation and others. |
| * All rights reserved. This program and the accompanying materials |
| * are made available under the terms of the Eclipse Public License v1.0 |
| * which accompanies this distribution, and is available at |
| * http://www.eclipse.org/legal/epl-v10.html |
| * |
| * Contributors: |
| * IBM Corporation - initial API and implementation |
| * Jens Lukowski/Innoopract - initial renaming/restructuring |
| * |
| *******************************************************************************/ |
| |
| package org.w3c.dom.traversal; |
| |
| import org.w3c.dom.DOMException; |
| import org.w3c.dom.Node; |
| |
| /** |
| * <code>Iterators</code> are used to step through a set of nodes, e.g. the |
| * set of nodes in a <code>NodeList</code>, the document subtree governed |
| * by a particular <code>Node</code>, 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 <code>NodeIterator</code>. DOM Level 2 specifies a |
| * single <code>NodeIterator</code> implementation for document-order |
| * traversal of a document subtree. Instances of these iterators are created |
| * by calling <code>DocumentTraversal</code> |
| * <code>.createNodeIterator()</code>. |
| * <p> |
| * See also the <a |
| * href='http://www.w3.org/TR/2000/REC-DOM-Level-2-Traversal-Range-20001113'>Document |
| * Object Model (DOM) Level 2 Traversal and Range Specification </a>. |
| * |
| * @since DOM Level 2 |
| */ |
| public interface NodeIterator { |
| /** |
| * The root node of the <code>NodeIterator</code>, as specified when it |
| * was created. |
| */ |
| public Node getRoot(); |
| |
| /** |
| * This attribute determines which node types are presented via the |
| * iterator. The available set of constants is defined in the |
| * <code>NodeFilter</code> interface. Nodes not accepted by |
| * <code>whatToShow</code> 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 <code>NodeFilter</code> used to screen nodes. |
| */ |
| public NodeFilter getFilter(); |
| |
| /** |
| * The value of this flag determines whether the children of entity |
| * reference nodes are visible to the iterator. If false, they and their |
| * descendants will be rejected. Note that this rejection takes precedence |
| * over <code>whatToShow</code> and the filter. Also note that this is |
| * currently the only situation where <code>NodeIterators</code> may |
| * reject a complete subtree rather than skipping individual nodes. <br> |
| * <br> |
| * To produce a view of the document that has entity references expanded |
| * and does not expose the entity reference node itself, use the |
| * <code>whatToShow</code> flags to hide the entity reference node and |
| * set <code>expandEntityReferences</code> to true when creating the |
| * iterator. To produce a view of the document that has entity reference |
| * nodes but no entity expansion, use the <code>whatToShow</code> flags |
| * to show the entity reference node and set |
| * <code>expandEntityReferences</code> to false. |
| */ |
| public boolean getExpandEntityReferences(); |
| |
| /** |
| * Returns the next node in the set and advances the position of the |
| * iterator in the set. After a <code>NodeIterator</code> is created, |
| * the first call to <code>nextNode()</code> returns the first node in |
| * the set. |
| * |
| * @return The next <code>Node</code> in the set being iterated over, or |
| * <code>null</code> if there are no more members in that set. |
| * @exception DOMException |
| * INVALID_STATE_ERR: Raised if this method is called after |
| * the <code>detach</code> method was invoked. |
| */ |
| public Node nextNode() throws DOMException; |
| |
| /** |
| * Returns the previous node in the set and moves the position of the |
| * <code>NodeIterator</code> backwards in the set. |
| * |
| * @return The previous <code>Node</code> in the set being iterated |
| * over, or <code>null</code> if there are no more members in |
| * that set. |
| * @exception DOMException |
| * INVALID_STATE_ERR: Raised if this method is called after |
| * the <code>detach</code> method was invoked. |
| */ |
| public Node previousNode() throws DOMException; |
| |
| /** |
| * Detaches the <code>NodeIterator</code> from the set which it iterated |
| * over, releasing any computational resources and placing the iterator in |
| * the INVALID state. After <code>detach</code> has been invoked, calls |
| * to <code>nextNode</code> or <code>previousNode</code> will raise |
| * the exception INVALID_STATE_ERR. |
| */ |
| public void detach(); |
| |
| } |