On result2 resolution result have addresses or error (grpc#11330)

Combined success / error status passed via ResolutionResult to the NameResolver.Listener2 interface's onResult2 method - Addresses in the success case or address resolution error in the failure case now get set in ResolutionResult::addressesOrError by the internal name resolvers.

Author: kannanjgithub

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

@@ -20,13 +20,13 @@
 import static com.google.common.base.Preconditions.checkNotNull;
 
 import com.google.common.base.MoreObjects;
+import com.google.common.base.MoreObjects.ToStringHelper;
 import com.google.common.base.Objects;
 import com.google.errorprone.annotations.InlineMe;
 import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.net.URI;
-import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
 import java.util.Map;
@@ -95,7 +95,8 @@ public void onError(Status error) {
 
           @Override
           public void onResult(ResolutionResult resolutionResult) {
-            listener.onAddresses(resolutionResult.getAddresses(), resolutionResult.getAttributes());
+            listener.onAddresses(resolutionResult.getAddressesOrError().getValue(),
+                resolutionResult.getAttributes());
           }
       });
     }
@@ -218,19 +219,21 @@ public abstract static class Listener2 implements Listener {
     @Override
     @Deprecated
     @InlineMe(
-        replacement = "this.onResult(ResolutionResult.newBuilder().setAddresses(servers)"
-            + ".setAttributes(attributes).build())",
-        imports = "io.grpc.NameResolver.ResolutionResult")
+        replacement = "this.onResult2(ResolutionResult.newBuilder().setAddressesOrError("
+            + "StatusOr.fromValue(servers)).setAttributes(attributes).build())",
+        imports = {"io.grpc.NameResolver.ResolutionResult", "io.grpc.StatusOr"})
     public final void onAddresses(
         List<EquivalentAddressGroup> servers, @ResolutionResultAttr Attributes attributes) {
       // TODO(jihuncho) need to promote Listener2 if we want to use ConfigOrError
-      onResult(
-          ResolutionResult.newBuilder().setAddresses(servers).setAttributes(attributes).build());
+      onResult2(
+          ResolutionResult.newBuilder().setAddressesOrError(
+              StatusOr.fromValue(servers)).setAttributes(attributes).build());
     }
 
     /**
      * Handles updates on resolved addresses and attributes.  If
-     * {@link ResolutionResult#getAddresses()} is empty, {@link #onError(Status)} will be called.
+     * {@link ResolutionResult#getAddressesOrError()} is empty, {@link #onError(Status)} will be
+     * called.
      *
      * @param resolutionResult the resolved server addresses, attributes, and Service Config.
      * @since 1.21.0
@@ -584,17 +587,17 @@ public abstract static class ServiceConfigParser {
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770")
   public static final class ResolutionResult {
-    private final List<EquivalentAddressGroup> addresses;
+    private final StatusOr<List<EquivalentAddressGroup>> addressesOrError;
     @ResolutionResultAttr
     private final Attributes attributes;
     @Nullable
     private final ConfigOrError serviceConfig;
 
     ResolutionResult(
-        List<EquivalentAddressGroup> addresses,
+        StatusOr<List<EquivalentAddressGroup>> addressesOrError,
         @ResolutionResultAttr Attributes attributes,
         ConfigOrError serviceConfig) {
-      this.addresses = Collections.unmodifiableList(new ArrayList<>(addresses));
+      this.addressesOrError = addressesOrError;
       this.attributes = checkNotNull(attributes, "attributes");
       this.serviceConfig = serviceConfig;
     }
@@ -615,7 +618,7 @@ public static Builder newBuilder() {
      */
     public Builder toBuilder() {
       return newBuilder()
-          .setAddresses(addresses)
+          .setAddressesOrError(addressesOrError)
           .setAttributes(attributes)
           .setServiceConfig(serviceConfig);
     }
@@ -624,9 +627,20 @@ public Builder toBuilder() {
      * Gets the addresses resolved by name resolution.
      *
      * @since 1.21.0
+     * @deprecated Will be superseded by getAddressesOrError
      */
+    @Deprecated
     public List<EquivalentAddressGroup> getAddresses() {
-      return addresses;
+      return addressesOrError.getValue();
+    }
+
+    /**
+     * Gets the addresses resolved by name resolution or the error in doing so.
+     *
+     * @since 1.65.0
+     */
+    public StatusOr<List<EquivalentAddressGroup>> getAddressesOrError() {
+      return addressesOrError;
     }
 
     /**
@@ -652,11 +666,11 @@ public ConfigOrError getServiceConfig() {
 
     @Override
     public String toString() {
-      return MoreObjects.toStringHelper(this)
-          .add("addresses", addresses)
-          .add("attributes", attributes)
-          .add("serviceConfig", serviceConfig)
-          .toString();
+      ToStringHelper stringHelper = MoreObjects.toStringHelper(this);
+      stringHelper.add("addressesOrError", addressesOrError.toString());
+      stringHelper.add("attributes", attributes);
+      stringHelper.add("serviceConfigOrError", serviceConfig);
+      return stringHelper.toString();
     }
 
     /**
@@ -668,7 +682,7 @@ public boolean equals(Object obj) {
         return false;
       }
       ResolutionResult that = (ResolutionResult) obj;
-      return Objects.equal(this.addresses, that.addresses)
+      return Objects.equal(this.addressesOrError, that.addressesOrError)
           && Objects.equal(this.attributes, that.attributes)
           && Objects.equal(this.serviceConfig, that.serviceConfig);
     }
@@ -678,7 +692,7 @@ public boolean equals(Object obj) {
      */
     @Override
     public int hashCode() {
-      return Objects.hashCode(addresses, attributes, serviceConfig);
+      return Objects.hashCode(addressesOrError, attributes, serviceConfig);
     }
 
     /**
@@ -688,7 +702,8 @@ public int hashCode() {
      */
     @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770")
     public static final class Builder {
-      private List<EquivalentAddressGroup> addresses = Collections.emptyList();
+      private StatusOr<List<EquivalentAddressGroup>> addresses =
+          StatusOr.fromValue(Collections.emptyList());
       private Attributes attributes = Attributes.EMPTY;
       @Nullable
       private ConfigOrError serviceConfig;
@@ -700,9 +715,21 @@ public static final class Builder {
        * Sets the addresses resolved by name resolution.  This field is required.
        *
        * @since 1.21.0
+       * @deprecated Will be superseded by setAddressesOrError
        */
+      @Deprecated
       public Builder setAddresses(List<EquivalentAddressGroup> addresses) {
-        this.addresses = addresses;
+        setAddressesOrError(StatusOr.fromValue(addresses));
+        return this;
+      }
+
+      /**
+       * Sets the addresses resolved by name resolution or the error in doing so. This field is
+       * required.
+       * @param addresses Resolved addresses or an error in resolving addresses
+       */
+      public Builder setAddressesOrError(StatusOr<List<EquivalentAddressGroup>> addresses) {
+        this.addresses = checkNotNull(addresses, "StatusOr addresses cannot be null.");
         return this;
       }
 

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

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2024 The gRPC Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.grpc;
+
+import static com.google.common.base.Preconditions.checkArgument;
+import static com.google.common.base.Preconditions.checkNotNull;
+
+import com.google.common.base.MoreObjects;
+import com.google.common.base.MoreObjects.ToStringHelper;
+import com.google.common.base.Objects;
+import javax.annotation.Nullable;
+
+/** Either a Status or a value. */
+@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11563")
+public class StatusOr<T> {
+  private StatusOr(Status status, T value) {
+    this.status = status;
+    this.value = value;
+  }
+
+  /** Construct from a value. */
+  public static <T> StatusOr<T> fromValue(@Nullable T value) {
+    StatusOr<T> result = new StatusOr<T>(null, value);
+    return result;
+  }
+
+  /** Construct from a non-Ok status. */
+  public static <T> StatusOr<T> fromStatus(Status status) {
+    StatusOr<T> result = new StatusOr<T>(checkNotNull(status, "status"), null);
+    checkArgument(!status.isOk(), "cannot use OK status: %s", status);
+    return result;
+  }
+
+  /** Returns whether there is a value. */
+  public boolean hasValue() {
+    return status == null;
+  }
+
+  /**
+   * Returns the value if set or throws exception if there is no value set. This method is meant
+   * to be called after checking the return value of hasValue() first.
+   */
+  public @Nullable T getValue() {
+    if (status != null) {
+      throw new IllegalStateException("No value present.");
+    }
+    return value;
+  }
+
+  /** Returns the status. If there is a value (which can be null), returns OK. */
+  public Status getStatus() {
+    return status == null ? Status.OK : status;
+  }
+
+  @Override
+  public boolean equals(Object other) {
+    if (!(other instanceof StatusOr)) {
+      return false;
+    }
+    StatusOr<?> otherStatus = (StatusOr<?>) other;
+    if (hasValue() != otherStatus.hasValue()) {
+      return false;
+    }
+    if (hasValue()) {
+      return Objects.equal(value, otherStatus.value);
+    }
+    return Objects.equal(status, otherStatus.status);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hashCode(status, value);
+  }
+
+  @Override
+  public String toString() {
+    ToStringHelper stringHelper = MoreObjects.toStringHelper(this);
+    if (status == null) {
+      stringHelper.add("value", value);
+    } else {
+      stringHelper.add("error", status);
+    }
+    return stringHelper.toString();
+  }
+
+  private final Status status;
+  private final T value;
+}