core: stabilize custom CallOptions API (#4457)

Deprecate `of()` in favor of `create()` and
`createWithDefault()`. Emphasize that the name string is only for
debug purposes.

Fixes #1869

core/src/jmh/java/io/grpc/CallOptionsBenchmark.java

@@ -51,7 +51,7 @@ public class CallOptionsBenchmark {
   public void setUp() throws Exception {
     customOptions = new ArrayList<CallOptions.Key<String>>(customOptionsCount);
     for (int i = 0; i < customOptionsCount; i++) {
-      customOptions.add(CallOptions.Key.of("name " + i, "defaultvalue"));
+      customOptions.add(CallOptions.Key.createWithDefault("name " + i, "defaultvalue"));
     }
 
     allOpts = CallOptions.DEFAULT;

core/src/main/java/io/grpc/BinaryLogProvider.java

@@ -34,7 +34,7 @@ import javax.annotation.Nullable;
 @Internal
 public abstract class BinaryLogProvider implements Closeable {
   public static final CallOptions.Key<CallId> CLIENT_CALL_ID_CALLOPTION_KEY
-      = CallOptions.Key.of("binarylog-calloptions-key", null);
+      = CallOptions.Key.create("binarylog-calloptions-key");
   @VisibleForTesting
   public static final Marshaller<byte[]> BYTEARRAY_MARSHALLER = new ByteArrayMarshaller();
 

core/src/main/java/io/grpc/CallOptions.java

@@ -231,13 +231,12 @@ public final class CallOptions {
   /**
    * Key for a key-value pair. Uses reference equality.
    */
-  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1869")
   public static final class Key<T> {
-    private final String name;
+    private final String debugString;
     private final T defaultValue;
 
-    private Key(String name, T defaultValue) {
+    private Key(String debugString, T defaultValue) {
-      this.name = name;
+      this.debugString = debugString;
       this.defaultValue = defaultValue;
     }
 
@@ -250,20 +249,50 @@ public final class CallOptions {
 
     @Override
     public String toString() {
-      return name;
+      return debugString;
     }
 
     /**
      * Factory method for creating instances of {@link Key}.
      *
-     * @param name the name of Key.
+     * @param debugString a string used to describe this key, used for debugging.
      * @param defaultValue default value to return when value for key not set
      * @param <T> Key type
      * @return Key object
+     * @deprecated Use {@link #create} or {@link #createWithDefault} instead.
      */
-    public static <T> Key<T> of(String name, T defaultValue) {
+    @Deprecated
-      Preconditions.checkNotNull(name, "name");
+    public static <T> Key<T> of(String debugString, T defaultValue) {
-      return new Key<T>(name, defaultValue);
+      Preconditions.checkNotNull(debugString, "debugString");
+      return new Key<T>(debugString, defaultValue);
+    }
+
+    /**
+     * Factory method for creating instances of {@link Key}. The default value of the
+     * key is {@code null}.
+     *
+     * @param debugString a debug string that describes this key.
+     * @param <T> Key type
+     * @return Key object
+     * @since 1.13.0
+     */
+    public static <T> Key<T> create(String debugString) {
+      Preconditions.checkNotNull(debugString, "debugString");
+      return new Key<T>(debugString, /*defaultValue=*/ null);
+    }
+
+    /**
+     * Factory method for creating instances of {@link Key}.
+     *
+     * @param debugString a debug string that describes this key.
+     * @param defaultValue default value to return when value for key not set
+     * @param <T> Key type
+     * @return Key object
+     * @since 1.13.0
+     */
+    public static <T> Key<T> createWithDefault(String debugString, T defaultValue) {
+      Preconditions.checkNotNull(debugString, "debugString");
+      return new Key<T>(debugString, defaultValue);
     }
   }
 
@@ -272,8 +301,8 @@ public final class CallOptions {
    *
    * @param key The option key
    * @param value The option value.
+   * @since 1.13.0
    */
-  @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1869")
   public <T> CallOptions withOption(Key<T> key, T value) {
     Preconditions.checkNotNull(key, "key");
     Preconditions.checkNotNull(value, "value");

core/src/main/java/io/grpc/internal/ServiceConfigInterceptor.java

@@ -237,7 +237,7 @@ final class ServiceConfigInterceptor implements ClientInterceptor {
   }
 
   static final CallOptions.Key<RetryPolicy.Provider> RETRY_POLICY_KEY =
-      CallOptions.Key.of("internal-retry-policy", null);
+      CallOptions.Key.create("internal-retry-policy");
 
   @Override
   public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(

core/src/test/java/io/grpc/CallOptionsTest.java

@@ -43,8 +43,8 @@ public class CallOptionsTest {
   private Deadline.Ticker ticker = new FakeTicker();
   private Deadline sampleDeadline = Deadline.after(1, NANOSECONDS, ticker);
   private CallCredentials sampleCreds = mock(CallCredentials.class);
-  private CallOptions.Key<String> option1 = CallOptions.Key.of("option1", "default");
+  private CallOptions.Key<String> option1 = CallOptions.Key.createWithDefault("option1", "default");
-  private CallOptions.Key<String> option2 = CallOptions.Key.of("option2", "default");
+  private CallOptions.Key<String> option2 = CallOptions.Key.createWithDefault("option2", "default");
   private ClientStreamTracer.Factory tracerFactory1 = new FakeTracerFactory("tracerFactory1");
   private ClientStreamTracer.Factory tracerFactory2 = new FakeTracerFactory("tracerFactory2");
   private CallOptions allSet = CallOptions.DEFAULT

core/src/test/java/io/grpc/ClientInterceptorsTest.java

@@ -395,7 +395,7 @@ public class ClientInterceptorsTest {
 
   @Test
   public void customOptionAccessible() {
-    CallOptions.Key<String> customOption = CallOptions.Key.of("custom", null);
+    CallOptions.Key<String> customOption = CallOptions.Key.create("custom");
     CallOptions callOptions = CallOptions.DEFAULT.withOption(customOption, "value");
     ArgumentCaptor<CallOptions> passedOptions = ArgumentCaptor.forClass(CallOptions.class);
     ClientInterceptor interceptor =

core/src/test/java/io/grpc/internal/CensusModulesTest.java

@@ -104,7 +104,7 @@ import org.mockito.MockitoAnnotations;
 @RunWith(JUnit4.class)
 public class CensusModulesTest {
   private static final CallOptions.Key<String> CUSTOM_OPTION =
-      CallOptions.Key.of("option1", "default");
+      CallOptions.Key.createWithDefault("option1", "default");
   private static final CallOptions CALL_OPTIONS =
       CallOptions.DEFAULT.withOption(CUSTOM_OPTION, "customvalue");
 

core/src/test/java/io/grpc/internal/DelayedClientTransportTest.java

@@ -78,7 +78,8 @@ public class DelayedClientTransportTest {
   @Captor private ArgumentCaptor<Status> statusCaptor;
   @Captor private ArgumentCaptor<ClientStreamListener> listenerCaptor;
 
-  private static final CallOptions.Key<Integer> SHARD_ID = CallOptions.Key.of("shard-id", -1);
+  private static final CallOptions.Key<Integer> SHARD_ID
+      = CallOptions.Key.createWithDefault("shard-id", -1);
   private static final Status SHUTDOWN_STATUS =
       Status.UNAVAILABLE.withDescription("shutdown called");