1 package edu.uci.ics.jung.graph;
2
3 import java.util.Collection;
4
5 /**
6 * An interface for a graph which consists of a collection of rooted
7 * directed acyclic graphs.
8 *
9 * @author Joshua O'Madadhain
10 */
11 public interface Forest<V,E> extends DirectedGraph<V,E> {
12
13 /**
14 * Returns a view of this graph as a collection of <code>Tree</code> instances.
15 * @return a view of this graph as a collection of <code>Tree</code>s
16 */
17 Collection<Tree<V,E>> getTrees();
18
19 /**
20 * Returns the parent of <code>vertex</code> in this tree.
21 * (If <code>vertex</code> is the root, returns <code>null</code>.)
22 * The parent of a vertex is defined as being its predecessor in the
23 * (unique) shortest path from the root to this vertex.
24 * This is a convenience method which is equivalent to
25 * <code>Graph.getPredecessors(vertex).iterator().next()</code>.
26 * @return the parent of <code>vertex</code> in this tree
27 * @see Graph#getPredecessors(Object)
28 * @see #getParentEdge(Object)
29 */
30 public V getParent(V vertex);
31
32 /**
33 * Returns the edge connecting <code>vertex</code> to its parent in
34 * this tree.
35 * (If <code>vertex</code> is the root, returns <code>null</code>.)
36 * The parent of a vertex is defined as being its predecessor in the
37 * (unique) shortest path from the root to this vertex.
38 * This is a convenience method which is equivalent to
39 * <code>Graph.getInEdges(vertex).iterator().next()</code>,
40 * and also to <code>Graph.findEdge(vertex, getParent(vertex))</code>.
41 * @return the edge connecting <code>vertex</code> to its parent, or
42 * <code>null</code> if <code>vertex</code> is the root
43 * @see Graph#getInEdges(Object)
44 * @see #getParent(Object)
45 */
46 public E getParentEdge(V vertex);
47
48 /**
49 * Returns the children of <code>vertex</code> in this tree.
50 * The children of a vertex are defined as being the successors of
51 * that vertex on the respective (unique) shortest paths from the root to
52 * those vertices.
53 * This is syntactic (maple) sugar for <code>getSuccessors(vertex)</code>.
54 * @param vertex the vertex whose children are to be returned
55 * @return the <code>Collection</code> of children of <code>vertex</code>
56 * in this tree
57 * @see Graph#getSuccessors(Object)
58 * @see #getChildEdges(Object)
59 */
60 public Collection<V> getChildren(V vertex);
61
62 /**
63 * Returns the edges connecting <code>vertex</code> to its children
64 * in this tree.
65 * The children of a vertex are defined as being the successors of
66 * that vertex on the respective (unique) shortest paths from the root to
67 * those vertices.
68 * This is syntactic (maple) sugar for <code>getOutEdges(vertex)</code>.
69 * @param vertex the vertex whose child edges are to be returned
70 * @return the <code>Collection</code> of edges connecting
71 * <code>vertex</code> to its children in this tree
72 * @see Graph#getOutEdges(Object)
73 * @see #getChildren(Object)
74 */
75 public Collection<E> getChildEdges(V vertex);
76
77 /**
78 * Returns the number of children that <code>vertex</code> has in this tree.
79 * The children of a vertex are defined as being the successors of
80 * that vertex on the respective (unique) shortest paths from the root to
81 * those vertices.
82 * This is syntactic (maple) sugar for <code>getSuccessorCount(vertex)</code>.
83 * @param vertex the vertex whose child edges are to be returned
84 * @return the <code>Collection</code> of edges connecting
85 * <code>vertex</code> to its children in this tree
86 * @see #getChildEdges(Object)
87 * @see #getChildren(Object)
88 * @see Graph#getSuccessorCount(Object)
89 */
90 public int getChildCount(V vertex);
91 }