stub: Document that noop onCancelHandler is useful

ejona86 · ejona86 · commit 9870db1f4793 · 2021-09-08T16:48:20.000-07:00
setOnCancelHandler tells gRPC that the application is handling cancellation. But it's fine to have noop behavior within the handler itself if the application doesn't need it. It is just a way to opt-in to the more recent no-exception-from-onNext behavior. Let's mention this use-case in the docs to make it more obvious it is a possibility. Came up as part of grpc#8409.
diff --git a/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java b/stub/src/main/java/io/grpc/stub/ServerCallStreamObserver.java
@@ -54,7 +54,9 @@ public abstract class ServerCallStreamObserver<V> extends CallStreamObserver<V>
    * service returns its {@code StreamObserver}.
    *
    * <p>Setting the onCancelHandler will suppress the on-cancel exception thrown by
-   * {@link #onNext}.
+   * {@link #onNext}. If the caller is already handling cancellation via polling or cannot
+   * substantially benefit from observing cancellation, using a no-op {@code onCancelHandler} is
+   * useful just to suppress the {@code onNext()} exception.
    *
    * @param onCancelHandler to call when client has cancelled the call.
    */

Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,9 @@ public abstract class ServerCallStreamObserver<V> extends CallStreamObserver<V>`
`54`	`54`	`* service returns its {@code StreamObserver}.`
`55`	`55`	`*`
`56`	`56`	`* <p>Setting the onCancelHandler will suppress the on-cancel exception thrown by`
`57`		`- * {@link #onNext}.`
	`57`	`+ * {@link #onNext}. If the caller is already handling cancellation via polling or cannot`
	`58`	`+ * substantially benefit from observing cancellation, using a no-op {@code onCancelHandler} is`
	`59`	`+ * useful just to suppress the {@code onNext()} exception.`
`58`	`60`	`*`
`59`	`61`	`* @param onCancelHandler to call when client has cancelled the call.`
`60`	`62`	`*/`