1 /*
2 * Created on Oct 17, 2005
3 *
4 * Copyright (c) 2005, The JUNG Authors
5 *
6 * All rights reserved.
7 *
8 * This software is open-source under the BSD license; see either
9 * "license.txt" or
10 * https://github.com/jrtom/jung/blob/master/LICENSE for a description.
11 */
12 package edu.uci.ics.jung.graph;
13
14 import java.util.Collection;
15
16 import edu.uci.ics.jung.graph.util.EdgeType;
17 import edu.uci.ics.jung.graph.util.Pair;
18
19
20 /**
21 * A graph consisting of a set of vertices of type <code>V</code>
22 * set and a set of edges of type <code>E</code>. Edges of this
23 * graph type have exactly two endpoints; whether these endpoints
24 * must be distinct depends on the implementation.
25 * <P>
26 * This interface permits, but does not enforce, any of the following
27 * common variations of graphs:
28 * <ul>
29 * <li> directed and undirected edges
30 * <li> vertices and edges with attributes (for example, weighted edges)
31 * <li> vertices and edges of different types (for example, bipartite
32 * or multimodal graphs)
33 * <li> parallel edges (multiple edges which connect a single set of vertices)
34 * <li> representations as matrices or as adjacency lists or adjacency maps
35 * </ul>
36 * Extensions or implementations of this interface
37 * may enforce or disallow any or all of these variations.
38 *
39 * <p>Definitions (with respect to a given vertex <code>v</code>):
40 * <ul>
41 * <li><b>incoming edge</b> of <code>v</code>: an edge that can be traversed
42 * from a neighbor of <code>v</code> to reach <code>v</code>
43 * <li><b>outgoing edge</b> of <code>v</code>: an edge that can be traversed
44 * from <code>v</code> to reach some neighbor of <code>v</code>
45 * <li><b>predecessor</b> of <code>v</code>: a vertex at the other end of an
46 * incoming edge of <code>v</code>
47 * <li><b>successor</b> of <code>v</code>: a vertex at the other end of an
48 * outgoing edge of <code>v</code>
49 * <li>
50 * </ul>
51 *
52 * @author Joshua O'Madadhain
53 */
54 public interface Graph<V,E> extends Hypergraph<V,E>
55 {
56 /**
57 * Returns a <code>Collection</code> view of the incoming edges incident to <code>vertex</code>
58 * in this graph.
59 * @param vertex the vertex whose incoming edges are to be returned
60 * @return a <code>Collection</code> view of the incoming edges incident
61 * to <code>vertex</code> in this graph
62 */
63 Collection<E> getInEdges(V vertex);
64
65 /**
66 * Returns a <code>Collection</code> view of the outgoing edges incident to <code>vertex</code>
67 * in this graph.
68 * @param vertex the vertex whose outgoing edges are to be returned
69 * @return a <code>Collection</code> view of the outgoing edges incident
70 * to <code>vertex</code> in this graph
71 */
72 Collection<E> getOutEdges(V vertex);
73
74 /**
75 * Returns a <code>Collection</code> view of the predecessors of <code>vertex</code>
76 * in this graph. A predecessor of <code>vertex</code> is defined as a vertex <code>v</code>
77 * which is connected to
78 * <code>vertex</code> by an edge <code>e</code>, where <code>e</code> is an outgoing edge of
79 * <code>v</code> and an incoming edge of <code>vertex</code>.
80 * @param vertex the vertex whose predecessors are to be returned
81 * @return a <code>Collection</code> view of the predecessors of
82 * <code>vertex</code> in this graph
83 */
84 Collection<V> getPredecessors(V vertex);
85
86 /**
87 * Returns a <code>Collection</code> view of the successors of <code>vertex</code>
88 * in this graph. A successor of <code>vertex</code> is defined as a vertex <code>v</code>
89 * which is connected to
90 * <code>vertex</code> by an edge <code>e</code>, where <code>e</code> is an incoming edge of
91 * <code>v</code> and an outgoing edge of <code>vertex</code>.
92 * @param vertex the vertex whose predecessors are to be returned
93 * @return a <code>Collection</code> view of the successors of
94 * <code>vertex</code> in this graph
95 */
96 Collection<V> getSuccessors(V vertex);
97
98 /**
99 * Returns the number of incoming edges incident to <code>vertex</code>.
100 * Equivalent to <code>getInEdges(vertex).size()</code>.
101 * @param vertex the vertex whose indegree is to be calculated
102 * @return the number of incoming edges incident to <code>vertex</code>
103 */
104 int inDegree(V vertex);
105
106 /**
107 * Returns the number of outgoing edges incident to <code>vertex</code>.
108 * Equivalent to <code>getOutEdges(vertex).size()</code>.
109 * @param vertex the vertex whose outdegree is to be calculated
110 * @return the number of outgoing edges incident to <code>vertex</code>
111 */
112 int outDegree(V vertex);
113
114 /**
115 * Returns <code>true</code> if <code>v1</code> is a predecessor of <code>v2</code> in this graph.
116 * Equivalent to <code>v1.getPredecessors().contains(v2)</code>.
117 * @param v1 the first vertex to be queried
118 * @param v2 the second vertex to be queried
119 * @return <code>true</code> if <code>v1</code> is a predecessor of <code>v2</code>, and false otherwise.
120 */
121 boolean isPredecessor(V v1, V v2);
122
123 /**
124 * Returns <code>true</code> if <code>v1</code> is a successor of <code>v2</code> in this graph.
125 * Equivalent to <code>v1.getSuccessors().contains(v2)</code>.
126 * @param v1 the first vertex to be queried
127 * @param v2 the second vertex to be queried
128 * @return <code>true</code> if <code>v1</code> is a successor of <code>v2</code>, and false otherwise.
129 */
130 boolean isSuccessor(V v1, V v2);
131
132 /**
133 * Returns the number of predecessors that <code>vertex</code> has in this graph.
134 * Equivalent to <code>vertex.getPredecessors().size()</code>.
135 * @param vertex the vertex whose predecessor count is to be returned
136 * @return the number of predecessors that <code>vertex</code> has in this graph
137 */
138 int getPredecessorCount(V vertex);
139
140 /**
141 * Returns the number of successors that <code>vertex</code> has in this graph.
142 * Equivalent to <code>vertex.getSuccessors().size()</code>.
143 * @param vertex the vertex whose successor count is to be returned
144 * @return the number of successors that <code>vertex</code> has in this graph
145 */
146 int getSuccessorCount(V vertex);
147
148 /**
149 * If <code>directed_edge</code> is a directed edge in this graph, returns the source;
150 * otherwise returns <code>null</code>.
151 * The source of a directed edge <code>d</code> is defined to be the vertex for which
152 * <code>d</code> is an outgoing edge.
153 * <code>directed_edge</code> is guaranteed to be a directed edge if
154 * its <code>EdgeType</code> is <code>DIRECTED</code>.
155 * @param directed_edge the edge whose source is to be returned
156 * @return the source of <code>directed_edge</code> if it is a directed edge in this graph, or <code>null</code> otherwise
157 */
158 V getSource(E directed_edge);
159
160 /**
161 * If <code>directed_edge</code> is a directed edge in this graph, returns the destination;
162 * otherwise returns <code>null</code>.
163 * The destination of a directed edge <code>d</code> is defined to be the vertex
164 * incident to <code>d</code> for which
165 * <code>d</code> is an incoming edge.
166 * <code>directed_edge</code> is guaranteed to be a directed edge if
167 * its <code>EdgeType</code> is <code>DIRECTED</code>.
168 * @param directed_edge the edge whose destination is to be returned
169 * @return the destination of <code>directed_edge</code> if it is a directed edge in this graph, or <code>null</code> otherwise
170 */
171 V getDest(E directed_edge);
172
173 /**
174 * Returns <code>true</code> if <code>vertex</code> is the source of <code>edge</code>.
175 * Equivalent to <code>getSource(edge).equals(vertex)</code>.
176 * @param vertex the vertex to be queried
177 * @param edge the edge to be queried
178 * @return <code>true</code> iff <code>vertex</code> is the source of <code>edge</code>
179 */
180 boolean isSource(V vertex, E edge);
181
182 /**
183 * Returns <code>true</code> if <code>vertex</code> is the destination of <code>edge</code>.
184 * Equivalent to <code>getDest(edge).equals(vertex)</code>.
185 * @param vertex the vertex to be queried
186 * @param edge the edge to be queried
187 * @return <code>true</code> iff <code>vertex</code> is the destination of <code>edge</code>
188 */
189 boolean isDest(V vertex, E edge);
190
191 /**
192 * Adds edge <code>e</code> to this graph such that it connects
193 * vertex <code>v1</code> to <code>v2</code>.
194 * Equivalent to <code>addEdge(e, new Pair(v1, v2))</code>.
195 * If this graph does not contain <code>v1</code>, <code>v2</code>,
196 * or both, implementations may choose to either silently add
197 * the vertices to the graph or throw an <code>IllegalArgumentException</code>.
198 * If this graph assigns edge types to its edges, the edge type of
199 * <code>e</code> will be the default for this graph.
200 * See <code>Hypergraph.addEdge()</code> for a listing of possible reasons
201 * for failure.
202 * @param e the edge to be added
203 * @param v1 the first vertex to be connected
204 * @param v2 the second vertex to be connected
205 * @return <code>true</code> if the add is successful, <code>false</code> otherwise
206 * @see Hypergraph#addEdge(Object, Collection)
207 * @see #addEdge(Object, Object, Object, EdgeType)
208 */
209 boolean addEdge(E e, V v1, V v2);
210
211 /**
212 * Adds edge <code>e</code> to this graph such that it connects
213 * vertex <code>v1</code> to <code>v2</code>.
214 * Equivalent to <code>addEdge(e, new Pair(v1, v2))</code>.
215 * If this graph does not contain <code>v1</code>, <code>v2</code>,
216 * or both, implementations may choose to either silently add
217 * the vertices to the graph or throw an <code>IllegalArgumentException</code>.
218 * If <code>edgeType</code> is not legal for this graph, this method will
219 * throw <code>IllegalArgumentException</code>.
220 * See <code>Hypergraph.addEdge()</code> for a listing of possible reasons
221 * for failure.
222 * @param e the edge to be added
223 * @param v1 the first vertex to be connected
224 * @param v2 the second vertex to be connected
225 * @param edgeType the type to be assigned to the edge
226 * @return <code>true</code> if the add is successful, <code>false</code> otherwise
227 * @see Hypergraph#addEdge(Object, Collection)
228 * @see #addEdge(Object, Object, Object)
229 */
230 boolean addEdge(E e, V v1, V v2, EdgeType edgeType);
231
232 /**
233 * Returns the endpoints of <code>edge</code> as a <code>Pair</code>.
234 * @param edge the edge whose endpoints are to be returned
235 * @return the endpoints (incident vertices) of <code>edge</code>
236 */
237 Pair<V> getEndpoints(E edge);
238
239 /**
240 * Returns the vertex at the other end of <code>edge</code> from <code>vertex</code>.
241 * (That is, returns the vertex incident to <code>edge</code> which is not <code>vertex</code>.)
242 * @param vertex the vertex to be queried
243 * @param edge the edge to be queried
244 * @return the vertex at the other end of <code>edge</code> from <code>vertex</code>
245 */
246 V getOpposite(V vertex, E edge);
247 }