Package com.google.api.gax.rpc (2.34.1)

Classes

ApiCallContext.Key<T>

Key for api call context options key-value pair.

ApiClientHeaderProvider

Implementation of HeaderProvider that provides headers describing the API client library making API calls.

ApiClientHeaderProvider.Builder

ApiExceptionFactory

A factory class that returns the corresponding type of exception class from the given status code.

ApiExceptions

A utility class for working with ApiException.

Batch<RequestT,ResponseT>

A Batch contains a collection of requests that are to be batched into a single API call.

A Batch contains a single UnaryCallable object, which will be used to make the API call, and a list of BatchedRequestIssuer objects, which represent the individual requests in the batch.

Additional batches can be merged into an existing batch using the <xref uid="com.google.api.gax.rpc.Batch.merge(com.google.api.gax.rpc.Batch<RequestT,ResponseT>)" data-throw-if-not-resolved="false">#merge(Batch) method. Request objects are combined using a RequestBuilder into a single request.

This is public only for technical reasons, for advanced usage.

BatchedFuture<ResponseT>

An ApiFuture to be used with batching.

This is public only for technical reasons, for advanced usage.

BatchedRequestIssuer<ResponseT>

BatchedRequestIssuer receives a response or an exception and waits to set the given batchedFuture until sendResult() is called.

This class is designed to be used by generated code.

BatcherFactory<RequestT,ResponseT>

A Factory class which, for each unique partitionKey, creates a trio including a ThresholdBatcher, BatchExecutor, and ThresholdBatchingForwarder. The ThresholdBatchingForwarder pulls items from the ThresholdBatcher and forwards them to the BatchExecutor for processing.

This is public only for technical reasons, for advanced usage.

BatchingCallSettings<RequestT,ResponseT>

A settings class to configure a UnaryCallable for calls to an API method that supports batching. The settings are provided using an instance of BatchingSettings.

BatchingCallSettings.Builder<RequestT,ResponseT>

BatchingCallable<RequestT,ResponseT>

A UnaryCallable which will batch requests based on the given BatchingDescriptor and BatcherFactory. The BatcherFactory provides a distinct Batcher for each partition as specified by the BatchingDescriptor. An example of a batching partition would be a pubsub topic.

This is public only for technical reasons, for advanced usage.

BidiStream<RequestT,ResponseT>

A wrapper around a bidirectional stream.

This class asynchronously pulls responses from upstream via StreamController#request(int) and exposes them via its Iterator. The implementation is back pressure aware and uses a constant buffer of 1 item.

Please note that the stream can only be consumed once and must either be fully consumed or be canceled.

This class can also be used to send requests to the server using #send(Object).

Neither this class nor the iterator it returns is thread-safe.

In the example below, we iterate through responses from the server and echo back the items we see:


 BidiStream<Item> stream = ...;

 for (Item item : stream) {
   System.out.println(item.id());

   stream.send(item.id());

   // Allow for early termination
   if (item.id().equals("needle")) {
     // Cancelling the stream will cause hasNext() to return false on the next iteration,
     // naturally breaking the loop.
     stream.cancel();
   }
 }

BidiStreamingCallable<RequestT,ResponseT>

A BidiStreamingCallable is an immutable object which is capable of making RPC calls to bidirectional streaming API methods. Not all transports support streaming.

It is considered advanced usage for a user to create a BidiStreamingCallable themselves. This class is intended to be created by a generated client class, and configured by instances of StreamingCallSettings.Builder which are exposed through the client settings class.

Callables

Class with utility methods to create callable objects using provided settings.

The callable objects wrap a given direct callable with features like retry and exception translation.

ClientContext

Encapsulates client state, including executor, credentials, and transport channel.

Unlike ClientSettings which allows users to configure the client, ClientContext is intended to be used in generated code. Most users will not need to use it.

ClientContext.Builder

ClientSettings<SettingsT>

A base settings class to configure a client class.

This base class includes settings that are applicable to all services, which includes things like settings for creating an executor, credentials, transport-specific settings, and identifiers for http headers.

If no ExecutorProvider is set, then InstantiatingExecutorProvider will be used, which creates a default executor.

ClientSettings.Builder<SettingsT,B>

ClientStreamingCallable<RequestT,ResponseT>

A ClientStreamingCallable is an immutable object which is capable of making RPC calls to client streaming API methods. Not all transports support streaming.

It is considered advanced usage for a user to create a ClientStreamingCallable themselves. This class is intended to be created by a generated client class, and configured by instances of StreamingCallSettings.Builder which are exposed through the client settings class.

ErrorDetails

This class contains a list of standard error messages that returns from server.

ErrorDetails.Builder

FixedHeaderProvider

An instance of HeaderProvider that always provides the same headers.

FixedTransportChannelProvider

An instance of TransportChannelProvider that always provides the same TransportChannel.

FixedWatchdogProvider

A watchdog provider which always returns the same watchdog instance provided to the provider during construction.

This is the internal class and is public only for technical reasons. It may change any time without notice, please do not depend on it explicitly.

InstantiatingWatchdogProvider

A watchdog provider which instantiates a new provider on every request.

This is the internal class and is public only for technical reasons. It may change any time without notice, please do not depend on it explicitly.

NoHeaderProvider

Implementation of HeaderProvider that provides empty headers.

OperationCallSettings<RequestT,ResponseT,MetadataT>

A settings class to configure an OperationCallable for calls to initiate, resume, and cancel a long-running operation.

OperationCallSettings.Builder<RequestT,ResponseT,MetadataT>

OperationCallable<RequestT,ResponseT,MetadataT>

An OperationCallable is an immutable object which is capable of initiating RPC calls to long-running API methods and returning an OperationFuture to manage the polling of the Operation and getting the response.

It is considered advanced usage for a user to create an OperationCallable themselves. This class is intended to be created by a generated client class, and configured by instances of OperationCallSettings.Builder which are exposed through the client settings class.

PageContext<RequestT,ResponseT,ResourceT>

The context for a page call.

PagedCallSettings<RequestT,ResponseT,PagedListResponseT>

A settings class to configure a UnaryCallable for calls to an API method that supports page streaming.

PagedCallSettings.Builder<RequestT,ResponseT,PagedListResponseT>

PagedCallable<RequestT,ResponseT,PagedListResponseT>

A UnaryCallable which provides page streaming functionality for unary calls.

Public for technical reasons - for advanced usage.

RequestParamsBuilder

This builder class builds a request params map that will be used by autogenerated implementation of RequestParamsExtractor.

RequestUrlParamsEncoder<RequestT>

The request params encoder, which encodes URL-encoded parameters in one URL parameters string.

ServerStream<V>

A blocking Iterable-style wrapper around server stream responses.

Please note that the stream can only be consumed once and must either be fully consumed or be canceled.

Neither this class nor the iterator it returns is thread-safe.

Example usage:


 ServerStream<Item> stream = ...;

 for (Item item : stream) {
   System.out.println(item.id());

   // Allow for early termination
   if (item.id().equals("needle")) {
     // Cancelling the stream will cause hasNext() to return false on the next iteration,
     // naturally breaking the loop.
     stream.cancel();
   }
 }

ServerStreamingCallSettings<RequestT,ResponseT>

A settings class to configure a ServerStreamingCallable.

This class includes settings that are applicable to all server streaming calls, which currently just includes retries and watchdog timers.

The watchdog timer is configured via idleTimeout and waitTimeout. The watchdog will terminate any stream that has not has seen any demand (via StreamController#request(int)) in the configured interval or has not seen a message from the server in waitTimeout. To turn off idle checks, set the interval to Duration#ZERO.

Retry configuration allows for the stream to be restarted and resumed. It is composed of 3 parts: the retryable codes, the retry settings and the stream resumption strategy. The retryable codes indicate which codes cause a retry to occur, the retry settings configure the retry logic when the retry needs to happen, and the stream resumption strategy composes the request to resume the stream. To turn off retries, set the retryable codes to the empty set.

The retry settings have slightly different semantics when compared to unary RPCs:

retry delays are reset to the initial value as soon as a response is received.
RPC timeouts are reset to the initial value as soon as a response is received.
RPC timeouts apply to the time interval between caller demanding more responses via StreamController#request(int) and the ResponseObserver receiving the message.
RPC timeouts are best effort and are checked once every StubSettings#getStreamWatchdogCheckInterval().
Attempt counts are reset as soon as a response is received. This means that max attempts is the maximum number of failures in a row.
totalTimeout still applies to the entire stream.

ServerStreamingCallSettings.Builder<RequestT,ResponseT>

ServerStreamingCallable<RequestT,ResponseT>

A ServerStreamingCallable is an immutable object which is capable of making RPC calls to server streaming API methods. Not all transports support streaming.

It is considered advanced usage for a user to create a ServerStreamingCallable themselves. This class is intended to be created by a generated client class, and configured by instances of StreamingCallSettings.Builder which are exposed through the client settings class.

StateCheckingResponseObserver<V>

Base implementation of ResponseObserver that performs state sanity checks.

StreamingCallSettings<RequestT,ResponseT>

A settings class to configure a streaming callable object for calls to a streaming API method.

StreamingCallSettings.Builder<RequestT,ResponseT>

StubSettings<SettingsT>

A base settings class to configure a client stub class.

If no ExecutorProvider is set, then InstantiatingExecutorProvider will be used, which creates a default executor.

StubSettings.Builder<SettingsT,B>

TranslatingUnaryCallable<InnerRequestT,InnerResponseT,OuterRequestT,OuterResponseT>

A UnaryCallable that translates request types and response types using the given transformers.

UnaryCallSettings<RequestT,ResponseT>

A base settings class to configure a UnaryCallable. An instance of UnaryCallSettings is not sufficient on its own to construct a UnaryCallable; a concrete derived type is necessary.

This base class includes settings that are applicable to all calls, which currently is just retry settings.

Retry configuration is composed of two parts: the retryable codes, and the retry settings. The retryable codes indicate which codes cause a retry to occur, and the retry settings configure the retry logic when the retry needs to happen. To turn off retries, set the retryable codes to the empty set.

UnaryCallSettings contains a concrete builder class, UnaryCallSettings.Builder. This builder class cannot be used to create an instance of UnaryCallSettings, because UnaryCallSettings is an abstract class.

UnaryCallSettings.Builder<RequestT,ResponseT>

A base builder class for UnaryCallSettings. This class should not be used to create an instance of the base class UnaryCallSettings. See the class documentation of UnaryCallSettings for a description of the different values that can be set, and for a description of when this builder may be used. Builders for concrete derived classes can be used to create instances of those classes.

UnaryCallable<RequestT,ResponseT>

A UnaryCallable is an immutable object which is capable of making RPC calls to non-streaming API methods.

In typical usage, the request to send to the remote service will not be bound to the UnaryCallable, but instead is provided at call time, which allows for a UnaryCallable to be saved and used indefinitely.

There are two styles of calls that can be made through a UnaryCallable: synchronous and asynchronous.

Synchronous example:


 RequestType request = RequestType.newBuilder().build();
 UnaryCallable<RequestType, ResponseType> unaryCallable = api.doSomethingCallable();
 ResponseType response = unaryCallable.call();

Asynchronous example:


 RequestType request = RequestType.newBuilder().build();
 UnaryCallable<RequestType, ResponseType> unaryCallable = api.doSomethingCallable();
 ApiFuture<ResponseType> resultFuture = unaryCallable.futureCall();
 // do other work
 // ...
 ResponseType response = resultFuture.get();

It is considered advanced usage for a user to create a UnaryCallable themselves. This class is intended to be created by a generated client class, and configured by instances of UnaryCallSettings.Builder which are exposed through the client settings class.

Watchdog

Prevents the streams from hanging indefinitely. This middleware garbage collects idle streams in case the user forgot to close a ServerStream or if a connection is reset and GRPC does not get notified.

For every checkInterval, this class checks two thresholds:

waitingTimeout: the amount of time to wait for a response (after the caller signaled demand) before forcefully closing the stream. Duration.ZERO disables the timeout.
idleTimeout: the amount of time to wait before assuming that the caller forgot to close the stream and forcefully closing the stream. This is measured from the last time the caller had no outstanding demand. Duration.ZERO disables the timeout.

Interfaces

ApiCallContext

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.

ApiStreamObserver<V>

Receives notifications from an observable stream of messages.

It is used for sending messages in bidi (bidirectional) or client-streaming calls, or for receiving messages in bidi or server-streaming calls.

For outgoing messages, an ApiStreamObserver is provided by GAX to the application, and the application then provides the messages to send. For incoming messages, the application implements the ApiStreamObserver and passes it to GAX, which then calls the observer with the messages for the application to receive them.

Implementations are expected to be thread-compatible. Separate ApiStreamObservers do not need to be synchronized together; incoming and outgoing directions are independent. Since individual ApiStreamObservers are not thread-safe, if multiple threads will be writing to a ApiStreamObserver concurrently, the application must synchronize calls.

This interface is a fork of io.grpc.stub.StreamObserver to enable shadowing of Guava, and also to allow for a transport-agnostic interface that doesn't depend on gRPC.

BatchingDescriptor<RequestT,ResponseT>

Interface which represents an object that transforms request/response data for the purposes of batching.

Implementations of BatchingDescriptor must guarantee that all methods are stateless and thread safe.

This class is designed to be used by generated code.

BidiStreamObserver<RequestT,ResponseT>

ClientStream<RequestT>

A wrapper used to send requests to the server.

After sending requests, users must either call #closeSend() or #closeSendWithError(Throwable) on the stream. The error, if any, will be propagated to the server.

Example usage:


 ClientStream<String> stream = ...;
 List<String> lines = getLinesFromFile();
 for (String line : lines) {
   stream.send(line);
 }
 stream.closeSend();

ClientStreamReadyObserver<V>

A callback used to report that the ClientStream is ready to send more messages.

HeaderProvider

Provider of headers to put on http requests.

LongRunningClient

Implementation-agnostic interface for managing long-running operations.

PagedListDescriptor<RequestT,ResponseT,ResourceT>

An interface which provides the functionality to extract data from requests and inject data into requests for the purposes of page streaming.

This class is designed to be used by generated code.

PagedListResponseFactory<RequestT,ResponseT,PagedListResponseT>

Interface for constructing futures which return PagedListResponse objects.

This class is designed to be used by generated code.

RequestParamsEncoder<RequestT>

A request params encoder takes a request object and encodes some (or all) of its parameters in a string form following specific parameter extraction and string encoding rules, defined by concrete implementations of this interface.

RequestParamsExtractor<RequestT>

A request params extractor takes a request message, extracts specific field values from it, converts them in strings and returns them as key-value pairs, where a key is a request field name and a value is a string representation of a field value. Nested fields should also be extractable, in such case the "dot notation" can be used to represent a nested field name, for example "field_name.nested_field_name".

Implementations of this interface are expected to be autogenerated.

ResponseObserver<V>

Receives notifications from server-streaming calls.

The application is responsible for implementing the ResponseObserver and passing it to GAX, which then calls the observer with the messages for the application to receive them. The methods might be called by different threads, but are guaranteed to happen sequentially. The order of callbacks is guaranteed to be:

exactly 1 onStart
0 or more on Response
exactly 1 onError or onComplete

By default, the stream uses automatic flow control, where the next response will be delivered as soon as the current one is processed by onResponse. A consumer can disable automatic flow control by calling disableAutoInboundFlowControl() in onStart. After this, the consumer must request responses by calling request().

StatusCode

Transport-specific status code.

The status codes are modeled after the status codes in grpc. For more information about grpc status codes, see https://github.com/grpc/grpc-java/blob/master/core/src/main/java/io/grpc/Status.java

StreamController

Allows the implementer of ResponseObserver to control the flow of responses.

An instance of this class will be passed to ResponseObserver#onStart(StreamController), at which point the receiver can disable automatic flow control. The receiver can also save a reference to the instance and terminate the stream early using cancel().

TransportChannel

Class whose instances can issue RPCs on a particular transport.

TransportChannelProvider

Provides an interface to either build a TransportChannel or provide a fixed TransportChannel that will be used to make calls to a service.

Implementations of TransportChannelProvider may choose to create a new TransportChannel for each call to #getTransportChannel, or may return a fixed TransportChannel instance.

Callers should use the following pattern to get a channel:


 TransportChannelProvider transportChannelProvider = ...;
 if (transportChannelProvider.needsHeaders()) {
   transportChannelProvider = transportChannelProvider.withHeaders(headers);
 }
 // optional: set executor for TransportChannel
 transportChannelProvider.withExecutor(executor);
 TransportChannel transportChannel = transportChannelProvider.getTransportChannel();

WatchdogProvider

Enums

StatusCode.Code

Exceptions

AbortedException

Exception thrown when the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.

AlreadyExistsException

Exception thrown when some entity that we attempted to create (e.g., file or directory) already exists.

ApiException

Represents an exception thrown during an RPC call.

AsyncTaskException

This exception is used to preserve the caller's stacktrace when invoking an async task in a sync context. It will be added as a suppressed exception when propagating the async exception. This allows callers to catch ApiException thrown in an async operation, while still maintaining the call site.

CancelledException

The exception thrown when the operation was cancelled (typically by the caller).

DataLossException

Exception thrown due to unrecoverable data loss or corruption.

DeadlineExceededException

Exception thrown when deadline expired before operation could complete. For operations that change the state of the system, this error may be returned even if the operation has completed successfully. For example, a successful response from a server could have been delayed long enough for the deadline to expire.

FailedPreconditionException

Exception thrown when the operation was rejected because the system is not in a state required for the operation's execution. For example, directory to be deleted may be non-empty, an rmdir operation is applied to a non-directory, etc.

InternalException

Exception thrown due to internal errors. Means some invariants expected by underlying system has been broken. If you see one of these errors, something is very broken.

InvalidArgumentException

Exception thrown when client specified an invalid argument. Note that this differs from FailedPreconditionException. This exception indicates arguments that are problematic regardless of the state of the system (e.g., a malformed file name).

NotFoundException

Exception thrown when some requested entity (e.g., file or directory) was not found.

OutOfRangeException

Exception thrown when the operation was attempted past the valid range. E.g., seeking or reading past end of file.

PermissionDeniedException

Exception thrown when the caller does not have permission to execute the specified operation.

ProtocolBufferParsingException

Exception thrown when parsing protocol buffer message failed

ResourceExhaustedException

Exception thrown when some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.

UnauthenticatedException

Exception thrown when the request does not have valid authentication credentials for the operation.

UnavailableException

Exception thrown when the service is currently unavailable. This is a most likely a transient condition and may be corrected by retrying with a backoff.

UnimplementedException

Exception thrown when the operation is not implemented or not supported/enabled in this service.

UnknownException

Exception thrown due to an unknown error. An example of where this error may be returned is if a Status value received from another address space belongs to an error-space that is not known in this address space. Also errors raised by APIs that do not return enough error information may be converted to this error.

WatchdogTimeoutException

The marker exception thrown when a timeout is exceeded.

This error can be thrown under 2 circumstances:

A wait timeout has exceeded, which means that the client timed out waiting for the next message from the server. In this case, #isRetryable() will be true.
An idle timeout has exceeded, which means that the stream is using manual flow control and the caller has not called StreamController#request(int) (in case of callback api) or next on ServerStream#iterator() (in case of blocking api).