org.jgrapht.Graph Maven / Gradle / Ivy
/*
* (C) Copyright 2003-2023, by Barak Naveh and Contributors.
*
* JGraphT : a free Java graph-theory library
*
* See the CONTRIBUTORS.md file distributed with this work for additional
* information regarding copyright ownership.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License 2.0 which is available at
* http://www.eclipse.org/legal/epl-2.0, or the
* GNU Lesser General Public License v2.1 or later
* which is available at
* http://www.gnu.org/licenses/old-licenses/lgpl-2.1-standalone.html.
*
* SPDX-License-Identifier: EPL-2.0 OR LGPL-2.1-or-later
*/
package org.jgrapht;
import java.util.Collection;
import java.util.Set;
import java.util.function.Supplier;
import org.jgrapht.graph.DefaultGraphIterables;
/**
* 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.
*
* @param the graph vertex type
* @param the graph edge type
*
* @author Barak Naveh
*/
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.
*/
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.
*/
E getEdge(V sourceVertex, V targetVertex);
/**
* Return the vertex supplier that the graph uses whenever it needs to create new vertices.
*
*
* A graph uses the vertex supplier to create new vertex objects whenever a user calls method
* {@link Graph#addVertex()}. Users can also create the vertex in user code and then use method
* {@link Graph#addVertex(Object)} to add the vertex.
*
*
* In contrast with the {@link Supplier} interface, the vertex supplier has the additional
* requirement that a new and distinct result is returned every time it is invoked. More
* specifically for a new vertex to be added in a graph v must not be equal
* to any other vertex in the graph. More formally, the graph must not contain any vertex
* v2 such that v2.equals(v).
*
*
* Care must also be taken when interchanging calls to methods {@link Graph#addVertex(Object)}
* and {@link Graph#addVertex()}. In such a case the user must make sure never to add vertices
* in the graph using method {@link Graph#addVertex(Object)}, which are going to be returned in
* the future by the supplied vertex supplier. Such a sequence will result into an
* {@link IllegalArgumentException} when calling method {@link Graph#addVertex()}.
*
* @return the vertex supplier or null if the graph has no such supplier
*/
Supplier getVertexSupplier();
/**
* Return the edge supplier that the graph uses whenever it needs to create new edges.
*
*
* A graph uses the edge supplier to create new edge objects whenever a user calls method
* {@link Graph#addEdge(Object, Object)}. Users can also create the edge in user code and then
* use method {@link Graph#addEdge(Object, Object, Object)} to add the edge.
*
*
* In contrast with the {@link Supplier} interface, the edge supplier has the additional
* requirement that a new and distinct result is returned every time it is invoked. More
* specifically for a new edge to be added in a graph e must not be equal to
* any other edge in the graph (even if the graph allows edge-multiplicity). More formally, the
* graph must not contain any edge e2 such that e2.equals(e).
*
* @return the edge supplier null if the graph has no such supplier
*/
Supplier getEdgeSupplier();
/**
* 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, then 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 {@link IllegalArgumentException} is thrown.
*
*
* This method creates the new edge e using this graph's edge supplier (see
* {@link #getEdgeSupplier()}). 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 and returns null.
*
*
* If the underlying graph implementation's {@link #getEdgeSupplier()} returns
* null, then this method cannot create edges and throws an
* {@link UnsupportedOperationException}.
*
* @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.
* @throws UnsupportedOperationException if the graph was not initialized with an edge supplier
*
* @see #getEdgeSupplier()
*/
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, then 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 #getEdgeSupplier()
*/
boolean addEdge(V sourceVertex, V targetVertex, E e);
/**
* Creates a new vertex in this graph and returns it.
*
*
* This method creates the new vertex v using this graph's vertex supplier (see
* {@link #getVertexSupplier()}). For the new vertex to be added v must not
* be equal to any other vertex in the graph. More formally, the graph must not contain any
* vertex v2 such that v2.equals(v). If such
* v2 is found then the newly created vertex v is abandoned, the method
* leaves this graph unchanged and throws an {@link IllegalArgumentException}.
*
*
* If the underlying graph implementation's {@link #getVertexSupplier()} returns
* null, then this method cannot create vertices and throws an
* {@link UnsupportedOperationException}.
*
*
* Care must also be taken when interchanging calls to methods {@link Graph#addVertex(Object)}
* and {@link Graph#addVertex()}. In such a case the user must make sure never to add vertices
* in the graph using method {@link Graph#addVertex(Object)}, which are going to be returned in
* the future by the supplied vertex supplier. Such a sequence will result into an
* {@link IllegalArgumentException} when calling method {@link Graph#addVertex()}.
*
* @return The newly created vertex if added to the graph.
*
* @throws IllegalArgumentException if the graph supplier returns a vertex which is already in
* the graph
* @throws UnsupportedOperationException if the graph was not initialized with a vertex supplier
*
* @see #getVertexSupplier()
*/
V addVertex();
/**
* 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.
*/
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.
*/
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.
*/
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.
*/
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.
*/
Set edgeSet();
/**
* Returns the degree of the specified vertex.
*
*
* A degree of a vertex in an undirected graph is the number of edges touching that vertex.
* Edges with same source and target vertices (self-loops) are counted twice.
*
*
* In directed graphs this method returns the sum of the "in degree" and the "out degree".
*
* @param vertex vertex whose degree is to be calculated.
* @return the degree of the specified vertex.
*
* @throws IllegalArgumentException if vertex is not found in the graph.
* @throws NullPointerException if vertex is null.
* @throws ArithmeticException if the result overflows an int
*/
int degreeOf(V vertex);
/**
* 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.
*/
Set edgesOf(V vertex);
/**
* Returns the "in degree" of the specified vertex.
*
*
* The "in degree" of a vertex in a directed graph is the number of inward directed edges from
* that vertex. See
* http://mathworld.wolfram.com/Indegree.html.
*
*
* In the case of undirected graphs this method returns the number of edges touching the vertex.
* Edges with same source and target vertices (self-loops) are counted twice.
*
* @param vertex vertex whose degree is to be calculated.
* @return the degree of the specified vertex.
*
* @throws IllegalArgumentException if vertex is not found in the graph.
* @throws NullPointerException if vertex is null.
* @throws ArithmeticException if the result overflows an int
*/
int inDegreeOf(V vertex);
/**
* Returns a set of all edges incoming into the specified vertex.
*
*
* In the case of undirected graphs this method returns all edges touching the vertex, thus,
* some of the returned edges may have their source and target vertices in the opposite order.
*
* @param vertex the vertex for which the list of incoming edges to be returned.
* @return a set of all edges incoming into the specified vertex.
*
* @throws IllegalArgumentException if vertex is not found in the graph.
* @throws NullPointerException if vertex is null.
*/
Set incomingEdgesOf(V vertex);
/**
* Returns the "out degree" of the specified vertex.
*
*
* The "out degree" of a vertex in a directed graph is the number of outward directed edges from
* that vertex. See
* http://mathworld.wolfram.com/Outdegree.html.
*
*
* In the case of undirected graphs this method returns the number of edges touching the vertex.
* Edges with same source and target vertices (self-loops) are counted twice.
*
* @param vertex vertex whose degree is to be calculated.
* @return the degree of the specified vertex.
*
* @throws IllegalArgumentException if vertex is not found in the graph.
* @throws NullPointerException if vertex is null.
* @throws ArithmeticException if the result overflows an int
*/
int outDegreeOf(V vertex);
/**
* Returns a set of all edges outgoing from the specified vertex.
*
*
* In the case of undirected graphs this method returns all edges touching the vertex, thus,
* some of the returned edges may have their source and target vertices in the opposite order.
*
* @param vertex the vertex for which the list of outgoing edges to be returned.
* @return a set of all edges outgoing from the specified vertex.
*
* @throws IllegalArgumentException if vertex is not found in the graph.
* @throws NullPointerException if vertex is null.
*/
Set outgoingEdgesOf(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)
*/
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
*/
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)
*/
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.
*/
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.
*/
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.
*/
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.
*/
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
*/
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
*/
V getEdgeTarget(E e);
/**
* Get the graph type. The graph type can be used to query for additional metadata such as
* whether the graph supports directed or undirected edges, self-loops, multiple (parallel)
* edges, weights, etc.
*
* @return the graph type
*/
GraphType getType();
/**
* The default weight for an edge.
*/
double DEFAULT_EDGE_WEIGHT = 1.0;
/**
* Returns the weight assigned to a given edge. Unweighted graphs return 1.0 (as defined by
* {@link #DEFAULT_EDGE_WEIGHT}), allowing weighted-graph algorithms to apply to them when
* meaningful.
*
* @param e edge of interest
* @return edge weight
*/
double getEdgeWeight(E e);
/**
* Assigns a weight to an edge.
*
* @param e edge on which to set weight
* @param weight new weight for edge
* @throws UnsupportedOperationException if the graph does not support weights
*/
void setEdgeWeight(E e, double weight);
/**
* Assigns a weight to an edge between sourceVertex and targetVertex.
* If no edge exists between sourceVertex and targetVertex or either
* of these vertices is null, a NullPointerException is thrown.
*
* When there exist multiple edges between sourceVertex and
* targetVertex, consider using {@link #setEdgeWeight(Object, double)} instead.
*
* @param sourceVertex source vertex of the edge
* @param targetVertex target vertex of the edge
* @param weight new weight for edge
* @throws UnsupportedOperationException if the graph does not support weights
*/
default void setEdgeWeight(V sourceVertex, V targetVertex, double weight)
{
this.setEdgeWeight(this.getEdge(sourceVertex, targetVertex), weight);
}
/**
* Access the graph using the {@link GraphIterables} interface. This allows accessing graphs
* without the restrictions imposed by 32-bit arithmetic. Moreover, graph implementations are
* free to implement this interface without explicitly materializing intermediate results.
*
* @return the graph iterables
*/
default GraphIterables iterables()
{
return new DefaultGraphIterables(this);
}
}