api: Javadoc changes for io.grpc.LoadBalancer method signatures

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

@@ -156,15 +156,17 @@ public String toString() {
   private int recursionCount;
 
   /**
-   * Handles newly resolved server groups and metadata attributes from name resolution system.
-   * {@code servers} contained in {@link EquivalentAddressGroup} should be considered equivalent
-   * but may be flattened into a single list if needed.
-   *
-   * <p>Implementations should not modify the given {@code servers}.
+   * Handles newly resolved addresses and metadata attributes from name resolution system.
+   * Addresses in {@link EquivalentAddressGroup} should be considered equivalent but may be
+   * flattened into a single list if needed.
    *
    * @param resolvedAddresses the resolved server addresses, attributes, and config.
    * @since 1.21.0
+   *
+   * @deprecated  As of release 1.69.0, use instead
+   *     {@link #acceptResolvedAddresses(ResolvedAddresses)}
    */
+  @Deprecated
   public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
     if (recursionCount++ == 0) {
       // Note that the information about the addresses actually being accepted will be lost
@@ -179,12 +181,15 @@ public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
    * EquivalentAddressGroup} addresses should be considered equivalent but may be flattened into a
    * single list if needed.
    *
-   * <p>Implementations can choose to reject the given addresses by returning {@code false}.
+   * <p>Implementations can choose to reject the given addresses by returning
+   * {@code Status.UNAVAILABLE}.
    *
-   * <p>Implementations should not modify the given {@code addresses}.
+   * <p>Implementations should not modify the given {@code resolvedAddresses}.
    *
    * @param resolvedAddresses the resolved server addresses, attributes, and config.
-   * @return {@code true} if the resolved addresses were accepted. {@code false} if rejected.
+   * @return {@code Status.OK} if the resolved addresses were accepted. {@code Status.UNAVAILABLE}
+   *     if rejected.
+   *
    * @since 1.49.0
    */
   public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {

interop-testing/src/main/java/io/grpc/testing/integration/RpcBehaviorLoadBalancerProvider.java

@@ -111,10 +111,10 @@ protected LoadBalancer delegate() {
     }
 
     @Override
-    public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       helper.setRpcBehavior(
           ((RpcBehaviorConfig) resolvedAddresses.getLoadBalancingPolicyConfig()).rpcBehavior);
-      delegateLb.handleResolvedAddresses(resolvedAddresses);
+      return delegateLb.acceptResolvedAddresses(resolvedAddresses);
     }
 
     @Override

interop-testing/src/test/java/io/grpc/testing/integration/RpcBehaviorLoadBalancerProviderTest.java

@@ -83,8 +83,8 @@ public void handleResolvedAddressesDelegated() {
     RpcBehaviorLoadBalancer lb = new RpcBehaviorLoadBalancer(new RpcBehaviorHelper(mockHelper),
         mockDelegateLb);
     ResolvedAddresses resolvedAddresses = buildResolvedAddresses(buildConfig());
-    lb.handleResolvedAddresses(resolvedAddresses);
-    verify(mockDelegateLb).handleResolvedAddresses(resolvedAddresses);
+    lb.acceptResolvedAddresses(resolvedAddresses);
+    verify(mockDelegateLb).acceptResolvedAddresses(resolvedAddresses);
   }
 
   @Test

util/src/main/java/io/grpc/util/ForwardingLoadBalancer.java

@@ -29,9 +29,21 @@ public abstract class ForwardingLoadBalancer extends LoadBalancer {
    */
   protected abstract LoadBalancer delegate();
 
-  @Override
+  /**
+   * Handles newly resolved addresses and metadata attributes from name resolution system.
+   *
+   * @deprecated  As of release 1.69.0,
+   *     use instead {@link #acceptResolvedAddresses(ResolvedAddresses)}
+   */
+  @Deprecated
+  @SuppressWarnings("all")
   public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
-    delegate().handleResolvedAddresses(resolvedAddresses);
+    acceptResolvedAddresses(resolvedAddresses);
+  }
+
+  @Override
+  public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    return delegate().acceptResolvedAddresses(resolvedAddresses);
   }
 
   @Override

util/src/main/java/io/grpc/util/GracefulSwitchLoadBalancer.java

@@ -49,6 +49,13 @@
 @NotThreadSafe // Must be accessed in SynchronizationContext
 public final class GracefulSwitchLoadBalancer extends ForwardingLoadBalancer {
   private final LoadBalancer defaultBalancer = new LoadBalancer() {
+    /**
+     * Handles newly resolved addresses and metadata attributes from name resolution system.
+     *
+     * @deprecated  As of release 1.69.0,
+     *     use instead {@link #acceptResolvedAddresses(ResolvedAddresses)}
+     */
+    @Deprecated
     @Override
     public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       throw new AssertionError("real LB is called instead");
@@ -97,6 +104,13 @@ public GracefulSwitchLoadBalancer(Helper helper) {
     this.helper = checkNotNull(helper, "helper");
   }
 
+  /**
+   * Handles newly resolved addresses and metadata attributes from name resolution system.
+   *
+   * @deprecated  As of release 1.69.0,
+   *     use instead {@link #acceptResolvedAddresses(ResolvedAddresses)}
+   */
+  @Deprecated
   @Override
   public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
     Config config = (Config) resolvedAddresses.getLoadBalancingPolicyConfig();

util/src/test/java/io/grpc/util/ForwardingLoadBalancerTest.java

@@ -45,6 +45,8 @@ public void allMethodsForwarded() throws Exception {
         mockDelegate,
         new TestBalancer(),
         Arrays.asList(
-            LoadBalancer.class.getMethod("acceptResolvedAddresses", ResolvedAddresses.class)));
+            LoadBalancer.class.getMethod("acceptResolvedAddresses", ResolvedAddresses.class),
+            LoadBalancer.class.getMethod("handleResolvedAddresses", ResolvedAddresses.class))
+    );
   }
 }

util/src/test/java/io/grpc/util/GracefulSwitchLoadBalancerTest.java

@@ -140,6 +140,7 @@ public void canHandleEmptyAddressListFromNameResolutionForwardedToLatestPolicy()
     assertThat(gracefulSwitchLb.canHandleEmptyAddressListFromNameResolution()).isTrue();
   }
 
+  @Deprecated
   @Test
   public void handleResolvedAddressesAndNameResolutionErrorForwardedToLatestPolicy() {
     ResolvedAddresses addresses = newFakeAddresses();

xds/src/test/java/io/grpc/xds/CdsLoadBalancer2Test.java

@@ -802,8 +802,9 @@ private final class FakeLoadBalancer extends LoadBalancer {
     }
 
     @Override
-    public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       config = resolvedAddresses.getLoadBalancingPolicyConfig();
+      return Status.OK;
     }
 
     @Override

xds/src/test/java/io/grpc/xds/MetadataLoadBalancerProvider.java

@@ -107,6 +107,13 @@ protected LoadBalancer delegate() {
       return delegateLb;
     }
 
+    /**
+     * Handles newly resolved addresses and metadata attributes from name resolution system.
+     *
+     * @deprecated  As of release 1.69.0,
+     *     use instead {@link #acceptResolvedAddresses(ResolvedAddresses)}
+     */
+    @Deprecated
     @Override
     public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       MetadataLoadBalancerConfig config

xds/src/test/java/io/grpc/xds/PriorityLoadBalancerTest.java

@@ -145,6 +145,7 @@ public void tearDown() {
     assertThat(fakeClock.getPendingTasks()).isEmpty();
   }
 
+  @Deprecated
   @Test
   public void acceptResolvedAddresses() {
     SocketAddress socketAddress = new InetSocketAddress(8080);
@@ -239,6 +240,7 @@ public void acceptResolvedAddresses() {
     verify(barBalancer0, never()).shutdown();
   }
 
+  @Deprecated
   @Test
   public void acceptResolvedAddresses_propagatesChildFailures() {
     LoadBalancerProvider lbProvider = new CannedLoadBalancer.Provider();
@@ -332,6 +334,7 @@ public void handleNameResolutionError() {
     verify(fooLb1).handleNameResolutionError(status);
   }
 
+  @Deprecated
   @Test
   public void typicalPriorityFailOverFlow() {
     PriorityChildConfig priorityChildConfig0 =
@@ -470,6 +473,7 @@ public PickResult pickSubchannel(PickSubchannelArgs args) {
     verify(balancer3).shutdown();
   }
 
+  @Deprecated
   @Test
   public void idleToConnectingDoesNotTriggerFailOver() {
     PriorityChildConfig priorityChildConfig0 =
@@ -506,6 +510,7 @@ public void idleToConnectingDoesNotTriggerFailOver() {
     assertThat(fooHelpers).hasSize(1);
   }
 
+  @Deprecated
   @Test
   public void connectingResetFailOverIfSeenReadyOrIdleSinceTransientFailure() {
     PriorityChildConfig priorityChildConfig0 =
@@ -548,6 +553,7 @@ public void connectingResetFailOverIfSeenReadyOrIdleSinceTransientFailure() {
     assertThat(fooHelpers).hasSize(2);
   }
 
+  @Deprecated
   @Test
   public void readyToConnectDoesNotFailOverButUpdatesPicker() {
     PriorityChildConfig priorityChildConfig0 =
@@ -605,6 +611,7 @@ public PickResult pickSubchannel(PickSubchannelArgs args) {
     assertThat(fooHelpers).hasSize(1);
   }
 
+  @Deprecated
   @Test
   public void typicalPriorityFailOverFlowWithIdleUpdate() {
     PriorityChildConfig priorityChildConfig0 =
@@ -713,6 +720,7 @@ public void typicalPriorityFailOverFlowWithIdleUpdate() {
     verify(balancer3).shutdown();
   }
 
+  @Deprecated
   @Test
   public void failover_propagatesChildFailures() {
     LoadBalancerProvider lbProvider = new CannedLoadBalancer.Provider();
@@ -790,6 +798,7 @@ public void bypassReresolutionRequestsIfConfiged() {
     verify(helper).refreshNameResolution();
   }
 
+  @Deprecated
   @Test
   public void raceBetweenShutdownAndChildLbBalancingStateUpdate() {
     PriorityChildConfig priorityChildConfig0 =
@@ -815,6 +824,7 @@ public void raceBetweenShutdownAndChildLbBalancingStateUpdate() {
     verifyNoMoreInteractions(helper);
   }
 
+  @Deprecated
   @Test
   public void noDuplicateOverallBalancingStateUpdate() {
     FakeLoadBalancerProvider fakeLbProvider = new FakeLoadBalancerProvider();
@@ -915,6 +925,7 @@ static class FakeLoadBalancer extends LoadBalancer {
       this.helper = helper;
     }
 
+    @Deprecated
     @Override
     public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       helper.updateBalancingState(

xds/src/test/java/io/grpc/xds/WeightedTargetLoadBalancerTest.java

@@ -179,6 +179,7 @@ public void tearDown() {
     }
   }
 
+  @Deprecated
   @Test
   public void handleResolvedAddresses() {
     ArgumentCaptor<ResolvedAddresses> resolvedAddressesCaptor =
@@ -264,6 +265,7 @@ public void handleResolvedAddresses() {
     }
   }
 
+  @Deprecated
   @Test
   public void handleNameResolutionError() {
     ArgumentCaptor<SubchannelPicker> pickerCaptor = ArgumentCaptor.forClass(SubchannelPicker.class);
@@ -302,6 +304,7 @@ public void handleNameResolutionError() {
     }
   }
 
+  @Deprecated
   @Test
   public void balancingStateUpdatedFromChildBalancers() {
     Map<String, WeightedPolicySelection> targets = ImmutableMap.of(
@@ -390,6 +393,7 @@ public void balancingStateUpdatedFromChildBalancers() {
             new WeightedChildPicker(weights[3], failurePickers[3]));
   }
 
+  @Deprecated
   @Test
   public void raceBetweenShutdownAndChildLbBalancingStateUpdate() {
     Map<String, WeightedPolicySelection> targets = ImmutableMap.of(
@@ -412,6 +416,7 @@ public void raceBetweenShutdownAndChildLbBalancingStateUpdate() {
 
   // When the ChildHelper is asked to update the overall balancing state, it should not do that if
   // the update was triggered by the parent LB that will handle triggering the overall state update.
+  @Deprecated
   @Test
   public void noDuplicateOverallBalancingStateUpdate() {
     FakeLoadBalancerProvider fakeLbProvider = new FakeLoadBalancerProvider();
@@ -469,6 +474,7 @@ static class FakeLoadBalancer extends LoadBalancer {
       this.helper = helper;
     }
 
+    @Deprecated
     @Override
     public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       helper.updateBalancingState(

xds/src/test/java/io/grpc/xds/WrrLocalityLoadBalancerTest.java

@@ -107,6 +107,7 @@ public void setUp() {
     loadBalancer = new WrrLocalityLoadBalancer(mockHelper, lbRegistry);
   }
 
+  @Deprecated
   @Test
   public void acceptResolvedAddresses() {
     // A two locality cluster with a mock child LB policy.
@@ -173,6 +174,7 @@ public void handleNameResolutionError_withChildLb() {
     verify(mockWeightedTargetLb).handleNameResolutionError(status);
   }
 
+  @Deprecated
   @Test
   public void localityWeightAttributeNotPropagated() {
     Object childPolicy = newChildConfig(mockChildProvider, null);
@@ -212,6 +214,7 @@ private Object newChildConfig(LoadBalancerProvider provider, Object config) {
     return GracefulSwitchLoadBalancer.createLoadBalancingPolicyConfig(provider, config);
   }
 
+  @Deprecated
   private void deliverAddresses(WrrLocalityConfig config, List<EquivalentAddressGroup> addresses) {
     loadBalancer.acceptResolvedAddresses(
         ResolvedAddresses.newBuilder().setAddresses(addresses).setLoadBalancingPolicyConfig(config)