From ebbf8005be98412d77dce9eff0e919d261609741 Mon Sep 17 00:00:00 2001 From: Kun Zhang Date: Mon, 1 Oct 2018 10:11:01 -0700 Subject: [PATCH] doc: organize Attributes with annotations. (#4892) * doc: organize Attributes Keys with annotations. Keys are annotated with the following annotations: 1. Grpc.TransportAttr: transport attributes returned by {Client,Server}Call.getAttributes(). 2. NameResolver.ResolutionResultAttr: attributes passed as the argument of NameResolver.Listener.onAddresses() and LoadBalancer.handleResolvedAddressGroups() 3. EquivalentAddressGroup.Attr: attributes from EquivalentAddressGroups. * Expand the usage of annotations to Attributes variables. --- .../alts/internal/AltsProtocolNegotiator.java | 14 ++++---------- .../internal/AltsProtocolNegotiatorTest.java | 4 ++-- core/src/main/java/io/grpc/Attributes.java | 12 ++++++++++++ core/src/main/java/io/grpc/CallCredentials.java | 2 ++ core/src/main/java/io/grpc/ClientCall.java | 3 +-- .../java/io/grpc/EquivalentAddressGroup.java | 16 ++++++++++++++-- core/src/main/java/io/grpc/Grpc.java | 13 +++++++++++++ core/src/main/java/io/grpc/LoadBalancer.java | 5 +++-- core/src/main/java/io/grpc/NameResolver.java | 16 ++++++++++++++-- core/src/main/java/io/grpc/ServerCall.java | 2 +- .../java/io/grpc/internal/GrpcAttributes.java | 5 +++++ 11 files changed, 71 insertions(+), 21 deletions(-) diff --git a/alts/src/main/java/io/grpc/alts/internal/AltsProtocolNegotiator.java b/alts/src/main/java/io/grpc/alts/internal/AltsProtocolNegotiator.java index e182f98a29..cd598c86aa 100644 --- a/alts/src/main/java/io/grpc/alts/internal/AltsProtocolNegotiator.java +++ b/alts/src/main/java/io/grpc/alts/internal/AltsProtocolNegotiator.java @@ -41,19 +41,13 @@ import io.netty.util.AsciiString; */ public abstract class AltsProtocolNegotiator implements ProtocolNegotiator { - private static final Attributes.Key TSI_PEER_KEY = Attributes.Key.create("TSI_PEER"); - private static final Attributes.Key ALTS_CONTEXT_KEY = + @Grpc.TransportAttr + public static final Attributes.Key TSI_PEER_KEY = Attributes.Key.create("TSI_PEER"); + @Grpc.TransportAttr + public static final Attributes.Key ALTS_CONTEXT_KEY = Attributes.Key.create("ALTS_CONTEXT_KEY"); private static final AsciiString scheme = AsciiString.of("https"); - public static Attributes.Key getTsiPeerAttributeKey() { - return TSI_PEER_KEY; - } - - public static Attributes.Key getAltsAuthContextAttributeKey() { - return ALTS_CONTEXT_KEY; - } - /** Creates a negotiator used for ALTS client. */ public static AltsProtocolNegotiator createClientNegotiator( final TsiHandshakerFactory handshakerFactory) { diff --git a/alts/src/test/java/io/grpc/alts/internal/AltsProtocolNegotiatorTest.java b/alts/src/test/java/io/grpc/alts/internal/AltsProtocolNegotiatorTest.java index 44341e0c47..9745e2c001 100644 --- a/alts/src/test/java/io/grpc/alts/internal/AltsProtocolNegotiatorTest.java +++ b/alts/src/test/java/io/grpc/alts/internal/AltsProtocolNegotiatorTest.java @@ -341,9 +341,9 @@ public class AltsProtocolNegotiatorTest { public void peerPropagated() throws Exception { doHandshake(); - assertThat(grpcHandler.attrs.get(AltsProtocolNegotiator.getTsiPeerAttributeKey())) + assertThat(grpcHandler.attrs.get(AltsProtocolNegotiator.TSI_PEER_KEY)) .isEqualTo(mockedTsiPeer); - assertThat(grpcHandler.attrs.get(AltsProtocolNegotiator.getAltsAuthContextAttributeKey())) + assertThat(grpcHandler.attrs.get(AltsProtocolNegotiator.ALTS_CONTEXT_KEY)) .isEqualTo(mockedAltsContext); assertThat(grpcHandler.attrs.get(Grpc.TRANSPORT_ATTR_REMOTE_ADDR).toString()) .isEqualTo("embedded"); diff --git a/core/src/main/java/io/grpc/Attributes.java b/core/src/main/java/io/grpc/Attributes.java index 9a13f5160e..411d11c337 100644 --- a/core/src/main/java/io/grpc/Attributes.java +++ b/core/src/main/java/io/grpc/Attributes.java @@ -29,6 +29,18 @@ import javax.annotation.concurrent.Immutable; /** * An immutable type-safe container of attributes. + * + *

Annotation semantics

+ * + *

As a convention, annotations such as {@link Grpc.TransportAttr} is defined to associate + * attribute {@link Key}s and their propagation paths. The annotation may be applied to a {@code + * Key} definition field, a method that returns {@link Attributes}, or a variable of type {@link + * Attributes}, to indicate that the annotated {@link Attributes} objects may contain the annotated + * {@code Key}. + * + *

Javadoc users may click "USE" on the navigation bars of the annotation's javadoc page to view + * references of such annotation. + * * @since 1.13.0 */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1764") diff --git a/core/src/main/java/io/grpc/CallCredentials.java b/core/src/main/java/io/grpc/CallCredentials.java index 7ce6219936..0d87bb6100 100644 --- a/core/src/main/java/io/grpc/CallCredentials.java +++ b/core/src/main/java/io/grpc/CallCredentials.java @@ -42,6 +42,7 @@ public interface CallCredentials { * overridden by the transport. */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") + @Grpc.TransportAttr public static final Key ATTR_SECURITY_LEVEL = Key.create("io.grpc.CallCredentials.securityLevel"); @@ -52,6 +53,7 @@ public interface CallCredentials { * io.grpc.CallOptions} with increasing precedence. */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") + @Grpc.TransportAttr public static final Key ATTR_AUTHORITY = Key.create("io.grpc.CallCredentials.authority"); /** diff --git a/core/src/main/java/io/grpc/ClientCall.java b/core/src/main/java/io/grpc/ClientCall.java index 936cb322b6..2aa5034b7b 100644 --- a/core/src/main/java/io/grpc/ClientCall.java +++ b/core/src/main/java/io/grpc/ClientCall.java @@ -262,12 +262,11 @@ public abstract class ClientCall { * or {@link Listener#onClose}. If called prematurely, the implementation may throw {@code * IllegalStateException} or return arbitrary {@code Attributes}. * - *

{@link Grpc} defines commonly used attributes, but they are not guaranteed to be present. - * * @return non-{@code null} attributes * @throws IllegalStateException (optional) if called before permitted */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2607") + @Grpc.TransportAttr public Attributes getAttributes() { return Attributes.EMPTY; } diff --git a/core/src/main/java/io/grpc/EquivalentAddressGroup.java b/core/src/main/java/io/grpc/EquivalentAddressGroup.java index 2218a7fae6..916e4a00a6 100644 --- a/core/src/main/java/io/grpc/EquivalentAddressGroup.java +++ b/core/src/main/java/io/grpc/EquivalentAddressGroup.java @@ -17,6 +17,9 @@ package io.grpc; import com.google.common.base.Preconditions; +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; import java.net.SocketAddress; import java.util.ArrayList; import java.util.Collections; @@ -50,7 +53,7 @@ public final class EquivalentAddressGroup { /** * List constructor with {@link Attributes}. */ - public EquivalentAddressGroup(List addrs, Attributes attrs) { + public EquivalentAddressGroup(List addrs, @Attr Attributes attrs) { Preconditions.checkArgument(!addrs.isEmpty(), "addrs is empty"); this.addrs = Collections.unmodifiableList(new ArrayList<>(addrs)); this.attrs = Preconditions.checkNotNull(attrs, "attrs"); @@ -69,7 +72,7 @@ public final class EquivalentAddressGroup { /** * Singleton constructor with Attributes. */ - public EquivalentAddressGroup(SocketAddress addr, Attributes attrs) { + public EquivalentAddressGroup(SocketAddress addr, @Attr Attributes attrs) { this(Collections.singletonList(addr), attrs); } @@ -83,6 +86,7 @@ public final class EquivalentAddressGroup { /** * Returns the attributes. */ + @Attr public Attributes getAttributes() { return attrs; } @@ -127,4 +131,12 @@ public final class EquivalentAddressGroup { } return true; } + + /** + * Annotation for {@link EquivalentAddressGroup}'s attributes. It follows the annotation semantics + * defined by {@link Attributes}. + */ + @Retention(RetentionPolicy.SOURCE) + @Documented + public @interface Attr {} } diff --git a/core/src/main/java/io/grpc/Grpc.java b/core/src/main/java/io/grpc/Grpc.java index aef0726062..4884a57ebe 100644 --- a/core/src/main/java/io/grpc/Grpc.java +++ b/core/src/main/java/io/grpc/Grpc.java @@ -16,6 +16,9 @@ package io.grpc; +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; import java.net.SocketAddress; import javax.net.ssl.SSLSession; @@ -31,6 +34,7 @@ public final class Grpc { * Attribute key for the remote address of a transport. */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1710") + @TransportAttr public static final Attributes.Key TRANSPORT_ATTR_REMOTE_ADDR = Attributes.Key.create("remote-addr"); @@ -38,6 +42,15 @@ public final class Grpc { * Attribute key for SSL session of a transport. */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1710") + @TransportAttr public static final Attributes.Key TRANSPORT_ATTR_SSL_SESSION = Attributes.Key.create("ssl-session"); + + /** + * Annotation for transport attributes. It follows the annotation semantics defined + * by {@link Attributes}. + */ + @Retention(RetentionPolicy.SOURCE) + @Documented + public @interface TransportAttr {} } diff --git a/core/src/main/java/io/grpc/LoadBalancer.java b/core/src/main/java/io/grpc/LoadBalancer.java index 9256ea8103..f1cef63fba 100644 --- a/core/src/main/java/io/grpc/LoadBalancer.java +++ b/core/src/main/java/io/grpc/LoadBalancer.java @@ -107,11 +107,12 @@ public abstract class LoadBalancer { *

Implementations should not modify the given {@code servers}. * * @param servers the resolved server addresses, never empty. - * @param attributes extra metadata from naming system. + * @param attributes extra information from naming system. * @since 1.2.0 */ public abstract void handleResolvedAddressGroups( - List servers, Attributes attributes); + List servers, + @NameResolver.ResolutionResultAttr Attributes attributes); /** * Handles an error from the name resolution system. diff --git a/core/src/main/java/io/grpc/NameResolver.java b/core/src/main/java/io/grpc/NameResolver.java index 60f819e4d1..03767ca108 100644 --- a/core/src/main/java/io/grpc/NameResolver.java +++ b/core/src/main/java/io/grpc/NameResolver.java @@ -16,6 +16,9 @@ package io.grpc; +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; import java.net.URI; import java.util.List; import javax.annotation.Nullable; @@ -134,10 +137,11 @@ public abstract class NameResolver { *

Implementations will not modify the given {@code servers}. * * @param servers the resolved server addresses. An empty list will trigger {@link #onError} - * @param attributes extra metadata from naming system + * @param attributes extra information from naming system. * @since 1.3.0 */ - void onAddresses(List servers, Attributes attributes); + void onAddresses( + List servers, @ResolutionResultAttr Attributes attributes); /** * Handles an error from the resolver. The listener is responsible for eventually invoking @@ -148,4 +152,12 @@ public abstract class NameResolver { */ void onError(Status error); } + + /** + * Annotation for name resolution result attributes. It follows the annotation semantics defined + * by {@link Attributes}. + */ + @Retention(RetentionPolicy.SOURCE) + @Documented + public @interface ResolutionResultAttr {} } diff --git a/core/src/main/java/io/grpc/ServerCall.java b/core/src/main/java/io/grpc/ServerCall.java index 106676fa7a..07711e381d 100644 --- a/core/src/main/java/io/grpc/ServerCall.java +++ b/core/src/main/java/io/grpc/ServerCall.java @@ -192,11 +192,11 @@ public abstract class ServerCall { * Returns properties of a single call. * *

Attributes originate from the transport and can be altered by {@link ServerTransportFilter}. - * {@link Grpc} defines commonly used attributes, but they are not guaranteed to be present. * * @return non-{@code null} Attributes container */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1779") + @Grpc.TransportAttr public Attributes getAttributes() { return Attributes.EMPTY; } diff --git a/core/src/main/java/io/grpc/internal/GrpcAttributes.java b/core/src/main/java/io/grpc/internal/GrpcAttributes.java index 67da06fa77..e620bb6d71 100644 --- a/core/src/main/java/io/grpc/internal/GrpcAttributes.java +++ b/core/src/main/java/io/grpc/internal/GrpcAttributes.java @@ -17,6 +17,8 @@ package io.grpc.internal; import io.grpc.Attributes; +import io.grpc.EquivalentAddressGroup; +import io.grpc.NameResolver; import java.util.Map; /** @@ -26,6 +28,7 @@ public final class GrpcAttributes { /** * Attribute key for service config. */ + @NameResolver.ResolutionResultAttr public static final Attributes.Key> NAME_RESOLVER_SERVICE_CONFIG = Attributes.Key.create("service-config"); @@ -33,6 +36,7 @@ public final class GrpcAttributes { * The naming authority of a gRPC LB server address. It is an address-group-level attribute, * present when the address group is a LoadBalancer. */ + @EquivalentAddressGroup.Attr public static final Attributes.Key ATTR_LB_ADDR_AUTHORITY = Attributes.Key.create("io.grpc.grpclb.lbAddrAuthority"); @@ -40,6 +44,7 @@ public final class GrpcAttributes { * Whether this EquivalentAddressGroup was provided by a GRPCLB server. It would be rare for this * value to be {@code false}; generally it would be better to not have the key present at all. */ + @EquivalentAddressGroup.Attr public static final Attributes.Key ATTR_LB_PROVIDED_BACKEND = Attributes.Key.create("io.grpc.grpclb.lbProvidedBackend");