Class GrpcCallContext (2.83.0)

2.83.0 (latest) 2.82.0 2.81.0 2.80.0 2.79.0 2.76.0 2.75.0 2.74.1 2.73.1 2.72.2 2.71.0 2.70.3 2.69.0 2.68.2 2.67.0 2.66.0 2.65.0 2.63.1 2.62.0 2.61.0 2.60.0 2.59.1 2.58.0 2.57.0 2.55.0 2.54.1 2.53.0 2.52.0 2.51.0 2.50.0 2.49.0 2.48.1 2.47.0 2.46.1 2.45.0 2.43.0 2.42.0 2.41.0 2.39.0 2.38.0 2.37.0 2.36.0 2.35.0 2.34.1 2.33.0 2.32.1 2.31.1 2.30.1 2.24.0 2.23.3 2.22.0 2.21.0 2.20.1 2.19.6 2.18.7 2.17.0 2.16.0 2.15.0 2.14.0 2.13.0 2.12.2 2.11.0 2.10.0 2.9.0 2.8.1 2.7.1

Beta

This library is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

public final class GrpcCallContext implements ApiCallContext

GrpcCallContext encapsulates context data used to make a grpc call.

GrpcCallContext is immutable in the sense that none of its methods modifies the GrpcCallContext itself or the underlying data. Methods of the form withX, such as #withTransportChannel, return copies of the object, but with one field changed. The immutability and thread safety of the arguments solely depends on the arguments themselves.

Inheritance

java.lang.Object > GrpcCallContext

Implements

ApiCallContext

Inherited Members

Object.clone()

Object.equals(Object)

Object.finalize()

Object.getClass()

Object.hashCode()

Object.notify()

Object.notifyAll()

Object.toString()

Object.wait()

Object.wait(long)

Object.wait(long,int)

Static Fields

TRACER_KEY

public static final CallOptions.Key<ApiTracer> TRACER_KEY

Field Value
Type	Description
io.grpc.CallOptions.Key<ApiTracer>

Static Methods

createDefault()

public static GrpcCallContext createDefault()

Returns an empty instance with a null channel and default CallOptions.

Returns
Type	Description
GrpcCallContext

of(Channel channel, CallOptions callOptions)

public static GrpcCallContext of(Channel channel, CallOptions callOptions)

Returns an instance with the given channel and CallOptions.

Parameters
Name	Description
channel	io.grpc.Channel
callOptions	io.grpc.CallOptions

Returns
Type	Description
GrpcCallContext

Methods

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

public 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 GrpcCallContext <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
GrpcCallContext

equals(@Nullable Object o)

public boolean equals(@Nullable Object o)

Parameter
Name	Description
o	@org.jspecify.annotations.Nullable java.lang.Object

Returns
Type	Description
boolean

Overrides

Object.equals(Object)

getCallOptions()

public CallOptions getCallOptions()

The CallOptions set on this context.

Returns
Type	Description
io.grpc.CallOptions

getChannel()

public @Nullable Channel getChannel()

The Channel set on this context.

Returns
Type	Description
@org.jspecify.annotations.Nullable io.grpc.Channel

getChannelAffinity()

public @Nullable Integer getChannelAffinity()

The channel affinity for this context.

Returns
Type	Description
@org.jspecify.annotations.Nullable java.lang.Integer

getExtraHeaders()

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

Beta

The surface for extra headers is not stable yet and may change in the future.

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

The extra header for this context.

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

getRetrySettings()

public RetrySettings getRetrySettings()

Returns the RetrySettings to use with this context, or null if the default RetrySettings should be used.

Returns
Type	Description
RetrySettings

getRetryableCodes()

public Set<StatusCode.Code> getRetryableCodes()

Returns the retryable codes to use with this context, or null if the default retryable codes should be used.

Returns
Type	Description
Set<Code>

getStreamIdleTimeout()

public @Nullable Duration getStreamIdleTimeout()

Obsolete

Use getStreamIdleTimeoutDuration() instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

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

Returns
Type	Description
@org.jspecify.annotations.Nullable org.threeten.bp.Duration

getStreamIdleTimeoutDuration()

public @Nullable Duration getStreamIdleTimeoutDuration()

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

Returns
Type	Description
@org.jspecify.annotations.Nullable java.time.Duration

getStreamWaitTimeout()

public @Nullable Duration getStreamWaitTimeout()

Obsolete

Use getStreamWaitTimeoutDuration() instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

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

Returns
Type	Description
@org.jspecify.annotations.Nullable org.threeten.bp.Duration

getStreamWaitTimeoutDuration()

public @Nullable Duration getStreamWaitTimeoutDuration()

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

Returns
Type	Description
@org.jspecify.annotations.Nullable java.time.Duration

getTimeout()

public @Nullable Duration getTimeout()

Obsolete

Use getTimeoutDuration() instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

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

Returns
Type	Description
@org.jspecify.annotations.Nullable org.threeten.bp.Duration

getTimeoutDuration()

public @Nullable Duration getTimeoutDuration()

Returns the configured per-RPC timeout.

Returns
Type	Description
@org.jspecify.annotations.Nullable java.time.Duration

getTracer()

public 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

hashCode()

public int hashCode()

Returns
Type	Description
int

Overrides

Object.hashCode()

merge(ApiCallContext inputCallContext)

public 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 GrpcCallContext nullToSelf(ApiCallContext inputContext)

Returns inputContext cast to GrpcCallContext, or an empty GrpcCallContext if inputContext is null.

Parameter
Name	Description
inputContext	ApiCallContext the ApiCallContext to cast if it is not null

Returns
Type	Description
GrpcCallContext

validateUniverseDomain()

public void validateUniverseDomain()

Internal Only: This feature is not stable for application use.

Validate the Universe Domain to ensure that the user configured Universe Domain and the Credentials' Universe Domain match. An exception will be raised if there are any issues when trying to validate (i.e. unable to access the universe domain).

withCallOptions(CallOptions newCallOptions)

public GrpcCallContext withCallOptions(CallOptions newCallOptions)

Returns a new instance with the call options set to the given call options.

Parameter
Name	Description
newCallOptions	io.grpc.CallOptions

Returns
Type	Description
GrpcCallContext

withChannel(@Nullable Channel newChannel)

public GrpcCallContext withChannel(@Nullable Channel newChannel)

Obsolete

Use withTransportChannel() instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

This method is obsolete. Use #withTransportChannel() instead. Returns a new instance with the channel set to the given channel.

Parameter
Name	Description
newChannel	@org.jspecify.annotations.Nullable io.grpc.Channel

Returns
Type	Description
GrpcCallContext

withChannelAffinity(@Nullable Integer affinity)

public GrpcCallContext withChannelAffinity(@Nullable Integer affinity)

Beta

The surface for channel affinity is not stable yet and may change in the future.

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

Parameter
Name	Description
affinity	@org.jspecify.annotations.Nullable java.lang.Integer

Returns
Type	Description
GrpcCallContext

withCredentials(Credentials newCredentials)

public GrpcCallContext withCredentials(Credentials newCredentials)

Returns a new ApiCallContext with the given credentials set.

Parameter
Name	Description
newCredentials	com.google.auth.Credentials

Returns
Type	Description
GrpcCallContext

withEndpointContext(EndpointContext endpointContext)

public GrpcCallContext withEndpointContext(EndpointContext endpointContext)

Returns a new ApiCallContext with the given Endpoint Context.

Parameter
Name	Description
endpointContext	EndpointContext

Returns
Type	Description
GrpcCallContext

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

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

Beta

The surface for extra headers is not stable yet and may change in the future.

This feature is covered by the Pre-GA Offerings Terms of the Terms of Service. Pre-GA libraries might have limited support, and changes to pre-GA libraries might not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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

Parameter
Name	Description
extraHeaders	Map<String,List<String>>

Returns
Type	Description
GrpcCallContext

withRequestParamsDynamicHeaderOption(String requestParams)

public GrpcCallContext withRequestParamsDynamicHeaderOption(String requestParams)

Parameter
Name	Description
requestParams	String

Returns
Type	Description
GrpcCallContext

withRetrySettings(RetrySettings retrySettings)

public GrpcCallContext 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
GrpcCallContext

withRetryableCodes(Set<StatusCode.Code> retryableCodes)

public GrpcCallContext 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
GrpcCallContext

withStreamIdleTimeout(@Nullable Duration streamIdleTimeout)

public GrpcCallContext withStreamIdleTimeout(@Nullable Duration streamIdleTimeout)

Obsolete

Use withStreamIdleTimeoutDuration(java.time.Duration) instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

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

Parameter
Name	Description
streamIdleTimeout	@org.jspecify.annotations.Nullable org.threeten.bp.Duration

Returns
Type	Description
GrpcCallContext

withStreamIdleTimeoutDuration(@Nullable Duration streamIdleTimeout)

public GrpcCallContext 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 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	@org.jspecify.annotations.Nullable java.time.Duration

Returns
Type	Description
GrpcCallContext

withStreamWaitTimeout(@Nullable Duration streamWaitTimeout)

public GrpcCallContext withStreamWaitTimeout(@Nullable Duration streamWaitTimeout)

Obsolete

Use withStreamWaitTimeoutDuration(java.time.Duration) instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

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

Parameter
Name	Description
streamWaitTimeout	@org.jspecify.annotations.Nullable org.threeten.bp.Duration

Returns
Type	Description
GrpcCallContext

withStreamWaitTimeoutDuration(@Nullable Duration streamWaitTimeout)

public GrpcCallContext 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 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	@org.jspecify.annotations.Nullable java.time.Duration

Returns
Type	Description
GrpcCallContext

withTimeout(@Nullable Duration timeout)

public GrpcCallContext withTimeout(@Nullable Duration timeout)

Obsolete

Use withTimeoutDuration(java.time.Duration) instead

This feature is stable for usage in this major version, but may be deprecated in a future release.

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

Parameter
Name	Description
timeout	@org.jspecify.annotations.Nullable org.threeten.bp.Duration

Returns
Type	Description
GrpcCallContext

withTimeoutDuration(@Nullable Duration timeout)

public GrpcCallContext 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 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	@org.jspecify.annotations.Nullable java.time.Duration

Returns
Type	Description
GrpcCallContext

withTracer(ApiTracer tracer)

public GrpcCallContext 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

Returns
Type	Description
GrpcCallContext

withTransportChannel(TransportChannel inputChannel)

public GrpcCallContext withTransportChannel(TransportChannel inputChannel)

Returns a new ApiCallContext with the given channel set.

Parameter
Name	Description
inputChannel	TransportChannel

Returns
Type	Description
GrpcCallContext