com.google.common.graph

Interface ValueGraph<N,V>

Type Parameters:

N - Node parameter type

V - Value parameter type

All Superinterfaces:

Graph<N>

All Known Subinterfaces:

MutableValueGraph<N,V>

All Known Implementing Classes:

AbstractValueGraph, ImmutableValueGraph

@Beta
public interface ValueGraph<N,V>
extends Graph<N>

An interface for graph-structured data, whose edges have associated non-unique values.

A graph is composed of a set of nodes and a set of edges connecting pairs of nodes.

There are three main interfaces provided to represent graphs. In order of increasing complexity they are: Graph, ValueGraph, and Network. You should generally prefer the simplest interface that satisfies your use case. See the "Choosing the right graph type" section of the Guava User Guide for more details.

Capabilities

ValueGraph supports the following use cases (definitions of terms):

• directed graphs
• undirected graphs
• graphs that do/don't allow self-loops
• graphs whose nodes/edges are insertion-ordered, sorted, or unordered
• graphs whose edges have associated values

ValueGraph, as a subtype of Graph, explicitly does not support parallel edges, and forbids implementations or extensions with parallel edges. If you need parallel edges, use Network. (You can use a positive Integer edge value as a loose representation of edge multiplicity, but the *degree() and mutation methods will not reflect your interpretation of the edge value as its multiplicity.)

Building a ValueGraph

The implementation classes that `common.graph` provides are not public, by design. To create an instance of one of the built-in implementations of ValueGraph, use the ValueGraphBuilder class:

   MutableValueGraph<Integer, Double> graph = ValueGraphBuilder.directed().build();
 

ValueGraphBuilder.build() returns an instance of MutableValueGraph, which is a subtype of ValueGraph that provides methods for adding and removing nodes and edges. If you do not need to mutate a graph (e.g. if you write a method than runs a read-only algorithm on the graph), you should use the non-mutating ValueGraph interface, or an ImmutableValueGraph.

You can create an immutable copy of an existing ValueGraph using ImmutableValueGraph.copyOf(ValueGraph):

   ImmutableValueGraph<Integer, Double> immutableGraph = ImmutableValueGraph.copyOf(graph);
 

Instances of ImmutableValueGraph do not implement MutableValueGraph (obviously!) and are contractually guaranteed to be unmodifiable and thread-safe.

The Guava User Guide has more information on (and examples of) building graphs.

Additional documentation

See the Guava User Guide for the common.graph package ("Graphs Explained") for additional documentation, including:

• equals(), hashCode(), and graph equivalence
• Synchronization policy
• Notes for implementors

Since:

20.0

Author:

James Sexton, Joshua O'Madadhain

Method Summary

Modifier and Type	Method and Description
V	edgeValue(Object nodeU, Object nodeV) If there is an edge connecting nodeU to nodeV, returns the non-null value associated with that edge.
V	edgeValueOrDefault(Object nodeU, Object nodeV, V defaultValue) If there is an edge connecting nodeU to nodeV, returns the non-null value associated with that edge; otherwise, returns defaultValue.
boolean	equals(Object object) For the default ValueGraph implementations, returns true if this == object (reference equality).
int	hashCode() For the default ValueGraph implementations, returns System.identityHashCode(this).

Methods inherited from interface com.google.common.graph.Graph

adjacentNodes, allowsSelfLoops, degree, edges, inDegree, isDirected, nodeOrder, nodes, outDegree, predecessors, successors

Method Detail

edgeValue

V edgeValue(@CompatibleWith(value="N")
            Object nodeU,
            @CompatibleWith(value="N")
            Object nodeV)

If there is an edge connecting nodeU to nodeV, returns the non-null value associated with that edge.

In an undirected graph, this is equal to edgeValue(nodeV, nodeU).

Throws:

IllegalArgumentException - if there is no edge connecting nodeU to nodeV.

edgeValueOrDefault

V edgeValueOrDefault(@CompatibleWith(value="N")
                     Object nodeU,
                     @CompatibleWith(value="N")
                     Object nodeV,
                     @Nullable
                     V defaultValue)

If there is an edge connecting nodeU to nodeV, returns the non-null value associated with that edge; otherwise, returns defaultValue.

In an undirected graph, this is equal to edgeValueOrDefault(nodeV, nodeU, defaultValue).

equals

boolean equals(@Nullable
               Object object)

For the default ValueGraph implementations, returns true if this == object (reference equality). External implementations are free to define this method as they see fit, as long as they satisfy the Object.equals(Object) contract.

To compare two ValueGraphs based on their contents rather than their references, see Graphs.equivalent(ValueGraph, ValueGraph).

Specified by:

equals in interface Graph<N>

Overrides:

equals in class Object

hashCode

int hashCode()

For the default ValueGraph implementations, returns System.identityHashCode(this). External implementations are free to define this method as they see fit, as long as they satisfy the Object.hashCode() contract.

Specified by:

hashCode in interface Graph<N>

Overrides:

hashCode in class Object