From 936515d2a7fe0bc3af1a76a0f1f1aad2797f2bfc Mon Sep 17 00:00:00 2001 From: ZHANG Dapeng Date: Tue, 25 Feb 2020 15:45:44 -0800 Subject: 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. --- xds/build.gradle | 5 ++++- xds/src/main/java/io/grpc/xds/Bootstrapper.java | 1 + xds/src/main/java/io/grpc/xds/CdsLoadBalancer.java | 2 +- xds/src/main/java/io/grpc/xds/EdsLoadBalancer.java | 2 +- xds/src/main/java/io/grpc/xds/LoadStatsStore.java | 2 +- .../xds/OrcaMetricReportingServerInterceptor.java | 4 +--- xds/src/main/java/io/grpc/xds/OrcaOobUtil.java | 4 +--- .../main/java/io/grpc/xds/OrcaPerRequestUtil.java | 4 +--- xds/src/main/java/io/grpc/xds/XdsNameResolver.java | 6 +++--- .../java/io/grpc/xds/XdsNameResolverProvider.java | 5 +++-- .../java/io/grpc/xds/internal/package-info.java | 24 ++++++++++++++++++++++ xds/src/main/java/io/grpc/xds/package-info.java | 11 +++++++++- .../test/java/io/grpc/xds/XdsNameResolverTest.java | 2 +- 13 files changed, 52 insertions(+), 20 deletions(-) create mode 100644 xds/src/main/java/io/grpc/xds/internal/package-info.java 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 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. * *

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. * *

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. * - *

Resolving a gRPC target involves contacting the traffic director via xDS protocol to - * retrieve service information and produce a service config to the caller. + *

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. * *

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. + * + *

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. + * + *

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. + * + *

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 -- cgit v1.2.3