stub: Mark Stub-based MetadataUtils methods deprecated

We don't want other APIs to copy the stub-based API to attach the
interceptor. The API has a shorter name, but isn't actually all that
easier to use and isn't fluent like using the interceptor API.

These are _very_ old methods, so we won't be quick to delete them. Seems
we should have them deprecated at least a year or two; they are easy to
maintain in the mean time.

See API Review notes in #1789

interop-testing/src/main/java/io/grpc/testing/integration/AbstractInteropTest.java

@@ -1043,19 +1043,18 @@ public void veryLargeResponse() throws Exception {
 
   @Test
   public void exchangeMetadataUnaryCall() throws Exception {
-    TestServiceGrpc.TestServiceBlockingStub stub = blockingStub;
-
     // Capture the metadata exchange
     Metadata fixedHeaders = new Metadata();
     // Send a context proto (as it's in the default extension registry)
     Messages.SimpleContext contextValue =
         Messages.SimpleContext.newBuilder().setValue("dog").build();
     fixedHeaders.put(Util.METADATA_KEY, contextValue);
-    stub = MetadataUtils.attachHeaders(stub, fixedHeaders);
     // .. and expect it to be echoed back in trailers
     AtomicReference<Metadata> trailersCapture = new AtomicReference<>();
     AtomicReference<Metadata> headersCapture = new AtomicReference<>();
-    stub = MetadataUtils.captureMetadata(stub, headersCapture, trailersCapture);
+    TestServiceGrpc.TestServiceBlockingStub stub = blockingStub.withInterceptors(
+        MetadataUtils.newAttachHeadersInterceptor(fixedHeaders),
+        MetadataUtils.newCaptureMetadataInterceptor(headersCapture, trailersCapture));
 
     assertNotNull(stub.emptyCall(EMPTY));
 
@@ -1066,19 +1065,18 @@ public void exchangeMetadataUnaryCall() throws Exception {
 
   @Test
   public void exchangeMetadataStreamingCall() throws Exception {
-    TestServiceGrpc.TestServiceStub stub = asyncStub;
-
     // Capture the metadata exchange
     Metadata fixedHeaders = new Metadata();
     // Send a context proto (as it's in the default extension registry)
     Messages.SimpleContext contextValue =
         Messages.SimpleContext.newBuilder().setValue("dog").build();
     fixedHeaders.put(Util.METADATA_KEY, contextValue);
-    stub = MetadataUtils.attachHeaders(stub, fixedHeaders);
     // .. and expect it to be echoed back in trailers
     AtomicReference<Metadata> trailersCapture = new AtomicReference<>();
     AtomicReference<Metadata> headersCapture = new AtomicReference<>();
-    stub = MetadataUtils.captureMetadata(stub, headersCapture, trailersCapture);
+    TestServiceGrpc.TestServiceStub stub = asyncStub.withInterceptors(
+        MetadataUtils.newAttachHeadersInterceptor(fixedHeaders),
+        MetadataUtils.newCaptureMetadataInterceptor(headersCapture, trailersCapture));
 
     List<Integer> responseSizes = Arrays.asList(50, 100, 150, 200);
     Messages.StreamingOutputCallRequest.Builder streamingOutputBuilder =
@@ -1490,11 +1488,11 @@ public void customMetadata() throws Exception {
     Metadata metadata = new Metadata();
     metadata.put(Util.ECHO_INITIAL_METADATA_KEY, "test_initial_metadata_value");
     metadata.put(Util.ECHO_TRAILING_METADATA_KEY, trailingBytes);
-    TestServiceGrpc.TestServiceBlockingStub blockingStub = this.blockingStub;
-    blockingStub = MetadataUtils.attachHeaders(blockingStub, metadata);
     AtomicReference<Metadata> headersCapture = new AtomicReference<>();
     AtomicReference<Metadata> trailersCapture = new AtomicReference<>();
-    blockingStub = MetadataUtils.captureMetadata(blockingStub, headersCapture, trailersCapture);
+    TestServiceGrpc.TestServiceBlockingStub blockingStub = this.blockingStub.withInterceptors(
+        MetadataUtils.newAttachHeadersInterceptor(metadata),
+        MetadataUtils.newCaptureMetadataInterceptor(headersCapture, trailersCapture));
     SimpleResponse response = blockingStub.unaryCall(request);
 
     assertResponse(goldenResponse, response);
@@ -1509,11 +1507,11 @@ public void customMetadata() throws Exception {
     metadata = new Metadata();
     metadata.put(Util.ECHO_INITIAL_METADATA_KEY, "test_initial_metadata_value");
     metadata.put(Util.ECHO_TRAILING_METADATA_KEY, trailingBytes);
-    TestServiceGrpc.TestServiceStub stub = asyncStub;
-    stub = MetadataUtils.attachHeaders(stub, metadata);
     headersCapture = new AtomicReference<>();
     trailersCapture = new AtomicReference<>();
-    stub = MetadataUtils.captureMetadata(stub, headersCapture, trailersCapture);
+    TestServiceGrpc.TestServiceStub stub = asyncStub.withInterceptors(
+        MetadataUtils.newAttachHeadersInterceptor(metadata),
+        MetadataUtils.newCaptureMetadataInterceptor(headersCapture, trailersCapture));
 
     StreamRecorder<Messages.StreamingOutputCallResponse> recorder = StreamRecorder.create();
     StreamObserver<Messages.StreamingOutputCallRequest> requestStream =

stub/src/main/java/io/grpc/stub/MetadataUtils.java

@@ -43,8 +43,10 @@ private MetadataUtils() {}
    * @param stub to bind the headers to.
    * @param extraHeaders the headers to be passed by each call on the returned stub.
    * @return an implementation of the stub with {@code extraHeaders} bound to each call.
+   * @deprecated Use {@code stub.withInterceptors(newAttachHeadersInterceptor(...))} instead.
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1789")
+  @Deprecated
   public static <T extends AbstractStub<T>> T attachHeaders(T stub, Metadata extraHeaders) {
     return stub.withInterceptors(newAttachHeadersInterceptor(extraHeaders));
   }
@@ -98,8 +100,10 @@ public void start(Listener<RespT> responseListener, Metadata headers) {
    * @param trailersCapture to record the last received trailers
    * @return an implementation of the stub that allows to access the last received call's
    *         headers and trailers via {@code headersCapture} and {@code trailersCapture}.
+   * @deprecated Use {@code stub.withInterceptors(newCaptureMetadataInterceptor())} instead.
    */
   @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1789")
+  @Deprecated
   public static <T extends AbstractStub<T>> T captureMetadata(
       T stub,
       AtomicReference<Metadata> headersCapture,