diff --git a/core/src/main/java/io/grpc/NameResolver.java b/core/src/main/java/io/grpc/NameResolver.java index c4d3993286..ac2aef1578 100644 --- a/core/src/main/java/io/grpc/NameResolver.java +++ b/core/src/main/java/io/grpc/NameResolver.java @@ -83,7 +83,7 @@ public abstract class NameResolver { * 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 @@ public abstract class NameResolver { * *

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 abstract class NameResolver { * {@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 abstract class NameResolver { * {@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 class NameResolver { * 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 abstract class NameResolver { /** * 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 abstract class NameResolver { /** * 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 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 abstract class NameResolver { /** * Gets the Service Config parsed by {@link NameResolver.Helper#parseServiceConfig(Map)}. * - * @since 1.20.0 + * @since 1.21.0 */ @Nullable public Object getServiceConfig() { @@ -496,20 +509,21 @@ public abstract class NameResolver { /** * A builder for {@link ResolutionResult}. * - * @since 1.20.0 + * @since 1.21.0 */ public static final class Builder { private List 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 servers) { this.servers = servers; @@ -517,9 +531,10 @@ public abstract class NameResolver { } /** - * 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 abstract class NameResolver { /** * 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 abstract class NameResolver { /** * 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);