package graph;

/**
 * A GraphVisitor is escorted to the edges and vertices of a graph in a
 * graph search.
 * While being escorted, a graph visitor is notified of events of the search by
 * invoking the methods declared here.
 * It is expected that a graph visitor will record vertex visitations so a
 * graph search method will invoke its isVisited() method to find out if a
 * vertex has already been visited.
 *
 * This is an abstract class.
 * Concrete subclasses must provide an implementation of the isVisited() method.
 * The other methods are implemented with default implementations that do
 * nothing.
 * The visitVertex() method is implemented to return true so that a search will
 * continue until its dispenser is empty.
 */
public abstract class GraphVisitor {

  /**
   * gv.enqueueEdge(edge) notifies gv that a search has enqueued edge.
   * The default implementation does nothing.
   * @param edge the enqueued edge
   */
  public void enqueueEdge(Object edge) {
  }

  /**
   * gv.visitEdge(edge) notifies gv that a search has visited edge because it
   * led to an unvisited vertex.
   * The default implementation does nothing.
   * @param edge the visited edge
   * @param edge
   */
  public void visitEdge(Object edge) {
  }

  /**
   * gv.discardEdge(edge) notifies gv that a search has discarded edge because
   * it led to a vertex that has already been visited.
   * The default implementation does nothing.
   * @param edge the discarded edge
   * @param edge
   */
  public void discardEdge(Object edge) {
  }

  /**
   * gv.visitVertex(vertex) notifies gv that a search has visited vertex.
   * gv can terminate the search by returning false.
   * It should return true if the search should continue.
   * The default implementation always returns true;
   * @param vertex
   * @return true if the search should continue
   */
  public boolean visitVertex(Object vertex) {
    return true;
  }

  /**
   * gv.isVisited(vertex) is invoked by a graph search to determine if vertex
   * has already been visited.
   * If so, the edge that led to vertex will be discarded and vertex will not be
   * visited.
   * If not, the edge that led to vertex will be visited.
   * Then vertex will be visited and edges that originate from vertex will be
   * enqueued.
   * @param vertex
   * @return true if vertex has been visited
   */
  public abstract boolean isVisited(Object vertex);

}