Package io.grpc.stub

Class AbstractStub<S extends 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 Detail

      • 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 Detail

      • 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

      • 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

      • 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