core: Document Metadata ownership passes to the Call{,Listener}
This was already clearly documented in ServerCall.Listener and
ClientCall.diff --git a/core/src/main/java/io/grpc/ClientCall.java b/core/src/main/java/io/grpc/ClientCall.java
index 6be5584..43ac85a 100644
--- a/core/src/main/java/io/grpc/ClientCall.java
+++ b/core/src/main/java/io/grpc/ClientCall.java
@@ -110,6 +110,9 @@
/**
* The response headers have been received. Headers always precede messages.
*
+ * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write)
+ * {@code headers} after this point.
+ *
* @param headers containing metadata sent by the server at the start of the response.
*/
public void onHeaders(Metadata headers) {}
@@ -127,6 +130,9 @@
* processed by the server. No further receiving will occur and no further notifications will be
* made.
*
+ * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write)
+ * {@code trailers} after this point.
+ *
* <p>If {@code status} returns false for {@link Status#isOk()}, then the call failed.
* An additional block of trailer metadata may be received at the end of the call from the
* server. An empty {@link Metadata} object is passed if no trailers are received.
@@ -153,8 +159,10 @@
* Start a call, using {@code responseListener} for processing response messages.
*
* <p>It must be called prior to any other method on this class, except for {@link #cancel} which
- * may be called at any time. Since {@link Metadata} is not thread-safe, the caller must not
- * access {@code headers} after this point.
+ * may be called at any time.
+ *
+ * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write) {@code
+ * headers} after this point.
*
* @param responseListener receives response messages
* @param headers which can contain extra call metadata, e.g. authentication credentials.
diff --git a/core/src/main/java/io/grpc/ServerCall.java b/core/src/main/java/io/grpc/ServerCall.java
index 42c2b62..f0b47bd 100644
--- a/core/src/main/java/io/grpc/ServerCall.java
+++ b/core/src/main/java/io/grpc/ServerCall.java
@@ -109,8 +109,8 @@
* 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.
+ * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write) {@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
@@ -147,8 +147,8 @@
* 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.
+ * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write) {@code
+ * trailers} after this point.
*
* @throws IllegalStateException if call is already {@code close}d
*/
diff --git a/core/src/main/java/io/grpc/ServerCallHandler.java b/core/src/main/java/io/grpc/ServerCallHandler.java
index ce57f15..f5ea9da 100644
--- a/core/src/main/java/io/grpc/ServerCallHandler.java
+++ b/core/src/main/java/io/grpc/ServerCallHandler.java
@@ -28,6 +28,9 @@
* Produce a non-{@code null} listener for the incoming call. Implementations are free to call
* methods on {@code call} before this method has returned.
*
+ * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write) {@code
+ * headers} after this point.
+ *
* <p>If the implementation throws an exception, {@code call} will be closed with an error.
* Implementations must not throw an exception if they started processing that may use {@code
* call} on another thread.
