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.      * @exception DOMException

  87.      *   NOT_SUPPORTED_ERR: Raised if an attempt is made to set 

  88.      *   <code>currentNode</code> to <code>null</code>.

  89.      */

  90.     public Node getCurrentNode();

  91.     /**

  92.      * The node at which the <code>TreeWalker</code> is currently positioned.

  93.      * <br>Alterations to the DOM tree may cause the current node to no longer 

  94.      * be accepted by the <code>TreeWalker</code>'s associated filter. 

  95.      * <code>currentNode</code> may also be explicitly set to any node, 

  96.      * whether or not it is within the subtree specified by the 

  97.      * <code>root</code> node or would be accepted by the filter and 

  98.      * <code>whatToShow</code> flags. Further traversal occurs relative to 

  99.      * <code>currentNode</code> even if it is not part of the current view, 

  100.      * by applying the filters in the requested direction; if no traversal 

  101.      * is possible, <code>currentNode</code> is not changed. 

  102.      * @exception DOMException

  103.      *   NOT_SUPPORTED_ERR: Raised if an attempt is made to set 

  104.      *   <code>currentNode</code> to <code>null</code>.

  105.      */

  106.     public void setCurrentNode(Node currentNode)

  107.                          throws DOMException;

  108. 

  109.     /**

  110.      * Moves to and returns the closest visible ancestor node of the current 

  111.      * node. If the search for <code>parentNode</code> attempts to step 

  112.      * upward from the <code>TreeWalker</code>'s <code>root</code> node, or 

  113.      * if it fails to find a visible ancestor node, this method retains the 

  114.      * current position and returns <code>null</code>.

  115.      * @return The new parent node, or <code>null</code> if the current node 

  116.      *   has no parent  in the <code>TreeWalker</code>'s logical view.  

  117.      */

  118.     public Node parentNode();

  119. 

  120.     /**

  121.      * Moves the <code>TreeWalker</code> to the first visible child of the 

  122.      * current node, and returns the new node. If the current node has no 

  123.      * visible children, returns <code>null</code>, and retains the current 

  124.      * node.

  125.      * @return The new node, or <code>null</code> if the current node has no 

  126.      *   visible children  in the <code>TreeWalker</code>'s logical view.  

  127.      */

  128.     public Node firstChild();

  129. 

  130.     /**

  131.      * Moves the <code>TreeWalker</code> to the last visible child of the 

  132.      * current node, and returns the new node. If the current node has no 

  133.      * visible children, returns <code>null</code>, and retains the current 

  134.      * node.

  135.      * @return The new node, or <code>null</code> if the current node has no 

  136.      *   children  in the <code>TreeWalker</code>'s logical view.  

  137.      */

  138.     public Node lastChild();

  139. 

  140.     /**

  141.      * Moves the <code>TreeWalker</code> to the previous sibling of the 

  142.      * current node, and returns the new node. If the current node has no 

  143.      * visible previous sibling, returns <code>null</code>, and retains the 

  144.      * current node.

  145.      * @return The new node, or <code>null</code> if the current node has no 

  146.      *   previous sibling.  in the <code>TreeWalker</code>'s logical view.  

  147.      */

  148.     public Node previousSibling();

  149. 

  150.     /**

  151.      * Moves the <code>TreeWalker</code> to the next sibling of the current 

  152.      * node, and returns the new node. If the current node has no visible 

  153.      * next sibling, returns <code>null</code>, and retains the current node.

  154.      * @return The new node, or <code>null</code> if the current node has no 

  155.      *   next sibling.  in the <code>TreeWalker</code>'s logical view.  

  156.      */

  157.     public Node nextSibling();

  158. 

  159.     /**

  160.      * Moves the <code>TreeWalker</code> to the previous visible node in 

  161.      * document order relative to the current node, and returns the new 

  162.      * node. If the current node has no previous node,  or if the search for 

  163.      * <code>previousNode</code> attempts to step upward from the 

  164.      * <code>TreeWalker</code>'s <code>root</code> node,  returns 

  165.      * <code>null</code>, and retains the current node. 

  166.      * @return The new node, or <code>null</code> if the current node has no 

  167.      *   previous node  in the <code>TreeWalker</code>'s logical view.  

  168.      */

  169.     public Node previousNode();

  170. 

  171.     /**

  172.      * Moves the <code>TreeWalker</code> to the next visible node in document 

  173.      * order relative to the current node, and returns the new node. If the 

  174.      * current node has no next node, or if the search for nextNode attempts 

  175.      * to step upward from the <code>TreeWalker</code>'s <code>root</code> 

  176.      * node, returns <code>null</code>, and retains the current node.

  177.      * @return The new node, or <code>null</code> if the current node has no 

  178.      *   next node  in the <code>TreeWalker</code>'s logical view.  

  179.      */

  180.     public Node nextNode();

  181. 

  182. }