stub: Document blocking exceptions and async extension types

invoke() needed to be re-defined for Javadoc to display the method.

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

@@ -59,6 +59,9 @@ public final class ClientCalls {
   /**
    * 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 @@ public final class ClientCalls {
    * 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 @@ public final class ClientCalls {
    * 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 @@ public final class ClientCalls {
    * 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 @@ public final class ClientCalls {
    * 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 @@ public final class ClientCalls {
    * 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 @@ public final class ClientCalls {
    * 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 @@ public final class ClientCalls {
    * 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.

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

@@ -84,22 +84,30 @@ public final class ServerCalls {
   /**
    * 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 @@ public final class ServerCalls {
   }
 
   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);
   }