Make thread-safety ownership of Metadata explicit

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

@@ -124,7 +124,8 @@ public abstract class ClientCall<ReqT, RespT> {
   /**
    * Start a call, using {@code responseListener} for processing response messages.
    *
-   * <p>It must be called prior to any other method on this class.
+   * <p>It must be called prior to any other method on this class. Since {@link Metadata} is not
+   * thread-safe, the caller must not access {@code headers} after this point.
    *
    * @param responseListener receives response messages
    * @param headers which can contain extra call metadata, e.g. authentication credentials.

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

@@ -119,6 +119,9 @@ public abstract class ServerCall<RespT> {
    * Send response header metadata prior to sending a response message. This method may
    * only be called once and cannot be called after calls to {@link #sendMessage} or {@link #close}.
    *
+   * <p>Since {@link Metadata} is not thread-safe, the caller must not access {@code headers} after
+   * this point.
+   *
    * @param headers metadata to send prior to any response body.
    * @throws IllegalStateException if {@code close} has been called, a message has been sent, or
    *     headers have already been sent
@@ -154,6 +157,9 @@ public abstract class ServerCall<RespT> {
    * notification should be expected, independent of {@code status}. Otherwise {@link
    * Listener#onCancel} has been or will be called.
    *
+   * <p>Since {@link Metadata} is not thread-safe, the caller must not access {@code trailers} after
+   * this point.
+   *
    * @throws IllegalStateException if call is already {@code close}d
    */
   public abstract void close(Status status, Metadata trailers);