Package io.grpc.stub

Class AbstractStub<S extends AbstractStub<S>>

java.lang.Object
io.grpc.stub.AbstractStub<S>
Type Parameters:
S - the concrete type of this stub.
Direct Known Subclasses:
AbstractAsyncStub, AbstractBlockingStub, AbstractFutureStub
@ThreadSafe @CheckReturnValue public abstract class AbstractStub<S extends AbstractStub<S>> extends Object
Common base type for stub implementations. Stub configuration is immutable; changing the configuration returns a new stub with updated configuration. Changing the configuration is cheap and may be done before every RPC, such as would be common when using withDeadlineAfter(long, java.util.concurrent.TimeUnit).

Configuration is stored in CallOptions and is passed to the Channel when performing an RPC.

DO NOT MOCK: Customizing options doesn't work properly in mocks. Use InProcessChannelBuilder to create a real channel suitable for testing. It is also possible to mock Channel instead.

Since:
1.0.0

  • Constructor Details

    • AbstractStub

      protected AbstractStub(Channel channel)
      Constructor for use by subclasses, with the default CallOptions.
      Parameters:
      channel - the channel that this stub will use to do communications
      Since:
      1.0.0

    • AbstractStub

      protected AbstractStub(Channel channel, CallOptions callOptions)
      Constructor for use by subclasses.
      Parameters:
      channel - the channel that this stub will use to do communications
      callOptions - the runtime call options to be applied to every call on this stub
      Since:
      1.0.0

  • Method Details

    • getChannel

      public final Channel getChannel()
      The underlying channel of the stub.
      Since:
      1.0.0

    • getCallOptions

      public final CallOptions getCallOptions()
      The CallOptions of the stub.
      Since:
      1.0.0

    • build

      protected abstract S build(Channel channel, CallOptions callOptions)
      Returns a new stub with the given channel for the provided method configurations.
      Parameters:
      channel - the channel that this stub will use to do communications
      callOptions - the runtime call options to be applied to every call on this stub
      Since:
      1.0.0

    • newStub

      public static <T extends AbstractStub<T>> T newStub(AbstractStub.StubFactory<T> factory, Channel channel)
      Returns a new stub with the given channel for the provided method configurations.
      Parameters:
      factory - the factory to create a stub
      channel - the channel that this stub will use to do communications
      Since:
      1.26.0

    • newStub

      public static <T extends AbstractStub<T>> T newStub(AbstractStub.StubFactory<T> factory, Channel channel, CallOptions callOptions)
      Returns a new stub with the given channel for the provided method configurations.
      Parameters:
      factory - the factory to create a stub
      channel - the channel that this stub will use to do communications
      callOptions - the runtime call options to be applied to every call on this stub
      Since:
      1.26.0

    • withDeadline

      public final S withDeadline(@Nullable Deadline deadline)
      Returns a new stub with an absolute deadline.

      This is mostly used for propagating an existing deadline. withDeadlineAfter(long, java.util.concurrent.TimeUnit) is the recommended way of setting a new deadline,

      Parameters:
      deadline - the deadline or null for unsetting the deadline.
      Since:
      1.0.0

    • withDeadlineAfter

      public final S withDeadlineAfter(long duration, TimeUnit unit)
      Returns a new stub with a deadline that is after the given duration from now.
      Since:
      1.0.0
      See Also:

    • withDeadlineAfter

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/11657") public final S withDeadlineAfter(Duration duration)

    • withExecutor

      public final S withExecutor(Executor executor)
      Returns a new stub with the given executor that is to be used instead of the default one specified with ManagedChannelBuilder.executor(java.util.concurrent.Executor). Note that setting this option may not take effect for blocking calls.
      Since:
      1.8.0

    • withCompression

      public final S withCompression(String compressorName)
      Set's the compressor name to use for the call. It is the responsibility of the application to make sure the server supports decoding the compressor picked by the client. To be clear, this is the compressor used by the stub to compress messages to the server.
      Parameters:
      compressorName - the name (e.g. "gzip") of the compressor to use.
      Since:
      1.0.0

    • withChannel

      @Deprecated public final S withChannel(Channel newChannel)
      Deprecated.
      Returns a new stub that uses the given channel.

      This method is vestigial and is unlikely to be useful. Instead, users should prefer to use withInterceptors(io.grpc.ClientInterceptor...).

      Since:
      1.0.0

    • withOption

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1869") public final <T> S withOption(CallOptions.Key<T> key, T value)
      Sets a custom option to be passed to client interceptors on the channel ClientInterceptor via the CallOptions parameter.
      Parameters:
      key - the option being set
      value - the value for the key
      Since:
      1.0.0

    • withInterceptors

      public final S withInterceptors(ClientInterceptor... interceptors)
      Returns a new stub that has the given interceptors attached to the underlying channel.
      Since:
      1.0.0

    • withCallCredentials

      public final S withCallCredentials(CallCredentials credentials)
      Returns a new stub that uses the given call credentials.
      Since:
      1.0.0

    • withWaitForReady

      public final S withWaitForReady()
      Returns a new stub that uses 'wait for ready' for the call. Wait-for-ready queues the RPC until a connection is available. This may dramatically increase the latency of the RPC, but avoids failing "unnecessarily." The default queues the RPC until an attempt to connect has completed, but fails RPCs without sending them if unable to connect.
      Since:
      1.1.0

    • withMaxInboundMessageSize

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563") public final S withMaxInboundMessageSize(int maxSize)
      Returns a new stub that limits the maximum acceptable message size from a remote peer.

      If unset, the ManagedChannelBuilder.maxInboundMessageSize(int) limit is used.

      Since:
      1.1.0

    • withMaxOutboundMessageSize

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563") public final S withMaxOutboundMessageSize(int maxSize)
      Returns a new stub that limits the maximum acceptable message size to send a remote peer.
      Since:
      1.1.0

    • withOnReadyThreshold

      @ExperimentalApi("https://github.com/grpc/grpc-java/issues/11021") public final S withOnReadyThreshold(int numBytes)
      Returns a new stub that limits the maximum number of bytes per stream in the queue.
      Since:
      1.1.0