001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2002-2006, GeoTools Project Managment Committee (PMC)
005: * (C) 2002, Refractions Reserach Inc.
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation;
010: * version 2.1 of the License.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: */
017: package org.geotools.graph.traverse;
018:
019: import org.geotools.graph.structure.Graph;
020: import org.geotools.graph.structure.Graphable;
021:
022: /**
023: * Iterates a GraphWalker over the
024: * components of a Graph. The order in which components are iterated over
025: * is determined by the GraphIterator class. The GraphTraversal is
026: * the mediator between the GraphWalker and the GraphIterator.<BR>
027: * <BR>
028: * Upon each visitation, the GraphWalker communicates to the GraphTraversal
029: * through a series of return codes, each specifying a different action to
030: * perform at that point of the travesal. The following summarizes the meaning
031: * of the codes.<BR>
032: * <BR>
033: * <TABLE border="1" width="60%" style="font-family:Arial;font-size=10pt">
034: * <TH width="20%">Code</TH>
035: * <TH width="40%">Action Taken</TH>
036: * <TR>
037: * <TD align="center">CONTINUE</TD>
038: * <TD>The traversal continues as normal.</TD>
039: * </TR>
040: * <TR>
041: * <TD align="center"f>SUSPEND</TD>
042: * <TD>Suspends the traversal at some intermediate stage. This code
043: * should be returned if the traversal is intended to be resumed.</TD>
044: * </TR>
045: * <TR>
046: * <TD align="center">KILL_BRANCH</TD>
047: * <TD>Kills the current branch of the traversal. Depending on the iteration
048: * algorithm, returning this code may end the traversal.</TD>
049: * </TR>
050: * <TR>
051: * <TD align="center">STOP</TD>
052: * <TD>Stops the traversal.</TD>
053: * </TR>
054: * </TABLE>
055: * <BR>
056: * <BR>
057: * GraphTraversals are started with a call to traverse(). If the traversal is
058: * suspended at some intermediate point, an additional call to traverse() will
059: * resume the traversal.<BR>
060: * <BR>
061: *
062: * @see GraphWalker
063: * @see GraphIterator
064: * @see Graph
065: *
066: * @author Justin Deoliveira, Refractions Research Inc, jdeolive@refractions.net
067: *
068: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/extension/graph/src/main/java/org/geotools/graph/traverse/GraphTraversal.java $
069: */
070: public interface GraphTraversal {
071:
072: /** Signals the traversal to continue **/
073: public static int CONTINUE = 0;
074:
075: /** Signals the traversal to suspend at some intermediate point **/
076: public static int SUSPEND = 1;
077:
078: /** Signals the traversal to kill the current branch **/
079: public static int KILL_BRANCH = 2;
080:
081: /** Signals the traversal to stop **/
082: public static int STOP = 3;
083:
084: /**
085: *
086: * Sets the graph being traversed.
087: *
088: * @param graph The graph whose components are being traversed.
089: */
090: public void setGraph(Graph graph);
091:
092: /**
093: * Returns the graph being traversed.
094: *
095: * @return The graph whose components are being traversed.
096: *
097: * @see Graph
098: */
099: public Graph getGraph();
100:
101: /**
102: * Sets the iterator that specifies the order in which visit graph components.
103: *
104: * @param iterator The iterator over the graph components.
105: */
106: public void setIterator(GraphIterator iterator);
107:
108: /**
109: * Returns the iterator that specifies the order in which to visit graph
110: * components.
111: *
112: * @return The iterator over the graph components.
113: *
114: * @see GraphIterator
115: */
116: public GraphIterator getIterator();
117:
118: /**
119: * Sets the walker (visitor) traversing the graph.
120: *
121: * @param walker The walker being iterated over the components of the graph.
122: */
123: public void setWalker(GraphWalker walker);
124:
125: /**
126: * Returns the walker (visitor) traversing the graph of the graph.
127: *
128: * @return The walker being iterated over the components.
129: */
130: public GraphWalker getWalker();
131:
132: /**
133: * Initializes the traversal.
134: */
135: public void init();
136:
137: /**
138: * Starts or resumes a traversal over the components of a graph.
139: */
140: public void traverse();
141:
142: //TODO:DOCUMENT ME!
143: public boolean isVisited(Graphable g);
144:
145: //TODO:DOCUMENT ME!
146: public void setVisited(Graphable g, boolean visited);
147: }
|