diff --git a/auth/src/main/java/io/grpc/auth/GoogleAuthLibraryCallCredentials.java b/auth/src/main/java/io/grpc/auth/GoogleAuthLibraryCallCredentials.java index 335b8abb00c..9cb3ba84614 100644 --- a/auth/src/main/java/io/grpc/auth/GoogleAuthLibraryCallCredentials.java +++ b/auth/src/main/java/io/grpc/auth/GoogleAuthLibraryCallCredentials.java @@ -68,6 +68,9 @@ public GoogleAuthLibraryCallCredentials(Credentials creds) { this.creds = creds; } + @Override + public void thisUsesUnstableApi() {} + @Override public void applyRequestMetadata(MethodDescriptor method, Attributes attrs, Executor appExecutor, final MetadataApplier applier) { diff --git a/auth/src/main/java/io/grpc/auth/MoreCallCredentials.java b/auth/src/main/java/io/grpc/auth/MoreCallCredentials.java index 1c67f172e1b..42e540ba361 100644 --- a/auth/src/main/java/io/grpc/auth/MoreCallCredentials.java +++ b/auth/src/main/java/io/grpc/auth/MoreCallCredentials.java @@ -18,15 +18,18 @@ import com.google.auth.Credentials; import io.grpc.CallCredentials; -import io.grpc.ExperimentalApi; /** * A utility class that converts other types of credentials to {@link CallCredentials}. */ -@ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914") public final class MoreCallCredentials { /** * Converts a Google Auth Library {@link Credentials} to {@link CallCredentials}. + * + *

Although this is a stable API, note that the returned instance's API is not stable. You are + * free to use the class name {@code CallCredentials} and pass the instance to other code, but the + * instance can't be called directly from code expecting stable behavior. See {@link + * CallCredentials}. */ public static CallCredentials from(Credentials creds) { return new GoogleAuthLibraryCallCredentials(creds); diff --git a/core/src/main/java/io/grpc/CallCredentials.java b/core/src/main/java/io/grpc/CallCredentials.java index f5ab782ec19..e12c0d25212 100644 --- a/core/src/main/java/io/grpc/CallCredentials.java +++ b/core/src/main/java/io/grpc/CallCredentials.java @@ -28,14 +28,20 @@ * FooGrpc.FooStub stub = FooGrpc.newStub(channel); * response = stub.withCallCredentials(creds).bar(request); * + * + *

The contents and nature of this interface (and whether it remains an interface) is + * experimental, in that it can change. However, we are guaranteeing stability for the + * name. That is, we are guaranteeing stability for code to be returned a reference and + * pass that reference to gRPC for usage. However, code may not call or implement the {@code + * CallCredentials} itself if it wishes to only use stable APIs. */ -@ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914") public interface CallCredentials { /** * The security level of the transport. It is guaranteed to be present in the {@code attrs} passed * to {@link #applyRequestMetadata}. It is by default {@link SecurityLevel#NONE} but can be * overridden by the transport. */ + @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") public static final Key ATTR_SECURITY_LEVEL = Key.of("io.grpc.CallCredentials.securityLevel"); @@ -45,6 +51,7 @@ public interface CallCredentials { * by default from the channel, but can be overridden by the transport and {@link * io.grpc.CallOptions} with increasing precedence. */ + @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") public static final Key ATTR_AUTHORITY = Key.of("io.grpc.CallCredentials.authority"); /** @@ -65,15 +72,24 @@ public interface CallCredentials { * @param applier The outlet of the produced headers. It can be called either before or after this * method returns. */ + @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") void applyRequestMetadata( MethodDescriptor method, Attributes attrs, Executor appExecutor, MetadataApplier applier); + /** + * Should be a noop but never called; tries to make it clearer to implementors that they may break + * in the future. + */ + @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") + void thisUsesUnstableApi(); + /** * The outlet of the produced headers. Not thread-safe. * *

Exactly one of its methods must be called to make the RPC proceed. */ + @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") public interface MetadataApplier { /** * Called when headers are successfully generated. They will be merged into the original diff --git a/core/src/main/java/io/grpc/CallOptions.java b/core/src/main/java/io/grpc/CallOptions.java index b34b1ae8568..015240eb581 100644 --- a/core/src/main/java/io/grpc/CallOptions.java +++ b/core/src/main/java/io/grpc/CallOptions.java @@ -91,7 +91,6 @@ public CallOptions withAuthority(@Nullable String authority) { /** * Returns a new {@code CallOptions} with the given call credentials. */ - @ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914") public CallOptions withCallCredentials(@Nullable CallCredentials credentials) { CallOptions newOptions = new CallOptions(this); newOptions.credentials = credentials; @@ -187,7 +186,6 @@ public String getAuthority() { /** * Returns the call credentials. */ - @ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914") @Nullable public CallCredentials getCredentials() { return credentials; diff --git a/stub/src/main/java/io/grpc/stub/AbstractStub.java b/stub/src/main/java/io/grpc/stub/AbstractStub.java index 3b3e6131049..c33fa0821e4 100644 --- a/stub/src/main/java/io/grpc/stub/AbstractStub.java +++ b/stub/src/main/java/io/grpc/stub/AbstractStub.java @@ -173,7 +173,6 @@ public final S withInterceptors(ClientInterceptor... interceptors) { * * @since 1.0.0 */ - @ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914") public final S withCallCredentials(CallCredentials credentials) { return build(channel, callOptions.withCallCredentials(credentials)); }