Classes
AbstractApiFuture<V>
Abstract implementation of ApiFuture that mirrors AbstractFuture in Guava.
AbstractApiService
Base class for ApiService. Similar to Guava's AbstractService but redeclared so
that Guava can be shaded.
ApiFutureToListenableFuture<V>
INTERNAL USE ONLY. Adapter from ApiFuture to Guava ListenableFuture.
ApiFutures
Static utility methods for the ApiFuture interface.
ApiService.Listener
A listener for the various state changes that a ApiService goes through in its lifecycle.
All methods are no-ops by default, implementors should override the ones they care about.
CurrentMillisClock
Implementation of the ApiClock interface, which uses System#currentTimeMillis() as time source.
ForwardingApiFuture<T>
ListenableFutureToApiFuture<V>
INTERNAL USE ONLY. Adapter from Guava ListenableFuture to ApiFuture.
NanoClock
Default implementation of the ApiClock interface, using call to System.nanoTime().
SettableApiFuture<V>
An ApiFuture whose result can be set. Similar to Guava's SettableFuture, but
redeclared so that Guava could be shaded.
Interfaces
ApiAsyncFunction<I,O>
Transforms a value, possibly asynchronously.
It is similar to Guava's AsyncFunction, redeclared so that Guava can be shaded.
ApiClock
An interface for getting the current value of a high-resolution time source, in nanoseconds.
Clocks other than NanoClock are typically used only for testing.
This interface is required in addition to Java 8's Clock, because nanoTime is required to compare values with io.grpc.CallOptions.getDeadlineNanoTime().
ApiFunction<F,T>
Legacy version of Function.
It is similar to Guava's Function, redeclared so that Guava can be shaded.
ApiFuture<V>
A Future that can have a listener added.
Similar to Guava's ListenableFuture, but redeclared so that Guava could be shaded.
ApiFutureCallback<V>
A callback for accepting the results of an ApiFuture.
It is similar to Guava's FutureCallback, redeclared so that Guava can be shaded.
ApiService
An object with an operational state, plus asynchronous #startAsync() and #stopAsync() lifecycle methods to transition between states. Example services include webservers, RPC servers and timers.
The normal lifecycle of a service is:
- NEW ->
- STARTING ->
- RUNNING ->
- STOPPING ->
- TERMINATED
There are deviations from this if there are failures or if ApiService#stopAsync is called before the ApiService reaches the RUNNING state. The set of legal transitions form a DAG, therefore every method of the listener will be called at most once. N.B. The State#FAILED and State#TERMINATED states are terminal states, once a service enters either of these states it cannot ever leave them.
Implementors of this interface are strongly encouraged to extend AbstractApiService which implement this interface and make the threading and state management easier.
Similar to Guava's Service, but redeclared so that Guava could be shaded.
Enums
ApiService.State
The lifecycle states of a service.
The ordering of the State enum is defined such that if there is a state transition
from A -> B then A.compareTo(B) < 0. N.B. The converse is not true, i.e. if
A.compareTo(B) < 0 then there is not guaranteed to be a valid state transition
A -> B.
Annotation Types
BetaApi
Indicates a public API that can change at any time, and has no guarantee of API stability and backward-compatibility.
Usage guidelines:
- This annotation is used only on APIs with public visibility. Internal interfaces should not use it.
- This annotation should only be added to new APIs. Adding it to an existing API is considered API-breaking.
- Removing this annotation from an API gives it stable status, assuming the API doesn't have other annotations denoting instability (such as InternalApi or InternalExtensionOnly).
InternalApi
Annotates a program element (class, method, package etc) which is internal to its containing library, not part of the public API, and should not be used by users of the library.
This annotation only makes sense on APIs that are not private. Its existence is necessary because Java does not have a visibility level for code within a compilation unit.
Adding this annotation to an API is considered API-breaking.
InternalExtensionOnly
Indicates a public API that is stable for callers to use, but has no guarantee of stability for extension. Consequently, the API should only be extended within the package containing the API.
For example:
- An interface marked with this annotation can have new methods added to it.
- A non-final class with this annotation can be marked final.
- A class with this annotation can have new abstract methods added.
- a non-final method with this annotation can be marked final.
The list above is just for illustration purposes and is not exhaustive.
Adding this annotation to an API is considered API-breaking.