net.sf.javagimmicks.graph.Graph Maven / Gradle / Ivy
Show all versions of gimmicks Show documentation
package net.sf.javagimmicks.graph;
import java.util.Collection;
import java.util.Map;
import java.util.Set;
/**
* Represents a graph data structure.
*
* Graphs consist of two types of elements: vertices and {@link Edge edges}.
*
* The first ones - vertices can by of an Java type and can have any
* value. Nevertheless it is strongly recommended that they have a well-defined
* {@link Object#equals(Object)} method. Concrete {@link Graph} might also have
* additional requirements (like a well-defined {@link Object#hashCode()}
* method).
*
* Edges must implement the {@link Edge} interface (or one of it's
* sub-interfaces) - please refer to the respective interface {@link Edge
* documentation} for more details
*
* @param
* the type of vertices of this {@link Graph}
* @param
* the type of {@link Edge}s of this {@link Graph}
*/
public interface Graph>
{
/**
* Returns the number of vertices that this instance contains.
*
* @return the number of vertices that this instance contains
*/
int size();
/**
* Returns if this instance is empty (it contains no vertices).
*
* @return if this instance is empty
*/
boolean isEmpty();
/**
* Returns a {@link Set} of all vertices contained within this instance.
*
* @return a {@link Set} of all vertices contained within this instance
*/
Set vertexSet();
/**
* Returns a {@link Map} of all vertices contained within this instance
* mapped to a {@link Set} of all {@link Edge}s connected to the vertex.
*
* @return a {@link Map} of all vertices contained within this instance
* mapped to a {@link Set} of all {@link Edge}s connected to the
* vertex
*/
Map> edgeMap();
/**
* Checks and returns of a given vertex is contained within this instance.
*
* @param vertex
* the vertex to check
* @return if the given vertex is contained within this instance
*/
boolean containsVertex(VertexType vertex);
/**
* Adds a new vertex to this instance (without any {@link Edge}s).
*
* @param vertex
* the vertex to add
* @return if the vertex was new (and this instance was updated)
*/
boolean addVertex(VertexType vertex);
/**
* Removes a given vertex from this instance.
*
* @param vertex
* the vertex to remove
* @return the {@link Set} of all {@link Edge}s that were connected to the
* remove vertex
*/
Set removeVertex(VertexType vertex);
/**
* Returns the {@link Set} of {@link Edge}s connected to a given vertex.
*
* @param vertex
* the vertex to retrieve the {@link Edge}s for
* @return the {@link Set} of {@link Edge}s connected to the given vertex
*/
Set edgesOf(VertexType vertex);
/**
* Retrieves the {@link Set} of vertices that are connected to a given
* vertex.
*
* @param vertex
* the vertex to get the connected vertices for
* @return the {@link Set} of vertices that are connected to the given vertex
*/
Set targetsOf(VertexType vertex);
/**
* Checks if two given vertices are connected within this instance.
*
* If the {@link Edge}s are not {@link DirectedEdge}s, it does not matter,
* which vertex is named first.
*
* @param source
* the source vertex of the connection to check
* @param target
* the target vertex of the connection to check
* @return if the two given vertices are connected within this instance
*/
boolean isConnected(VertexType source, VertexType target);
/**
* Returns the {@link Set} of {@link Edge}s that connect two given vertices.
*
* @param source
* the source vertex of the {@link Edge}s to retrieve
* @param target
* the target vertex of the {@link Edge}s to retrieve
* @return the resulting {@link Set} of {@link Edge}s (will be empty if the
* vertices are not connected within this instance)
*/
Set getEdges(VertexType source, VertexType target);
/**
* Return the first {@link Edge} that connects two given vertices.
*
* @param source
* the source vertex of the {@link Edge} to retrieve
* @param target
* the target vertex of the {@link Edge} to retrieve
* @return the resulting {@link Edge} or {@code null} if the two given
* vertices are not connected within this instance
*/
EdgeType getEdge(VertexType source, VertexType target);
/**
* Adds two given vertices to this instance (if not yet contained) and
* connects them together with an {@link Edge}.
*
* Important note: it depends on the concrete {@link Graph}
* implementation if a new {@link Edge} is created for two already connected
* vertices or the existing one is reused and returned.
*
* @param source
* the source vertex of the new connection
* @param target
* the target vertex of the new connection
* @return the resulting {@link Edge}
*/
EdgeType addEdge(VertexType source, VertexType target);
/**
* A bulk version of {@link #addEdge(Object, Object)} that connects (and
* optionally adds) a bunch of target vertices to one single source vertex.
*
* @param source
* the source vertex of the new connections
* @param targets
* the target vertices of the new connections
* @return a {@link Set} of containing all newly created {@link Edge}s
*/
Set addEdges(VertexType source, Collection targets);
/**
* Removes all {@link Edge}s that connect the two given vertices.
*
* @param source
* the source vertex of the {@link Edge}s to remove
* @param target
* the target vertex of the {@link Edge}s to remove
* @return the {@link Set} of removed {@link Edge}s (will be empty if the
* vertices are not connected within this instance)
*/
Set removeEdges(VertexType source, VertexType target);
/**
* Removes the first {@link Edge}s that connects the two given vertices.
*
* @param source
* the source vertex of the {@link Edge} to remove
* @param target
* the target vertex of the {@link Edge} to remove
* @return the removed {@link Edge} or {@code null} if the vertices are not
* connected within this instance
*/
EdgeType removeEdge(VertexType source, VertexType target);
/**
* Removes all {@link Edge}s that connect the given source vertex with any of
* the given target vertices.
*
* @param source
* the source vertex of the {@link Edge}s to remove
* @param targets
* the {@link Collection} of target vertices of the {@link Edge}s
* to remove
* @return the {@link Set} of removed {@link Edge}s (will be empty if none of
* the given target vertices is connected to the given source vertex
* within this instance)
*/
Set removeEdges(VertexType source, Collection targets);
}