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 *
27 * @param vertex the vertex whose parent is to be returned
28 * @return the parent of <code>vertex</code> in this tree
29 * @see Graph#getPredecessors(Object)
30 * @see #getParentEdge(Object)
31 */
32 public V getParent(V vertex);
33
34 /**
35 * Returns the edge connecting <code>vertex</code> to its parent in
36 * this tree.
37 * (If <code>vertex</code> is the root, returns <code>null</code>.)
38 * The parent of a vertex is defined as being its predecessor in the
39 * (unique) shortest path from the root to this vertex.
40 * This is a convenience method which is equivalent to
41 * <code>Graph.getInEdges(vertex).iterator().next()</code>,
42 * and also to <code>Graph.findEdge(vertex, getParent(vertex))</code>.
43 *
44 * @param vertex the vertex whose incoming edge is to be returned
45 * @return the edge connecting <code>vertex</code> to its parent, or
46 * <code>null</code> if <code>vertex</code> is the root
47 *
48 * @see Graph#getInEdges(Object)
49 * @see #getParent(Object)
50 */
51 public E getParentEdge(V vertex);
52
53 /**
54 * Returns the children of <code>vertex</code> in this tree.
55 * The children of a vertex are defined as being the successors of
56 * that vertex on the respective (unique) shortest paths from the root to
57 * those vertices.
58 * This is syntactic (maple) sugar for <code>getSuccessors(vertex)</code>.
59 * @param vertex the vertex whose children are to be returned
60 * @return the <code>Collection</code> of children of <code>vertex</code>
61 * in this tree
62 * @see Graph#getSuccessors(Object)
63 * @see #getChildEdges(Object)
64 */
65 public Collection<V> getChildren(V vertex);
66
67 /**
68 * Returns the edges connecting <code>vertex</code> to its children
69 * in this tree.
70 * The children of a vertex are defined as being the successors of
71 * that vertex on the respective (unique) shortest paths from the root to
72 * those vertices.
73 * This is syntactic (maple) sugar for <code>getOutEdges(vertex)</code>.
74 * @param vertex the vertex whose child edges are to be returned
75 * @return the <code>Collection</code> of edges connecting
76 * <code>vertex</code> to its children in this tree
77 * @see Graph#getOutEdges(Object)
78 * @see #getChildren(Object)
79 */
80 public Collection<E> getChildEdges(V vertex);
81
82 /**
83 * Returns the number of children that <code>vertex</code> has in this tree.
84 * The children of a vertex are defined as being the successors of
85 * that vertex on the respective (unique) shortest paths from the root to
86 * those vertices.
87 * This is syntactic (maple) sugar for <code>getSuccessorCount(vertex)</code>.
88 * @param vertex the vertex whose child edges are to be returned
89 * @return the <code>Collection</code> of edges connecting
90 * <code>vertex</code> to its children in this tree
91 * @see #getChildEdges(Object)
92 * @see #getChildren(Object)
93 * @see Graph#getSuccessorCount(Object)
94 */
95 public int getChildCount(V vertex);
96 }