From 6d4841a8c22c1c53c1df71756c5459c3a9ed1af7 Mon Sep 17 00:00:00 2001 From: Carl Mastrangelo Date: Mon, 13 Aug 2018 14:36:32 -0700 Subject: [PATCH] stub: update docs about Call lifetime + minor cleanups * Reflowed some method parameters to be on the same line, else one parameter per line * Used `@link` where appropriate * Made some parameters non-final where it had no effect * Renamed some parameters to be consistent --- .../main/java/io/grpc/stub/ClientCalls.java | 89 +++++++++++-------- .../main/java/io/grpc/stub/ServerCalls.java | 26 +++--- 2 files changed, 64 insertions(+), 51 deletions(-) diff --git a/stub/src/main/java/io/grpc/stub/ClientCalls.java b/stub/src/main/java/io/grpc/stub/ClientCalls.java index 8bf3ff018e..db2440381e 100644 --- a/stub/src/main/java/io/grpc/stub/ClientCalls.java +++ b/stub/src/main/java/io/grpc/stub/ClientCalls.java @@ -55,27 +55,29 @@ public final class ClientCalls { private ClientCalls() {} /** - * Executes a unary call with a response {@link StreamObserver}. + * 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. */ public static void asyncUnaryCall( - ClientCall call, - ReqT param, - StreamObserver observer) { - asyncUnaryRequestCall(call, param, observer, false); + ClientCall call, ReqT req, StreamObserver responseObserver) { + asyncUnaryRequestCall(call, req, responseObserver, false); } /** - * Executes a server-streaming call with a response {@link StreamObserver}. + * 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. */ public static void asyncServerStreamingCall( - ClientCall call, - ReqT param, - StreamObserver responseObserver) { - asyncUnaryRequestCall(call, param, responseObserver, true); + ClientCall call, ReqT req, StreamObserver responseObserver) { + asyncUnaryRequestCall(call, req, responseObserver, true); } /** * Executes a client-streaming call returning a {@link StreamObserver} for the request messages. + * The {@code call} should not be already started. After calling this method, {@code call} + * should no longer be used. + * * @return request stream observer. */ public static StreamObserver asyncClientStreamingCall( @@ -85,7 +87,9 @@ public final class ClientCalls { } /** - * Executes a bidi-streaming call. + * 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. */ public static StreamObserver asyncBidiStreamingCall( @@ -94,12 +98,14 @@ public final class ClientCalls { } /** - * Executes a unary call and blocks on the response. + * 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. + * * @return the single response message. */ - public static RespT blockingUnaryCall(ClientCall call, ReqT param) { + public static RespT blockingUnaryCall(ClientCall call, ReqT req) { try { - return getUnchecked(futureUnaryCall(call, param)); + return getUnchecked(futureUnaryCall(call, req)); } catch (RuntimeException e) { throw cancelThrow(call, e); } catch (Error e) { @@ -108,16 +114,17 @@ public final class ClientCalls { } /** - * Executes a unary call and blocks on the response. + * 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. * * @return the single response message. */ public static RespT blockingUnaryCall( - Channel channel, MethodDescriptor method, CallOptions callOptions, ReqT param) { + Channel channel, MethodDescriptor method, CallOptions callOptions, ReqT req) { ThreadlessExecutor executor = new ThreadlessExecutor(); ClientCall call = channel.newCall(method, callOptions.withExecutor(executor)); try { - ListenableFuture responseFuture = futureUnaryCall(call, param); + ListenableFuture responseFuture = futureUnaryCall(call, req); while (!responseFuture.isDone()) { try { executor.waitAndDrain(); @@ -139,43 +146,47 @@ public final class ClientCalls { /** * Executes a server-streaming call returning a blocking {@link Iterator} over the - * response stream. + * response stream. The {@code call} should not be already started. After calling this method, + * {@code call} should no longer be used. + * * @return an iterator over the response stream. */ // TODO(louiscryan): Not clear if we want to use this idiom for 'simple' stubs. public static Iterator blockingServerStreamingCall( - ClientCall call, ReqT param) { + ClientCall call, ReqT req) { BlockingResponseStream result = new BlockingResponseStream(call); - asyncUnaryRequestCall(call, param, result.listener(), true); + asyncUnaryRequestCall(call, req, result.listener(), true); return result; } /** * Executes a server-streaming call returning a blocking {@link Iterator} over the - * response stream. + * response stream. The {@code call} should not be already started. After calling this method, + * {@code call} should no longer be used. * * @return an iterator over the response stream. */ // TODO(louiscryan): Not clear if we want to use this idiom for 'simple' stubs. public static Iterator blockingServerStreamingCall( - Channel channel, MethodDescriptor method, CallOptions callOptions, ReqT param) { + Channel channel, MethodDescriptor method, CallOptions callOptions, ReqT req) { ThreadlessExecutor executor = new ThreadlessExecutor(); ClientCall call = channel.newCall(method, callOptions.withExecutor(executor)); BlockingResponseStream result = new BlockingResponseStream(call, executor); - asyncUnaryRequestCall(call, param, result.listener(), true); + asyncUnaryRequestCall(call, req, result.listener(), true); return result; } /** - * Executes a unary call and returns a {@link ListenableFuture} to the response. + * Executes a unary call and returns a {@link ListenableFuture} to the response. The + * {@code call} should not be already started. After calling this method, {@code call} should no + * longer be used. * * @return a future for the single response message. */ public static ListenableFuture futureUnaryCall( - ClientCall call, - ReqT param) { + ClientCall call, ReqT req) { GrpcFuture responseFuture = new GrpcFuture(call); - asyncUnaryRequestCall(call, param, new UnaryStreamToFuture(responseFuture), false); + asyncUnaryRequestCall(call, req, new UnaryStreamToFuture(responseFuture), false); return responseFuture; } @@ -249,11 +260,11 @@ public final class ClientCalls { } private static void asyncUnaryRequestCall( - ClientCall call, ReqT param, StreamObserver responseObserver, + ClientCall call, ReqT req, StreamObserver responseObserver, boolean streamingResponse) { asyncUnaryRequestCall( call, - param, + req, new StreamObserverToCallListenerAdapter( responseObserver, new CallToStreamObserverAdapter(call), @@ -263,12 +274,12 @@ public final class ClientCalls { private static void asyncUnaryRequestCall( ClientCall call, - ReqT param, + ReqT req, ClientCall.Listener responseListener, boolean streamingResponse) { startCall(call, responseListener, streamingResponse); try { - call.sendMessage(param); + call.sendMessage(req); call.halfClose(); } catch (RuntimeException e) { throw cancelThrow(call, e); @@ -278,7 +289,8 @@ public final class ClientCalls { } private static StreamObserver asyncStreamingRequestCall( - ClientCall call, StreamObserver responseObserver, + ClientCall call, + StreamObserver responseObserver, boolean streamingResponse) { CallToStreamObserverAdapter adapter = new CallToStreamObserverAdapter(call); startCall( @@ -289,8 +301,10 @@ public final class ClientCalls { return adapter; } - private static void startCall(ClientCall call, - ClientCall.Listener responseListener, boolean streamingResponse) { + private static void startCall( + ClientCall call, + ClientCall.Listener responseListener, + boolean streamingResponse) { call.start(responseListener, new Metadata()); if (streamingResponse) { call.request(1); @@ -430,7 +444,7 @@ public final class ClientCalls { } /** - * Complete a GrpcFuture using {@link StreamObserver} events. + * Completes a {@link GrpcFuture} using {@link StreamObserver} events. */ private static final class UnaryStreamToFuture extends ClientCall.Listener { private final GrpcFuture responseFuture; @@ -500,11 +514,10 @@ public final class ClientCalls { } /** - * Convert events on a {@link io.grpc.ClientCall.Listener} into a blocking - * {@link Iterator}. + * Convert events on a {@link io.grpc.ClientCall.Listener} into a blocking {@link Iterator}. * *

The class is not thread-safe, but it does permit {@link ClientCall.Listener} calls in a - * separate thread from {@code Iterator} calls. + * separate thread from {@link Iterator} calls. */ // TODO(ejona86): determine how to allow ClientCall.cancel() in case of application error. private static final class BlockingResponseStream implements Iterator { diff --git a/stub/src/main/java/io/grpc/stub/ServerCalls.java b/stub/src/main/java/io/grpc/stub/ServerCalls.java index 5b043701ac..aac13a5f87 100644 --- a/stub/src/main/java/io/grpc/stub/ServerCalls.java +++ b/stub/src/main/java/io/grpc/stub/ServerCalls.java @@ -42,42 +42,42 @@ public final class ServerCalls { } /** - * Creates a {@code ServerCallHandler} for a unary call method of the service. + * Creates a {@link ServerCallHandler} for a unary call method of the service. * * @param method an adaptor to the actual method on the service implementation. */ public static ServerCallHandler asyncUnaryCall( - final UnaryMethod method) { + UnaryMethod method) { return asyncUnaryRequestCall(method); } /** - * Creates a {@code ServerCallHandler} for a server streaming method of the service. + * Creates a {@link ServerCallHandler} for a server streaming method of the service. * * @param method an adaptor to the actual method on the service implementation. */ public static ServerCallHandler asyncServerStreamingCall( - final ServerStreamingMethod method) { + ServerStreamingMethod method) { return asyncUnaryRequestCall(method); } /** - * Creates a {@code ServerCallHandler} for a client streaming method of the service. + * Creates a {@link ServerCallHandler} for a client streaming method of the service. * * @param method an adaptor to the actual method on the service implementation. */ public static ServerCallHandler asyncClientStreamingCall( - final ClientStreamingMethod method) { + ClientStreamingMethod method) { return asyncStreamingRequestCall(method); } /** - * Creates a {@code ServerCallHandler} for a bidi streaming method of the service. + * Creates a {@link ServerCallHandler} for a bidi streaming method of the service. * * @param method an adaptor to the actual method on the service implementation. */ public static ServerCallHandler asyncBidiStreamingCall( - final BidiStreamingMethod method) { + BidiStreamingMethod method) { return asyncStreamingRequestCall(method); } @@ -97,7 +97,7 @@ public final class ServerCalls { public interface ClientStreamingMethod extends StreamingRequestMethod {} /** - * Adaptor to a bi-directional streaming method. + * Adaptor to a bidirectional streaming method. */ public interface BidiStreamingMethod extends StreamingRequestMethod {} @@ -195,7 +195,7 @@ public final class ServerCalls { } /** - * Creates a {@code ServerCallHandler} for a unary request call method of the service. + * Creates a {@link ServerCallHandler} for a unary request call method of the service. * * @param method an adaptor to the actual method on the service implementation. */ @@ -283,7 +283,7 @@ public final class ServerCalls { } /** - * Creates a {@code ServerCallHandler} for a streaming request call method of the service. + * Creates a {@link ServerCallHandler} for a streaming request call method of the service. * * @param method an adaptor to the actual method on the service implementation. */ @@ -399,8 +399,8 @@ public final class ServerCalls { * @param methodDescriptor of method for which error will be thrown. * @param responseObserver on which error will be set. */ - public static void asyncUnimplementedUnaryCall(MethodDescriptor methodDescriptor, - StreamObserver responseObserver) { + public static void asyncUnimplementedUnaryCall( + MethodDescriptor methodDescriptor, StreamObserver responseObserver) { checkNotNull(methodDescriptor, "methodDescriptor"); checkNotNull(responseObserver, "responseObserver"); responseObserver.onError(Status.UNIMPLEMENTED