stub: Redefine exception handling for StreamObserver

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

@@ -31,6 +31,10 @@
  * not need to be synchronized together; incoming and outgoing directions are independent.
  * Since individual {@code StreamObserver}s are not thread-safe, if multiple threads will be
  * writing to a {@code StreamObserver} concurrently, the application must synchronize calls.
+ *
+ * <p>Implementations are expected to not throw exceptions, except when called incorrectly. For
+ * example, a call to {@code onNext()} after {@code onCompleted()} may throw. {@link Error}s may
+ * also still occur.
  */
 public interface StreamObserver<V>  {
   /**
@@ -43,9 +47,18 @@ public interface StreamObserver<V>  {
    * server streaming calls, but may receive many onNext callbacks.  Servers may invoke onNext at
    * most once for client streaming calls, but may receive many onNext callbacks.
    *
-   * <p>If an exception is thrown by an implementation the caller is expected to terminate the
-   * stream by calling {@link #onError(Throwable)} with the caught exception prior to
-   * propagating it.
+   * <p>Although implementations are expected to not throw exceptions, if an exception occurs the
+   * caller is encouraged to call {@link #onError} as part of normal application exception handling.
+   * That is to say, {@code onError} should be called if any related part of the application throws
+   * an exception, generally independent of the source, to avoid leaks. gRPC will call {@code
+   * onError()} when an application's implementation throws.
+   *
+   * <p>As an exception to the rule and for historical reasons, on server-side, {@code onNext()} may
+   * throw with a {@code StatusRuntimeException} if the client cancels the call after {@code
+   * onCompleted()}. This was necessary because there was not a callback available to notify the
+   * service. Services are encouraged to use {@link
+   * ServerCallStreamObserver#setOnCancelHandler} which provides a callback and disables this
+   * exception-throwing behavior.
    *
    * @param value the value passed to the stream
    */
@@ -54,9 +67,9 @@ public interface StreamObserver<V>  {
   /**
    * Receives a terminating error from the stream.
    *
-   * <p>May only be called once and if called it must be the last method called. In particular if an
-   * exception is thrown by an implementation of {@code onError} no further calls to any method are
-   * allowed.
+   * <p>May only be called once and if called it must be the last method called. Although
+   * implementations are expected to not throw exceptions, if an exception is thrown by {@code
+   * onError()} further calls to the observer should be avoided.
    *
    * <p>{@code t} should be a {@link io.grpc.StatusException} or {@link
    * io.grpc.StatusRuntimeException}, but other {@code Throwable} types are possible. Callers should
@@ -71,9 +84,9 @@ public interface StreamObserver<V>  {
   /**
    * Receives a notification of successful stream completion.
    *
-   * <p>May only be called once and if called it must be the last method called. In particular if an
-   * exception is thrown by an implementation of {@code onCompleted} no further calls to any method
-   * are allowed.
+   * <p>May only be called once and if called it must be the last method called. Although
+   * implementations are expected to not throw exceptions, if an exception is thrown by {@code
+   * onCompleted()} further calls to the observer should be avoided.
    */
   void onCompleted();
 }