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 java.lang.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 Summary

      Constructors 
      Modifier Constructor Description
      protected AbstractStub​(io.grpc.Channel channel)
      Constructor for use by subclasses, with the default CallOptions.
      protected AbstractStub​(io.grpc.Channel channel, io.grpc.CallOptions callOptions)
      Constructor for use by subclasses.

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      protected abstract S build​(io.grpc.Channel channel, io.grpc.CallOptions callOptions)
      Returns a new stub with the given channel for the provided method configurations.
      io.grpc.CallOptions getCallOptions()
      The CallOptions of the stub.
      io.grpc.Channel getChannel()
      The underlying channel of the stub.
      static <T extends AbstractStub<T>>
      T      		 newStub​(AbstractStub.StubFactory<T> factory, io.grpc.Channel channel)
      Returns a new stub with the given channel for the provided method configurations.
      static <T extends AbstractStub<T>>
      T      		 newStub​(AbstractStub.StubFactory<T> factory, io.grpc.Channel channel, io.grpc.CallOptions callOptions)
      Returns a new stub with the given channel for the provided method configurations.
      S withCallCredentials​(io.grpc.CallCredentials credentials)
      Returns a new stub that uses the given call credentials.
      S withChannel​(io.grpc.Channel newChannel)
      Deprecated.
      S withCompression​(java.lang.String compressorName)
      Set's the compressor name to use for the call.
      S withDeadline​(io.grpc.Deadline deadline)
      Returns a new stub with an absolute deadline.
      S withDeadlineAfter​(long duration, java.util.concurrent.TimeUnit unit)
      Returns a new stub with a deadline that is after the given duration from now.
      S withExecutor​(java.util.concurrent.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).
      S withInterceptors​(io.grpc.ClientInterceptor... interceptors)
      Returns a new stub that has the given interceptors attached to the underlying channel.
      S withMaxInboundMessageSize​(int maxSize)
      Returns a new stub that limits the maximum acceptable message size from a remote peer.
      S withMaxOutboundMessageSize​(int maxSize)
      Returns a new stub that limits the maximum acceptable message size to send a remote peer.
      <T> S withOption​(io.grpc.CallOptions.Key<T> key, T value)
      Sets a custom option to be passed to client interceptors on the channel ClientInterceptor via the CallOptions parameter.
      S withWaitForReady()
      Returns a new stub that uses 'wait for ready' for the call.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • AbstractStub

        protected AbstractStub​(io.grpc.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​(io.grpc.Channel channel,
                       io.grpc.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 io.grpc.Channel getChannel()
        The underlying channel of the stub.
        Since:
        1.0.0

      • getCallOptions

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

      • build

        protected abstract S build​(io.grpc.Channel channel,
                           io.grpc.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,
                                                    io.grpc.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,
                                                    io.grpc.Channel channel,
                                                    io.grpc.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
                            io.grpc.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,
                                 java.util.concurrent.TimeUnit unit)
        Returns a new stub with a deadline that is after the given duration from now.
        Since:
        1.0.0
        See Also:
        CallOptions.withDeadlineAfter(long, java.util.concurrent.TimeUnit)

      • withExecutor

        public final S withExecutor​(java.util.concurrent.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​(java.lang.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​(io.grpc.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​(io.grpc.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​(io.grpc.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​(io.grpc.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