core: update since javadoc, and add toBuilder for NameResolver results

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

@@ -83,7 +83,7 @@ public void start(Listener listener) {
    * Starts the resolution.  This method will become abstract in 1.21.0.
    *
    * @param observer used to receive updates on the target
-   * @since 1.20.0
+   * @since 1.21.0
    */
   public void start(Observer observer) {
     start((Listener) observer);
@@ -231,7 +231,7 @@ void onAddresses(
    *
    * <p>All methods are expected to return quickly.
    *
-   * @since 1.20.0
+   * @since 1.21.0
    */
   public abstract static class Observer implements Listener {
     /**
@@ -249,7 +249,7 @@ public final void onAddresses(
      * {@link ResolutionResult#getServers()} is empty, {@link #onError(Status)} will be called.
      *
      * @param resolutionResult the resolved server addresses, attributes, and Service Config.
-     * @since 1.20.0
+     * @since 1.21.0
      */
     public abstract void onResult(ResolutionResult resolutionResult);
 
@@ -258,7 +258,7 @@ public final void onAddresses(
      * {@link NameResolver#refresh()} to re-attempt resolution.
      *
      * @param error a non-OK status
-     * @since 1.20.0
+     * @since 1.21.0
      */
     @Override
     public abstract void onError(Status error);
@@ -299,7 +299,7 @@ public abstract static class Helper {
      * Returns the {@link SynchronizationContext} where {@link #start(Observer)}, {@link #shutdown}
      * and {@link #refresh} are run from.
      *
-     * @since 1.20.0
+     * @since 1.21.0
      */
     public SynchronizationContext getSynchronizationContext() {
       throw new UnsupportedOperationException("Not implemented");
@@ -411,7 +411,7 @@ public String toString() {
   /**
    * Represents the results from a Name Resolver.
    *
-   * @since 1.20.0
+   * @since 1.21.0
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1770")
   public static final class ResolutionResult {
@@ -433,25 +433,38 @@ public static final class ResolutionResult {
     /**
      * Constructs a new builder of a name resolution result.
      *
-     * @since 1.20.0
+     * @since 1.21.0
      */
     public static Builder newBuilder() {
       return new Builder();
     }
 
+    /**
+     * Converts these results back to a builder.
+     *
+     * @since 1.21.0
+     */
+    public Builder toBuilder() {
+      return newBuilder()
+          .setServers(servers)
+          .setAttributes(attributes)
+          .setServiceConfig(serviceConfig);
+    }
+
     /**
      * Gets the servers resolved by name resolution.
      *
-     * @since 1.20.0
+     * @since 1.21.0
      */
     public List<EquivalentAddressGroup> getServers() {
       return servers;
     }
 
     /**
-     * Gets the attributes associated with the servers resolved by name resolution.
+     * Gets the attributes associated with the servers resolved by name resolution.  If there are
+     * no attributes, {@link Attributes#EMPTY} will be returned.
      *
-     * @since 1.20.0
+     * @since 1.21.0
      */
     @ResolutionResultAttr
     public Attributes getAttributes() {
@@ -461,7 +474,7 @@ public Attributes getAttributes() {
     /**
      * Gets the Service Config parsed by {@link NameResolver.Helper#parseServiceConfig(Map)}.
      *
-     * @since 1.20.0
+     * @since 1.21.0
      */
     @Nullable
     public Object getServiceConfig() {
@@ -496,30 +509,32 @@ public int hashCode() {
     /**
      * A builder for {@link ResolutionResult}.
      *
-     * @since 1.20.0
+     * @since 1.21.0
      */
     public static final class Builder {
       private List<EquivalentAddressGroup> servers = Collections.emptyList();
       private Attributes attributes = Attributes.EMPTY;
       @Nullable
       private Object serviceConfig;
+      //  Make sure to update #toBuilder above!
 
       Builder() {}
 
       /**
-       * Sets the servers resolved by name resolution.
+       * Sets the servers resolved by name resolution.  This field is required.
        *
-       * @since 1.20.0
+       * @since 1.21.0
        */
       public Builder setServers(List<EquivalentAddressGroup> servers) {
         this.servers = servers;
         return this;
       }
 
       /**
-       * Sets the attributes for the servers resolved by name resolution.
+       * Sets the attributes for the servers resolved by name resolution.  If unset,
+       * {@link Attributes#EMPTY} will be used as a default.
        *
-       * @since 1.20.0
+       * @since 1.21.0
        */
       public Builder setAttributes(Attributes attributes) {
         this.attributes = attributes;
@@ -528,8 +543,9 @@ public Builder setAttributes(Attributes attributes) {
 
       /**
        * Sets the Service Config parsed by {@link NameResolver.Helper#parseServiceConfig(Map)}.
+       * This field is optional.
        *
-       * @since 1.20.0
+       * @since 1.21.0
        */
       public Builder setServiceConfig(@Nullable Object serviceConfig) {
         this.serviceConfig = serviceConfig;
@@ -539,7 +555,7 @@ public Builder setServiceConfig(@Nullable Object serviceConfig) {
       /**
        * Constructs a new {@link ResolutionResult} from this builder.
        *
-       * @since 1.20.0
+       * @since 1.21.0
        */
       public ResolutionResult build() {
         return new ResolutionResult(servers, attributes, serviceConfig);