api: Deprecate LoadBalancer.handleResolvedAddresses() (grpc#11623)

Also deprecate its companion
canHandleEmptyAddressListFromNameResolution().
Also fixup the Javadoc to align with the arguments/return values, so
that people would have a better idea of how to use it.

Fixes grpc#11194

---------

Co-authored-by: MV Shiva Prasad <okshiva@google.com>
Co-authored-by: Eric Anderson <ejona@google.com>

Author: 3 people

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

@@ -156,15 +156,16 @@ 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  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 +180,10 @@ 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 should not modify the given {@code addresses}.
+   * @param resolvedAddresses the resolved server addresses, attributes, and config
+   * @return {@code Status.OK} if the resolved addresses were accepted, otherwise an error to report
+   *     to the name resolver
    *
-   * @param resolvedAddresses the resolved server addresses, attributes, and config.
-   * @return {@code true} if the resolved addresses were accepted. {@code false} if rejected.
    * @since 1.49.0
    */
   public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
@@ -418,7 +417,16 @@ public void handleSubchannelState(
    *
    * <p>This method should always return a constant value.  It's not specified when this will be
    * called.
+   * 
+   * <p>Note that this method is only called when implementing {@code handleResolvedAddresses()}
+   * instead of {@code acceptResolvedAddresses()}.
+   *
+   * @deprecated Instead of overwriting this and {@code handleResolvedAddresses()}, only
+   *     overwrite {@code acceptResolvedAddresses()} which indicates if the addresses provided
+   *     by the name resolver are acceptable with the {@code boolean} return value.
    */
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public boolean canHandleEmptyAddressListFromNameResolution() {
     return false;
   }

grpclb/src/main/java/io/grpc/grpclb/GrpclbLoadBalancer.java

@@ -154,6 +154,8 @@ public void handleNameResolutionError(Status error) {
   }
 
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public boolean canHandleEmptyAddressListFromNameResolution() {
     return true;
   }

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

@@ -110,6 +110,7 @@ protected LoadBalancer delegate() {
       return delegateLb;
     }
 
+    @Deprecated
     @Override
     public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       helper.setRpcBehavior(

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

@@ -78,6 +78,7 @@ public void parseInvalidConfig() {
     assertThat(status.getDescription()).contains("rpcBehavior");
   }
 
+  @Deprecated
   @Test
   public void handleResolvedAddressesDelegated() {
     RpcBehaviorLoadBalancer lb = new RpcBehaviorLoadBalancer(new RpcBehaviorHelper(mockHelper),

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

@@ -29,6 +29,7 @@ public abstract class ForwardingLoadBalancer extends LoadBalancer {
    */
   protected abstract LoadBalancer delegate();
 
+  @Deprecated
   @Override
   public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
     delegate().handleResolvedAddresses(resolvedAddresses);
@@ -52,6 +53,8 @@ public void shutdown() {
   }
 
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public boolean canHandleEmptyAddressListFromNameResolution() {
     return delegate().canHandleEmptyAddressListFromNameResolution();
   }

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

@@ -84,6 +84,7 @@ public GracefulSwitchLoadBalancer(Helper helper) {
     this.helper = checkNotNull(helper, "helper");
   }
 
+  @Deprecated
   @Override
   public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
     Config config = (Config) resolvedAddresses.getLoadBalancingPolicyConfig();

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

@@ -102,6 +102,7 @@ public void handleSubchannelState_shouldThrow() {
   }
 
   @Test
+  @Deprecated
   public void canHandleEmptyAddressListFromNameResolutionForwardedToLatestPolicy() {
     assertIsOk(gracefulSwitchLb.acceptResolvedAddresses(addressesBuilder()
         .setLoadBalancingPolicyConfig(createConfig(lbPolicies[0], new Object()))
@@ -136,6 +137,7 @@ public void canHandleEmptyAddressListFromNameResolutionForwardedToLatestPolicy()
     assertThat(gracefulSwitchLb.canHandleEmptyAddressListFromNameResolution()).isTrue();
   }
 
+  @Deprecated
   @Test
   public void handleResolvedAddressesAndNameResolutionErrorForwardedToLatestPolicy() {
     ResolvedAddresses addresses = newFakeAddresses();

xds/src/main/java/io/grpc/xds/ClusterImplLoadBalancer.java

@@ -152,14 +152,13 @@ public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
     childLbHelper.updateFilterMetadata(config.filterMetadata);
     childLbHelper.updateBackendMetricPropagation(config.backendMetricPropagation);
 
-    childSwitchLb.handleResolvedAddresses(
+    return childSwitchLb.acceptResolvedAddresses(
         resolvedAddresses.toBuilder()
             .setAttributes(attributes.toBuilder()
               .set(NameResolver.ATTR_BACKEND_SERVICE, cluster)
               .build())
             .setLoadBalancingPolicyConfig(config.childConfig)
             .build());
-    return Status.OK;
   }
 
   @Override

xds/src/main/java/io/grpc/xds/WeightedTargetLoadBalancer.java

@@ -128,6 +128,8 @@ public void handleNameResolutionError(Status error) {
   }
 
   @Override
+  @Deprecated
+  @SuppressWarnings("InlineMeSuggester")
   public boolean canHandleEmptyAddressListFromNameResolution() {
     return true;
   }

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

@@ -107,6 +107,7 @@ protected LoadBalancer delegate() {
       return delegateLb;
     }
 
+    @Deprecated
     @Override
     public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       MetadataLoadBalancerConfig config