Change the return types of transitiveClosure() and reachableNodes() to Immutable* types.

One of those changes is only a change in the declared return type; the other is a behavior change:
- `reachableNodes()` already returned an immutable object, even though that was not reflected in the declared return type.
- `transitiveClosure()` used to return a mutable object.

RELNOTES=`graph`: Changed the return types of `transitiveClosure()` and `reachableNodes()` to `Immutable*` types. `reachableNodes()` already returned an immutable object (even though that was not reflected in the declared return type); `transitiveClosure()` used to return a mutable object.
PiperOrigin-RevId: 607051970

Author: cushon

android/guava/src/com/google/common/graph/Graphs.java

@@ -43,7 +43,7 @@
  */
 @Beta
 @ElementTypesAreNonnullByDefault
-public final class Graphs {
+public final class Graphs extends GraphsBridgeMethods {
 
   private Graphs() {}
 
@@ -146,10 +146,13 @@ private static boolean canTraverseWithoutReusingEdge(
    * <p>This is a "snapshot" based on the current topology of {@code graph}, rather than a live view
    * of the transitive closure of {@code graph}. In other words, the returned {@link Graph} will not
    * be updated after modifications to {@code graph}.
+   *
+   * @since NEXT (present with return type {@code Graph} since 20.0)
    */
   // TODO(b/31438252): Consider potential optimizations for this algorithm.
-  public static <N> Graph<N> transitiveClosure(Graph<N> graph) {
-    MutableGraph<N> transitiveClosure = GraphBuilder.from(graph).allowsSelfLoops(true).build();
+  public static <N> ImmutableGraph<N> transitiveClosure(Graph<N> graph) {
+    ImmutableGraph.Builder<N> transitiveClosure =
+        GraphBuilder.from(graph).allowsSelfLoops(true).<N>immutable();
     // Every node is, at a minimum, reachable from itself. Since the resulting transitive closure
     // will have no isolated nodes, we can skip adding nodes explicitly and let putEdge() do it.
 
@@ -178,7 +181,7 @@ public static <N> Graph<N> transitiveClosure(Graph<N> graph) {
       }
     }
 
-    return transitiveClosure;
+    return transitiveClosure.build();
   }
 
   /**
@@ -191,8 +194,9 @@ public static <N> Graph<N> transitiveClosure(Graph<N> graph) {
    * not be updated after modifications to {@code graph}.
    *
    * @throws IllegalArgumentException if {@code node} is not present in {@code graph}
+   * @since NEXT (present with return type {@code Set} since 20.0)
    */
-  public static <N> Set<N> reachableNodes(Graph<N> graph, N node) {
+  public static <N> ImmutableSet<N> reachableNodes(Graph<N> graph, N node) {
     checkArgument(graph.nodes().contains(node), NODE_NOT_IN_GRAPH, node);
     return ImmutableSet.copyOf(Traverser.forGraph(graph).breadthFirst(node));
   }

android/guava/src/com/google/common/graph/GraphsBridgeMethods.java

@@ -0,0 +1,23 @@
+package com.google.common.graph;
+
+import com.google.common.annotations.Beta;
+import java.util.Set;
+
+/**
+ * Supertype for {@link Graphs}, containing the old signatures of methods whose signatures we've
+ * changed. This provides binary compatibility for users who compiled against the old signatures.
+ */
+@Beta
+@ElementTypesAreNonnullByDefault
+abstract class GraphsBridgeMethods {
+
+  @SuppressWarnings("PreferredInterfaceType")
+  public static <N> Graph<N> transitiveClosure(Graph<N> graph) {
+    return Graphs.transitiveClosure(graph);
+  }
+
+  @SuppressWarnings("PreferredInterfaceType")
+  public static <N> Set<N> reachableNodes(Graph<N> graph, N node) {
+    return Graphs.reachableNodes(graph, node);
+  }
+}

guava/src/com/google/common/graph/Graphs.java

@@ -44,7 +44,7 @@
  */
 @Beta
 @ElementTypesAreNonnullByDefault
-public final class Graphs {
+public final class Graphs extends GraphsBridgeMethods {
 
   private Graphs() {}
 
@@ -147,10 +147,13 @@ private static boolean canTraverseWithoutReusingEdge(
    * <p>This is a "snapshot" based on the current topology of {@code graph}, rather than a live view
    * of the transitive closure of {@code graph}. In other words, the returned {@link Graph} will not
    * be updated after modifications to {@code graph}.
+   *
+   * @since NEXT (present with return type {@code Graph} since 20.0)
    */
   // TODO(b/31438252): Consider potential optimizations for this algorithm.
-  public static <N> Graph<N> transitiveClosure(Graph<N> graph) {
-    MutableGraph<N> transitiveClosure = GraphBuilder.from(graph).allowsSelfLoops(true).build();
+  public static <N> ImmutableGraph<N> transitiveClosure(Graph<N> graph) {
+    ImmutableGraph.Builder<N> transitiveClosure =
+        GraphBuilder.from(graph).allowsSelfLoops(true).<N>immutable();
     // Every node is, at a minimum, reachable from itself. Since the resulting transitive closure
     // will have no isolated nodes, we can skip adding nodes explicitly and let putEdge() do it.
 
@@ -179,7 +182,7 @@ public static <N> Graph<N> transitiveClosure(Graph<N> graph) {
       }
     }
 
-    return transitiveClosure;
+    return transitiveClosure.build();
   }
 
   /**
@@ -192,8 +195,9 @@ public static <N> Graph<N> transitiveClosure(Graph<N> graph) {
    * not be updated after modifications to {@code graph}.
    *
    * @throws IllegalArgumentException if {@code node} is not present in {@code graph}
+   * @since NEXT (present with return type {@code Set} since 20.0)
    */
-  public static <N> Set<N> reachableNodes(Graph<N> graph, N node) {
+  public static <N> ImmutableSet<N> reachableNodes(Graph<N> graph, N node) {
     checkArgument(graph.nodes().contains(node), NODE_NOT_IN_GRAPH, node);
     return ImmutableSet.copyOf(Traverser.forGraph(graph).breadthFirst(node));
   }

guava/src/com/google/common/graph/GraphsBridgeMethods.java

@@ -0,0 +1,23 @@
+package com.google.common.graph;
+
+import com.google.common.annotations.Beta;
+import java.util.Set;
+
+/**
+ * Supertype for {@link Graphs}, containing the old signatures of methods whose signatures we've
+ * changed. This provides binary compatibility for users who compiled against the old signatures.
+ */
+@Beta
+@ElementTypesAreNonnullByDefault
+abstract class GraphsBridgeMethods {
+
+  @SuppressWarnings("PreferredInterfaceType")
+  public static <N> Graph<N> transitiveClosure(Graph<N> graph) {
+    return Graphs.transitiveClosure(graph);
+  }
+
+  @SuppressWarnings("PreferredInterfaceType")
+  public static <N> Set<N> reachableNodes(Graph<N> graph, N node) {
+    return Graphs.reachableNodes(graph, node);
+  }
+}