Package com.jgalgo.graph

Interface GraphFactory<V,E>

Type Parameters:

V - the vertices type

E - the edges type

All Known Subinterfaces:

IndexGraphFactory, IntGraphFactory

public interface GraphFactory<V,E>

A factory for Graph objects.

The factory can be used to create new empty graphs, with different options and capabilities. Few methods are available to optimize the graph implementation choice. The factory can also be used to create a copy of an existing graphs, with the same vertices and edges, with/without copying the vertices/edges weights.

Both the graph factory and GraphBuilder are used to create new graphs. The difference is that vertices and edges can be added to the builder, which is then used to construct non empty graphs, while the factory is only used to choose a graph implementation and create an empty graph.

Author:

Barak Ugav

See Also:

directed(), undirected(), Graph, GraphBuilder

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static class	GraphFactory.Hint	Hints for a graph factory.

Method Summary

Modifier and Type	Method	Description
GraphFactory<V,E>	addHint(GraphFactory.Hint hint)	Add a hint to this factory.
default GraphFactory<V,E>	allowParallelEdges()	Change the config of this factory so that the built graphs will support parallel edges.
GraphFactory<V,E>	allowParallelEdges(boolean parallelEdges)	Determine if graphs built by this factory should be support parallel edges.
default GraphFactory<V,E>	allowSelfEdges()	Change the config of this factory so that the built graphs will support self edges.
GraphFactory<V,E>	allowSelfEdges(boolean selfEdges)	Determine if graphs built by this factory should be support self edges.
static <V,E> GraphFactory<V,E>	directed()	Create a directed graph factory.
GraphFactory<V,E>	expectedEdgesNum(int expectedEdgesNum)	Set the expected number of edges that will exist in the graph.
GraphFactory<V,E>	expectedVerticesNum(int expectedVerticesNum)	Set the expected number of vertices that will exist in the graph.
GraphBuilder<V,E>	newBuilder()	Create a new graph builder with the factory parameters.
default GraphBuilder<V,E>	newBuilderCopyOf(Graph<V,E> g)	Create a new graph builder with the factory parameters initialized with an existing graph vertices and edges, without copying the weights.
GraphBuilder<V,E>	newBuilderCopyOf(Graph<V,E> g, boolean copyVerticesWeights, boolean copyEdgesWeights)	Create a new graph builder with the factory parameters initialized with an existing graph vertices and edges, with/without copying the weights.
default Graph<V,E>	newCopyOf(Graph<V,E> g)	Create a copy of a given graph, with the same vertices and edges, without copying weights.
Graph<V,E>	newCopyOf(Graph<V,E> g, boolean copyVerticesWeights, boolean copyEdgesWeights)	Create a copy of a given graph, with the same vertices and edges, with/without copying weights.
Graph<V,E>	newGraph()	Create a new empty graph.
default Graph<V,E>	newImmutableCopyOf(Graph<V,E> g)	Create a new immutable copy of a given graph, with the same vertices and edges, without copying weights.
Graph<V,E>	newImmutableCopyOf(Graph<V,E> g, boolean copyVerticesWeights, boolean copyEdgesWeights)	Create a new immutable copy of a given graph, with the same vertices and edges, with/without copying weights.
static <V,E> GraphFactory<V,E>	newInstance(boolean directed)	Create a new un/directed graph factory.
GraphFactory<V,E>	removeHint(GraphFactory.Hint hint)	Remove a hint from this factory.
GraphFactory<V,E>	setDirected(boolean directed)	Determine if graphs built by this factory should be directed.
default GraphFactory<V,E>	setEdgeBuilder(IdBuilder<E> edgeBuilder)	Set the edge builder used by the built graph(s).
GraphFactory<V,E>	setEdgeFactory(Supplier<? extends IdBuilder<E>> edgeFactory)	Set the edge factory which create builders for the edges of the built graph(s).
default GraphFactory<V,E>	setOption(String key, Object value)	[TL;DR Don't call me!]
default GraphFactory<V,E>	setVertexBuilder(IdBuilder<V> vertexBuilder)	Set the vertex builder used by the built graph(s).
GraphFactory<V,E>	setVertexFactory(Supplier<? extends IdBuilder<V>> vertexFactory)	Set the vertex factory which create builders for the vertices of the built graph(s).
static <V,E> GraphFactory<V,E>	undirected()	Create an undirected graph factory.

Method Detail

newGraph

Graph<V,E> newGraph()

Create a new empty graph.

Returns:

a new graph with the factory options

newCopyOf

default Graph<V,E> newCopyOf(Graph<V,E> g)

Create a copy of a given graph, with the same vertices and edges, without copying weights.

An identical copy of the given graph will be created, with the same vertices and edges, without copying the vertices/edges weights. The returned Graph will always be mutable, with no side affects on the original graph.

Differing from Graph.copy(), the capabilities of the new graph are determined by the factory configuration, rather than copied from the given graph. Note for example that if the factory chooses to use an implementation that does not support self edges (if allowSelfEdges(boolean) was not called with true), attempting to create a copy of a graph that does contains self edges will result in an exception.

For an immutable copy of a graph, see newImmutableCopyOf(Graph, boolean, boolean).

Parameters:

g - the original graph to copy

Returns:

an identical copy of the given graph, with the same vertices and edges, without the original graph weights

newCopyOf

Graph<V,E> newCopyOf(Graph<V,E> g,
                           boolean copyVerticesWeights,
                           boolean copyEdgesWeights)

Create a copy of a given graph, with the same vertices and edges, with/without copying weights.

An identical copy of the given graph will be created, with the same vertices and edges, with/without copying the vertices/edges weights. The returned Graph will always be mutable, with no side affects on the original graph.

Differing from Graph.copy(boolean, boolean), the capabilities of the new graph are determined by the factory configuration, rather than copied from the given graph. Note for example that if the factory chooses to use an implementation that does not support self edges (if allowSelfEdges(boolean) was not called with true), attempting to create a copy of a graph that does contains self edges will result in an exception.

For an immutable copy of a graph, see newImmutableCopyOf(Graph, boolean, boolean).

Parameters:

g - the original graph to copy

copyVerticesWeights - if true, the weights of the vertices will be copied to the new graph

copyEdgesWeights - if true, the weights of the edges will be copied to the new graph

Returns:

an identical copy of the given graph, with the same vertices and edges, with/without the original graph weights

newImmutableCopyOf

default Graph<V,E> newImmutableCopyOf(Graph<V,E> g)

Create a new immutable copy of a given graph, with the same vertices and edges, without copying weights.

An identical copy of the given graph will be created, with the same vertices and edges, without copying the vertices/edges weights. The returned Graph will be immutable, with no side affects on the original graph.

Differing from Graph.immutableCopy(), the capabilities of the new graph are determined by the factory configuration, rather than copied from the given graph. Note for example that if the factory chooses to use an implementation that does not support self edges (if allowSelfEdges(boolean) was not called with true), attempting to create a copy of a graph that does contains self edges will result in an exception.

For a mutable copy of a graph, see newCopyOf(Graph, boolean, boolean).

Parameters:

g - the original graph to copy

Returns:

an identical immutable copy of the given graph, with the same vertices and edges, without the original graph weights

newImmutableCopyOf

Graph<V,E> newImmutableCopyOf(Graph<V,E> g,
                                    boolean copyVerticesWeights,
                                    boolean copyEdgesWeights)

Create a new immutable copy of a given graph, with the same vertices and edges, with/without copying weights.

An identical copy of the given graph will be created, with the same vertices and edges, with/without copying the vertices/edges weights. The returned Graph will be immutable, with no side affects on the original graph.

Differing from Graph.immutableCopy(boolean, boolean), the capabilities of the new graph are determined by the factory configuration, rather than copied from the given graph. Note for example that if the factory chooses to use an implementation that does not support self edges (if allowSelfEdges(boolean) was not called with true), attempting to create a copy of a graph that does contains self edges will result in an exception.

For a mutable copy of a graph, see newCopyOf(Graph, boolean, boolean).

Parameters:

g - the original graph to copy

copyVerticesWeights - if true, the weights of the vertices will be copied to the new graph

copyEdgesWeights - if true, the weights of the edges will be copied to the new graph

Returns:

an identical immutable copy of the given graph, with the same vertices and edges, without the original graph weights

newBuilder

GraphBuilder<V,E> newBuilder()

Create a new graph builder with the factory parameters.

The created builder can be used to add vertices and edges, and then build a (mutable or immutable) non empty graph, differing from the factory which only builds empty graphs. The capabilities such as un/directed, support of self edges, support of parallel edges, and hints such as expected number of vertices and edges, other hints, etc. are copied from the factory to the builder.

Returns:

a new graph builder with the factory parameters

newBuilderCopyOf

default GraphBuilder<V,E> newBuilderCopyOf(Graph<V,E> g)

Create a new graph builder with the factory parameters initialized with an existing graph vertices and edges, without copying the weights.

If the given graph is directed, the new builder will build directed graphs, and similarly for undirected graphs.

Parameters:

g - a graph

Returns:

a graph builder with the factory parameters initialized with the given graph vertices and edges, without the original graph vertices/edges weights.

newBuilderCopyOf

GraphBuilder<V,E> newBuilderCopyOf(Graph<V,E> g,
                                         boolean copyVerticesWeights,
                                         boolean copyEdgesWeights)

Create a new graph builder with the factory parameters initialized with an existing graph vertices and edges, with/without copying the weights.

If the given graph is directed, the new builder will build directed graphs, and similarly for undirected graphs.

Parameters:

g - a graph

copyVerticesWeights - if true, the weights of the vertices will be copied from the graph to the builder

copyEdgesWeights - if true, the weights of the edges will be copied from the graph to the builder

Returns:

a graph builder with the factory parameters initialized with the given graph vertices and edges, with/without the original graph vertices/edges weights.

setDirected

GraphFactory<V,E> setDirected(boolean directed)

Determine if graphs built by this factory should be directed.

Usually the factory will be created using either directed() or undirected(), and there will be no need to call this method. However, it is sometimes useful use the same factory to build both directed and undirected graphs, and this method can be used to change the factory configuration. For example, a factory can be passed to a random graph generator, which can generated both directed and undirected graphs, depending on the generator parameters.

Parameters:

directed - if true graphs built by this factory will be directed, else they will be undirected

Returns:

this factory

allowSelfEdges

default GraphFactory<V,E> allowSelfEdges()

Change the config of this factory so that the built graphs will support self edges.

By default, graphs built by this factory will not support self edges.

Returns:

this factory

allowSelfEdges

GraphFactory<V,E> allowSelfEdges(boolean selfEdges)

Determine if graphs built by this factory should be support self edges.

By default, graphs built by this factory will not support self edges.

Parameters:

selfEdges - if true graphs built by this factory will support self edges, else they will not

Returns:

this factory

allowParallelEdges

default GraphFactory<V,E> allowParallelEdges()

Change the config of this factory so that the built graphs will support parallel edges.

By default, graphs built by this factory will support parallel edges. The reason is that in order to enforce no parallel edges are added to the graph, an efficient lookup of edges (keyed by an edge's vertices) is required, which is an operation most graph algorithms do not use and therefore most implementations are not optimized for. See GraphFactory.Hint.FastEdgeLookup.

Returns:

this factory

allowParallelEdges

GraphFactory<V,E> allowParallelEdges(boolean parallelEdges)

Determine if graphs built by this factory should be support parallel edges.

By default, graphs built by this factory will support parallel edges. The reason is that in order to enforce no parallel edges are added to the graph, an efficient lookup of edges (keyed by an edge's vertices) is required, which is an operation most graph algorithms do not use and therefore most implementations are not optimized for. See GraphFactory.Hint.FastEdgeLookup.

Parameters:

parallelEdges - if true graphs built by this factory will support parallel edges, else they will not

Returns:

this factory

expectedVerticesNum

GraphFactory<V,E> expectedVerticesNum(int expectedVerticesNum)

Set the expected number of vertices that will exist in the graph.

Parameters:

expectedVerticesNum - the expected number of vertices in the graph

Returns:

this factory

expectedEdgesNum

GraphFactory<V,E> expectedEdgesNum(int expectedEdgesNum)

Set the expected number of edges that will exist in the graph.

Parameters:

expectedEdgesNum - the expected number of edges in the graph

Returns:

this factory

setVertexBuilder

default GraphFactory<V,E> setVertexBuilder(IdBuilder<V> vertexBuilder)

Set the vertex builder used by the built graph(s).

The vertex builder is used by graphs to create new vertices when the user does not provide them explicitly, see Graph.addVertex(). The same vertex builder will be used for all graphs built by this factory, and graphs built by GraphBuilder created by this factory. If a different instance of a vertex builder is required for each graph, consider using setVertexFactory(Supplier) instead.

For some types there is a default vertex builder, see IdBuilder.defaultBuilder(Class).

By default, graphs built by this factory will not have a vertex builder, namely a null vertex builder.

Parameters:

vertexBuilder - the vertex builder, or null if no vertex builder should be used

Returns:

this factory

setVertexFactory

GraphFactory<V,E> setVertexFactory(Supplier<? extends IdBuilder<V>> vertexFactory)

Set the vertex factory which create builders for the vertices of the built graph(s).

The vertex builder is used by graphs to create new vertices when the user does not provide them explicitly, see Graph.addVertex(). The factory will be used to insatiate a new vertex builder for each graph built by this factory, and graphs built by GraphBuilder created by this factory. If the same vertex builder can be used for all graphs, consider using setVertexBuilder(IdBuilder) instead.

For some types there is a default vertex factory, see IdBuilder.defaultFactory(Class).

By default, graphs built by this factory will not have a vertex builder, namely a null vertex builder.

Parameters:

vertexFactory - the vertex factory, or null if no vertex builder should be used

Returns:

this factory

setEdgeBuilder

default GraphFactory<V,E> setEdgeBuilder(IdBuilder<E> edgeBuilder)

Set the edge builder used by the built graph(s).

The edge builder is used by graphs to create new edges when the user does not provide them explicitly, see Graph.addEdge(Object, Object). The same edge builder will be used for all graphs built by this factory, and graphs built by GraphBuilder created by this factory. If a different instance of an edge builder is required for each graph, consider using setEdgeFactory(Supplier) instead.

For some types there is a default edge builder, see IdBuilder.defaultBuilder(Class).

By default, graphs built by this factory will not have an edge builder, namely a null edge builder.

Parameters:

edgeBuilder - the edge builder, or null if no edge builder should be used

Returns:

this factory

setEdgeFactory

GraphFactory<V,E> setEdgeFactory(Supplier<? extends IdBuilder<E>> edgeFactory)

Set the edge factory which create builders for the edges of the built graph(s).

The edge builder is used by graphs to create new edges when the user does not provide them explicitly, see Graph.addEdge(Object, Object). The factory will be used to insatiate a new edge builder for each graph built by this factory, and graphs built by GraphBuilder created by this factory. If the same edge builder can be used for all graphs, consider using setEdgeBuilder(IdBuilder) instead.

For some types there is a default edge factory, see IdBuilder.defaultFactory(Class).

By default, graphs built by this factory will not have an edge builder, namely a null edge builder.

Parameters:

edgeFactory - the edge factory, or null if no edge builder should be used

Returns:

this factory

addHint

GraphFactory<V,E> addHint(GraphFactory.Hint hint)

Add a hint to this factory.

Hints do not change the behavior of the graphs built by this factory, by may affect performance.

Parameters:

hint - the hint to add

Returns:

this factory

removeHint

GraphFactory<V,E> removeHint(GraphFactory.Hint hint)

Remove a hint from this factory.

Hints do not change the behavior of the graphs built by this factory, by may affect performance.

Parameters:

hint - the hint to remove

Returns:

this factory

undirected

static <V,E> GraphFactory<V,E> undirected()

Create an undirected graph factory.

Type Parameters:

V - the vertices type

E - the edges type

Returns:

a new factory that can build undirected graphs

directed

static <V,E> GraphFactory<V,E> directed()

Create a directed graph factory.

Type Parameters:

V - the vertices type

E - the edges type

Returns:

a new factory that can build directed graphs

newInstance

static <V,E> GraphFactory<V,E> newInstance(boolean directed)

Create a new un/directed graph factory.

Type Parameters:

V - the vertices type

E - the edges type

Parameters:

directed - whether the graphs created by the factory should be directed

Returns:

a new factory that can build un/directed graphs

setOption

default GraphFactory<V,E> setOption(String key,
                                          Object value)

[TL;DR Don't call me!] Set an option.

The builder might support different options to customize its implementation. These options never change the behavior of the algorithm, only its internal implementation. The possible options are not exposed as 'public' because they are not part of the API and may change in the future.

These options are mainly for debug and benchmark purposes.

Parameters:

key - the option key

value - the option value

Returns:

this builder