Forest.java

package edu.uci.ics.jung.graph;

import java.util.Collection;

/**
 * An interface for a graph which consists of a collection of rooted directed
 * acyclic graphs.
 * 
 * @author Joshua O'Madadhain
 */
public interface Forest<V, E> extends DirectedGraph<V, E> {

	/**
	 * Returns a view of this graph as a collection of <code>Tree</code>
	 * instances.
	 * 
	 * @return a view of this graph as a collection of <code>Tree</code>s
	 */
	Collection<Tree<V, E>> getTrees();

	/**
	 * Returns the parent of <code>vertex</code> in this tree. (If
	 * <code>vertex</code> is the root, returns <code>null</code>.) The parent
	 * of a vertex is defined as being its predecessor in the (unique) shortest
	 * path from the root to this vertex. This is a convenience method which is
	 * equivalent to
	 * <code>Graph.getPredecessors(vertex).iterator().next()</code>.
	 * 
	 * @return the parent of <code>vertex</code> in this tree
	 * @see Graph#getPredecessors(Object)
	 * @see #getParentEdge(Object)
	 */
	public V getParent(V vertex);

	/**
	 * Returns the edge connecting <code>vertex</code> to its parent in this
	 * tree. (If <code>vertex</code> is the root, returns <code>null</code>.)
	 * The parent of a vertex is defined as being its predecessor in the
	 * (unique) shortest path from the root to this vertex. This is a
	 * convenience method which is equivalent to
	 * <code>Graph.getInEdges(vertex).iterator().next()</code>, and also to
	 * <code>Graph.findEdge(vertex, getParent(vertex))</code>.
	 * 
	 * @return the edge connecting <code>vertex</code> to its parent, or
	 *         <code>null</code> if <code>vertex</code> is the root
	 * @see Graph#getInEdges(Object)
	 * @see #getParent(Object)
	 */
	public E getParentEdge(V vertex);

	/**
	 * Returns the children of <code>vertex</code> in this tree. The children of
	 * a vertex are defined as being the successors of that vertex on the
	 * respective (unique) shortest paths from the root to those vertices. This
	 * is syntactic (maple) sugar for <code>getSuccessors(vertex)</code>.
	 * 
	 * @param vertex
	 *            the vertex whose children are to be returned
	 * @return the <code>Collection</code> of children of <code>vertex</code> in
	 *         this tree
	 * @see Graph#getSuccessors(Object)
	 * @see #getChildEdges(Object)
	 */
	public Collection<V> getChildren(V vertex);

	/**
	 * Returns the edges connecting <code>vertex</code> to its children in this
	 * tree. The children of a vertex are defined as being the successors of
	 * that vertex on the respective (unique) shortest paths from the root to
	 * those vertices. This is syntactic (maple) sugar for
	 * <code>getOutEdges(vertex)</code>.
	 * 
	 * @param vertex
	 *            the vertex whose child edges are to be returned
	 * @return the <code>Collection</code> of edges connecting
	 *         <code>vertex</code> to its children in this tree
	 * @see Graph#getOutEdges(Object)
	 * @see #getChildren(Object)
	 */
	public Collection<E> getChildEdges(V vertex);

	/**
	 * Returns the number of children that <code>vertex</code> has in this tree.
	 * The children of a vertex are defined as being the successors of that
	 * vertex on the respective (unique) shortest paths from the root to those
	 * vertices. This is syntactic (maple) sugar for
	 * <code>getSuccessorCount(vertex)</code>.
	 * 
	 * @param vertex
	 *            the vertex whose child edges are to be returned
	 * @return the <code>Collection</code> of edges connecting
	 *         <code>vertex</code> to its children in this tree
	 * @see #getChildEdges(Object)
	 * @see #getChildren(Object)
	 * @see Graph#getSuccessorCount(Object)
	 */
	public int getChildCount(V vertex);
}