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 #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.
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. This class expects that name-value pairs, returned from parameters extractor are already URL-encoded and can perform optional validation of that, but does not encode the name-value pairs themselves.
ServerStream<V>
A blocking Iterable-style wrapper around server stream responses.
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.
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. The watchdog will terminate any
stream that has not has seen any demand (via StreamController#request(int)) in the
configured interval. 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.
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.
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
Asynchronous example:
RequestType request = RequestType.newBuilder().build();
UnaryCallable
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.
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).