org.jgrapht.Graph Maven / Gradle / Ivy
/*
* (C) Copyright 2003-2017, by Barak Naveh and Contributors.
*
* JGraphT : a free Java graph-theory library
*
* 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.
*/
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.
*
* @param the graph vertex type
* @param the graph edge type
*
* @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.
*/
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);
/**
* 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.
*/
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()
*/
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()
*/
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.
*/
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 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);
/**
* 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);
/**
* 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
*/
double getEdgeWeight(E e);
}
// End Graph.java