001/* 002 * Copyright (c) 2000 World Wide Web Consortium, 003 * (Massachusetts Institute of Technology, Institut National de 004 * Recherche en Informatique et en Automatique, Keio University). All 005 * Rights Reserved. This program is distributed under the W3C's Software 006 * Intellectual Property License. This program is distributed in the 007 * hope that it will be useful, but WITHOUT ANY WARRANTY; without even 008 * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 009 * PURPOSE. 010 * See W3C License http://www.w3.org/Consortium/Legal/ for more details. 011 */ 012 013package org.w3c.dom.traversal; 014 015import org.w3c.dom.Node; 016import org.w3c.dom.DOMException; 017 018/** 019 * <code>TreeWalker</code> objects are used to navigate a document tree or 020 * subtree using the view of the document defined by their 021 * <code>whatToShow</code> flags and filter (if any). Any function which 022 * performs navigation using a <code>TreeWalker</code> will automatically 023 * support any view defined by a <code>TreeWalker</code>. 024 * <p>Omitting nodes from the logical view of a subtree can result in a 025 * structure that is substantially different from the same subtree in the 026 * complete, unfiltered document. Nodes that are siblings in the 027 * <code>TreeWalker</code> view may be children of different, widely 028 * separated nodes in the original view. For instance, consider a 029 * <code>NodeFilter</code> that skips all nodes except for Text nodes and 030 * the root node of a document. In the logical view that results, all text 031 * nodes will be siblings and appear as direct children of the root node, no 032 * matter how deeply nested the structure of the original document. 033 * <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>. 034 * @since DOM Level 2 035 */ 036public interface TreeWalker { 037 /** 038 * The <code>root</code> node of the <code>TreeWalker</code>, as specified 039 * when it was created. 040 */ 041 public Node getRoot(); 042 043 /** 044 * This attribute determines which node types are presented via the 045 * <code>TreeWalker</code>. The available set of constants is defined in 046 * the <code>NodeFilter</code> interface. Nodes not accepted by 047 * <code>whatToShow</code> will be skipped, but their children may still 048 * be considered. Note that this skip takes precedence over the filter, 049 * if any. 050 */ 051 public int getWhatToShow(); 052 053 /** 054 * The filter used to screen nodes. 055 */ 056 public NodeFilter getFilter(); 057 058 /** 059 * The value of this flag determines whether the children of entity 060 * reference nodes are visible to the <code>TreeWalker</code>. If false, 061 * they and their descendants will be rejected. Note that this 062 * rejection takes precedence over <code>whatToShow</code> and the 063 * filter, if any. 064 * <br> To produce a view of the document that has entity references 065 * expanded and does not expose the entity reference node itself, use 066 * the <code>whatToShow</code> flags to hide the entity reference node 067 * and set <code>expandEntityReferences</code> to true when creating the 068 * <code>TreeWalker</code>. To produce a view of the document that has 069 * entity reference nodes but no entity expansion, use the 070 * <code>whatToShow</code> flags to show the entity reference node and 071 * set <code>expandEntityReferences</code> to false. 072 */ 073 public boolean getExpandEntityReferences(); 074 075 /** 076 * The node at which the <code>TreeWalker</code> is currently positioned. 077 * <br>Alterations to the DOM tree may cause the current node to no longer 078 * be accepted by the <code>TreeWalker</code>'s associated filter. 079 * <code>currentNode</code> may also be explicitly set to any node, 080 * whether or not it is within the subtree specified by the 081 * <code>root</code> node or would be accepted by the filter and 082 * <code>whatToShow</code> flags. Further traversal occurs relative to 083 * <code>currentNode</code> even if it is not part of the current view, 084 * by applying the filters in the requested direction; if no traversal 085 * is possible, <code>currentNode</code> is not changed. 086 * @exception DOMException 087 * NOT_SUPPORTED_ERR: Raised if an attempt is made to set 088 * <code>currentNode</code> to <code>null</code>. 089 */ 090 public Node getCurrentNode(); 091 public void setCurrentNode(Node currentNode) 092 throws DOMException; 093 094 /** 095 * Moves to and returns the closest visible ancestor node of the current 096 * node. If the search for <code>parentNode</code> attempts to step 097 * upward from the <code>TreeWalker</code>'s <code>root</code> node, or 098 * if it fails to find a visible ancestor node, this method retains the 099 * current position and returns <code>null</code>. 100 * @return The new parent node, or <code>null</code> if the current node 101 * has no parent in the <code>TreeWalker</code>'s logical view. 102 */ 103 public Node parentNode(); 104 105 /** 106 * Moves the <code>TreeWalker</code> to the first visible child of the 107 * current node, and returns the new node. If the current node has no 108 * visible children, returns <code>null</code>, and retains the current 109 * node. 110 * @return The new node, or <code>null</code> if the current node has no 111 * visible children in the <code>TreeWalker</code>'s logical view. 112 */ 113 public Node firstChild(); 114 115 /** 116 * Moves the <code>TreeWalker</code> to the last visible child of the 117 * current node, and returns the new node. If the current node has no 118 * visible children, returns <code>null</code>, and retains the current 119 * node. 120 * @return The new node, or <code>null</code> if the current node has no 121 * children in the <code>TreeWalker</code>'s logical view. 122 */ 123 public Node lastChild(); 124 125 /** 126 * Moves the <code>TreeWalker</code> to the previous sibling of the 127 * current node, and returns the new node. If the current node has no 128 * visible previous sibling, returns <code>null</code>, and retains the 129 * current node. 130 * @return The new node, or <code>null</code> if the current node has no 131 * previous sibling. in the <code>TreeWalker</code>'s logical view. 132 */ 133 public Node previousSibling(); 134 135 /** 136 * Moves the <code>TreeWalker</code> to the next sibling of the current 137 * node, and returns the new node. If the current node has no visible 138 * next sibling, returns <code>null</code>, and retains the current node. 139 * @return The new node, or <code>null</code> if the current node has no 140 * next sibling. in the <code>TreeWalker</code>'s logical view. 141 */ 142 public Node nextSibling(); 143 144 /** 145 * Moves the <code>TreeWalker</code> to the previous visible node in 146 * document order relative to the current node, and returns the new 147 * node. If the current node has no previous node, or if the search for 148 * <code>previousNode</code> attempts to step upward from the 149 * <code>TreeWalker</code>'s <code>root</code> node, returns 150 * <code>null</code>, and retains the current node. 151 * @return The new node, or <code>null</code> if the current node has no 152 * previous node in the <code>TreeWalker</code>'s logical view. 153 */ 154 public Node previousNode(); 155 156 /** 157 * Moves the <code>TreeWalker</code> to the next visible node in document 158 * order relative to the current node, and returns the new node. If the 159 * current node has no next node, or if the search for nextNode attempts 160 * to step upward from the <code>TreeWalker</code>'s <code>root</code> 161 * node, returns <code>null</code>, and retains the current node. 162 * @return The new node, or <code>null</code> if the current node has no 163 * next node in the <code>TreeWalker</code>'s logical view. 164 */ 165 public Node nextNode(); 166 167}