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
10 * See W3C License http://www.w3.org/Consortium/Legal/ for more details.
13 package org.w3c.dom.traversal;
15 import org.w3c.dom.Node;
16 import org.w3c.dom.DOMException;
19 * <code>DocumentTraversal</code> contains methods that create
20 * <code>NodeIterators</code> and <code>TreeWalkers</code> to traverse a
21 * node and its children in document order (depth first, pre-order
22 * traversal, which is equivalent to the order in which the start tags occur
23 * in the text representation of the document). In DOMs which support the
24 * Traversal feature, <code>DocumentTraversal</code> will be implemented by
25 * the same objects that implement the Document interface.
26 * <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>.
29 public interface DocumentTraversal {
31 * Create a new <code>NodeIterator</code> over the subtree rooted at the
33 * @param root The node which will be iterated together with its
34 * children. The <code>NodeIterator</code> is initially positioned
35 * just before this node. The <code>whatToShow</code> flags and the
36 * filter, if any, are not considered when setting this position. The
37 * root must not be <code>null</code>.
38 * @param whatToShow This flag specifies which node types may appear in
39 * the logical view of the tree presented by the
40 * <code>NodeIterator</code>. See the description of
41 * <code>NodeFilter</code> for the set of possible <code>SHOW_</code>
42 * values.These flags can be combined using <code>OR</code>.
43 * @param filter The <code>NodeFilter</code> to be used with this
44 * <code>NodeIterator</code>, or <code>null</code> to indicate no
46 * @param entityReferenceExpansion The value of this flag determines
47 * whether entity reference nodes are expanded.
48 * @return The newly created <code>NodeIterator</code>.
49 * @exception DOMException
50 * NOT_SUPPORTED_ERR: Raised if the specified <code>root</code> is
53 public NodeIterator createNodeIterator(Node root,
56 boolean entityReferenceExpansion)
60 * Create a new <code>TreeWalker</code> over the subtree rooted at the
62 * @param root The node which will serve as the <code>root</code> for the
63 * <code>TreeWalker</code>. The <code>whatToShow</code> flags and the
64 * <code>NodeFilter</code> are not considered when setting this value;
65 * any node type will be accepted as the <code>root</code>. The
66 * <code>currentNode</code> of the <code>TreeWalker</code> is
67 * initialized to this node, whether or not it is visible. The
68 * <code>root</code> functions as a stopping point for traversal
69 * methods that look upward in the document structure, such as
70 * <code>parentNode</code> and nextNode. The <code>root</code> must
71 * not be <code>null</code>.
72 * @param whatToShow This flag specifies which node types may appear in
73 * the logical view of the tree presented by the
74 * <code>TreeWalker</code>. See the description of
75 * <code>NodeFilter</code> for the set of possible <code>SHOW_</code>
76 * values.These flags can be combined using <code>OR</code>.
77 * @param filter The <code>NodeFilter</code> to be used with this
78 * <code>TreeWalker</code>, or <code>null</code> to indicate no filter.
79 * @param entityReferenceExpansion If this flag is false, the contents of
80 * <code>EntityReference</code> nodes are not presented in the logical
82 * @return The newly created <code>TreeWalker</code>.
83 * @exception DOMException
84 * NOT_SUPPORTED_ERR: Raised if the specified <code>root</code> is
87 public TreeWalker createTreeWalker(Node root,
90 boolean entityReferenceExpansion)