Package io.grpc

Class CallOptions

  • @Immutable
@CheckReturnValue
public final class CallOptions
extends java.lang.Object
    The collection of runtime options for a new RPC call.

    A field that is not set is null.

    • Field Detail

      • DEFAULT

        public static final CallOptions DEFAULT
        A blank CallOptions that all fields are not set.

      • deadline

        @Nullable
private final Deadline deadline

      • executor

        @Nullable
private final java.util.concurrent.Executor executor

      • authority

        @Nullable
private final java.lang.String authority

      • compressorName

        @Nullable
private final java.lang.String compressorName

      • customOptions

        private final java.lang.Object[][] customOptions

      • waitForReady

        @Nullable
private final java.lang.Boolean waitForReady
        Opposite to fail fast.

      • maxInboundMessageSize

        @Nullable
private final java.lang.Integer maxInboundMessageSize

      • maxOutboundMessageSize

        @Nullable
private final java.lang.Integer maxOutboundMessageSize

      • onReadyThreshold

        @Nullable
private final java.lang.Integer onReadyThreshold

    • Method Detail

      • withAuthority

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1767")
public CallOptions withAuthority​(@Nullable
                                 java.lang.String authority)
        Override the HTTP/2 authority the channel claims to be connecting to. This is not generally safe. Overriding allows advanced users to re-use a single Channel for multiple services, even if those services are hosted on different domain names. That assumes the server is virtually hosting multiple domains and is guaranteed to continue doing so. It is rare for a service provider to make such a guarantee. At this time, there is no security verification of the overridden value, such as making sure the authority matches the server's TLS certificate.

      • withCallCredentials

        public CallOptions withCallCredentials​(@Nullable
                                       CallCredentials credentials)
        Returns a new CallOptions with the given call credentials.

      • withCompression

        public CallOptions withCompression​(@Nullable
                                   java.lang.String compressorName)
        Sets the compression to use for the call. The compressor must be a valid name known in the CompressorRegistry. By default, the "gzip" compressor will be available.

        It is only safe to call this if the server supports the compression format chosen. There is no negotiation performed; if the server does not support the compression chosen, the call will fail.

      • withDeadline

        public CallOptions withDeadline​(@Nullable
                                Deadline deadline)
        Returns a new CallOptions with the given 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.

      • withDeadlineAfter

        public CallOptions withDeadlineAfter​(long duration,
                                     java.util.concurrent.TimeUnit unit)
        Returns a new CallOptions with a deadline that is after the given duration from now.

      • getDeadline

        @Nullable
public Deadline getDeadline()
        Returns the deadline or null if the deadline is not set.

      • withWaitForReady

        public CallOptions withWaitForReady()
        Enables '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.

      • withoutWaitForReady

        public CallOptions withoutWaitForReady()
        Disables 'wait for ready' feature for the call. This method should be rarely used because the default is without 'wait for ready'.

      • withOnReadyThreshold

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/11021")
public CallOptions withOnReadyThreshold​(int numBytes)
        Specifies how many bytes must be queued before the call is considered not ready to send more messages.
        Parameters:
        numBytes - The number of bytes that must be queued. Must be a positive integer.

      • clearOnReadyThreshold

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/11021")
public CallOptions clearOnReadyThreshold()
        Resets to the default number of bytes that must be queued before the call will leave the 'wait for ready' state.

      • getOnReadyThreshold

        @Nullable
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/11021")
public java.lang.Integer getOnReadyThreshold()
        Returns to the default number of bytes that must be queued before the call will leave the 'wait for ready' state.
        Returns:
        null if the default threshold is used.

      • getCompressor

        @Nullable
public java.lang.String getCompressor()
        Returns the compressor's name.

      • getAuthority

        @Nullable
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/1767")
public java.lang.String getAuthority()
        Override the HTTP/2 authority the channel claims to be connecting to. This is not generally safe. Overriding allows advanced users to re-use a single Channel for multiple services, even if those services are hosted on different domain names. That assumes the server is virtually hosting multiple domains and is guaranteed to continue doing so. It is rare for a service provider to make such a guarantee. At this time, there is no security verification of the overridden value, such as making sure the authority matches the server's TLS certificate.

      • getCredentials

        @Nullable
public CallCredentials getCredentials()
        Returns the call credentials.

      • withStreamTracerFactory

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2861")
public CallOptions withStreamTracerFactory​(ClientStreamTracer.Factory factory)
        Returns a new CallOptions with a ClientStreamTracerFactory in addition to the existing factories.

        This method doesn't replace existing factories, or try to de-duplicate factories.

      • getStreamTracerFactories

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2861")
public java.util.List<ClientStreamTracer.Factory> getStreamTracerFactories()
        Returns an immutable list of ClientStreamTracerFactorys.

      • withOption

        public <T> CallOptions withOption​(CallOptions.Key<T> key,
                                  T value)
        Sets a custom option. Any existing value for the key is overwritten.
        Parameters:
        key - The option key
        value - The option value.
        Since:
        1.13.0

      • getOption

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/1869")
public <T> T getOption​(CallOptions.Key<T> key)
        Get the value for a custom option or its inherent default.
        Parameters:
        key - Key identifying option

      • getExecutor

        @Nullable
public java.util.concurrent.Executor getExecutor()
        Returns the executor override to use for this specific call, or null if there is no override. The executor is only for servicing this one call, so is not safe to use after ClientCall.Listener.onClose(io.grpc.Status, io.grpc.Metadata).

      • isWaitForReady

        public boolean isWaitForReady()
        Returns whether 'wait for ready' option is enabled for the call. 'Fail fast' is the default option for gRPC calls and 'wait for ready' is the opposite to it.

      • getWaitForReady

        java.lang.Boolean getWaitForReady()

      • withMaxOutboundMessageSize

        @ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563")
public CallOptions withMaxOutboundMessageSize​(int maxSize)
        Sets the maximum allowed message size acceptable sent to the remote peer.

      • getMaxInboundMessageSize

        @Nullable
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563")
public java.lang.Integer getMaxInboundMessageSize()
        Gets the maximum allowed message size acceptable from the remote peer.

      • getMaxOutboundMessageSize

        @Nullable
@ExperimentalApi("https://github.com/grpc/grpc-java/issues/2563")
public java.lang.Integer getMaxOutboundMessageSize()
        Gets the maximum allowed message size acceptable to send the remote peer.

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object