Interface ApiCallContext (2.58.0) 

public interface ApiCallContext extends RetryingContext

Context for an API call.

An API call can be composed of many RPCs (in case of retries). This class contains settings for both: API calls and RPCs.

Implementations need to be immutable because default instances are stored in callable objects.

This is transport specific and each transport has an implementation with its own options.

Implements

RetryingContext

Methods

<T>getOption(ApiCallContext.Key<T> key)

public abstract T <T>getOption(ApiCallContext.Key<T> key)

Return the api call context option set for this context.

Parameter
Name Description
key Key<T>
Returns
Type Description
T

<T>withOption(ApiCallContext.Key<T> key, T value)

public abstract ApiCallContext <T>withOption(ApiCallContext.Key<T> key, T value)

Return a new ApiCallContext with additional option merged into the present instance. Any existing value of the key is overwritten.

Parameters
Name Description
key Key<T>
value T
Returns
Type Description
ApiCallContext

getExtraHeaders()

public abstract Map<String,List<String>> getExtraHeaders()

Return the extra headers set for this context.

Returns
Type Description
Map<String,List<String>>

getStreamIdleTimeout()

public abstract Duration getStreamIdleTimeout()

This method is obsolete. Use #getStreamIdleTimeoutDuration() instead.

Returns
Type Description
org.threeten.bp.Duration

getStreamIdleTimeoutDuration()

public abstract Duration getStreamIdleTimeoutDuration()

The stream idle timeout set for this context. See Also: #withStreamIdleTimeoutDuration(java.time.Duration)

Returns
Type Description
Duration

getStreamWaitTimeout()

public abstract Duration getStreamWaitTimeout()

This method is obsolete. Use #getStreamWaitTimeoutDuration() instead.

Returns
Type Description
org.threeten.bp.Duration

getStreamWaitTimeoutDuration()

public abstract Duration getStreamWaitTimeoutDuration()

Return the stream wait timeout set for this context. See Also: #withStreamWaitTimeoutDuration(java.time.Duration)

Returns
Type Description
Duration

getTimeout()

public abstract Duration getTimeout()

This method is obsolete. Use #getTimeoutDuration() instead.

Returns
Type Description
org.threeten.bp.Duration

getTimeoutDuration()

public abstract Duration getTimeoutDuration()

Returns the configured per-RPC timeout.

Returns
Type Description
Duration

getTracer()

public abstract ApiTracer getTracer()

The ApiTracer that was previously set for this context.

The ApiTracer will be used to trace the current operation and to annotate various events like retries.

Returns
Type Description
ApiTracer

merge(ApiCallContext inputCallContext)

public abstract ApiCallContext merge(ApiCallContext inputCallContext)

For any values in inputCallContext that are not null, override the corresponding values in the present instance.

Parameter
Name Description
inputCallContext ApiCallContext
Returns
Type Description
ApiCallContext

nullToSelf(ApiCallContext inputContext)

public abstract ApiCallContext nullToSelf(ApiCallContext inputContext)

If inputContext is not null, returns it; if it is null, returns the present instance.

Parameter
Name Description
inputContext ApiCallContext
Returns
Type Description
ApiCallContext

withCredentials(Credentials credentials)

public abstract ApiCallContext withCredentials(Credentials credentials)

Returns a new ApiCallContext with the given credentials set.

Parameter
Name Description
credentials com.google.auth.Credentials
Returns
Type Description
ApiCallContext

withEndpointContext(EndpointContext endpointContext)

public abstract ApiCallContext withEndpointContext(EndpointContext endpointContext)

Returns a new ApiCallContext with the given Endpoint Context.

Parameter
Name Description
endpointContext EndpointContext
Returns
Type Description
ApiCallContext

withExtraHeaders(Map<String,List<String>> extraHeaders)

public abstract ApiCallContext withExtraHeaders(Map<String,List<String>> extraHeaders)

Return a new ApiCallContext with the extraHeaders merged into the present instance.

Parameter
Name Description
extraHeaders Map<String,List<String>>
Returns
Type Description
ApiCallContext

withRetrySettings(RetrySettings retrySettings)

public abstract ApiCallContext withRetrySettings(RetrySettings retrySettings)

Returns a new ApiCallContext with the given RetrySettings set.

This sets the RetrySettings to use for the RPC. These settings will work in combination with either the default retryable codes for the RPC, or the retryable codes supplied through #withRetryableCodes(Set). Calling #withRetrySettings(RetrySettings) on an RPC that does not include Code#DEADLINE_EXCEEDED as one of its retryable codes (or without calling #withRetryableCodes(Set) with a set that includes at least Code#DEADLINE_EXCEEDED) will effectively only set a single timeout that is equal to RetrySettings#getInitialRpcTimeout(). If this timeout is exceeded, the RPC will not be retried and will fail with Code#DEADLINE_EXCEEDED.

Example usage:


 ApiCallContext context = GrpcCallContext.createDefault()
   .withRetrySettings(RetrySettings.newBuilder()
     .setInitialRetryDelay(Duration.ofMillis(10L))
     .setInitialRpcTimeout(Duration.ofMillis(100L))
     .setMaxAttempts(10)
     .setMaxRetryDelay(Duration.ofSeconds(10L))
     .setMaxRpcTimeout(Duration.ofSeconds(30L))
     .setRetryDelayMultiplier(1.4)
     .setRpcTimeoutMultiplier(1.5)
     .setTotalTimeout(Duration.ofMinutes(10L))
     .build())
   .withRetryableCodes(Sets.newSet(
     StatusCode.Code.UNAVAILABLE,
     StatusCode.Code.DEADLINE_EXCEEDED));

Setting a logical call timeout for the context can be done similarly with RetrySettings.Builder#setLogicalTimeout(java.time.Duration timeout).

Example usage:


 ApiCallContext context = GrpcCallContext.createDefault()
   .withRetrySettings(RetrySettings.newBuilder()
     .setInitialRetryDelay(Duration.ofMillis(10L))
     .setMaxRetryDelay(Duration.ofSeconds(10L))
     .setRetryDelayMultiplier(1.4)
     .setMaxAttempts(10)
     .setLogicalTimeout(Duration.ofSeconds(30L))
     .build());
Parameter
Name Description
retrySettings RetrySettings
Returns
Type Description
ApiCallContext

withRetryableCodes(Set<StatusCode.Code> retryableCodes)

public abstract ApiCallContext withRetryableCodes(Set<StatusCode.Code> retryableCodes)

Returns a new ApiCallContext with the given retryable codes set.

This sets the retryable codes to use for the RPC. These settings will work in combination with either the default RetrySettings for the RPC, or the RetrySettings supplied through #withRetrySettings(RetrySettings).

Setting a non-empty set of retryable codes for an RPC that is not already retryable by default, will not have any effect and the RPC will NOT be retried. This option can only be used to change which codes are considered retryable for an RPC that already has at least one retryable code in its default settings.

Parameter
Name Description
retryableCodes Set<Code>
Returns
Type Description
ApiCallContext

withStreamIdleTimeout(Duration streamIdleTimeout)

public abstract ApiCallContext withStreamIdleTimeout(Duration streamIdleTimeout)

This method is obsolete. Use #withStreamIdleTimeoutDuration(java.time.Duration) instead.

Parameter
Name Description
streamIdleTimeout org.threeten.bp.Duration
Returns
Type Description
ApiCallContext

withStreamIdleTimeoutDuration(Duration streamIdleTimeout)

public abstract ApiCallContext withStreamIdleTimeoutDuration(Duration streamIdleTimeout)

Returns a new ApiCallContext with the given stream idle timeout set.

This timeout only applies to a ServerStreamingCallables. It limits the maximum amount of timeout that can pass between a message being received by ResponseObserver#onResponse(Object) and demand being signaled via StreamController#request(int). Please note that this timeout is best effort and the maximum resolution configured in StubSettings#getStreamWatchdogCheckIntervalDuration(). This is useful to clean up streams that were partially read but never closed. When the timeout has been reached, the stream will be closed with a nonretryable WatchdogTimeoutException and a status of StatusCode.Code#ABORTED.

A value of java.time.Duration#ZERO, disables the streaming idle timeout and a null value will use the default in the callable.

Please note that this timeout is best effort and the maximum resolution is configured in StubSettings#getStreamWatchdogCheckIntervalDuration().

Parameter
Name Description
streamIdleTimeout Duration
Returns
Type Description
ApiCallContext

withStreamWaitTimeout(Duration streamWaitTimeout)

public abstract ApiCallContext withStreamWaitTimeout(Duration streamWaitTimeout)

This method is obsolete. Use #withStreamWaitTimeoutDuration(java.time.Duration) instead.

Parameter
Name Description
streamWaitTimeout org.threeten.bp.Duration
Returns
Type Description
ApiCallContext

withStreamWaitTimeoutDuration(Duration streamWaitTimeout)

public abstract ApiCallContext withStreamWaitTimeoutDuration(Duration streamWaitTimeout)

Returns a new ApiCallContext with the given stream timeout set.

This timeout only applies to a ServerStreamingCallables. It limits the maximum amount of time that can pass between demand being signaled via StreamController#request(int) and actual message delivery to ResponseObserver#onResponse(Object). Or, in the case of automatic flow control, since the last message was delivered to ResponseObserver#onResponse(Object). This is useful to detect server or connection stalls. When the timeout has been reached, the stream will be closed with a retryable WatchdogTimeoutException and a status of StatusCode.Code#ABORTED.

A value of java.time.Duration#ZERO, disables the streaming wait timeout and a null value will use the default in the callable.

Please note that this timeout is best effort and the maximum resolution is configured in StubSettings#getStreamWatchdogCheckIntervalDuration().

Parameter
Name Description
streamWaitTimeout Duration
Returns
Type Description
ApiCallContext

withTimeout(Duration timeout)

public abstract ApiCallContext withTimeout(Duration timeout)

This method is obsolete. Use #withTimeoutDuration(java.time.Duration) instead.

Parameter
Name Description
timeout org.threeten.bp.Duration
Returns
Type Description
ApiCallContext

withTimeoutDuration(Duration timeout)

public abstract ApiCallContext withTimeoutDuration(Duration timeout)

Returns a new ApiCallContext with the given timeout set.

This sets the maximum amount of time a single unary RPC attempt can take. If retries are enabled, then this can take much longer, as each RPC attempt will have the same constant timeout. Unlike a deadline, timeouts are relative durations that are measure from the beginning of each RPC attempt. Please note that this limits the duration of a server streaming RPC as well.

If a method has default com.google.api.gax.retrying.RetrySettings, the max attempts and/or total timeout is still respected when scheduling each RPC attempt.

Parameter
Name Description
timeout Duration
Returns
Type Description
ApiCallContext

withTracer(ApiTracer tracer)

public abstract ApiCallContext withTracer(ApiTracer tracer)

Returns a new ApiCallContext with the given ApiTracer.

The ApiTracer will be used to trace the current operation and to annotate various events like retries.

Parameter
Name Description
tracer ApiTracer

the ApiTracer to set.
Returns
Type Description
ApiCallContext

withTransportChannel(TransportChannel channel)

public abstract ApiCallContext withTransportChannel(TransportChannel channel)

Returns a new ApiCallContext with the given channel set.

Parameter
Name Description
channel TransportChannel
Returns
Type Description
ApiCallContext