api: Deprecate the old way of handling resolved addresses in LoadBala…

…ncer

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

@@ -126,6 +126,10 @@ public abstract class LoadBalancer {
    *
    * @param resolvedAddresses the resolved server addresses, attributes, and config.
    * @since 1.21.0
+   * @deprecated Please override {@code acceptResolvedAddresses()} instead. Also note that
+   * {@code canHandleEmptyAddressListFromNameResolution()} is deprecated as well as
+   * {@code acceptResolvedAddresses()} should now indicate the acceptance of the addresses with its
+   * return value.
    */
   public void handleResolvedAddresses(ResolvedAddresses resolvedAddresses) {
     if (recursionCount++ == 0) {
@@ -141,7 +145,9 @@ 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 false}. Please
+   * note that an empty list of addresses could be provided and that the deprecated {@code
+   * canHandleEmptyAddressListFromNameResolution()} will be ignored when this method is overwritten.
    *
    * <p>Implementations should not modify the given {@code addresses}.
    *
@@ -379,6 +385,13 @@ 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 the deprecated {@code handleResolvedAddresses()}
+   * is overwritten.
+   *
+   * @deprecated Instead of overwriting this and {@code handleResolvedAddresses()} please only
+   * overwrite {@code acceptResolvedAddresses()}. In that method you can indicate if the addresses
+   * provided by the name resolver are acceptable with the {@code boolean} return value.
    */
   public boolean canHandleEmptyAddressListFromNameResolution() {
     return false;