KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > jorphan > collections > HashTreeTraverser


1 // $Header: /home/cvs/jakarta-jmeter/src/jorphan/org/apache/jorphan/collections/HashTreeTraverser.java,v 1.3 2004/02/11 23:46:32 sebb Exp $
2 /*
3  * Copyright 2001-2004 The Apache Software Foundation.
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  *
17 */
18
19 package org.apache.jorphan.collections;
20
21 /**
22  * By implementing this interface, a class can easily traverse a HashTree
23  * object, and be notified via callbacks of certain events. There are three
24  * such events:
25  * <ol>
26  * <li>When a node is first encountered, the traverser's
27  * {@link #addNode(Object,HashTree)} method is called. It is handed the
28  * object at that node, and the entire sub-tree of the node.</li>
29  * <li>When a leaf node is encountered, the traverser is notified that a full
30  * path has been finished via the {@link #processPath()} method. It is
31  * the traversing class's responsibility to know the path that has just
32  * finished (this can be done by keeping a simple stack of all added
33  * nodes).</li>
34  * <li>When a node is retraced, the traverser's {@link #subtractNode()} is
35  * called. Again, it is the traverser's responsibility to know which
36  * node has been retraced.</li>
37  * </ol>
38  * To summarize, as the traversal goes down a tree path, nodes are added. When
39  * the end of the path is reached, the {@link #processPath()} call is sent. As
40  * the traversal backs up, nodes are subtracted.
41  * <p>
42  * The traversal is a depth-first traversal.
43  *
44  * @see HashTree
45  * @see SearchByClass
46  *
47  * @author Michael Stover (mstover1 at apache.org)
48  * @version $Revision: 1.3 $
49  */
50 public interface HashTreeTraverser
51 {
52     /**
53      * The tree traverses itself depth-first, calling addNode for each object
54      * it encounters as it goes. This is a callback method, and should not be
55      * called except by a HashTree during traversal.
56      *
57      * @param node the node currently encountered
58      * @param subTree the HashTree under the node encountered
59      */
60     public void addNode(Object JavaDoc node, HashTree subTree);
61
62     /**
63      * Indicates traversal has moved up a step, and the visitor should remove
64      * the top node from its stack structure. This is a callback method, and
65      * should not be called except by a HashTree during traversal.
66      */
67     public void subtractNode();
68
69     /**
70      * Process path is called when a leaf is reached. If a visitor wishes to
71      * generate Lists of path elements to each leaf, it should keep a Stack
72      * data structure of nodes passed to it with addNode, and removing top
73      * items for every {@link #subtractNode()} call. This is a callback
74      * method, and should not be called except by a HashTree during traversal.
75      */
76     public void processPath();
77 }
Popular Tags