com.google.common.graph.ValueGraph Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of payment-retries-plugin Show documentation
Kill Bill Payment Retries plugin
The newest version!
/*
 * Copyright (C) 2016 The Guava Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package com.google.common.graph;

import com.google.common.annotations.Beta;
import javax.annotation.Nullable;

/**
 * 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: {@link Graph}, {@link ValueGraph}, and {@link 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
 *
 * {@code 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
 * 
 *
 * {@code ValueGraph}, as a subtype of {@code Graph}, explicitly does not support parallel edges,
 * and forbids implementations or extensions with parallel edges. If you need parallel edges, use
 * {@link Network}. (You can use a positive {@code Integer} edge value as a loose representation of
 * edge multiplicity, but the {@code *degree()} and mutation methods will not reflect your
 * interpretation of the edge value as its multiplicity.)
 *
 * 
Building a {@code 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 {@code ValueGraph}, use the {@link
 * ValueGraphBuilder} class:
 *
 * 
{@code
 *   MutableValueGraph graph = ValueGraphBuilder.directed().build();
 * }
 *
 * {@link ValueGraphBuilder#build()} returns an instance of {@link MutableValueGraph}, which is a
 * subtype of {@code 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 {@link ValueGraph} interface, or an {@link
 * ImmutableValueGraph}.
 *
 * 
You can create an immutable copy of an existing {@code ValueGraph} using {@link
 * ImmutableValueGraph#copyOf(ValueGraph)}:
 *
 * 
{@code
 *   ImmutableValueGraph immutableGraph = ImmutableValueGraph.copyOf(graph);
 * }
 *
 * Instances of {@link ImmutableValueGraph} do not implement {@link 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 {@code common.graph} package ("Graphs Explained") for
 * additional documentation, including:
 *
 * 

 *   
 *       {@code equals()}, {@code hashCode()}, and graph equivalence
 *   

 *       Synchronization policy
 *   
Notes
 *       for implementors
 * 
 *
 * @author James Sexton
 * @author Joshua O'Madadhain
 * @param  Node parameter type
 * @param  Value parameter type
 * @since 20.0
 */
@Beta
public interface ValueGraph extends Graph {

  /**
   * If there is an edge connecting {@code nodeU} to {@code nodeV}, returns the non-null value
   * associated with that edge.
   *
   * In an undirected graph, this is equal to {@code edgeValue(nodeV, nodeU)}.
   *
   * @throws IllegalArgumentException if there is no edge connecting {@code nodeU} to {@code nodeV}.
   */
  V edgeValue(Object nodeU, Object nodeV);

  /**
   * If there is an edge connecting {@code nodeU} to {@code nodeV}, returns the non-null value
   * associated with that edge; otherwise, returns {@code defaultValue}.
   *
   * 
In an undirected graph, this is equal to {@code edgeValueOrDefault(nodeV, nodeU,
   * defaultValue)}.
   */
  V edgeValueOrDefault(Object nodeU, Object nodeV, @Nullable V defaultValue);

  //
  // ValueGraph identity
  //

  /**
   * For the default {@link ValueGraph} implementations, returns true if {@code this == object}
   * (reference equality). External implementations are free to define this method as they see fit,
   * as long as they satisfy the {@link Object#equals(Object)} contract.
   *
   * To compare two {@link ValueGraph}s based on their contents rather than their references, see
   * {@link Graphs#equivalent(ValueGraph, ValueGraph)}.
   */
  @Override
  boolean equals(@Nullable Object object);

  /**
   * For the default {@link ValueGraph} implementations, returns {@code
   * System.identityHashCode(this)}. External implementations are free to define this method as they
   * see fit, as long as they satisfy the {@link Object#hashCode()} contract.
   */
  @Override
  int hashCode();
}