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

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.
+   * Handles newly resolved addresses and metadata attributes from name resolution system.
+   * {@link EquivalentAddressGroup} addresses should be considered equivalent but may be flattened
+   * into a single list if needed.
    *
-   * <p>Implementations should not modify the given {@code servers}.
+   * <p>Implementations should not modify the given {@code resolvedAddresses}.
    *
    * @param resolvedAddresses the resolved server addresses, attributes, and config.
    * @since 1.21.0
    */
+  @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,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) {
@@ -197,7 +201,7 @@ public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       return unavailableStatus;
     } else {
       if (recursionCount++ == 0) {
-        handleResolvedAddresses(resolvedAddresses);
+        //handleResolvedAddresses(resolvedAddresses);
       }
       recursionCount = 0;
 

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

@@ -263,7 +263,7 @@ public void shutdown() {
         new EquivalentAddressGroup(new SocketAddress(){}));
     ResolvedAddresses addresses = ResolvedAddresses.newBuilder().setAddresses(servers)
         .setAttributes(attrs).build();
-    balancer.handleResolvedAddresses(addresses);
+    balancer.acceptResolvedAddresses(addresses);
     assertThat(resultCapture.get()).isEqualTo(
         ResolvedAddresses.newBuilder().setAddresses(servers).setAttributes(attrs).build());
   }
@@ -275,8 +275,9 @@ public void acceptResolvedAddresses_delegatesToHandleResolvedAddressGroups() {
 
     LoadBalancer balancer = new LoadBalancer() {
         @Override
-        public void handleResolvedAddresses(ResolvedAddresses addresses) {
+        public Status acceptResolvedAddresses(ResolvedAddresses addresses) {
           addressesCapture.set(addresses);
+          return Status.OK;
         }
 
         @Override
@@ -297,7 +298,7 @@ public void shutdown() {
         new EquivalentAddressGroup(new SocketAddress(){}));
     ResolvedAddresses addresses = ResolvedAddresses.newBuilder().setAddresses(servers)
         .setAttributes(attrs).build();
-    balancer.handleResolvedAddresses(addresses);
+    balancer.acceptResolvedAddresses(addresses);
     assertThat(addressesCapture.get().getAddresses()).isEqualTo(servers);
     assertThat(addressesCapture.get().getAttributes()).isEqualTo(attrs);
   }
@@ -309,9 +310,10 @@ public void acceptResolvedAddresses_noInfiniteLoop() {
 
     LoadBalancer balancer = new LoadBalancer() {
       @Override
-      public void handleResolvedAddresses(ResolvedAddresses addresses) {
+      public Status acceptResolvedAddresses(ResolvedAddresses addresses) {
         addressesCapture.add(addresses);
-        super.handleResolvedAddresses(addresses);
+        super.acceptResolvedAddresses(addresses);
+        return Status.OK;
       }
 
       @Override
@@ -328,7 +330,7 @@ public void shutdown() {
         new EquivalentAddressGroup(new SocketAddress(){}));
     ResolvedAddresses addresses = ResolvedAddresses.newBuilder().setAddresses(servers)
         .setAttributes(attrs).build();
-    balancer.handleResolvedAddresses(addresses);
+    balancer.acceptResolvedAddresses(addresses);
     assertThat(addressesCapture).hasSize(1);
     assertThat(addressesCapture.get(0).getAddresses()).isEqualTo(servers);
     assertThat(addressesCapture.get(0).getAttributes()).isEqualTo(attrs);

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);
     }
   }
 

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

services/src/main/java/io/grpc/protobuf/services/HealthCheckingLoadBalancerFactory.java

@@ -187,14 +187,14 @@ protected LoadBalancer delegate() {
     }
 
     @Override
-    public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
       Map<String, ?> healthCheckingConfig =
           resolvedAddresses
               .getAttributes()
               .get(LoadBalancer.ATTR_HEALTH_CHECKING_CONFIG);
       String serviceName = ServiceConfigUtil.getHealthCheckedServiceName(healthCheckingConfig);
       helper.setHealthCheckedService(serviceName);
-      super.handleResolvedAddresses(resolvedAddresses);
+      return super.acceptResolvedAddresses(resolvedAddresses);
     }
 
     @Override