core: Deprecate ForwardingChannelBuilder (#10587)

Deprecate `ForwardingChannelBuilder` in favor of `ForwardingChannelBuilder2`.

alts/src/main/java/io/grpc/alts/AltsChannelBuilder.java

@@ -18,7 +18,7 @@ package io.grpc.alts;
 
 import com.google.common.annotations.VisibleForTesting;
 import io.grpc.ExperimentalApi;
-import io.grpc.ForwardingChannelBuilder;
+import io.grpc.ForwardingChannelBuilder2;
 import io.grpc.ManagedChannel;
 import io.grpc.ManagedChannelBuilder;
 import io.grpc.internal.GrpcUtil;
@@ -32,7 +32,7 @@ import javax.annotation.Nullable;
  * commmunication between two cloud VMs using ALTS.
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/4151")
-public final class AltsChannelBuilder extends ForwardingChannelBuilder<AltsChannelBuilder> {
+public final class AltsChannelBuilder extends ForwardingChannelBuilder2<AltsChannelBuilder> {
   private final NettyChannelBuilder delegate;
   private final AltsChannelCredentials.Builder credentialsBuilder =
       new AltsChannelCredentials.Builder();

alts/src/main/java/io/grpc/alts/ComputeEngineChannelBuilder.java

@@ -45,6 +45,7 @@ public final class ComputeEngineChannelBuilder
   }
 
   @Override
+  @SuppressWarnings("deprecation") // Not extending ForwardingChannelBuilder2 to preserve ABI.
   protected NettyChannelBuilder delegate() {
     return delegate;
   }

alts/src/main/java/io/grpc/alts/GoogleDefaultChannelBuilder.java

@@ -45,6 +45,7 @@ public final class GoogleDefaultChannelBuilder
   }
 
   @Override
+  @SuppressWarnings("deprecation") // Not extending ForwardingChannelBuilder2 to preserve ABI.
   protected NettyChannelBuilder delegate() {
     return delegate;
   }

android/src/main/java/io/grpc/android/AndroidChannelBuilder.java

@@ -156,6 +156,7 @@ public final class AndroidChannelBuilder extends ForwardingChannelBuilder<Androi
   }
 
   @Override
+  @SuppressWarnings("deprecation") // Not extending ForwardingChannelBuilder2 to preserve ABI.
   protected ManagedChannelBuilder<?> delegate() {
     return delegateBuilder;
   }

api/src/main/java/io/grpc/ForwardingChannelBuilder.java

@@ -26,7 +26,7 @@ import javax.annotation.Nullable;
  * A {@link ManagedChannelBuilder} that delegates all its builder methods to another builder by
  * default.
  *
- * <p>Important! Use {@link ForwardingChannelBuilder2} instead!
+ * <p>DEPRECATED: Use {@link ForwardingChannelBuilder2} instead!
  *
  * <p>This class mistakenly used {@code <T extends ForwardingChannelBuilder<T>>} which causes
  * return types to be {@link ForwardingChannelBuilder} instead of {@link ManagedChannelBuilder}.
@@ -38,14 +38,29 @@ import javax.annotation.Nullable;
  */
 public abstract class ForwardingChannelBuilder<T extends ForwardingChannelBuilder<T>>
     extends ForwardingChannelBuilder2<T> {
-  // TODO(sergiitk): deprecate after stabilizing
-
   /**
    * The default constructor.
    */
   protected ForwardingChannelBuilder() {
   }
 
+
+  /**
+   * Returns the delegated {@code ManagedChannelBuilder}.
+   *
+   * <p>NOTE: this method is marked deprecated instead the class itself, so that classes extending
+   * {@link ForwardingChannelBuilder2} won't need class-level
+   * {@code @SuppressWarnings("deprecation")} annotation. Such annotation would suppress all
+   * deprecation warnings in all methods, inadvertently hiding any real deprecation warnings needing
+   * to be addressed. However, each child class is expected to implement {@code delegate()}.
+   * Therefore, the {@code @Deprecated} annotation is added to this method, and not to the class.
+   *
+   * @deprecated As of 1.60.0, use {@link ForwardingChannelBuilder2} instead.
+   */
+  @Override
+  @Deprecated
+  protected abstract ManagedChannelBuilder<?> delegate();
+
   @Override
   public T directExecutor() {
     delegate().directExecutor();

api/src/test/java/io/grpc/ForwardingChannelBuilderTest.java

@@ -39,6 +39,7 @@ public class ForwardingChannelBuilderTest {
 
   private final class TestBuilder extends ForwardingChannelBuilder<TestBuilder> {
     @Override
+    @SuppressWarnings("deprecation")
     protected ManagedChannelBuilder<?> delegate() {
       return mockDelegate;
     }

api/src/test/java/io/grpc/ManagedChannelRegistryTest.java

@@ -125,7 +125,7 @@ public class ManagedChannelRegistryTest {
         return NewChannelBuilderResult.error("dodging");
       }
     });
-    class MockChannelBuilder extends ForwardingChannelBuilder<MockChannelBuilder> {
+    class MockChannelBuilder extends ForwardingChannelBuilder2<MockChannelBuilder> {
       @Override public ManagedChannelBuilder<?> delegate() {
         throw new UnsupportedOperationException();
       }
@@ -199,7 +199,7 @@ public class ManagedChannelRegistryTest {
         throw new AssertionError();
       }
     });
-    class MockChannelBuilder extends ForwardingChannelBuilder<MockChannelBuilder> {
+    class MockChannelBuilder extends ForwardingChannelBuilder2<MockChannelBuilder> {
       @Override public ManagedChannelBuilder<?> delegate() {
         throw new UnsupportedOperationException();
       }
@@ -282,7 +282,7 @@ public class ManagedChannelRegistryTest {
     NameResolverRegistry nameResolverRegistry = new NameResolverRegistry();
 
     ManagedChannelRegistry registry = new ManagedChannelRegistry();
-    class MockChannelBuilder extends ForwardingChannelBuilder<MockChannelBuilder> {
+    class MockChannelBuilder extends ForwardingChannelBuilder2<MockChannelBuilder> {
       @Override public ManagedChannelBuilder<?> delegate() {
         throw new UnsupportedOperationException();
       }
@@ -320,7 +320,7 @@ public class ManagedChannelRegistryTest {
     });
 
     ManagedChannelRegistry registry = new ManagedChannelRegistry();
-    class MockChannelBuilder extends ForwardingChannelBuilder<MockChannelBuilder> {
+    class MockChannelBuilder extends ForwardingChannelBuilder2<MockChannelBuilder> {
       @Override public ManagedChannelBuilder<?> delegate() {
         throw new UnsupportedOperationException();
       }
@@ -351,7 +351,7 @@ public class ManagedChannelRegistryTest {
 
     ManagedChannelRegistry registry = new ManagedChannelRegistry();
 
-    class MockChannelBuilder extends ForwardingChannelBuilder<MockChannelBuilder> {
+    class MockChannelBuilder extends ForwardingChannelBuilder2<MockChannelBuilder> {
       @Override public ManagedChannelBuilder<?> delegate() {
         throw new UnsupportedOperationException();
       }

binder/src/main/java/io/grpc/binder/BinderChannelBuilder.java

@@ -231,6 +231,7 @@ public final class BinderChannelBuilder
   }
 
   @Override
+  @SuppressWarnings("deprecation") // Not extending ForwardingChannelBuilder2 to preserve ABI.
   protected ManagedChannelBuilder<?> delegate() {
     return managedChannelImplBuilder;
   }

core/src/main/java/io/grpc/internal/ManagedChannelImpl.java

@@ -49,7 +49,7 @@ import io.grpc.Context;
 import io.grpc.Deadline;
 import io.grpc.DecompressorRegistry;
 import io.grpc.EquivalentAddressGroup;
-import io.grpc.ForwardingChannelBuilder;
+import io.grpc.ForwardingChannelBuilder2;
 import io.grpc.ForwardingClientCall;
 import io.grpc.Grpc;
 import io.grpc.InternalChannelz;
@@ -1593,7 +1593,7 @@ final class ManagedChannelImpl extends ManagedChannel implements
       checkNotNull(channelCreds, "channelCreds");
 
       final class ResolvingOobChannelBuilder
-          extends ForwardingChannelBuilder<ResolvingOobChannelBuilder> {
+          extends ForwardingChannelBuilder2<ResolvingOobChannelBuilder> {
         final ManagedChannelBuilder<?> delegate;
 
         ResolvingOobChannelBuilder() {

rls/src/test/java/io/grpc/rls/CachingRlsLbClientTest.java

@@ -40,7 +40,7 @@ import io.grpc.ChannelCredentials;
 import io.grpc.ChannelLogger;
 import io.grpc.ConnectivityState;
 import io.grpc.EquivalentAddressGroup;
-import io.grpc.ForwardingChannelBuilder;
+import io.grpc.ForwardingChannelBuilder2;
 import io.grpc.LoadBalancer;
 import io.grpc.LoadBalancer.Helper;
 import io.grpc.LoadBalancer.PickResult;
@@ -817,7 +817,7 @@ public class CachingRlsLbClientTest {
       final InProcessChannelBuilder builder =
           InProcessChannelBuilder.forName(target).directExecutor();
 
-      class CleaningChannelBuilder extends ForwardingChannelBuilder<CleaningChannelBuilder> {
+      class CleaningChannelBuilder extends ForwardingChannelBuilder2<CleaningChannelBuilder> {
 
         @Override
         protected ManagedChannelBuilder<?> delegate() {

rls/src/test/java/io/grpc/rls/RlsLoadBalancerTest.java

@@ -36,7 +36,7 @@ import io.grpc.ChannelLogger;
 import io.grpc.ConnectivityState;
 import io.grpc.ConnectivityStateInfo;
 import io.grpc.EquivalentAddressGroup;
-import io.grpc.ForwardingChannelBuilder;
+import io.grpc.ForwardingChannelBuilder2;
 import io.grpc.LoadBalancer.CreateSubchannelArgs;
 import io.grpc.LoadBalancer.Helper;
 import io.grpc.LoadBalancer.PickResult;
@@ -519,7 +519,7 @@ public class RlsLoadBalancerTest {
       final InProcessChannelBuilder builder =
           InProcessChannelBuilder.forName(target).directExecutor();
 
-      class CleaningChannelBuilder extends ForwardingChannelBuilder<CleaningChannelBuilder> {
+      class CleaningChannelBuilder extends ForwardingChannelBuilder2<CleaningChannelBuilder> {
 
         @Override
         protected ManagedChannelBuilder<?> delegate() {