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) {

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

services/src/test/java/io/grpc/protobuf/services/HealthCheckingLoadBalancerFactoryTest.java

@@ -206,15 +206,16 @@ public void setup() throws Exception {
         boolean shutdown;
 
         @Override
-        public void handleResolvedAddresses(final ResolvedAddresses resolvedAddresses) {
+        public Status acceptResolvedAddresses(final ResolvedAddresses resolvedAddresses) {
           syncContext.execute(new Runnable() {
               @Override
               public void run() {
                 if (!shutdown) {
-                  hcLb.handleResolvedAddresses(resolvedAddresses);
+                  hcLb.acceptResolvedAddresses(resolvedAddresses);
                 }
               }
             });
+          return Status.OK;
         }
 
         @Override
@@ -264,9 +265,9 @@ public void typicalWorkflow() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result);
+    hcLbEventDelivery.acceptResolvedAddresses(result);
 
-    verify(origLb).handleResolvedAddresses(result);
+    verify(origLb).acceptResolvedAddresses(result);
     verify(origHelper, atLeast(0)).getSynchronizationContext();
     verify(origHelper, atLeast(0)).getScheduledExecutorService();
     verifyNoMoreInteractions(origHelper);
@@ -404,9 +405,9 @@ public void healthCheckDisabledWhenServiceNotImplemented() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result);
+    hcLbEventDelivery.acceptResolvedAddresses(result);
 
-    verify(origLb).handleResolvedAddresses(result);
+    verify(origLb).acceptResolvedAddresses(result);
     verifyNoMoreInteractions(origLb);
 
     // We create 2 Subchannels. One of them connects to a server that doesn't implement health check
@@ -489,9 +490,9 @@ public void backoffRetriesWhenServerErroneouslyClosesRpcBeforeAnyResponse() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result);
+    hcLbEventDelivery.acceptResolvedAddresses(result);
 
-    verify(origLb).handleResolvedAddresses(result);
+    verify(origLb).acceptResolvedAddresses(result);
     verifyNoMoreInteractions(origLb);
 
     SubchannelStateListener mockHealthListener = mockHealthListeners[0];
@@ -567,9 +568,9 @@ public void serverRespondResetsBackoff() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result);
+    hcLbEventDelivery.acceptResolvedAddresses(result);
 
-    verify(origLb).handleResolvedAddresses(result);
+    verify(origLb).acceptResolvedAddresses(result);
     verifyNoMoreInteractions(origLb);
 
     SubchannelStateListener mockStateListener = mockStateListeners[0];
@@ -667,9 +668,9 @@ public void serviceConfigHasNoHealthCheckingInitiallyButDoesLater() {
         .setAddresses(resolvedAddressList)
         .setAttributes(Attributes.EMPTY)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
 
-    verify(origLb).handleResolvedAddresses(result1);
+    verify(origLb).acceptResolvedAddresses(result1);
     verifyNoMoreInteractions(origLb);
 
     // First, create Subchannels 0
@@ -688,8 +689,8 @@ public void serviceConfigHasNoHealthCheckingInitiallyButDoesLater() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result2);
-    verify(origLb).handleResolvedAddresses(result2);
+    hcLbEventDelivery.acceptResolvedAddresses(result2);
+    verify(origLb).acceptResolvedAddresses(result2);
 
     // Health check started on existing Subchannel
     assertThat(healthImpls[0].calls).hasSize(1);
@@ -711,9 +712,9 @@ public void serviceConfigDisablesHealthCheckWhenRpcActive() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
 
-    verify(origLb).handleResolvedAddresses(result1);
+    verify(origLb).acceptResolvedAddresses(result1);
     verifyNoMoreInteractions(origLb);
 
     Subchannel subchannel = createSubchannel(0, Attributes.EMPTY, maybeGetMockListener());
@@ -738,15 +739,15 @@ public void serviceConfigDisablesHealthCheckWhenRpcActive() {
         .setAddresses(resolvedAddressList)
         .setAttributes(Attributes.EMPTY)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result2);
+    hcLbEventDelivery.acceptResolvedAddresses(result2);
 
     // Health check RPC cancelled.
     assertThat(serverCall.cancelled).isTrue();
     // Subchannel uses original state
     inOrder.verify(getMockListener()).onSubchannelState(
         eq(ConnectivityStateInfo.forNonError(READY)));
 
-    inOrder.verify(origLb).handleResolvedAddresses(result2);
+    inOrder.verify(origLb).acceptResolvedAddresses(result2);
 
     verifyNoMoreInteractions(origLb, mockStateListeners[0]);
     assertThat(healthImpl.calls).isEmpty();
@@ -759,9 +760,9 @@ public void serviceConfigDisablesHealthCheckWhenRetryPending() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result);
+    hcLbEventDelivery.acceptResolvedAddresses(result);
 
-    verify(origLb).handleResolvedAddresses(result);
+    verify(origLb).acceptResolvedAddresses(result);
     verifyNoMoreInteractions(origLb);
 
     SubchannelStateListener mockHealthListener = mockHealthListeners[0];
@@ -793,7 +794,7 @@ public void serviceConfigDisablesHealthCheckWhenRetryPending() {
         .setAddresses(resolvedAddressList)
         .setAttributes(Attributes.EMPTY)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result2);
+    hcLbEventDelivery.acceptResolvedAddresses(result2);
 
     // Retry timer is cancelled
     assertThat(clock.getPendingTasks()).isEmpty();
@@ -805,7 +806,7 @@ public void serviceConfigDisablesHealthCheckWhenRetryPending() {
     inOrder.verify(getMockListener()).onSubchannelState(
         eq(ConnectivityStateInfo.forNonError(READY)));
 
-    inOrder.verify(origLb).handleResolvedAddresses(result2);
+    inOrder.verify(origLb).acceptResolvedAddresses(result2);
 
     verifyNoMoreInteractions(origLb, mockStateListeners[0]);
   }
@@ -817,9 +818,9 @@ public void serviceConfigDisablesHealthCheckWhenRpcInactive() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
 
-    verify(origLb).handleResolvedAddresses(result1);
+    verify(origLb).acceptResolvedAddresses(result1);
     verifyNoMoreInteractions(origLb);
 
     Subchannel subchannel = createSubchannel(0, Attributes.EMPTY, maybeGetMockListener());
@@ -842,9 +843,9 @@ public void serviceConfigDisablesHealthCheckWhenRpcInactive() {
         .setAddresses(resolvedAddressList)
         .setAttributes(Attributes.EMPTY)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result2);
+    hcLbEventDelivery.acceptResolvedAddresses(result2);
 
-    inOrder.verify(origLb).handleResolvedAddresses(result2);
+    inOrder.verify(origLb).acceptResolvedAddresses(result2);
 
     // Underlying subchannel is now ready
     deliverSubchannelState(0, ConnectivityStateInfo.forNonError(READY));
@@ -870,9 +871,9 @@ public void serviceConfigChangesServiceNameWhenRpcActive() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
 
-    verify(origLb).handleResolvedAddresses(result1);
+    verify(origLb).acceptResolvedAddresses(result1);
     verifyNoMoreInteractions(origLb);
 
     SubchannelStateListener mockHealthListener = mockHealthListeners[0];
@@ -900,9 +901,9 @@ public void serviceConfigChangesServiceNameWhenRpcActive() {
         eq(ConnectivityStateInfo.forNonError(READY)));
 
     // Service config returns with the same health check name.
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
     // It's delivered to origLb, but nothing else happens
-    inOrder.verify(origLb).handleResolvedAddresses(result1);
+    inOrder.verify(origLb).acceptResolvedAddresses(result1);
     verifyNoMoreInteractions(origLb, mockListener);
 
     // Service config returns a different health check name.
@@ -911,8 +912,8 @@ public void serviceConfigChangesServiceNameWhenRpcActive() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result2);
-    inOrder.verify(origLb).handleResolvedAddresses(result2);
+    hcLbEventDelivery.acceptResolvedAddresses(result2);
+    inOrder.verify(origLb).acceptResolvedAddresses(result2);
 
     // Current health check RPC cancelled.
     assertThat(serverCall.cancelled).isTrue();
@@ -934,9 +935,9 @@ public void serviceConfigChangesServiceNameWhenRetryPending() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
 
-    verify(origLb).handleResolvedAddresses(result1);
+    verify(origLb).acceptResolvedAddresses(result1);
     verifyNoMoreInteractions(origLb);
 
     SubchannelStateListener mockHealthListener = mockHealthListeners[0];
@@ -969,9 +970,9 @@ public void serviceConfigChangesServiceNameWhenRetryPending() {
 
     // Service config returns with the same health check name.
 
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
     // It's delivered to origLb, but nothing else happens
-    inOrder.verify(origLb).handleResolvedAddresses(result1);
+    inOrder.verify(origLb).acceptResolvedAddresses(result1);
     verifyNoMoreInteractions(origLb, mockListener);
     assertThat(clock.getPendingTasks()).hasSize(1);
     assertThat(healthImpl.calls).isEmpty();
@@ -982,12 +983,12 @@ public void serviceConfigChangesServiceNameWhenRetryPending() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result2);
+    hcLbEventDelivery.acceptResolvedAddresses(result2);
     // Concluded CONNECTING state
     inOrder.verify(getMockListener()).onSubchannelState(
         eq(ConnectivityStateInfo.forNonError(CONNECTING)));
 
-    inOrder.verify(origLb).handleResolvedAddresses(result2);
+    inOrder.verify(origLb).acceptResolvedAddresses(result2);
 
     // Current retry timer cancelled
     assertThat(clock.getPendingTasks()).isEmpty();
@@ -1008,9 +1009,9 @@ public void serviceConfigChangesServiceNameWhenRpcInactive() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
 
-    verify(origLb).handleResolvedAddresses(result1);
+    verify(origLb).acceptResolvedAddresses(result1);
     verifyNoMoreInteractions(origLb);
 
     Subchannel subchannel = createSubchannel(0, Attributes.EMPTY, maybeGetMockListener());
@@ -1031,9 +1032,9 @@ public void serviceConfigChangesServiceNameWhenRpcInactive() {
     inOrder.verifyNoMoreInteractions();
 
     // Service config returns with the same health check name.
-    hcLbEventDelivery.handleResolvedAddresses(result1);
+    hcLbEventDelivery.acceptResolvedAddresses(result1);
     // It's delivered to origLb, but nothing else happens
-    inOrder.verify(origLb).handleResolvedAddresses(result1);
+    inOrder.verify(origLb).acceptResolvedAddresses(result1);
     assertThat(healthImpl.calls).isEmpty();
     verifyNoMoreInteractions(origLb);
 
@@ -1043,9 +1044,9 @@ public void serviceConfigChangesServiceNameWhenRpcInactive() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result2);
+    hcLbEventDelivery.acceptResolvedAddresses(result2);
 
-    inOrder.verify(origLb).handleResolvedAddresses(result2);
+    inOrder.verify(origLb).acceptResolvedAddresses(result2);
 
     // Underlying subchannel is now ready
     deliverSubchannelState(0, ConnectivityStateInfo.forNonError(READY));
@@ -1092,9 +1093,9 @@ public void balancerShutdown() {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result);
+    hcLbEventDelivery.acceptResolvedAddresses(result);
 
-    verify(origLb).handleResolvedAddresses(result);
+    verify(origLb).acceptResolvedAddresses(result);
     verifyNoMoreInteractions(origLb);
     ServerSideCall[] serverCalls = new ServerSideCall[NUM_SUBCHANNELS];
 
@@ -1172,8 +1173,8 @@ public LoadBalancer newLoadBalancer(Helper helper) {
         .setAddresses(resolvedAddressList)
         .setAttributes(resolutionAttrs)
         .build();
-    hcLbEventDelivery.handleResolvedAddresses(result);
-    verify(origLb).handleResolvedAddresses(result);
+    hcLbEventDelivery.acceptResolvedAddresses(result);
+    verify(origLb).acceptResolvedAddresses(result);
     createSubchannel(0, Attributes.EMPTY);
     assertThat(healthImpls[0].calls).isEmpty();
     deliverSubchannelState(0, ConnectivityStateInfo.forNonError(READY));

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

@@ -30,8 +30,8 @@ public abstract class ForwardingLoadBalancer extends LoadBalancer {
   protected abstract LoadBalancer delegate();
 
   @Override
-  public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
-    delegate().handleResolvedAddresses(resolvedAddresses);
+  public Status acceptResolvedAddresses(ResolvedAddresses resolvedAddresses) {
+    return delegate().acceptResolvedAddresses(resolvedAddresses);
   }
 
   @Override