org.jgrapht.Graph Maven / Gradle / Ivy
/* ==========================================
* JGraphT : a free Java graph-theory library
* ==========================================
*
* Project Info: http://jgrapht.sourceforge.net/
* Project Creator: Barak Naveh (http://sourceforge.net/users/barak_naveh)
*
* (C) Copyright 2003-2008, by Barak Naveh and Contributors.
*
* This program and the accompanying materials are dual-licensed under
* either
*
* (a) the terms of the GNU Lesser General Public License version 2.1
* as published by the Free Software Foundation, or (at your option) any
* later version.
*
* or (per the licensee's choosing)
*
* (b) the terms of the Eclipse Public License v1.0 as published by
* the Eclipse Foundation.
*/
/* ----------
* Graph.java
* ----------
* (C) Copyright 2003-2008, by Barak Naveh and Contributors.
*
* Original Author: Barak Naveh
* Contributor(s): John V. Sichi
* Christian Hammer
*
* $Id$
*
* Changes
* -------
* 24-Jul-2003 : Initial revision (BN);
* 06-Nov-2003 : Change edge sharing semantics (JVS);
* 11-Mar-2004 : Made generic (CH);
* 07-May-2006 : Changed from List to Set (JVS);
* 28-May-2006 : Moved connectivity info from edge to graph (JVS);
*
*/
package org.jgrapht;
import java.util.*;
/**
* The root interface in the graph hierarchy. A mathematical graph-theory graph
* object G(V,E) contains a set V of vertices and a set
* E of edges. Each edge e=(v1,v2) in E connects vertex v1 to vertex v2.
* for more information about graphs and their related definitions see
* http://mathworld.wolfram.com/Graph.html.
*
* This library generally follows the terminology found at:
* http://mathworld.wolfram.com/topics/GraphTheory.html. Implementation of
* this interface can provide simple-graphs, multigraphs, pseudographs etc. The
* package org.jgrapht.graph provides a gallery of abstract and
* concrete graph implementations.
*
* This library works best when vertices represent arbitrary objects and
* edges represent the relationships between them. Vertex and edge instances may
* be shared by more than one graph.
*
* Through generics, a graph can be typed to specific classes for vertices
* V and edges E<T>. Such a graph can contain
* vertices of type V and all sub-types and Edges of type
* E and all sub-types.
*
* For guidelines on vertex and edge classes, see this wiki
* page.
*
* @author Barak Naveh
* @since Jul 14, 2003
*/
public interface Graph
{
/**
* Returns a set of all edges connecting source vertex to target vertex if
* such vertices exist in this graph. If any of the vertices does not exist
* or is null, returns null. If both vertices
* exist but no edges found, returns an empty set.
*
* In undirected graphs, some of the returned edges may have their source
* and target vertices in the opposite order. In simple graphs the returned
* set is either singleton set or empty set.
*
* @param sourceVertex source vertex of the edge.
* @param targetVertex target vertex of the edge.
*
* @return a set of all edges connecting source vertex to target vertex.
*/
public Set getAllEdges(V sourceVertex, V targetVertex);
/**
* Returns an edge connecting source vertex to target vertex if such
* vertices and such edge exist in this graph. Otherwise returns
* null. If any of the specified vertices is null
* returns null
*
* In undirected graphs, the returned edge may have its source and target
* vertices in the opposite order.
*
* @param sourceVertex source vertex of the edge.
* @param targetVertex target vertex of the edge.
*
* @return an edge connecting source vertex to target vertex.
*/
public E getEdge(V sourceVertex, V targetVertex);
/**
* Returns the edge factory using which this graph creates new edges. The
* edge factory is defined when the graph is constructed and must not be
* modified.
*
* @return the edge factory using which this graph creates new edges.
*/
public EdgeFactory getEdgeFactory();
/**
* Creates a new edge in this graph, going from the source vertex to the
* target vertex, and returns the created edge. Some graphs do not allow
* edge-multiplicity. In such cases, if the graph already contains an edge
* from the specified source to the specified target, than this method does
* not change the graph and returns null.
*
* The source and target vertices must already be contained in this
* graph. If they are not found in graph IllegalArgumentException is
* thrown.
*
* This method creates the new edge e using this graph's
* EdgeFactory. For the new edge to be added e
* must not be equal to any other edge the graph (even if the graph
* allows edge-multiplicity). More formally, the graph must not contain any
* edge e2 such that e2.equals(e). If such
* e2 is found then the newly created edge e is
* abandoned, the method leaves this graph unchanged returns
* null.
*
* @param sourceVertex source vertex of the edge.
* @param targetVertex target vertex of the edge.
*
* @return The newly created edge if added to the graph, otherwise
* null.
*
* @throws IllegalArgumentException if source or target vertices are not
* found in the graph.
* @throws NullPointerException if any of the specified vertices is
* null.
*
* @see #getEdgeFactory()
*/
public E addEdge(V sourceVertex, V targetVertex);
/**
* Adds the specified edge to this graph, going from the source vertex to
* the target vertex. More formally, adds the specified edge,
* e, to this graph if this graph contains no edge e2
* such that e2.equals(e). If this graph already contains such
* an edge, the call leaves this graph unchanged and returns false.
* Some graphs do not allow edge-multiplicity. In such cases, if the graph
* already contains an edge from the specified source to the specified
* target, than this method does not change the graph and returns
* false. If the edge was added to the graph, returns
* true.
*
* The source and target vertices must already be contained in this
* graph. If they are not found in graph IllegalArgumentException is
* thrown.
*
* @param sourceVertex source vertex of the edge.
* @param targetVertex target vertex of the edge.
* @param e edge to be added to this graph.
*
* @return true if this graph did not already contain the specified
* edge.
*
* @throws IllegalArgumentException if source or target vertices are not
* found in the graph.
* @throws ClassCastException if the specified edge is not assignment
* compatible with the class of edges produced by the edge factory of this
* graph.
* @throws NullPointerException if any of the specified vertices is
* null.
*
* @see #addEdge(Object, Object)
* @see #getEdgeFactory()
*/
public boolean addEdge(V sourceVertex, V targetVertex, E e);
/**
* Adds the specified vertex to this graph if not already present. More
* formally, adds the specified vertex, v, to this graph if
* this graph contains no vertex u such that
* u.equals(v). If this graph already contains such vertex, the call
* leaves this graph unchanged and returns false. In combination
* with the restriction on constructors, this ensures that graphs never
* contain duplicate vertices.
*
* @param v vertex to be added to this graph.
*
* @return true if this graph did not already contain the specified
* vertex.
*
* @throws NullPointerException if the specified vertex is
* null.
*/
public boolean addVertex(V v);
/**
* Returns true if and only if this graph contains an edge going
* from the source vertex to the target vertex. In undirected graphs the
* same result is obtained when source and target are inverted. If any of
* the specified vertices does not exist in the graph, or if is
* null, returns false.
*
* @param sourceVertex source vertex of the edge.
* @param targetVertex target vertex of the edge.
*
* @return true if this graph contains the specified edge.
*/
public boolean containsEdge(V sourceVertex, V targetVertex);
/**
* Returns true if this graph contains the specified edge. More
* formally, returns true if and only if this graph contains an
* edge e2 such that e.equals(e2). If the
* specified edge is null returns false.
*
* @param e edge whose presence in this graph is to be tested.
*
* @return true if this graph contains the specified edge.
*/
public boolean containsEdge(E e);
/**
* Returns true if this graph contains the specified vertex. More
* formally, returns true if and only if this graph contains a
* vertex u such that u.equals(v). If the
* specified vertex is null returns false.
*
* @param v vertex whose presence in this graph is to be tested.
*
* @return true if this graph contains the specified vertex.
*/
public boolean containsVertex(V v);
/**
* Returns a set of the edges contained in this graph. The set is backed by
* the graph, so changes to the graph are reflected in the set. If the graph
* is modified while an iteration over the set is in progress, the results
* of the iteration are undefined.
*
* The graph implementation may maintain a particular set ordering (e.g.
* via {@link java.util.LinkedHashSet}) for deterministic iteration, but
* this is not required. It is the responsibility of callers who rely on
* this behavior to only use graph implementations which support it.
*
* @return a set of the edges contained in this graph.
*/
public Set edgeSet();
/**
* Returns a set of all edges touching the specified vertex. If no edges are
* touching the specified vertex returns an empty set.
*
* @param vertex the vertex for which a set of touching edges is to be
* returned.
*
* @return a set of all edges touching the specified vertex.
*
* @throws IllegalArgumentException if vertex is not found in the graph.
* @throws NullPointerException if vertex is null.
*/
public Set edgesOf(V vertex);
/**
* Removes all the edges in this graph that are also contained in the
* specified edge collection. After this call returns, this graph will
* contain no edges in common with the specified edges. This method will
* invoke the {@link #removeEdge(Object)} method.
*
* @param edges edges to be removed from this graph.
*
* @return true if this graph changed as a result of the call
*
* @throws NullPointerException if the specified edge collection is
* null.
*
* @see #removeEdge(Object)
* @see #containsEdge(Object)
*/
public boolean removeAllEdges(Collection edges);
/**
* Removes all the edges going from the specified source vertex to the
* specified target vertex, and returns a set of all removed edges. Returns
* null if any of the specified vertices does not exist in the
* graph. If both vertices exist but no edge is found, returns an empty set.
* This method will either invoke the {@link #removeEdge(Object)} method, or
* the {@link #removeEdge(Object, Object)} method.
*
* @param sourceVertex source vertex of the edge.
* @param targetVertex target vertex of the edge.
*
* @return the removed edges, or null if either vertex is not
* part of graph
*/
public Set removeAllEdges(V sourceVertex, V targetVertex);
/**
* Removes all the vertices in this graph that are also contained in the
* specified vertex collection. After this call returns, this graph will
* contain no vertices in common with the specified vertices. This method
* will invoke the {@link #removeVertex(Object)} method.
*
* @param vertices vertices to be removed from this graph.
*
* @return true if this graph changed as a result of the call
*
* @throws NullPointerException if the specified vertex collection is
* null.
*
* @see #removeVertex(Object)
* @see #containsVertex(Object)
*/
public boolean removeAllVertices(Collection vertices);
/**
* Removes an edge going from source vertex to target vertex, if such
* vertices and such edge exist in this graph. Returns the edge if removed
* or null otherwise.
*
* @param sourceVertex source vertex of the edge.
* @param targetVertex target vertex of the edge.
*
* @return The removed edge, or null if no edge removed.
*/
public E removeEdge(V sourceVertex, V targetVertex);
/**
* Removes the specified edge from the graph. Removes the specified edge
* from this graph if it is present. More formally, removes an edge
* e2 such that e2.equals(e), if the graph contains such
* edge. Returns true if the graph contained the specified edge.
* (The graph will not contain the specified edge once the call returns).
*
* If the specified edge is null returns
* false.
*
* @param e edge to be removed from this graph, if present.
*
* @return true if and only if the graph contained the
* specified edge.
*/
public boolean removeEdge(E e);
/**
* Removes the specified vertex from this graph including all its touching
* edges if present. More formally, if the graph contains a vertex
* u such that u.equals(v), the call removes all edges
* that touch u and then removes u itself. If no
* such u is found, the call leaves the graph unchanged.
* Returns true if the graph contained the specified vertex. (The
* graph will not contain the specified vertex once the call returns).
*
* If the specified vertex is null returns
* false.
*
* @param v vertex to be removed from this graph, if present.
*
* @return true if the graph contained the specified vertex;
* false otherwise.
*/
public boolean removeVertex(V v);
/**
* Returns a set of the vertices contained in this graph. The set is backed
* by the graph, so changes to the graph are reflected in the set. If the
* graph is modified while an iteration over the set is in progress, the
* results of the iteration are undefined.
*
* The graph implementation may maintain a particular set ordering (e.g.
* via {@link java.util.LinkedHashSet}) for deterministic iteration, but
* this is not required. It is the responsibility of callers who rely on
* this behavior to only use graph implementations which support it.
*
* @return a set view of the vertices contained in this graph.
*/
public Set vertexSet();
/**
* Returns the source vertex of an edge. For an undirected graph, source and
* target are distinguishable designations (but without any mathematical
* meaning).
*
* @param e edge of interest
*
* @return source vertex
*/
public V getEdgeSource(E e);
/**
* Returns the target vertex of an edge. For an undirected graph, source and
* target are distinguishable designations (but without any mathematical
* meaning).
*
* @param e edge of interest
*
* @return target vertex
*/
public V getEdgeTarget(E e);
/**
* Returns the weight assigned to a given edge. Unweighted graphs return 1.0
* (as defined by {@link WeightedGraph#DEFAULT_EDGE_WEIGHT}), allowing
* weighted-graph algorithms to apply to them where meaningful.
*
* @param e edge of interest
*
* @return edge weight
*
* @see WeightedGraph
*/
public double getEdgeWeight(E e);
}
// End Graph.java