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:
013: package org.w3c.dom.traversal;
014:
015: import org.w3c.dom.Node;
016: import 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: */
036: public 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: * these children and their descendants will be rejected. Note that
062: * this 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:
092: /**
093: * The node at which the <code>TreeWalker</code> is currently positioned.
094: * <br>Alterations to the DOM tree may cause the current node to no longer
095: * be accepted by the <code>TreeWalker</code>'s associated filter.
096: * <code>currentNode</code> may also be explicitly set to any node,
097: * whether or not it is within the subtree specified by the
098: * <code>root</code> node or would be accepted by the filter and
099: * <code>whatToShow</code> flags. Further traversal occurs relative to
100: * <code>currentNode</code> even if it is not part of the current view,
101: * by applying the filters in the requested direction; if no traversal
102: * is possible, <code>currentNode</code> is not changed.
103: * @exception DOMException
104: * NOT_SUPPORTED_ERR: Raised if an attempt is made to set
105: * <code>currentNode</code> to <code>null</code>.
106: */
107: public void setCurrentNode(Node currentNode) 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: }
|