From 72dd8f9a982b66d4579922967b64c9b83b998bfe Mon Sep 17 00:00:00 2001 From: Eric Anderson Date: Wed, 7 Jun 2017 16:13:47 -0700 Subject: [PATCH] core: Mark NameResolverProvider experimental and clarify docs We don't want people to be desensitized to the Internal annotation. NameResolverProvider should have probably been ExperimentalApi from the start, but it was copied from ManagedChannelProvider. Theoretically, ManagedChannelProvider could be marked ExperimentalApi as well, but there are no known use cases for doing so since making an alternative ManagedChannel implementation is quite difficuilt and we aren't aware of anybody interested in doing so. That isn't the case for NameResolverProvider; NameResolverProvider is core to 'targets' being useful. --- core/src/main/java/io/grpc/ManagedChannelBuilder.java | 10 +++++++--- core/src/main/java/io/grpc/NameResolverProvider.java | 2 +- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/core/src/main/java/io/grpc/ManagedChannelBuilder.java b/core/src/main/java/io/grpc/ManagedChannelBuilder.java index 7b1696e4dc..0745cddd8f 100644 --- a/core/src/main/java/io/grpc/ManagedChannelBuilder.java +++ b/core/src/main/java/io/grpc/ManagedChannelBuilder.java @@ -159,10 +159,14 @@ public abstract class ManagedChannelBuilder> public abstract T usePlaintext(boolean skipNegotiation); /** - * Provides a custom {@link NameResolver.Factory} for the channel. + * Provides a custom {@link NameResolver.Factory} for the channel. If this method is not called, + * the builder will try the providers listed by {@link NameResolverProvider#providers()} for the + * given target. * - *

If this method is not called, the builder will try the providers listed by {@link - * NameResolverProvider#providers()} for the given target. + *

This method should rarely be used, as name resolvers should provide a {@code + * NameResolverProvider} and users rely on service loading to find implementations in the class + * path. That allows application's configuration to easily choose the name resolver via the + * 'target' string passed to {@link ManagedChannelBuilder#forTarget(String)}. * * @return this * @since 1.0.0 diff --git a/core/src/main/java/io/grpc/NameResolverProvider.java b/core/src/main/java/io/grpc/NameResolverProvider.java index d056ac4605..34c36c5e27 100644 --- a/core/src/main/java/io/grpc/NameResolverProvider.java +++ b/core/src/main/java/io/grpc/NameResolverProvider.java @@ -33,7 +33,7 @@ import java.util.ServiceLoader; * exceptions may reasonably occur for implementation-specific reasons, implementations should * generally handle the exception gracefully and return {@code false} from {@link #isAvailable()}. */ -@Internal +@ExperimentalApi public abstract class NameResolverProvider extends NameResolver.Factory { /** * The port number used in case the target or the underlying naming system doesn't provide a