stub: add ServerCallStreamObserver.setOnCloseHandler(...) (#5895)

[morgwai]

This allows for user code to be notified when the messages are actually put on the wire and the stream is closed.

The name onSuccessHandler was chosen over onCompleteHandler to avoid confusion with StreamObserver.onCompleted(), but it is up to discussion of course.

[ejona86]

Looks pretty close to me.

"Success" seems pretty fair, since we can't use "complete." Only other option that comes immediately to mind is "done." I've added this to the agenda of our API review meeting this Thursday. (API review isn't a blocker for experimental APIs, but an initial review helps avoid annoying name changes later.)

[ejona86]

Finish does look better than Success. Thanks for the name brainstorming. We'll choose a name in the API meeting.

[morgwai]

@ejona86
I've cleaned and rebuilt everything again, but cannot reproduce the error that occurred in the checks. Furthermore, looking at the output it does not seem to be related to my changes:

Task :grpc-netty:test

io.grpc.netty.AdvancedTlsTest > onFileReloadingKeyManagerTrustManagerTest FAILED
java.lang.AssertionError: Find error: UNAVAILABLE: io exception
Channel Pipeline: [SslHandler#0, ProtocolNegotiators$ClientTlsHandler#0, WriteBufferingAndExceptionHandler#0, DefaultChannelPipeline$TailContext#0]
at org.junit.Assert.fail(Assert.java:88)
at io.grpc.netty.AdvancedTlsTest.onFileReloadingKeyManagerTrustManagerTest(AdvancedTlsTest.java:385)

any hints how to deal with it? ;-)

[ejona86]

@morgwai, don't worry about it. #8454

[morgwai]

if #8476 is indeed a bug (as opposed to documentation omission, that I suspect), then onCloseHandler may be useful also for streaming clients, so that they do not exit before trailing metadata is transffered. In such case setOnCloseHandler should probably be moved to CallStreamObserver.

[ejona86]

then onCloseHandler may be useful also for streaming clients

The onCloseHandler is powered by ServerCall.Listener.onComplete(). On client-side, the equivalent would be ClientCall.Listener.onClose(). However, ClientCall.Listener.onClose() already calls StreamObserver.onCompleted() or StreamObserver.onError(), depending on the status code. So on client-side the equivalent callback(s) already exist.

[morgwai]

@ejona86 I've applied most of your comments. Please have a look at the one I was not sure about if you like the way it is now.

[morgwai]

@ejona86 friendly ping :)
Please let me know if the current doc is ok or if you want me to change it somehow. Thanks!

[ejona86]

Oh, thanks for the ping. Yes, this had been lost. I'll try and take a look tomorrow.

[ejona86]

Thank you, @morgwai! Thanks for putting up with the process.

[morgwai]

@ejona86 my pleasure :) thanks for the review!