xds: Improve grpc-xds javadoc and make it publishable

- Improve package-info.java and make minor changes to other javadoc.
- Make Orca API non-public for the moment.
- Make grpc-xds publishable.

13 files changed, 52 insertions, 20 deletions

diff --git a/xds/build.gradle b/xds/build.gradle
index fa53527fe..994d77b20 100644
--- a/xds/build.gradle
+++ b/xds/build.gradle
@@ -63,6 +63,10 @@ jar {
     classifier = 'original'
 }
 
+javadoc {
+    exclude 'io/grpc/xds/internal/**'
+}
+
 shadowJar {
     classifier = null
     dependencies {
@@ -95,4 +99,3 @@ publishing {
         }
     }
 }
-[publishMavenPublicationToMavenRepository]*.onlyIf { false }
diff --git a/xds/src/main/java/io/grpc/xds/Bootstrapper.java b/xds/src/main/java/io/grpc/xds/Bootstrapper.java
index ab6076f83..54eaff148 100644
--- a/xds/src/main/java/io/grpc/xds/Bootstrapper.java
+++ b/xds/src/main/java/io/grpc/xds/Bootstrapper.java
@@ -234,6 +234,7 @@ public abstract class Bootstrapper {
   /**
    * Data class containing the results of reading bootstrap.
    */
+  @Internal
   @Immutable
   public static class BootstrapInfo {
     private List<ServerInfo> servers;
diff --git a/xds/src/main/java/io/grpc/xds/CdsLoadBalancer.java b/xds/src/main/java/io/grpc/xds/CdsLoadBalancer.java
index 832e365b9..eedea9858 100644
--- a/xds/src/main/java/io/grpc/xds/CdsLoadBalancer.java
+++ b/xds/src/main/java/io/grpc/xds/CdsLoadBalancer.java
@@ -50,7 +50,7 @@ import javax.annotation.Nullable;
 /**
  * Load balancer for cds_experimental LB policy.
  */
-public final class CdsLoadBalancer extends LoadBalancer {
+final class CdsLoadBalancer extends LoadBalancer {
   private final ChannelLogger channelLogger;
   private final LoadBalancerRegistry lbRegistry;
   private final GracefulSwitchLoadBalancer switchingLoadBalancer;
diff --git a/xds/src/main/java/io/grpc/xds/EdsLoadBalancer.java b/xds/src/main/java/io/grpc/xds/EdsLoadBalancer.java
index 5331ed14c..9ad0f86fc 100644
--- a/xds/src/main/java/io/grpc/xds/EdsLoadBalancer.java
+++ b/xds/src/main/java/io/grpc/xds/EdsLoadBalancer.java
@@ -148,7 +148,7 @@ final class EdsLoadBalancer extends LoadBalancer {
               TRANSIENT_FAILURE,
               new ErrorPicker(
                   Status.UNAVAILABLE
-                      .withDescription("No traffic director provided by bootstrap")));
+                      .withDescription("No management server provided by bootstrap")));
           return;
         }
         XdsClientFactory xdsClientFactory = new XdsClientFactory() {
diff --git a/xds/src/main/java/io/grpc/xds/LoadStatsStore.java b/xds/src/main/java/io/grpc/xds/LoadStatsStore.java
index 76e430aa8..cd76be41e 100644
--- a/xds/src/main/java/io/grpc/xds/LoadStatsStore.java
+++ b/xds/src/main/java/io/grpc/xds/LoadStatsStore.java
@@ -53,7 +53,7 @@ interface LoadStatsStore {
    * once all of theirs loads are completed and reported.
    *
    * <p>The fields {@code cluster_name} and {@code load_report_interval} in the returned {@link
-   * ClusterStats} needs to be set before it is ready to be sent to the traffic directory for load
+   * ClusterStats} needs to be set before it is ready to be sent to the traffic director for load
    * reporting.
    *
    * <p>This method is not thread-safe and should be called from the same synchronized context
diff --git a/xds/src/main/java/io/grpc/xds/OrcaMetricReportingServerInterceptor.java b/xds/src/main/java/io/grpc/xds/OrcaMetricReportingServerInterceptor.java
index a420d5eae..8a503bd35 100644
--- a/xds/src/main/java/io/grpc/xds/OrcaMetricReportingServerInterceptor.java
+++ b/xds/src/main/java/io/grpc/xds/OrcaMetricReportingServerInterceptor.java
@@ -20,7 +20,6 @@ import com.github.udpa.udpa.data.orca.v1.OrcaLoadReport;
 import com.google.common.annotations.VisibleForTesting;
 import io.grpc.Context;
 import io.grpc.Contexts;
-import io.grpc.ExperimentalApi;
 import io.grpc.ForwardingServerCall.SimpleForwardingServerCall;
 import io.grpc.Metadata;
 import io.grpc.ServerCall;
@@ -41,8 +40,7 @@ import java.util.Map;
  *
  * @since 1.23.0
  */
-@ExperimentalApi("https://github.com/grpc/grpc-java/issues/6021")
-public final class OrcaMetricReportingServerInterceptor implements ServerInterceptor {
+final class OrcaMetricReportingServerInterceptor implements ServerInterceptor {
 
   private static final OrcaMetricReportingServerInterceptor INSTANCE =
       new OrcaMetricReportingServerInterceptor();
diff --git a/xds/src/main/java/io/grpc/xds/OrcaOobUtil.java b/xds/src/main/java/io/grpc/xds/OrcaOobUtil.java
index 557515624..1b5acd8c0 100644
--- a/xds/src/main/java/io/grpc/xds/OrcaOobUtil.java
+++ b/xds/src/main/java/io/grpc/xds/OrcaOobUtil.java
@@ -37,7 +37,6 @@ import io.grpc.ChannelLogger;
 import io.grpc.ChannelLogger.ChannelLogLevel;
 import io.grpc.ClientCall;
 import io.grpc.ConnectivityStateInfo;
-import io.grpc.ExperimentalApi;
 import io.grpc.LoadBalancer;
 import io.grpc.LoadBalancer.CreateSubchannelArgs;
 import io.grpc.LoadBalancer.Helper;
@@ -69,8 +68,7 @@ import javax.annotation.Nullable;
  * Utility class that provides method for {@link LoadBalancer} to install listeners to receive
  * out-of-band backend cost metrics in the format of Open Request Cost Aggregation (ORCA).
  */
-@ExperimentalApi("https://github.com/grpc/grpc-java/issues/5790")
-public abstract class OrcaOobUtil {
+abstract class OrcaOobUtil {
 
   private static final Logger logger = Logger.getLogger(OrcaPerRequestUtil.class.getName());
   private static final OrcaOobUtil DEFAULT_INSTANCE =
diff --git a/xds/src/main/java/io/grpc/xds/OrcaPerRequestUtil.java b/xds/src/main/java/io/grpc/xds/OrcaPerRequestUtil.java
index 9719a9193..c193f5e35 100644
--- a/xds/src/main/java/io/grpc/xds/OrcaPerRequestUtil.java
+++ b/xds/src/main/java/io/grpc/xds/OrcaPerRequestUtil.java
@@ -23,7 +23,6 @@ import com.google.common.annotations.VisibleForTesting;
 import io.grpc.CallOptions;
 import io.grpc.ClientStreamTracer;
 import io.grpc.ClientStreamTracer.StreamInfo;
-import io.grpc.ExperimentalApi;
 import io.grpc.LoadBalancer;
 import io.grpc.Metadata;
 import io.grpc.protobuf.ProtoUtils;
@@ -35,8 +34,7 @@ import java.util.List;
  * Utility class that provides method for {@link LoadBalancer} to install listeners to receive
  * per-request backend cost metrics in the format of Open Request Cost Aggregation (ORCA).
  */
-@ExperimentalApi("https://github.com/grpc/grpc-java/issues/5790")
-public abstract class OrcaPerRequestUtil {
+abstract class OrcaPerRequestUtil {
   private static final ClientStreamTracer NOOP_CLIENT_STREAM_TRACER = new ClientStreamTracer() {};
   private static final ClientStreamTracer.Factory NOOP_CLIENT_STREAM_TRACER_FACTORY =
       new ClientStreamTracer.Factory() {
diff --git a/xds/src/main/java/io/grpc/xds/XdsNameResolver.java b/xds/src/main/java/io/grpc/xds/XdsNameResolver.java
index ea142a707..e65044016 100644
--- a/xds/src/main/java/io/grpc/xds/XdsNameResolver.java
+++ b/xds/src/main/java/io/grpc/xds/XdsNameResolver.java
@@ -50,8 +50,8 @@ import javax.annotation.Nullable;
 /**
  * A {@link NameResolver} for resolving gRPC target names with "xds-experimental" scheme.
  *
- * <p>Resolving a gRPC target involves contacting the traffic director via xDS protocol to
- * retrieve service information and produce a service config to the caller.
+ * <p>Resolving a gRPC target involves contacting the control plane management server via xDS
+ * protocol to retrieve service information and produce a service config to the caller.
  *
  * @see XdsNameResolverProvider
  */
@@ -114,7 +114,7 @@ final class XdsNameResolver extends NameResolver {
     final Node node = bootstrapInfo.getNode();
     if (serverList.isEmpty()) {
       listener.onError(
-          Status.UNAVAILABLE.withDescription("No traffic director provided by bootstrap"));
+          Status.UNAVAILABLE.withDescription("No management server provided by bootstrap"));
       return;
     }
 
diff --git a/xds/src/main/java/io/grpc/xds/XdsNameResolverProvider.java b/xds/src/main/java/io/grpc/xds/XdsNameResolverProvider.java
index 7087489e1..9b9003e1e 100644
--- a/xds/src/main/java/io/grpc/xds/XdsNameResolverProvider.java
+++ b/xds/src/main/java/io/grpc/xds/XdsNameResolverProvider.java
@@ -17,6 +17,7 @@
 package io.grpc.xds;
 
 import com.google.common.base.Preconditions;
+import io.grpc.Internal;
 import io.grpc.NameResolver.Args;
 import io.grpc.NameResolverProvider;
 import io.grpc.internal.ExponentialBackoffPolicy;
@@ -32,9 +33,9 @@ import java.net.URI;
  * slash {@code '/'}, will indicate the name to use in the VHDS query.
  *
  * <p>This class should not be directly referenced in code. The resolver should be accessed
- * through {@link io.grpc.NameResolverRegistry#asFactory#newNameResolver(URI, Args)} with the URI
- * scheme "xds-experimental".
+ * through {@link io.grpc.NameResolverRegistry} with the URI scheme "xds-experimental".
  */
+@Internal
 public final class XdsNameResolverProvider extends NameResolverProvider {
 
   private static final String SCHEME = "xds-experimental";
diff --git a/xds/src/main/java/io/grpc/xds/internal/package-info.java b/xds/src/main/java/io/grpc/xds/internal/package-info.java
new file mode 100644
index 000000000..fc2208605
--- /dev/null
+++ b/xds/src/main/java/io/grpc/xds/internal/package-info.java
@@ -0,0 +1,24 @@
+/*
+ * Copyright 2020 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.
+ */
+
+/**
+ * Interfaces and implementations that are internal to gRPC.
+ *
+ * <p>All the content under this package and its subpackages are considered annotated with {@link
+ * io.grpc.Internal}.
+ */
+@io.grpc.Internal
+package io.grpc.xds.internal;
diff --git a/xds/src/main/java/io/grpc/xds/package-info.java b/xds/src/main/java/io/grpc/xds/package-info.java
index 6dc57e8ad..631e20da9 100644
--- a/xds/src/main/java/io/grpc/xds/package-info.java
+++ b/xds/src/main/java/io/grpc/xds/package-info.java
@@ -15,7 +15,16 @@
  */
 
 /**
- * The XDS loadbalancer plugin implementation.
+ * Library for gPRC proxyless service mesh using Envoy xDS protocol.
+ *
+ * <p>The package currently includes a name resolver plugin and a family of load balancer plugins.
+ * A gRPC channel for a target with {@code "xds-experimental"} scheme will load the plugins and a
+ * bootstrap file, and will communicate with an external control plane management server (e.g.
+ * Traffic Director) that speaks Envoy xDS protocol to retrieve routing, load balancing, load
+ * reporting configurations etc. for the channel. More features will be added.
+ *
+ * <p>The library is currently in an agile development phase, so API and design are subject to
+ * breaking changes.
  */
 @io.grpc.ExperimentalApi("https://github.com/grpc/grpc-java/issues/5288")
 package io.grpc.xds;
diff --git a/xds/src/test/java/io/grpc/xds/XdsNameResolverTest.java b/xds/src/test/java/io/grpc/xds/XdsNameResolverTest.java
index cb82406da..7ce286d8c 100644
--- a/xds/src/test/java/io/grpc/xds/XdsNameResolverTest.java
+++ b/xds/src/test/java/io/grpc/xds/XdsNameResolverTest.java
@@ -202,7 +202,7 @@ public class XdsNameResolverTest {
     verify(mockListener).onError(statusCaptor.capture());
     assertThat(statusCaptor.getValue().getCode()).isEqualTo(Code.UNAVAILABLE);
     assertThat(statusCaptor.getValue().getDescription())
-        .isEqualTo("No traffic director provided by bootstrap");
+        .isEqualTo("No management server provided by bootstrap");
   }
 
   @Test