api,stub: Clarify isReady()/onReady() interaction semantics

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

@@ -144,11 +144,17 @@ public abstract class ClientCall<ReqT, RespT> {
     public void onClose(Status status, Metadata trailers) {}
 
     /**
-     * This indicates that the ClientCall is now capable of sending additional messages (via
+     * This indicates that the ClientCall may now be capable of sending additional messages (via
      * {@link #sendMessage}) without requiring excessive buffering internally. This event is
      * just a suggestion and the application is free to ignore it, however doing so may
      * result in excessive buffering within the ClientCall.
      *
+     * <p>Because there is a processing delay to deliver this notification, it is possible for
+     * concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious"
+     * notifications by checking {@code isReady()}'s current value instead of assuming it is now
+     * {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be
+     * <em>another</em> {@code onReady()} callback.
+     *
      * <p>If the type of a call is either {@link MethodDescriptor.MethodType#UNARY} or
      * {@link MethodDescriptor.MethodType#SERVER_STREAMING}, this callback may not be fired. Calls
      * that send exactly one message should not await this callback.
@@ -236,12 +242,15 @@ public abstract class ClientCall<ReqT, RespT> {
    * just a suggestion and the application is free to ignore it, however doing so may
    * result in excessive buffering within the call.
    *
-   * <p>This abstract class's implementation always returns {@code true}. Implementations generally
+   * <p>If {@code false}, {@link Listener#onReady()} will be called after {@code isReady()}
-   * override the method.
+   * transitions to {@code true}.
    *
    * <p>If the type of the call is either {@link MethodDescriptor.MethodType#UNARY} or
    * {@link MethodDescriptor.MethodType#SERVER_STREAMING}, this method may persistently return
    * false. Calls that send exactly one message should not check this method.
+   *
+   * <p>This abstract class's implementation always returns {@code true}. Implementations generally
+   * override the method.
    */
   public boolean isReady() {
     return true;

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

@@ -83,10 +83,16 @@ public abstract class ServerCall<ReqT, RespT> {
     public void onComplete() {}
 
     /**
-     * This indicates that the call is now capable of sending additional messages (via
+     * This indicates that the call may now be capable of sending additional messages (via
      * {@link #sendMessage}) without requiring excessive buffering internally. This event is
      * just a suggestion and the application is free to ignore it, however doing so may
      * result in excessive buffering within the call.
+     *
+     * <p>Because there is a processing delay to deliver this notification, it is possible for
+     * concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious"
+     * notifications by checking {@code isReady()}'s current value instead of assuming it is now
+     * {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be
+     * <em>another</em> {@code onReady()} callback.
      */
     public void onReady() {}
   }
@@ -133,7 +139,11 @@ public abstract class ServerCall<ReqT, RespT> {
    * just a suggestion and the application is free to ignore it, however doing so may
    * result in excessive buffering within the call.
    *
-   * <p>This implementation always returns {@code true}.
+   * <p>If {@code false}, {@link Listener#onReady()} will be called after {@code isReady()}
+   * transitions to {@code true}.
+   *
+   * <p>This abstract class's implementation always returns {@code true}. Implementations generally
+   * override the method.
    */
   public boolean isReady() {
     return true;

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

@@ -48,6 +48,9 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
    * without requiring excessive buffering internally. This value is just a suggestion and the
    * application is free to ignore it, however doing so may result in excessive buffering within the
    * observer.
+   *
+   * <p>If {@code false}, the runnable passed to {@link #setOnReadyHandler} will be called after
+   * {@code isReady()} transitions to {@code true}.
    */
   public abstract boolean isReady();
 
@@ -61,8 +64,11 @@ public abstract class CallStreamObserver<V> implements StreamObserver<V> {
    * ClientResponseObserver#beforeStart}. On server-side it may only be called during the initial
    * call to the application, before the service returns its {@code StreamObserver}.
    *
-   * <p>Note that the handler may be called some time after {@link #isReady} has transitioned to
+   * <p>Because there is a processing delay to deliver this notification, it is possible for
-   * true as other callbacks may still be executing in the 'inbound' observer.
+   * concurrent writes to cause {@code isReady() == false} within this callback. Handle "spurious"
+   * notifications by checking {@code isReady()}'s current value instead of assuming it is now
+   * {@code true}. If {@code isReady() == false} the normal expectations apply, so there would be
+   * <em>another</em> {@code onReadyHandler} callback.
    *
    * @param onReadyHandler to call when peer is ready to receive more messages.
    */