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. }