1 /* 2 * Copyright 2016 The gRPC Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package io.grpc; 18 19 import java.util.concurrent.Executor; 20 21 /** 22 * Carries credential data that will be propagated to the server via request metadata for each RPC. 23 * 24 * <p>This is used by {@link CallOptions#withCallCredentials} and {@code withCallCredentials()} on 25 * the generated stub, for example: 26 * <pre> 27 * FooGrpc.FooStub stub = FooGrpc.newStub(channel); 28 * response = stub.withCallCredentials(creds).bar(request); 29 * </pre> 30 * 31 * <p>The contents and nature of this class (and whether it remains an abstract class) is 32 * experimental, in that it can change. However, we are guaranteeing stability for the 33 * <em>name</em>. That is, we are guaranteeing stability for code to be returned a reference and 34 * pass that reference to gRPC for usage. However, code may not call or implement the {@code 35 * CallCredentials} itself if it wishes to only use stable APIs. 36 */ 37 public abstract class CallCredentials { 38 39 /** 40 * Pass the credential data to the given {@link CallCredentials.MetadataApplier}, which will 41 * propagate it to the request metadata. 42 * 43 * <p>It is called for each individual RPC, within the {@link Context} of the call, before the 44 * stream is about to be created on a transport. Implementations should not block in this 45 * method. If metadata is not immediately available, e.g., needs to be fetched from network, the 46 * implementation may give the {@code applier} to an asynchronous task which will eventually call 47 * the {@code applier}. The RPC proceeds only after the {@code applier} is called. 48 * 49 * @param requestInfo request-related information 50 * @param appExecutor The application thread-pool. It is provided to the implementation in case it 51 * needs to perform blocking operations. 52 * @param applier The outlet of the produced headers. It can be called either before or after this 53 * method returns. 54 */ applyRequestMetadata( RequestInfo requestInfo, Executor appExecutor, CallCredentials.MetadataApplier applier)55 public abstract void applyRequestMetadata( 56 RequestInfo requestInfo, Executor appExecutor, CallCredentials.MetadataApplier applier); 57 58 /** 59 * With this class now being stable this method moves from an abstract one to a normal one with 60 * a no-op implementation. This method is marked deprecated to allow extenders time to remove the 61 * method before it is removed here. 62 */ 63 @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1914") 64 @Deprecated thisUsesUnstableApi()65 public void thisUsesUnstableApi() { 66 } 67 68 /** 69 * The outlet of the produced headers. Not thread-safe. 70 * 71 * <p>Exactly one of its methods must be called to make the RPC proceed. 72 */ 73 public abstract static class MetadataApplier { 74 /** 75 * Called when headers are successfully generated. They will be merged into the original 76 * headers. 77 */ apply(Metadata headers)78 public abstract void apply(Metadata headers); 79 80 /** 81 * Called when there has been an error when preparing the headers. This will fail the RPC. 82 */ fail(Status status)83 public abstract void fail(Status status); 84 } 85 86 /** 87 * The request-related information passed to {@code CallCredentials.applyRequestMetadata()}. 88 */ 89 public abstract static class RequestInfo { 90 /** 91 * The method descriptor of this RPC. 92 */ getMethodDescriptor()93 public abstract MethodDescriptor<?, ?> getMethodDescriptor(); 94 95 /** 96 * The call options used to call this RPC. 97 */ getCallOptions()98 public CallOptions getCallOptions() { 99 throw new UnsupportedOperationException("Not implemented"); 100 } 101 102 /** 103 * The security level on the transport. 104 */ getSecurityLevel()105 public abstract SecurityLevel getSecurityLevel(); 106 107 /** 108 * Returns the authority string used to authenticate the server for this call. 109 */ getAuthority()110 public abstract String getAuthority(); 111 112 /** 113 * Returns the transport attributes. 114 */ 115 @Grpc.TransportAttr getTransportAttrs()116 public abstract Attributes getTransportAttrs(); 117 } 118 } 119