TreeWalker


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.Node  ;
16  import org.w3c.dom.DOMException  ;
17  
18  /**
19   * <code>TreeWalker</code> objects are used to navigate a document tree or 
20   * subtree using the view of the document defined by their 
21   * <code>whatToShow</code> flags and filter (if any). Any function which 
22   * performs navigation using a <code>TreeWalker</code> will automatically 
23   * support any view defined by a <code>TreeWalker</code>.
24   * <p>Omitting nodes from the logical view of a subtree can result in a 
25   * structure that is substantially different from the same subtree in the 
26   * complete, unfiltered document. Nodes that are siblings in the 
27   * <code>TreeWalker</code> view may be children of different, widely 
28   * separated nodes in the original view. For instance, consider a 
29   * <code>NodeFilter</code> that skips all nodes except for Text nodes and 
30   * the root node of a document. In the logical view that results, all text 
31   * nodes will be siblings and appear as direct children of the root node, no 
32   * matter how deeply nested the structure of the original document.
33   * <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>.
34   * @since DOM Level 2
35   */
36  public interface TreeWalker {
37      /**
38       * The <code>root</code> node of the <code>TreeWalker</code>, as specified 
39       * when it was created.
40       */
41      public Node   getRoot();
42  
43      /**
44       * This attribute determines which node types are presented via the 
45       * <code>TreeWalker</code>. The available set of constants is defined in 
46       * the <code>NodeFilter</code> interface.  Nodes not accepted by 
47       * <code>whatToShow</code> will be skipped, but their children may still 
48       * be considered. Note that this skip takes precedence over the filter, 
49       * if any. 
50       */
51      public int getWhatToShow();
52  
53      /**
54       * The filter used to screen nodes.
55       */
56      public NodeFilter getFilter();
57  
58      /**
59       * The value of this flag determines whether the children of entity 
60       * reference nodes are visible to the <code>TreeWalker</code>. If false, 
61       * these children  and their descendants will be rejected. Note that 
62       * this rejection takes precedence over <code>whatToShow</code> and the 
63       * filter, if any. 
64       * <br> To produce a view of the document that has entity references 
65       * expanded and does not expose the entity reference node itself, use 
66       * the <code>whatToShow</code> flags to hide the entity reference node 
67       * and set <code>expandEntityReferences</code> to true when creating the 
68       * <code>TreeWalker</code>. To produce a view of the document that has 
69       * entity reference nodes but no entity expansion, use the 
70       * <code>whatToShow</code> flags to show the entity reference node and 
71       * set <code>expandEntityReferences</code> to false.
72       */
73      public boolean getExpandEntityReferences();
74  
75      /**
76       * The node at which the <code>TreeWalker</code> is currently positioned.
77       * <br>Alterations to the DOM tree may cause the current node to no longer 
78       * be accepted by the <code>TreeWalker</code>'s associated filter. 
79       * <code>currentNode</code> may also be explicitly set to any node, 
80       * whether or not it is within the subtree specified by the 
81       * <code>root</code> node or would be accepted by the filter and 
82       * <code>whatToShow</code> flags. Further traversal occurs relative to 
83       * <code>currentNode</code> even if it is not part of the current view, 
84       * by applying the filters in the requested direction; if no traversal 
85       * is possible, <code>currentNode</code> is not changed. 
86       */
87      public Node   getCurrentNode();
88      /**
89       * The node at which the <code>TreeWalker</code> is currently positioned.
90       * <br>Alterations to the DOM tree may cause the current node to no longer 
91       * be accepted by the <code>TreeWalker</code>'s associated filter. 
92       * <code>currentNode</code> may also be explicitly set to any node, 
93       * whether or not it is within the subtree specified by the 
94       * <code>root</code> node or would be accepted by the filter and 
95       * <code>whatToShow</code> flags. Further traversal occurs relative to 
96       * <code>currentNode</code> even if it is not part of the current view, 
97       * by applying the filters in the requested direction; if no traversal 
98       * is possible, <code>currentNode</code> is not changed. 
99       * @exception DOMException
100      *   NOT_SUPPORTED_ERR: Raised if an attempt is made to set 
101      *   <code>currentNode</code> to <code>null</code>.
102      */
103     public void setCurrentNode(Node   currentNode)
104                          throws DOMException  ;
105 
106     /**
107      * Moves to and returns the closest visible ancestor node of the current 
108      * node. If the search for <code>parentNode</code> attempts to step 
109      * upward from the <code>TreeWalker</code>'s <code>root</code> node, or 
110      * if it fails to find a visible ancestor node, this method retains the 
111      * current position and returns <code>null</code>.
112      * @return The new parent node, or <code>null</code> if the current node 
113      *   has no parent  in the <code>TreeWalker</code>'s logical view.  
114      */
115     public Node   parentNode();
116 
117     /**
118      * Moves the <code>TreeWalker</code> to the first visible child of the 
119      * current node, and returns the new node. If the current node has no 
120      * visible children, returns <code>null</code>, and retains the current 
121      * node.
122      * @return The new node, or <code>null</code> if the current node has no 
123      *   visible children  in the <code>TreeWalker</code>'s logical view.  
124      */
125     public Node   firstChild();
126 
127     /**
128      * Moves the <code>TreeWalker</code> to the last visible child of the 
129      * current node, and returns the new node. If the current node has no 
130      * visible children, returns <code>null</code>, and retains the current 
131      * node.
132      * @return The new node, or <code>null</code> if the current node has no 
133      *   children  in the <code>TreeWalker</code>'s logical view.  
134      */
135     public Node   lastChild();
136 
137     /**
138      * Moves the <code>TreeWalker</code> to the previous sibling of the 
139      * current node, and returns the new node. If the current node has no 
140      * visible previous sibling, returns <code>null</code>, and retains the 
141      * current node.
142      * @return The new node, or <code>null</code> if the current node has no 
143      *   previous sibling.  in the <code>TreeWalker</code>'s logical view.  
144      */
145     public Node   previousSibling();
146 
147     /**
148      * Moves the <code>TreeWalker</code> to the next sibling of the current 
149      * node, and returns the new node. If the current node has no visible 
150      * next sibling, returns <code>null</code>, and retains the current node.
151      * @return The new node, or <code>null</code> if the current node has no 
152      *   next sibling.  in the <code>TreeWalker</code>'s logical view.  
153      */
154     public Node   nextSibling();
155 
156     /**
157      * Moves the <code>TreeWalker</code> to the previous visible node in 
158      * document order relative to the current node, and returns the new 
159      * node. If the current node has no previous node,  or if the search for 
160      * <code>previousNode</code> attempts to step upward from the 
161      * <code>TreeWalker</code>'s <code>root</code> node,  returns 
162      * <code>null</code>, and retains the current node. 
163      * @return The new node, or <code>null</code> if the current node has no 
164      *   previous node  in the <code>TreeWalker</code>'s logical view.  
165      */
166     public Node   previousNode();
167 
168     /**
169      * Moves the <code>TreeWalker</code> to the next visible node in document 
170      * order relative to the current node, and returns the new node. If the 
171      * current node has no next node, or if the search for nextNode attempts 
172      * to step upward from the <code>TreeWalker</code>'s <code>root</code> 
173      * node, returns <code>null</code>, and retains the current node.
174      * @return The new node, or <code>null</code> if the current node has no 
175      *   next node  in the <code>TreeWalker</code>'s logical view.  
176      */
177     public Node   nextNode();
178 
179 }
180
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags