Skip to content

doc: Document error handling and Observer callback behavior #11876

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kannanjgithub wants to merge 5 commits into
base: master
Choose a base branch
from
Open

doc: Document error handling and Observer callback behavior #11876

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
68b4f42
Changes
kannanjgithub Feb 1, 2025
916e848
Documenting error transmission and callback behavior.
kannanjgithub Feb 4, 2025
f8b457a
Address review comments.
kannanjgithub Aug 27, 2026
3edd086
Merge branch 'master' into inconsistencies-error-handling
kannanjgithub Aug 27, 2026
00dd36f
Redo javadoc changes after accepting the copy from master, and also a…
kannanjgithub Aug 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 98 additions & 2 deletions stub/src/main/java/io/grpc/stub/ClientCalls.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,12 @@ private ClientCalls() {}
*
* <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
* {@code beforeStart()} will be called.
*
* <h3>Server errors</h3>
* If the server completes the RPC with status code OK, then {@code
* responseObserver.onCompleted()} is called at the end of the RPC. Otherwise the status and
* trailers are passed as a Throwable to {@code onError()} and can be accessed with {@link
* Status#fromThrowable} and {@link Status#trailersFromThrowable}.
*/
public static <ReqT, RespT> void asyncUnaryCall(
ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
Expand All @@ -91,6 +97,12 @@ public static <ReqT, RespT> void asyncUnaryCall(
*
* <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
* {@code beforeStart()} will be called.
*
* <h3>Server errors</h3>
* If the server completes the RPC with status code OK, then {@code
* responseObserver.onCompleted()} is called at the end of the RPC. Otherwise the status and
* trailers are passed as a Throwable to {@code onError()} and can be accessed with {@link
* Status#fromThrowable} and {@link Status#trailersFromThrowable}.
*/
public static <ReqT, RespT> void asyncServerStreamingCall(
ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
Expand All @@ -106,6 +118,25 @@ public static <ReqT, RespT> void asyncServerStreamingCall(
* <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
* {@code beforeStart()} will be called.
*
* <h3>Client errors</h3>
* {@link StreamObserver#onError} called on the request stream observer will result in stream
* cancellation. The response
* {@link StreamObserver} will be immediately notified of the cancellation with a
* {@link io.grpc.StatusRuntimeException} with the exception passed to onError set as the cause
* and the stream is considered closed. The server's request stream observer will receive an
* {@link StreamObserver#onError} callback with a throwable which when converted to a status
* with
* Status.fromThrowable(), always has the status code CANCELLED and exception cause set to
* null because the actual exception
* passed by the client to onError is never actually transmitted to the server and the server
* just receives a RST_STREAM frame indicating cancellation by the client.
*
* <h3>Server errors</h3>
* If the server completes the RPC with status code OK, then {@code
* responseObserver.onCompleted()} is called at the end of the RPC. Otherwise the status and
* trailers are passed as a Throwable to {@code onError()} and can be accessed with {@link
* Status#fromThrowable} and {@link Status#trailersFromThrowable}.
*
* @return request stream observer. It will extend {@link ClientCallStreamObserver}
*/
public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
Expand All @@ -122,6 +153,25 @@ public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
* <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
* {@code beforeStart()} will be called.
*
* <h3>Client errors</h3>
* {@link StreamObserver#onError} called on the request stream observer will result in stream
* cancellation. The response
* {@link StreamObserver} will be immediately notified of the cancellation with a
* {@link io.grpc.StatusRuntimeException} with the exception passed to onError set as the cause
* and the stream is considered closed. The server's request stream observer will receive an
* {@link StreamObserver#onError} callback with a throwable which when converted to a status
* with
* Status.fromThrowable(), always has the status code CANCELLED and exception cause set to
* null because the actual exception
* passed by the client to onError is never actually transmitted to the server and the server
* just receives a RST_STREAM frame indicating cancellation by the client.
*
* <h3>Server errors</h3>
* If the server completes the RPC with status code OK, then {@code
* responseObserver.onCompleted()} is called at the end of the RPC. Otherwise the status and
* trailers are passed as a Throwable to {@code onError()} and can be accessed with {@link
* Status#fromThrowable} and {@link Status#trailersFromThrowable}.
*
* @return request stream observer. It will extend {@link ClientCallStreamObserver}
*/
public static <ReqT, RespT> StreamObserver<ReqT> asyncBidiStreamingCall(
Expand All @@ -134,6 +184,10 @@ public static <ReqT, RespT> StreamObserver<ReqT> asyncBidiStreamingCall(
* Executes a unary call and blocks on the response. The {@code call} should not be already
* started. After calling this method, {@code call} should no longer be used.
*
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, a {@link StatusRuntimeException}
* is thrown. The status code and trailers can be accessed from the exception.
*
* @return the single response message.
* @throws StatusRuntimeException on error
*/
Expand All @@ -149,6 +203,10 @@ public static <ReqT, RespT> RespT blockingUnaryCall(ClientCall<ReqT, RespT> call
* Executes a unary call and blocks on the response. The {@code call} should not be already
* started. After calling this method, {@code call} should no longer be used.
*
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, a {@link StatusRuntimeException}
* is thrown. The status code and trailers can be accessed from the exception.
*
* @return the single response message.
* @throws StatusRuntimeException on error
*/
Expand Down Expand Up @@ -186,6 +244,10 @@ public static <ReqT, RespT> RespT blockingUnaryCall(
* Executes a unary call and blocks on the response,
* throws a checked {@link StatusException}.
*
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, a {@link StatusException}
* is thrown. The status code and trailers can be accessed from the exception.
*
* @return the single response message.
* @throws StatusException on error
*/
Expand All @@ -204,7 +266,11 @@ public static <ReqT, RespT> RespT blockingV2UnaryCall(
* response stream. The {@code call} should not be already started. After calling this method,
* {@code call} should no longer be used.
*
* <p>The returned iterator may throw {@link StatusRuntimeException} on error.
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, the returned iterator will throw
* a {@link StatusRuntimeException} when attempting to read the error response (e.g. in
* {@link Iterator#hasNext} or {@link Iterator#next}). The status code and trailers can be
* accessed from the exception.
*
* @return an iterator over the response stream.
*/
Expand All @@ -219,7 +285,11 @@ public static <ReqT, RespT> Iterator<RespT> blockingServerStreamingCall(
* Executes a server-streaming call returning a blocking {@link Iterator} over the
* response stream.
*
* <p>The returned iterator may throw {@link StatusRuntimeException} on error.
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, the returned iterator will throw
* a {@link StatusRuntimeException} when attempting to read the error response (e.g. in
* {@link Iterator#hasNext} or {@link Iterator#next}). The status code and trailers can be
* accessed from the exception.
*
* <p>Warning: the iterator can result in leaks if not completely consumed.
*
Expand All @@ -242,6 +312,13 @@ public static <ReqT, RespT> Iterator<RespT> blockingServerStreamingCall(
* <p>The methods {@link BlockingClientCall#hasNext()} and {@link
* BlockingClientCall#cancel(String, Throwable)} can be used for more extensive control.
*
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, the returned {@link BlockingClientCall}
* will throw a {@link StatusException} when calling read or write operations (e.g.,
* {@link BlockingClientCall#read()}, {@link BlockingClientCall#hasNext()}, or
* {@link BlockingClientCall#write(Object)}). The status code and trailers can be accessed from
* the exception.
*
* @return A {@link BlockingClientCall} that has had the request sent and halfClose called
*/
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
Expand Down Expand Up @@ -280,6 +357,13 @@ public static <ReqT, RespT> BlockingClientCall<ReqT, RespT> blockingV2ServerStre
* {@link #blockingServerStreamingCall(Channel, MethodDescriptor, CallOptions, Object)}
* which returns an iterator, which would leave the stream open if not completely consumed.
*
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, the returned {@link BlockingClientCall}
* will throw a {@link StatusException} when calling read or write operations (e.g.,
* {@link BlockingClientCall#read()}, {@link BlockingClientCall#hasNext()}, or
* {@link BlockingClientCall#write(Object)}). The status code and trailers can be accessed from
* the exception.
*
* @return A {@link BlockingClientCall} which can be used by the client to write and receive
* messages over the grpc channel.
*/
Expand All @@ -294,6 +378,13 @@ public static <ReqT, RespT> BlockingClientCall<ReqT, RespT> blockingClientStream
* ({@link BlockingClientCall}) which can be used by the client to send and receive messages over
* the grpc channel.
*
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, the returned {@link BlockingClientCall}
* will throw a {@link StatusException} when calling read or write operations (e.g.,
* {@link BlockingClientCall#read()}, {@link BlockingClientCall#hasNext()}, or
* {@link BlockingClientCall#write(Object)}). The status code and trailers can be accessed from
* the exception.
*
* @return an object representing the call which can be used to read, write and terminate it.
*/
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/10918")
Expand All @@ -316,6 +407,11 @@ public static <ReqT, RespT> BlockingClientCall<ReqT, RespT> blockingBidiStreamin
* {@code call} should not be already started. After calling this method, {@code call} should no
* longer be used.
*
* <h3>Server errors</h3>
* If the server completes the RPC with a non-OK status, the returned future will fail with
* a {@link StatusRuntimeException}. The status code and trailers can be accessed from the
* exception.
*
* @return a future for the single response message.
*/
public static <ReqT, RespT> ListenableFuture<RespT> futureUnaryCall(
Expand Down
64 changes: 64 additions & 0 deletions stub/src/main/java/io/grpc/stub/ServerCalls.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,27 +85,91 @@ public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncBidiStreamingCal
* Adaptor to a unary call method.
*/
public interface UnaryMethod<ReqT, RespT> extends UnaryRequestMethod<ReqT, RespT> {
/**
* Invoke the method.
*
* @param request the request message from the client
* @param responseObserver the observer to receive the single response. Calling {@code
* responseObserver}'s {@link StreamObserver#onCompleted} or {@link
* StreamObserver#onError} is the end of the RPC. {@code onCompleted()} will close the RPC
* with status code OK. {@code onError()} will convert the Throwable to a Status with {@link
* Status#fromThrowable} and trailers with {@link Status#trailersFromThrowable}. The {@link
* Status#getCause} is not sent to the client, except if done by an interceptor. Callers
* generally create a Throwable with {@link Status#asException()}, {@link
* Status#asException(Metadata)}, {@link Status#asRuntimeException()}, or {@link
* Status#asRuntimeException(Metadata)}.
*/
@Override void invoke(ReqT request, StreamObserver<RespT> responseObserver);
}

/**
* Adaptor to a server streaming method.
*/
public interface ServerStreamingMethod<ReqT, RespT> extends UnaryRequestMethod<ReqT, RespT> {
/**
* Invoke the method.
*
* @param request the request message from the client
* @param responseObserver the observer to receive the response stream. Calling {@code
* responseObserver}'s {@link StreamObserver#onCompleted} or {@link
* StreamObserver#onError} is the end of the RPC. {@code onCompleted()} will close the RPC
* with status code OK. {@code onError()} will convert the Throwable to a Status with {@link
* Status#fromThrowable} and trailers with {@link Status#trailersFromThrowable}. The {@link
* Status#getCause} is not sent to the client, except if done by an interceptor. Callers
* generally create a Throwable with {@link Status#asException()}, {@link
* Status#asException(Metadata)}, {@link Status#asRuntimeException()}, or {@link
* Status#asRuntimeException(Metadata)}.
*/
@Override void invoke(ReqT request, StreamObserver<RespT> responseObserver);
}

/**
* Adaptor to a client streaming method.
*/
public interface ClientStreamingMethod<ReqT, RespT> extends StreamingRequestMethod<ReqT, RespT> {
/**
* Invoke the method.
*
* <h3>Client errors</h3>
* The Throwable received by the server's request stream observer when converted to a status
* with Status.fromThrowable(), always has the status code CANCELLED.
*
* @param responseObserver the observer to receive the single response. Calling {@code
* responseObserver}'s {@link StreamObserver#onCompleted} or {@link
* StreamObserver#onError} is the end of the RPC. {@code onCompleted()} will close the RPC
* with status code OK. {@code onError()} will convert the Throwable to a Status with {@link
* Status#fromThrowable} and trailers with {@link Status#trailersFromThrowable}. The {@link
* Status#getCause} is not sent to the client, except if done by an interceptor. Callers
* generally create a Throwable with {@link Status#asException()}, {@link
* Status#asException(Metadata)}, {@link Status#asRuntimeException()}, or {@link
* Status#asRuntimeException(Metadata)}.
* @return a stream observer for receiving the request stream from the client
*/
@Override StreamObserver<ReqT> invoke(StreamObserver<RespT> responseObserver);
}

/**
* Adaptor to a bidirectional streaming method.
*/
public interface BidiStreamingMethod<ReqT, RespT> extends StreamingRequestMethod<ReqT, RespT> {
/**
* Invoke the method.
*
* <h3>Client errors</h3>
* The Throwable received by the server's request stream observer when converted to a status
* with Status.fromThrowable(), always has the status code CANCELLED.
*
* @param responseObserver the observer to receive the response stream. Calling {@code
* responseObserver}'s {@link StreamObserver#onCompleted} or {@link
* StreamObserver#onError} is the end of the RPC. {@code onCompleted()} will close the RPC
* with status code OK. {@code onError()} will convert the Throwable to a Status with {@link
* Status#fromThrowable} and trailers with {@link Status#trailersFromThrowable}. The {@link
* Status#getCause} is not sent to the client, except if done by an interceptor. Callers
* generally create a Throwable with {@link Status#asException()}, {@link
* Status#asException(Metadata)}, {@link Status#asRuntimeException()}, or {@link
* Status#asRuntimeException(Metadata)}.
* @return a stream observer for receiving the request stream from the client
*/
@Override StreamObserver<ReqT> invoke(StreamObserver<RespT> responseObserver);
}

Expand Down
Loading