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>DocumentTraversal</code> contains methods that create 
020     * <code>NodeIterators</code> and <code>TreeWalkers</code> to traverse a 
021     * node and its children in document order (depth first, pre-order 
022     * traversal, which is equivalent to the order in which the start tags occur 
023     * in the text representation of the document). In DOMs which support the 
024     * Traversal feature, <code>DocumentTraversal</code> will be implemented by 
025     * the same objects that implement the Document interface.
026     * <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>.
027     * @since DOM Level 2
028     */
029    public interface DocumentTraversal {
030        /**
031         * Create a new <code>NodeIterator</code> over the subtree rooted at the 
032         * specified node.
033         * @param root The node which will be iterated together with its 
034         *   children. The <code>NodeIterator</code> is initially positioned 
035         *   just before this node. The <code>whatToShow</code> flags and the 
036         *   filter, if any, are not considered when setting this position. The 
037         *   root must not be <code>null</code>.
038         * @param whatToShow This flag specifies which node types may appear in 
039         *   the logical view of the tree presented by the 
040         *   <code>NodeIterator</code>. See the description of 
041         *   <code>NodeFilter</code> for the set of possible <code>SHOW_</code> 
042         *   values.These flags can be combined using <code>OR</code>.
043         * @param filter The <code>NodeFilter</code> to be used with this 
044         *   <code>NodeIterator</code>, or <code>null</code> to indicate no 
045         *   filter.
046         * @param entityReferenceExpansion The value of this flag determines 
047         *   whether entity reference nodes are expanded.
048         * @return The newly created <code>NodeIterator</code>.
049         * @exception DOMException
050         *   NOT_SUPPORTED_ERR: Raised if the specified <code>root</code> is 
051         *   <code>null</code>.
052         */
053        public NodeIterator createNodeIterator(Node root, 
054                                               int whatToShow, 
055                                               NodeFilter filter, 
056                                               boolean entityReferenceExpansion)
057                                               throws DOMException;
058    
059        /**
060         * Create a new <code>TreeWalker</code> over the subtree rooted at the 
061         * specified node.
062         * @param root The node which will serve as the <code>root</code> for the 
063         *   <code>TreeWalker</code>. The <code>whatToShow</code> flags and the 
064         *   <code>NodeFilter</code> are not considered when setting this value; 
065         *   any node type will be accepted as the <code>root</code>. The 
066         *   <code>currentNode</code> of the <code>TreeWalker</code> is 
067         *   initialized to this node, whether or not it is visible. The 
068         *   <code>root</code> functions as a stopping point for traversal 
069         *   methods that look upward in the document structure, such as 
070         *   <code>parentNode</code> and nextNode. The <code>root</code> must 
071         *   not be <code>null</code>.
072         * @param whatToShow This flag specifies which node types may appear in 
073         *   the logical view of the tree presented by the 
074         *   <code>TreeWalker</code>. See the description of 
075         *   <code>NodeFilter</code> for the set of possible <code>SHOW_</code> 
076         *   values.These flags can be combined using <code>OR</code>.
077         * @param filter The <code>NodeFilter</code> to be used with this 
078         *   <code>TreeWalker</code>, or <code>null</code> to indicate no filter.
079         * @param entityReferenceExpansion If this flag is false, the contents of 
080         *   <code>EntityReference</code> nodes are not presented in the logical 
081         *   view.
082         * @return The newly created <code>TreeWalker</code>.
083         * @exception DOMException
084         *    NOT_SUPPORTED_ERR: Raised if the specified <code>root</code> is 
085         *   <code>null</code>.
086         */
087        public TreeWalker createTreeWalker(Node root, 
088                                           int whatToShow, 
089                                           NodeFilter filter, 
090                                           boolean entityReferenceExpansion)
091                                           throws DOMException;
092    
093    }