diff options
author | Carl Mastrangelo <notcarl@google.com> | 2017-03-15 13:31:09 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2017-03-15 13:31:09 -0700 |
commit | 6d44f2ffa45ee955dd913e5b3f93724eeb4da4bc (patch) | |
tree | 2d6b929156f8902974d6cece4418500382dafd71 /stub | |
parent | c44a4b24dd7b5a9c15840ef780e64c4e1e01a960 (diff) | |
download | grpc-grpc-java-6d44f2ffa45ee955dd913e5b3f93724eeb4da4bc.tar.gz |
stub: document withChannel and document method history
Diffstat (limited to 'stub')
-rw-r--r-- | stub/src/main/java/io/grpc/stub/AbstractStub.java | 29 |
1 files changed, 29 insertions, 0 deletions
diff --git a/stub/src/main/java/io/grpc/stub/AbstractStub.java b/stub/src/main/java/io/grpc/stub/AbstractStub.java index 0c9319fe6..8b8d33032 100644 --- a/stub/src/main/java/io/grpc/stub/AbstractStub.java +++ b/stub/src/main/java/io/grpc/stub/AbstractStub.java @@ -50,6 +50,7 @@ import javax.annotation.Nullable; * <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. * + * @since 1.0.0 * @param <S> the concrete type of this stub. */ public abstract class AbstractStub<S extends AbstractStub<S>> { @@ -59,6 +60,7 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Constructor for use by subclasses, with the default {@code CallOptions}. * + * @since 1.0.0 * @param channel the channel that this stub will use to do communications */ protected AbstractStub(Channel channel) { @@ -68,6 +70,7 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Constructor for use by subclasses, with the default {@code CallOptions}. * + * @since 1.0.0 * @param channel the channel that this stub will use to do communications * @param callOptions the runtime call options to be applied to every call on this stub */ @@ -78,6 +81,8 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * The underlying channel of the stub. + * + * @since 1.0.0 */ public final Channel getChannel() { return channel; @@ -85,6 +90,8 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * The {@code CallOptions} of the stub. + * + * @since 1.0.0 */ public final CallOptions getCallOptions() { return callOptions; @@ -93,6 +100,7 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Returns a new stub with the given channel for the provided method configurations. * + * @since 1.0.0 * @param channel the channel that this stub will use to do communications * @param callOptions the runtime call options to be applied to every call on this stub */ @@ -104,6 +112,7 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { * <p>This is mostly used for propagating an existing deadline. {@link #withDeadlineAfter} is the * recommended way of setting a new deadline, * + * @since 1.0.0 * @param deadline the deadline or {@code null} for unsetting the deadline. */ public final S withDeadline(@Nullable Deadline deadline) { @@ -113,6 +122,7 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Returns a new stub with a deadline that is after the given {@code duration} from now. * + * @since 1.0.0 * @see CallOptions#withDeadlineAfter */ public final S withDeadlineAfter(long duration, TimeUnit unit) { @@ -126,6 +136,7 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { * compressed responses from the server, set the appropriate {@link io.grpc.DecompressorRegistry} * on the {@link io.grpc.ManagedChannelBuilder}. * + * @since 1.0.0 * @param compressorName the name (e.g. "gzip") of the compressor to use. */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1704") @@ -135,7 +146,13 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Returns a new stub that uses the given channel. + * + * <p>This method is vestigial and is unlikely to be useful. Instead, users should prefer to + * use {@link #withInterceptors}. + * + * @since 1.0.0 */ + @Deprecated // use withInterceptors() instead public final S withChannel(Channel newChannel) { return build(newChannel, callOptions); } @@ -143,6 +160,8 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Sets a custom option to be passed to client interceptors on the channel * {@link io.grpc.ClientInterceptor} via the CallOptions parameter. + * + * @since 1.0.0 * @param key the option being set * @param value the value for the key */ @@ -153,6 +172,8 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Returns a new stub that has the given interceptors attached to the underlying channel. + * + * @since 1.0.0 */ public final S withInterceptors(ClientInterceptor... interceptors) { return build(ClientInterceptors.intercept(channel, interceptors), callOptions); @@ -160,6 +181,8 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Returns a new stub that uses the given call credentials. + * + * @since 1.0.0 */ @ExperimentalApi("https//github.com/grpc/grpc-java/issues/1914") public final S withCallCredentials(CallCredentials credentials) { @@ -168,6 +191,8 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Returns a new stub that uses the 'wait for ready' call option. + * + * @since 1.1.0 */ public final S withWaitForReady() { return build(channel, callOptions.withWaitForReady()); @@ -177,6 +202,8 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { * Returns a new stub that limits the maximum acceptable message size from a remote peer. * * <p>If unset, the {@link ManagedChannelBuilder#maxInboundMessageSize(int)} limit is used. + * + * @since 1.1.0 */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563") public final S withMaxInboundMessageSize(int maxSize) { @@ -185,6 +212,8 @@ public abstract class AbstractStub<S extends AbstractStub<S>> { /** * Returns a new stub that limits the maximum acceptable message size to send a remote peer. + * + * @since 1.1.0 */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563") public final S withMaxOutboundMessageSize(int maxSize) { |