Mutable{Graph, Network, ValueGraph}.java: tighten the contract for th…

…e edge-adding methods. The contract now states that if the specified nodes are not already present in the graph, they are silently added. (Removes the option of throwing in this case.) RELNOTES=`graph`: `Mutable{Graph, Network, ValueGraph}.java`: tighten the contract for the edge-adding methods. This is a breaking change; implementors of these interfaces should verify that they still comply with this contract. ------------- Created by MOE: https://github.com/google/moe MOE_MIGRATED_REVID=176364203
google · Nov 20, 2017 · ec48806 · ec48806
1 parent 16b1a0f
commit ec48806
Show file tree

Hide file tree

Showing 6 changed files with 12 additions and 24 deletions.
diff --git a/android/guava/src/com/google/common/graph/MutableGraph.java b/android/guava/src/com/google/common/graph/MutableGraph.java
@@ -45,10 +45,8 @@ public interface MutableGraph<N> extends Graph<N> {
    * Adds an edge connecting {@code nodeU} to {@code nodeV} if one is not already present. In an
    * undirected graph, the edge will also connect {@code nodeV} to {@code nodeU}.
    *
-   * <p>Behavior if {@code nodeU} and {@code nodeV} are not already present in this graph is
-   * implementation-dependent. Suggested behaviors include (a) silently {@link #addNode(Object)
-   * adding} {@code nodeU} and {@code nodeV} to the graph (this is the behavior of the default
-   * implementations) or (b) throwing {@code IllegalArgumentException}.
+   * <p>If {@code nodeU} and {@code nodeV} are not already present in this graph, this method
+   * will silently {@link #addNode(Object) add} {@code nodeU} and {@code nodeV} to the graph.
    *
    * @return {@code true} if the graph was modified as a result of this call
    * @throws IllegalArgumentException if the introduction of the edge would violate {@link

diff --git a/android/guava/src/com/google/common/graph/MutableNetwork.java b/android/guava/src/com/google/common/graph/MutableNetwork.java
@@ -48,10 +48,8 @@ public interface MutableNetwork<N, E> extends Network<N, E> {
    *
    * <p><b>Edges must be unique</b>, just as {@code Map} keys must be. They must also be non-null.
    *
-   * <p>Behavior if {@code nodeU} and {@code nodeV} are not already present in this network is
-   * implementation-dependent. Suggested behaviors include (a) silently {@link #addNode(Object)
-   * adding} {@code nodeU} and {@code nodeV} to the network (this is the behavior of the default
-   * implementations) or (b) throwing {@code IllegalArgumentException}.
+   * <p>If {@code nodeU} and {@code nodeV} are not already present in this graph, this method
+   * will silently {@link #addNode(Object) add} {@code nodeU} and {@code nodeV} to the graph.
    *
    * <p>If {@code edge} already connects {@code nodeU} to {@code nodeV} (in the specified order if
    * this network {@link #isDirected()}, else in any order), then this method will have no effect.

diff --git a/android/guava/src/com/google/common/graph/MutableValueGraph.java b/android/guava/src/com/google/common/graph/MutableValueGraph.java
@@ -48,10 +48,8 @@ public interface MutableValueGraph<N, V> extends ValueGraph<N, V> {
    *
    * <p>Values do not have to be unique. However, values must be non-null.
    *
-   * <p>Behavior if {@code nodeU} and {@code nodeV} are not already present in this graph is
-   * implementation-dependent. Suggested behaviors include (a) silently {@link #addNode(Object)
-   * adding} {@code nodeU} and {@code nodeV} to the graph (this is the behavior of the default
-   * implementations) or (b) throwing {@code IllegalArgumentException}.
+   * <p>If {@code nodeU} and {@code nodeV} are not already present in this graph, this method
+   * will silently {@link #addNode(Object) add} {@code nodeU} and {@code nodeV} to the graph.
    *
    * @return the value previously associated with the edge connecting {@code nodeU} to {@code
    *     nodeV}, or null if there was no such edge.

diff --git a/guava/src/com/google/common/graph/MutableGraph.java b/guava/src/com/google/common/graph/MutableGraph.java
@@ -45,10 +45,8 @@ public interface MutableGraph<N> extends Graph<N> {
    * Adds an edge connecting {@code nodeU} to {@code nodeV} if one is not already present. In an
    * undirected graph, the edge will also connect {@code nodeV} to {@code nodeU}.
    *
-   * <p>Behavior if {@code nodeU} and {@code nodeV} are not already present in this graph is
-   * implementation-dependent. Suggested behaviors include (a) silently {@link #addNode(Object)
-   * adding} {@code nodeU} and {@code nodeV} to the graph (this is the behavior of the default
-   * implementations) or (b) throwing {@code IllegalArgumentException}.
+   * <p>If {@code nodeU} and {@code nodeV} are not already present in this graph, this method
+   * will silently {@link #addNode(Object) add} {@code nodeU} and {@code nodeV} to the graph.
    *
    * @return {@code true} if the graph was modified as a result of this call
    * @throws IllegalArgumentException if the introduction of the edge would violate {@link

diff --git a/guava/src/com/google/common/graph/MutableNetwork.java b/guava/src/com/google/common/graph/MutableNetwork.java
@@ -48,10 +48,8 @@ public interface MutableNetwork<N, E> extends Network<N, E> {
    *
    * <p><b>Edges must be unique</b>, just as {@code Map} keys must be. They must also be non-null.
    *
-   * <p>Behavior if {@code nodeU} and {@code nodeV} are not already present in this network is
-   * implementation-dependent. Suggested behaviors include (a) silently {@link #addNode(Object)
-   * adding} {@code nodeU} and {@code nodeV} to the network (this is the behavior of the default
-   * implementations) or (b) throwing {@code IllegalArgumentException}.
+   * <p>If {@code nodeU} and {@code nodeV} are not already present in this graph, this method
+   * will silently {@link #addNode(Object) add} {@code nodeU} and {@code nodeV} to the graph.
    *
    * <p>If {@code edge} already connects {@code nodeU} to {@code nodeV} (in the specified order if
    * this network {@link #isDirected()}, else in any order), then this method will have no effect.

diff --git a/guava/src/com/google/common/graph/MutableValueGraph.java b/guava/src/com/google/common/graph/MutableValueGraph.java
@@ -48,10 +48,8 @@ public interface MutableValueGraph<N, V> extends ValueGraph<N, V> {
    *
    * <p>Values do not have to be unique. However, values must be non-null.
    *
-   * <p>Behavior if {@code nodeU} and {@code nodeV} are not already present in this graph is
-   * implementation-dependent. Suggested behaviors include (a) silently {@link #addNode(Object)
-   * adding} {@code nodeU} and {@code nodeV} to the graph (this is the behavior of the default
-   * implementations) or (b) throwing {@code IllegalArgumentException}.
+   * <p>If {@code nodeU} and {@code nodeV} are not already present in this graph, this method
+   * will silently {@link #addNode(Object) add} {@code nodeU} and {@code nodeV} to the graph.
    *
    * @return the value previously associated with the edge connecting {@code nodeU} to {@code
    *     nodeV}, or null if there was no such edge.