Polish javadoc for stub/*
diff --git a/stub/src/main/java/io/grpc/stub/AbstractServiceDescriptor.java b/stub/src/main/java/io/grpc/stub/AbstractServiceDescriptor.java
index b917ad8..0b21224 100644
--- a/stub/src/main/java/io/grpc/stub/AbstractServiceDescriptor.java
+++ b/stub/src/main/java/io/grpc/stub/AbstractServiceDescriptor.java
@@ -51,6 +51,8 @@
/**
* Returns a new stub configuration for the provided method configurations.
+ *
+ * @param methodMap a map from fully qualified method names to {@code MethodDescriptor}s
*/
protected abstract T build(Map<String, MethodDescriptor<?, ?>> methodMap);
}
diff --git a/stub/src/main/java/io/grpc/stub/AbstractStub.java b/stub/src/main/java/io/grpc/stub/AbstractStub.java
index 26e3c8a..9cc7483 100644
--- a/stub/src/main/java/io/grpc/stub/AbstractStub.java
+++ b/stub/src/main/java/io/grpc/stub/AbstractStub.java
@@ -44,14 +44,14 @@
import java.util.concurrent.TimeUnit;
/**
- * Common base type for stub implementations. Allows for reconfiguration.
+ * Common base type for stub implementations.
+ *
+ * <p>This is the base class of the stub classes from the generated code. It allows for
+ * reconfiguration, e.g., attaching interceptors to the stub.
*
* @param <S> the concrete type of this stub.
* @param <C> the service descriptor type
*/
-// TODO(louiscryan): Move into 3rd party when tidy
-// TODO(louiscryan): Excessive parameterization can be a pain, try to eliminate once the generated
-// code is more tangible.
public abstract class AbstractStub<S extends AbstractStub<?, ?>,
C extends AbstractServiceDescriptor<C>> {
protected final Channel channel;
@@ -59,6 +59,9 @@
/**
* Constructor for use by subclasses.
+ *
+ * @param channel the channel that this stub will use to do communications
+ * @param config defines the RPC methods of the stub
*/
protected AbstractStub(Channel channel, C config) {
this.channel = channel;
@@ -69,16 +72,25 @@
return config;
}
+ /**
+ * Creates a builder for reconfiguring the stub.
+ */
public StubConfigBuilder configureNewStub() {
return new StubConfigBuilder();
}
+ /**
+ * The underlying channel of the stub.
+ */
public Channel getChannel() {
return channel;
}
/**
- * Returns a new stub configuration for the provided method configurations.
+ * Returns a new stub with the given channel for the provided method configurations.
+ *
+ * @param channel the channel that this stub will use to do communications
+ * @param config defines the RPC methods of the stub
*/
protected abstract S build(Channel channel, C config);
@@ -100,7 +112,7 @@
}
/**
- * Set a timeout for all methods in the stub.
+ * Sets a timeout for all methods in the stub.
*/
public StubConfigBuilder setTimeout(long timeout, TimeUnit unit) {
for (Map.Entry<String, MethodDescriptor<?, ?>> entry : methodMap.entrySet()) {
@@ -118,7 +130,7 @@
}
/**
- * Adds a client interceptor to be attached to the channel.
+ * Adds a client interceptor to be attached to the channel of the reconfigured stub.
*/
public StubConfigBuilder addInterceptor(ClientInterceptor interceptor) {
interceptors.add(interceptor);
@@ -126,7 +138,7 @@
}
/**
- * Create a new stub configuration
+ * Create a new stub with the configurations made on this builder.
*/
public S build() {
return AbstractStub.this.build(ClientInterceptors.intercept(stubChannel, interceptors),
diff --git a/stub/src/main/java/io/grpc/stub/Calls.java b/stub/src/main/java/io/grpc/stub/Calls.java
index 9371632..9a21008 100644
--- a/stub/src/main/java/io/grpc/stub/Calls.java
+++ b/stub/src/main/java/io/grpc/stub/Calls.java
@@ -60,7 +60,7 @@
public class Calls {
/**
- * Creates a MethodDescriptor for a given method.
+ * Creates a {@link MethodDescriptor} for a given method.
*
* @param fullServiceName fully qualified service name
* @param method carries all invariants of the method
@@ -74,7 +74,8 @@
}
/**
- * Execute a unary call and return a {@link ListenableFuture} to the response.
+ * Executes a unary call and returns a {@link ListenableFuture} to the response.
+ *
* @return a future for the single response message.
*/
public static <ReqT, RespT> ListenableFuture<RespT> unaryFutureCall(
@@ -119,7 +120,7 @@
}
/**
- * Execute a unary call and block on the response.
+ * Executes a unary call and blocks on the response.
* @return the single response message.
*/
public static <ReqT, RespT> RespT blockingUnaryCall(Call<ReqT, RespT> call, ReqT param) {
@@ -132,7 +133,7 @@
}
/**
- * Execute a unary call with a response {@link StreamObserver}.
+ * Executes a unary call with a response {@link StreamObserver}.
*/
public static <ReqT, RespT> void asyncUnaryCall(
Call<ReqT, RespT> call,
@@ -142,7 +143,7 @@
}
/**
- * Execute a server-streaming call returning a blocking {@link Iterator} over the
+ * Executes a server-streaming call returning a blocking {@link Iterator} over the
* response stream.
* @return an iterator over the response stream.
*/
@@ -155,7 +156,7 @@
}
/**
- * Execute a server-streaming call with a response {@link StreamObserver}.
+ * Executes a server-streaming call with a response {@link StreamObserver}.
*/
public static <ReqT, RespT> void asyncServerStreamingCall(
Call<ReqT, RespT> call,
@@ -181,7 +182,7 @@
}
/**
- * Execute a client-streaming call with a blocking {@link Iterator} of request messages.
+ * Executes a client-streaming call with a blocking {@link Iterator} of request messages.
* @return the single response value.
*/
public static <ReqT, RespT> RespT blockingClientStreamingCall(
@@ -207,7 +208,7 @@
}
/**
- * Execute a client-streaming call returning a {@link StreamObserver} for the request messages.
+ * Executes a client-streaming call returning a {@link StreamObserver} for the request messages.
* @return request stream observer.
*/
public static <ReqT, RespT> StreamObserver<ReqT> asyncClientStreamingCall(
@@ -217,7 +218,7 @@
}
/**
- * Execute a duplex-streaming call.
+ * Executes a duplex-streaming call.
* @return request stream observer.
*/
public static <ReqT, RespT> StreamObserver<ReqT> duplexStreamingCall(Call<ReqT, RespT> call,
@@ -327,8 +328,8 @@
* Convert events on a {@link io.grpc.Call.Listener} into a blocking
* {@link Iterator}.
*
- * <p>The class is not thread-safe, but it does permit Call.Listener calls in a separate thread
- * from Iterator calls.
+ * <p>The class is not thread-safe, but it does permit {@link Call.Listener} calls in a separate
+ * thread from {@code Iterator} calls.
*/
// TODO(ejona86): determine how to allow Call.cancel() in case of application error.
private static class BlockingResponseStream<T> implements Iterator<T> {
diff --git a/stub/src/main/java/io/grpc/stub/MetadataUtils.java b/stub/src/main/java/io/grpc/stub/MetadataUtils.java
index 9c303b8..552c0af 100644
--- a/stub/src/main/java/io/grpc/stub/MetadataUtils.java
+++ b/stub/src/main/java/io/grpc/stub/MetadataUtils.java
@@ -48,10 +48,11 @@
public class MetadataUtils {
/**
- * Attach a set of request headers to a stub.
+ * Attaches a set of request headers to a stub.
+ *
* @param stub to bind the headers to.
* @param extraHeaders the headers to be passed by each call on the returned stub.
- * @return an implementation of the stub with extraHeaders bound to each call.
+ * @return an implementation of the stub with {@code extraHeaders} bound to each call.
*/
@SuppressWarnings({"unchecked", "rawtypes"})
public static <T extends AbstractStub> T attachHeaders(
@@ -62,7 +63,7 @@
}
/**
- * Return a client interceptor that attaches a set of headers to requests.
+ * Returns a client interceptor that attaches a set of headers to requests.
*
* @param extraHeaders the headers to be passed by each call that is processed by the returned
* interceptor
@@ -84,11 +85,12 @@
}
/**
- * Capture the last received metadata for a stub. Useful for testing
+ * Captures the last received metadata for a stub. Useful for testing
+ *
* @param stub to capture for
* @param headersCapture to record the last received headers
* @param trailersCapture to record the last received trailers
- * @return an implementation of the stub with extraHeaders bound to each call.
+ * @return an implementation of the stub with {@code extraHeaders} bound to each call.
*/
@SuppressWarnings({"unchecked", "rawtypes"})
public static <T extends AbstractStub> T captureMetadata(
@@ -100,7 +102,7 @@
}
/**
- * Capture the last received metadata on a channel. Useful for testing
+ * Captures the last received metadata on a channel. Useful for testing.
*
* @param headersCapture to record the last received headers
* @param trailersCapture to record the last received trailers
diff --git a/stub/src/main/java/io/grpc/stub/Method.java b/stub/src/main/java/io/grpc/stub/Method.java
index 21e2300..a11b2ab 100644
--- a/stub/src/main/java/io/grpc/stub/Method.java
+++ b/stub/src/main/java/io/grpc/stub/Method.java
@@ -84,10 +84,16 @@
return name;
}
+ /**
+ * The marshaller used to serialize/deserialize the request.
+ */
public Marshaller<RequestT> getRequestMarshaller() {
return requestMarshaller;
}
+ /**
+ * The marshaller used to serialize/deserialize the response.
+ */
public Marshaller<ResponseT> getResponseMarshaller() {
return responseMarshaller;
}
diff --git a/stub/src/main/java/io/grpc/stub/ServerCalls.java b/stub/src/main/java/io/grpc/stub/ServerCalls.java
index 4def475..99a4361 100644
--- a/stub/src/main/java/io/grpc/stub/ServerCalls.java
+++ b/stub/src/main/java/io/grpc/stub/ServerCalls.java
@@ -38,19 +38,28 @@
import io.grpc.Status;
/**
- * Utility functions for adapting ServerCallHandlers to application service implementation.
+ * Utility functions for adapting {@link ServerCallHandler}s to application service implementation,
+ * meant to be used by the generated code.
*/
public class ServerCalls {
private ServerCalls() {
}
+ /**
+ * Attaches the handler to a method and gets a {@code ServerMethodDefinition}.
+ */
public static <ReqT, RespT> ServerMethodDefinition<ReqT, RespT> createMethodDefinition(
Method<ReqT, RespT> method, ServerCallHandler<ReqT, RespT> handler) {
return ServerMethodDefinition.create(method.getName(), method.getRequestMarshaller(),
method.getResponseMarshaller(), handler);
}
+ /**
+ * Creates a {@code ServerCallHandler} for a unary request call method of the service.
+ *
+ * @param method an adaptor to the actual method on the service implementation.
+ */
public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncUnaryRequestCall(
final UnaryRequestMethod<ReqT, RespT> method) {
return new ServerCallHandler<ReqT, RespT>() {
@@ -97,6 +106,11 @@
};
}
+ /**
+ * Creates a {@code ServerCallHandler} for a streaming request call method of the service.
+ *
+ * @param method an adaptor to the actual method on the service implementation.
+ */
public static <ReqT, RespT> ServerCallHandler<ReqT, RespT> asyncStreamingRequestCall(
final StreamingRequestMethod<ReqT, RespT> method) {
return new ServerCallHandler<ReqT, RespT>() {
diff --git a/stub/src/main/java/io/grpc/stub/StreamObserver.java b/stub/src/main/java/io/grpc/stub/StreamObserver.java
index 91eac77..98cdb22 100644
--- a/stub/src/main/java/io/grpc/stub/StreamObserver.java
+++ b/stub/src/main/java/io/grpc/stub/StreamObserver.java
@@ -34,37 +34,46 @@
/**
* Receives notifications from an observable stream of messages.
*
- * <p>Implementations are expected to be thread-compatible. Separate StreamObservers do not need to
- * be sychronized together; incoming and outgoing directions are independent.
+ * <p>It is used by both the client stubs and service implementations for sending or receiving
+ * stream messages. For outgoing messages, a {@code StreamObserver} is provided by the GRPC library
+ * to the application. For incoming messages, the application implements the {@code StreamObserver}
+ * and passes it to the GRPC library for receiving.
+ *
+ * <p>Implementations are expected to be thread-compatible. Separate {@code StreamObserver}s do
+ * not need to be sychronized together; incoming and outgoing directions are independent.
*/
-// TODO(louiscryan): Consider whether we need to interact with flow-control at this layer. E.g.
-// public ListenableFuture<Void> onValue(V value). Do we layer it in here or as an additional
-// interface? Interaction with flow control can be done by blocking here.
public interface StreamObserver<V> {
/**
- * Receive a value from the stream.
+ * Receives a value from the stream.
*
- * <p>Can be called many times but is never called after onError or onCompleted are called.
+ * <p>Can be called many times but is never called after {@link #onError(Throwable)} or {@link
+ * #onCompleted()} are called.
*
* <p>If an exception is thrown by an implementation the caller is expected to terminate the
- * stream by calling {@linkplain #onError(Throwable)} with the caught exception prior to
+ * stream by calling {@link #onError(Throwable)} with the caught exception prior to
* propagating it.
+ *
+ * @param value the value passed to the stream
*/
public void onValue(V value);
/**
- * Receive a terminating error from the stream.
+ * Receives a terminating error from the stream.
*
- * <p>May only be called once and is never called after onCompleted. In particular if an exception
- * is thrown by an implementation of onError no further calls to any method are allowed.
+ * <p>May only be called once and is never called after {@link #onCompleted()}. In particular if
+ * an exception is thrown by an implementation of {@code onError} no further calls to any
+ * method are allowed.
+ *
+ * @param t the error occurred on the stream
*/
public void onError(Throwable t);
/**
- * Notifies successful stream completion.
+ * Receives a notification of successful stream completion.
*
- * <p>May only be called once and is never called after onError. In particular if an exception is
- * thrown by an implementation of onCompleted no further calls to any method are allowed.
+ * <p>May only be called once and is never called after {@link #onError(Throwable)}. In particular
+ * if an exception is thrown by an implementation of {@code onCompleted} no further calls to
+ * any method are allowed.
*/
public void onCompleted();
}
diff --git a/stub/src/main/java/io/grpc/stub/StreamRecorder.java b/stub/src/main/java/io/grpc/stub/StreamRecorder.java
index cfd5c07..eb473e1 100644
--- a/stub/src/main/java/io/grpc/stub/StreamRecorder.java
+++ b/stub/src/main/java/io/grpc/stub/StreamRecorder.java
@@ -43,13 +43,13 @@
import javax.annotation.Nullable;
/**
- * Utility implementation of {link StreamObserver} used in testing. Records all the observed
+ * Utility implementation of {@link StreamObserver} used in testing. Records all the observed
* values produced by the stream as well as any errors.
*/
public class StreamRecorder<T> implements StreamObserver<T> {
/**
- * Create a new recorder.
+ * Creates a new recorder.
*/
public static <T> StreamRecorder<T> create() {
return new StreamRecorder<T>();
@@ -92,35 +92,35 @@
}
/**
- * Wait for the stream to terminate.
+ * Waits for the stream to terminate.
*/
public void awaitCompletion() throws Exception {
latch.await();
}
/**
- * Wait a fixed timeout for the stream to terminate.
+ * Waits a fixed timeout for the stream to terminate.
*/
public boolean awaitCompletion(int timeout, TimeUnit unit) throws Exception {
return latch.await(timeout, unit);
}
/**
- * Return the current set of received values.
+ * Returns the current set of received values.
*/
public List<T> getValues() {
return Collections.unmodifiableList(results);
}
/**
- * Return the stream terminating error.
+ * Returns the stream terminating error.
*/
@Nullable public Throwable getError() {
return error;
}
/**
- * Return a {@link ListenableFuture} for the first value received from the stream. Useful
+ * Returns a {@link ListenableFuture} for the first value received from the stream. Useful
* for testing unary call patterns.
*/
public ListenableFuture<T> firstValue() {