01: /*
02: * Licensed to the Apache Software Foundation (ASF) under one or more
03: * contributor license agreements. See the NOTICE file distributed with
04: * this work for additional information regarding copyright ownership.
05: * The ASF licenses this file to You under the Apache License, Version 2.0
06: * (the "License"); you may not use this file except in compliance with
07: * the License. You may obtain a copy of the License at
08: *
09: * 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 such
24: * 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 object
28: * 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 the
31: * traversing class's responsibility to know the path that has just finished
32: * (this can be done by keeping a simple stack of all added nodes).</li>
33: * <li>When a node is retraced, the traverser's {@link #subtractNode()} is
34: * called. Again, it is the traverser's responsibility to know which node has
35: * been retraced.</li>
36: * </ol>
37: * To summarize, as the traversal goes down a tree path, nodes are added. When
38: * the end of the path is reached, the {@link #processPath()} call is sent. As
39: * the traversal backs up, nodes are subtracted.
40: * <p>
41: * The traversal is a depth-first traversal.
42: *
43: * @see HashTree
44: * @see SearchByClass
45: *
46: * @author Michael Stover (mstover1 at apache.org)
47: * @version $Revision: 493784 $
48: */
49: public interface HashTreeTraverser {
50: /**
51: * The tree traverses itself depth-first, calling addNode for each object it
52: * encounters as it goes. This is a callback method, and should not be
53: * called except by a HashTree during traversal.
54: *
55: * @param node
56: * the node currently encountered
57: * @param subTree
58: * the HashTree under the node encountered
59: */
60: public void addNode(Object 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 data
72: * structure of nodes passed to it with addNode, and removing top items for
73: * every {@link #subtractNode()} call. This is a callback method, and should
74: * not be called except by a HashTree during traversal.
75: */
76: public void processPath();
77: }
|