api: Add documentation for Provider SPI discovery

4 files changed, 26 insertions, 0 deletions

diff --git a/api/src/main/java/io/grpc/LoadBalancerProvider.java b/api/src/main/java/io/grpc/LoadBalancerProvider.java
index 2b2db7a6d..bb4c57421 100644
--- a/api/src/main/java/io/grpc/LoadBalancerProvider.java
+++ b/api/src/main/java/io/grpc/LoadBalancerProvider.java
@@ -23,6 +23,16 @@ import java.util.Map;
 /**
  * Provider of {@link LoadBalancer}s.  Each provider is bounded to a load-balancing policy name.
  *
+ * <p>Implementations can be automatically discovered by gRPC via Java's SPI mechanism. For
+ * automatic discovery, the implementation must have a zero-argument constructor and include
+ * a resource named {@code META-INF/services/io.grpc.LoadBalancerProvider} in their JAR. The
+ * file's contents should be the implementation's class name. Implementations that need arguments in
+ * their constructor can be manually registered by {@link LoadBalancerRegistry#register}.
+ *
+ * <p>Implementations <em>should not</em> throw. If they do, it may interrupt class loading. If
+ * exceptions may reasonably occur for implementation-specific reasons, implementations should
+ * generally handle the exception gracefully and return {@code false} from {@link #isAvailable()}.
+ *
  * @since 1.17.0
  */
 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1771")
diff --git a/api/src/main/java/io/grpc/ManagedChannelProvider.java b/api/src/main/java/io/grpc/ManagedChannelProvider.java
index 26e29727b..76a8d6707 100644
--- a/api/src/main/java/io/grpc/ManagedChannelProvider.java
+++ b/api/src/main/java/io/grpc/ManagedChannelProvider.java
@@ -25,6 +25,11 @@ import java.util.List;
 /**
  * Provider of managed channels for transport agnostic consumption.
  *
+ * <p>Implementations can be automatically discovered by gRPC via Java's SPI mechanism. For
+ * automatic discovery, the implementation must have a zero-argument constructor and include
+ * a resource named {@code META-INF/services/io.grpc.ManagedChannelProvider} in their JAR. The
+ * file's contents should be the implementation's class name.
+ *
  * <p>Implementations <em>should not</em> throw. If they do, it may interrupt class loading. If
  * exceptions may reasonably occur for implementation-specific reasons, implementations should
  * generally handle the exception gracefully and return {@code false} from {@link #isAvailable()}.
diff --git a/api/src/main/java/io/grpc/NameResolverProvider.java b/api/src/main/java/io/grpc/NameResolverProvider.java
index 8875092b0..6cf6e3716 100644
--- a/api/src/main/java/io/grpc/NameResolverProvider.java
+++ b/api/src/main/java/io/grpc/NameResolverProvider.java
@@ -21,6 +21,12 @@ import java.util.List;
 /**
  * Provider of name resolvers for name agnostic consumption.
  *
+ * <p>Implementations can be automatically discovered by gRPC via Java's SPI mechanism. For
+ * automatic discovery, the implementation must have a zero-argument constructor and include
+ * a resource named {@code META-INF/services/io.grpc.NameResolverProvider} in their JAR. The
+ * file's contents should be the implementation's class name. Implementations that need arguments in
+ * their constructor can be manually registered by {@link NameResolverRegistry#register}.
+ *
  * <p>Implementations <em>should not</em> throw. If they do, it may interrupt class loading. If
  * exceptions may reasonably occur for implementation-specific reasons, implementations should
  * generally handle the exception gracefully and return {@code false} from {@link #isAvailable()}.
diff --git a/api/src/main/java/io/grpc/ServerProvider.java b/api/src/main/java/io/grpc/ServerProvider.java
index 301d05b77..a6a28dd86 100644
--- a/api/src/main/java/io/grpc/ServerProvider.java
+++ b/api/src/main/java/io/grpc/ServerProvider.java
@@ -23,6 +23,11 @@ import java.util.Collections;
 /**
  * Provider of servers for transport agnostic consumption.
  *
+ * <p>Implementations can be automatically discovered by gRPC via Java's SPI mechanism. For
+ * automatic discovery, the implementation must have a zero-argument constructor and include
+ * a resource named {@code META-INF/services/io.grpc.ServerProvider} in their JAR. The
+ * file's contents should be the implementation's class name.
+ *
  * <p>Implementations <em>should not</em> throw. If they do, it may interrupt class loading. If
  * exceptions may reasonably occur for implementation-specific reasons, implementations should
  * generally handle the exception gracefully and return {@code false} from {@link #isAvailable()}.