Package com.google.api.gax.rpc

Interface ApiCallContext

All Superinterfaces:

RetryingContext

@InternalExtensionOnly
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.

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static final class	ApiCallContext.Key<T>	Key for api call context options key-value pair.

Method Summary

Modifier and Type	Method	Description
Map<String,List<String>>	getExtraHeaders()	Return the extra headers set for this context.
<T> T	getOption(ApiCallContext.Key<T> key)	Return the api call context option set for this context.
org.threeten.bp.Duration	getStreamIdleTimeout()	This method is obsolete.
Duration	getStreamIdleTimeoutDuration()	The stream idle timeout set for this context.
org.threeten.bp.Duration	getStreamWaitTimeout()	This method is obsolete.
Duration	getStreamWaitTimeoutDuration()	Return the stream wait timeout set for this context.
org.threeten.bp.Duration	getTimeout()	This method is obsolete.
Duration	getTimeoutDuration()	Returns the configured per-RPC timeout.
ApiTracer	getTracer()	The ApiTracer that was previously set for this context.
ApiCallContext	merge(ApiCallContext inputCallContext)	For any values in inputCallContext that are not null, override the corresponding values in the present instance.
ApiCallContext	nullToSelf(ApiCallContext inputContext)	If inputContext is not null, returns it; if it is null, returns the present instance.
ApiCallContext	withCredentials(com.google.auth.Credentials credentials)	Returns a new ApiCallContext with the given credentials set.
ApiCallContext	withEndpointContext(EndpointContext endpointContext)	Returns a new ApiCallContext with the given Endpoint Context.
ApiCallContext	withExtraHeaders(Map<String,List<String>> extraHeaders)	Return a new ApiCallContext with the extraHeaders merged into the present instance.
<T> ApiCallContext	withOption(ApiCallContext.Key<T> key, T value)	Return a new ApiCallContext with additional option merged into the present instance.
ApiCallContext	withRetryableCodes(Set<StatusCode.Code> retryableCodes)	Returns a new ApiCallContext with the given retryable codes set.
ApiCallContext	withRetrySettings(RetrySettings retrySettings)	Returns a new ApiCallContext with the given RetrySettings set.
ApiCallContext	withStreamIdleTimeout(org.threeten.bp.Duration streamIdleTimeout)	This method is obsolete.
ApiCallContext	withStreamIdleTimeoutDuration(Duration streamIdleTimeout)	Returns a new ApiCallContext with the given stream idle timeout set.
ApiCallContext	withStreamWaitTimeout(org.threeten.bp.Duration streamWaitTimeout)	This method is obsolete.
ApiCallContext	withStreamWaitTimeoutDuration(Duration streamWaitTimeout)	Returns a new ApiCallContext with the given stream timeout set.
ApiCallContext	withTimeout(org.threeten.bp.Duration timeout)	This method is obsolete.
ApiCallContext	withTimeoutDuration(Duration timeout)	Returns a new ApiCallContext with the given timeout set.
ApiCallContext	withTracer(ApiTracer tracer)	Returns a new ApiCallContext with the given ApiTracer.
ApiCallContext	withTransportChannel(TransportChannel channel)	Returns a new ApiCallContext with the given channel set.

Methods inherited from interface com.google.api.gax.retrying.RetryingContext

getRetryableCodes, getRetrySettings

Method Details

withCredentials

ApiCallContext withCredentials(com.google.auth.Credentials credentials)

Returns a new ApiCallContext with the given credentials set.

withTransportChannel

ApiCallContext withTransportChannel(TransportChannel channel)

Returns a new ApiCallContext with the given channel set.

withEndpointContext

ApiCallContext withEndpointContext(EndpointContext endpointContext)

Returns a new ApiCallContext with the given Endpoint Context.

withTimeout

@ObsoleteApi("Use withTimeoutDuration(java.time.Duration) instead")
ApiCallContext withTimeout(@Nullable
 org.threeten.bp.Duration timeout)

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

withTimeoutDuration

ApiCallContext withTimeoutDuration(@Nullable
 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 RetrySettings, the max attempts and/or total timeout is still respected when scheduling each RPC attempt.

getTimeout

@Nullable
@ObsoleteApi("Use getTimeoutDuration() instead")
org.threeten.bp.Duration getTimeout()

This method is obsolete. Use getTimeoutDuration() instead.

getTimeoutDuration

@Nullable
Duration getTimeoutDuration()

Returns the configured per-RPC timeout.

withStreamWaitTimeout

@ObsoleteApi("Use withStreamWaitTimeoutDuration(java.time.Duration) instead")
ApiCallContext withStreamWaitTimeout(@Nullable
 org.threeten.bp.Duration streamWaitTimeout)

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

withStreamWaitTimeoutDuration

ApiCallContext withStreamWaitTimeoutDuration(@Nullable
 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 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().

getStreamWaitTimeout

@Nullable
@ObsoleteApi("Use getStreamWaitTimeoutDuration() instead")
org.threeten.bp.Duration getStreamWaitTimeout()

This method is obsolete. Use getStreamWaitTimeoutDuration() instead.

getStreamWaitTimeoutDuration

@Nullable
Duration getStreamWaitTimeoutDuration()

Return the stream wait timeout set for this context.

See Also:

• withStreamWaitTimeoutDuration(java.time.Duration)

withStreamIdleTimeout

@ObsoleteApi("Use withStreamIdleTimeoutDuration(java.time.Duration) instead")
ApiCallContext withStreamIdleTimeout(@Nullable
 org.threeten.bp.Duration streamIdleTimeout)

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

withStreamIdleTimeoutDuration

ApiCallContext withStreamIdleTimeoutDuration(@Nullable
 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 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().

getStreamIdleTimeout

@Nullable
@ObsoleteApi("Use getStreamIdleTimeoutDuration() instead")
org.threeten.bp.Duration getStreamIdleTimeout()

This method is obsolete. Use getStreamIdleTimeoutDuration() instead.

getStreamIdleTimeoutDuration

@Nullable
Duration getStreamIdleTimeoutDuration()

The stream idle timeout set for this context.

See Also:

• withStreamIdleTimeoutDuration(java.time.Duration)

getTracer

@BetaApi("The surface for tracing is not stable yet and may change in the future")
@Nonnull
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.

Specified by:

getTracer in interface RetryingContext

withTracer

@BetaApi("The surface for tracing is not stable yet and may change in the future")
ApiCallContext withTracer(@Nonnull
 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.

Parameters:

tracer - the ApiTracer to set.

withRetrySettings

@BetaApi
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 StatusCode.Code.DEADLINE_EXCEEDED as one of its retryable codes (or without calling withRetryableCodes(Set) with a set that includes at least StatusCode.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 StatusCode.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());
 

withRetryableCodes

@BetaApi
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.

nullToSelf

ApiCallContext nullToSelf(ApiCallContext inputContext)

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

merge

ApiCallContext merge(ApiCallContext inputCallContext)

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

withExtraHeaders

@BetaApi("The surface for extra headers is not stable yet and may change in the future.")
ApiCallContext withExtraHeaders(Map<String,List<String>> extraHeaders)

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

getExtraHeaders

@BetaApi("The surface for extra headers is not stable yet and may change in the future.")
Map<String,List<String>> getExtraHeaders()

Return the extra headers set for this context.

withOption

@BetaApi("The surface for call context options is not stable yet and may change in the future.")
<T> ApiCallContext 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.

getOption

@BetaApi("The surface for call context options is not stable yet and may change in the future.")
<T> T getOption(ApiCallContext.Key<T> key)

Return the api call context option set for this context.