stub: Document blocking exceptions and async extension types
invoke() needed to be re-defined for Javadoc to display the method.
diff --git a/stub/src/main/java/io/grpc/stub/ClientCalls.java b/stub/src/main/java/io/grpc/stub/ClientCalls.java
index aa507bb..f946b3b 100644
--- a/stub/src/main/java/io/grpc/stub/ClientCalls.java
+++ b/stub/src/main/java/io/grpc/stub/ClientCalls.java
@@ -59,6 +59,9 @@
/**
* Executes a unary call with a response {@link StreamObserver}. The {@code call} should not be
* already started. After calling this method, {@code call} should no longer be used.
+ *
+ * <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
+ * {@code beforeStart()} will be called.
*/
public static <ReqT, RespT> void asyncUnaryCall(
ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
@@ -69,6 +72,9 @@
* Executes a server-streaming call with a response {@link StreamObserver}. The {@code call}
* should not be already started. After calling this method, {@code call} should no longer be
* used.
+ *
+ * <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
+ * {@code beforeStart()} will be called.
*/
public static <ReqT, RespT> void asyncServerStreamingCall(
ClientCall<ReqT, RespT> call, ReqT req, StreamObserver<RespT> responseObserver) {
@@ -80,7 +86,10 @@
* The {@code call} should not be already started. After calling this method, {@code call}
* should no longer be used.
*
- * @return request stream observer.
+ * <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
+ * {@code beforeStart()} will be called.
+ *
+ * @return request stream observer. It will extend {@link ClientCallStreamObserver}
*/
public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
ClientCall<ReqT, RespT> call,
@@ -92,7 +101,10 @@
* Executes a bidirectional-streaming call. The {@code call} should not be already started.
* After calling this method, {@code call} should no longer be used.
*
- * @return request stream observer.
+ * <p>If the provided {@code responseObserver} is an instance of {@link ClientResponseObserver},
+ * {@code beforeStart()} will be called.
+ *
+ * @return request stream observer. It will extend {@link ClientCallStreamObserver}
*/
public static <ReqT, RespT> StreamObserver<ReqT> asyncBidiStreamingCall(
ClientCall<ReqT, RespT> call, StreamObserver<RespT> responseObserver) {
@@ -104,6 +116,7 @@
* started. After calling this method, {@code call} should no longer be used.
*
* @return the single response message.
+ * @throws StatusRuntimeException on error
*/
public static <ReqT, RespT> RespT blockingUnaryCall(ClientCall<ReqT, RespT> call, ReqT req) {
try {
@@ -120,6 +133,7 @@
* started. After calling this method, {@code call} should no longer be used.
*
* @return the single response message.
+ * @throws StatusRuntimeException on error
*/
public static <ReqT, RespT> RespT blockingUnaryCall(
Channel channel, MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, ReqT req) {
@@ -158,6 +172,8 @@
* 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.
+ *
* @return an iterator over the response stream.
*/
// TODO(louiscryan): Not clear if we want to use this idiom for 'simple' stubs.
@@ -173,6 +189,8 @@
* 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.
+ *
* @return an iterator over the response stream.
*/
// TODO(louiscryan): Not clear if we want to use this idiom for 'simple' stubs.
diff --git a/stub/src/main/java/io/grpc/stub/ServerCalls.java b/stub/src/main/java/io/grpc/stub/ServerCalls.java
index 8e5ed1e..f3f8cd7 100644
--- a/stub/src/main/java/io/grpc/stub/ServerCalls.java
+++ b/stub/src/main/java/io/grpc/stub/ServerCalls.java
@@ -84,22 +84,30 @@
/**
* Adaptor to a unary call method.
*/
- public interface UnaryMethod<ReqT, RespT> extends UnaryRequestMethod<ReqT, RespT> {}
+ public interface UnaryMethod<ReqT, RespT> extends UnaryRequestMethod<ReqT, RespT> {
+ @Override void invoke(ReqT request, StreamObserver<RespT> responseObserver);
+ }
/**
* Adaptor to a server streaming method.
*/
- public interface ServerStreamingMethod<ReqT, RespT> extends UnaryRequestMethod<ReqT, RespT> {}
+ public interface ServerStreamingMethod<ReqT, RespT> extends UnaryRequestMethod<ReqT, RespT> {
+ @Override void invoke(ReqT request, StreamObserver<RespT> responseObserver);
+ }
/**
* Adaptor to a client streaming method.
*/
- public interface ClientStreamingMethod<ReqT, RespT> extends StreamingRequestMethod<ReqT, RespT> {}
+ public interface ClientStreamingMethod<ReqT, RespT> extends StreamingRequestMethod<ReqT, RespT> {
+ @Override StreamObserver<ReqT> invoke(StreamObserver<RespT> responseObserver);
+ }
/**
* Adaptor to a bidirectional streaming method.
*/
- public interface BidiStreamingMethod<ReqT, RespT> extends StreamingRequestMethod<ReqT, RespT> {}
+ public interface BidiStreamingMethod<ReqT, RespT> extends StreamingRequestMethod<ReqT, RespT> {
+ @Override StreamObserver<ReqT> invoke(StreamObserver<RespT> responseObserver);
+ }
private static final class UnaryServerCallHandler<ReqT, RespT>
implements ServerCallHandler<ReqT, RespT> {
@@ -296,10 +304,16 @@
}
private interface UnaryRequestMethod<ReqT, RespT> {
+ /**
+ * The provided {@code responseObserver} will extend {@link ServerCallStreamObserver}.
+ */
void invoke(ReqT request, StreamObserver<RespT> responseObserver);
}
private interface StreamingRequestMethod<ReqT, RespT> {
+ /**
+ * The provided {@code responseObserver} will extend {@link ServerCallStreamObserver}.
+ */
StreamObserver<ReqT> invoke(StreamObserver<RespT> responseObserver);
}
