1 /*
2  * Copyright (c) 2000 World Wide Web Consortium,
3  * (Massachusetts Institute of Technology, Institut National de
4  * Recherche en Informatique et en Automatique, Keio University). All
5  * Rights Reserved. This program is distributed under the W3C's Software
6  * Intellectual Property License. This program is distributed in the
7  * hope that it will be useful, but WITHOUT ANY WARRANTY; without even
8  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
9  * PURPOSE.
10  * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
11  */
12 
13 package org.w3c.dom.traversal;
14 
15 import org.w3c.dom.DOMException;
16 import org.w3c.dom.Node;
17 
18 import android.compat.annotation.UnsupportedAppUsage;
19 
20 /**
21  * <code>NodeIterators</code> are used to step through a set of nodes, e.g.
22  * the set of nodes in a <code>NodeList</code>, the document subtree
23  * governed by a particular <code>Node</code>, the results of a query, or
24  * any other set of nodes. The set of nodes to be iterated is determined by
25  * the implementation of the <code>NodeIterator</code>. DOM Level 2
26  * specifies a single <code>NodeIterator</code> implementation for
27  * document-order traversal of a document subtree. Instances of these
28  * <code>NodeIterators</code> are created by calling
29  * <code>DocumentTraversal</code><code>.createNodeIterator()</code>.
30  * <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>.
31  * @since DOM Level 2
32  *
33  * @hide
34  */
35 public interface NodeIterator {
36     /**
37      * The root node of the <code>NodeIterator</code>, as specified when it
38      * was created.
39      */
getRoot()40     public Node getRoot();
41 
42     /**
43      * This attribute determines which node types are presented via the
44      * <code>NodeIterator</code>. The available set of constants is defined
45      * in the <code>NodeFilter</code> interface.  Nodes not accepted by
46      * <code>whatToShow</code> will be skipped, but their children may still
47      * be considered. Note that this skip takes precedence over the filter,
48      * if any.
49      */
getWhatToShow()50     public int getWhatToShow();
51 
52     /**
53      * The <code>NodeFilter</code> used to screen nodes.
54      */
getFilter()55     public NodeFilter getFilter();
56 
57     /**
58      *  The value of this flag determines whether the children of entity
59      * reference nodes are visible to the <code>NodeIterator</code>. If
60      * false, these children  and their descendants will be rejected. Note
61      * that this rejection takes precedence over <code>whatToShow</code> and
62      * the filter. Also note that this is currently the only situation where
63      * <code>NodeIterators</code> may reject a complete subtree rather than
64      * skipping individual nodes.
65      * <br>
66      * <br> To produce a view of the document that has entity references
67      * expanded and does not expose the entity reference node itself, use
68      * the <code>whatToShow</code> flags to hide the entity reference node
69      * and set <code>expandEntityReferences</code> to true when creating the
70      * <code>NodeIterator</code>. To produce a view of the document that has
71      * entity reference nodes but no entity expansion, use the
72      * <code>whatToShow</code> flags to show the entity reference node and
73      * set <code>expandEntityReferences</code> to false.
74      */
getExpandEntityReferences()75     public boolean getExpandEntityReferences();
76 
77     /**
78      * Returns the next node in the set and advances the position of the
79      * <code>NodeIterator</code> in the set. After a
80      * <code>NodeIterator</code> is created, the first call to
81      * <code>nextNode()</code> returns the first node in the set.
82      * @return The next <code>Node</code> in the set being iterated over, or
83      *   <code>null</code> if there are no more members in that set.
84      * @exception DOMException
85      *   INVALID_STATE_ERR: Raised if this method is called after the
86      *   <code>detach</code> method was invoked.
87      */
88     @UnsupportedAppUsage
nextNode()89     public Node nextNode()
90                          throws DOMException;
91 
92     /**
93      * Returns the previous node in the set and moves the position of the
94      * <code>NodeIterator</code> backwards in the set.
95      * @return The previous <code>Node</code> in the set being iterated over,
96      *   or <code>null</code> if there are no more members in that set.
97      * @exception DOMException
98      *   INVALID_STATE_ERR: Raised if this method is called after the
99      *   <code>detach</code> method was invoked.
100      */
previousNode()101     public Node previousNode()
102                              throws DOMException;
103 
104     /**
105      * Detaches the <code>NodeIterator</code> from the set which it iterated
106      * over, releasing any computational resources and placing the
107      * <code>NodeIterator</code> in the INVALID state. After
108      * <code>detach</code> has been invoked, calls to <code>nextNode</code>
109      * or <code>previousNode</code> will raise the exception
110      * INVALID_STATE_ERR.
111      */
112     @UnsupportedAppUsage
detach()113     public void detach();
114 
115 }
116