Known Direct Subclasses
|
Represents a pending result from calling an API method in Google Play services. The final result object from a PendingResult is of type R, which can be retrieved in one of two ways.
- via blocking calls to
await()
, orawait(long, TimeUnit)
, or - via a callback by passing in an object implementing interface
ResultCallback
tosetResultCallback(ResultCallback super R> )
.
After the result has been retrieved using await()
or delivered to the result callback, it is an error to attempt to retrieve the result again.
It is the responsibility of the caller or callback receiver to release any resources
associated with the returned result. Some result types may implement Releasable
,
in which case Releasable.release()
should be used to free the associated resources.
Public Constructor Summary
Public Method Summary
abstract R |
await()
Blocks until the task is completed.
|
abstract R | |
abstract void |
cancel()
Requests that the PendingResult be canceled.
|
abstract boolean |
isCanceled()
Indicates whether the pending result has been canceled either due to calling
GoogleApiClient.disconnect() or calling
cancel() directly on the pending result or an enclosing
Batch .
|
abstract void |
setResultCallback(ResultCallback<? super R>
callback)
Set the callback here if you want the result to be delivered via a callback
when the result is ready.
|
abstract void |
setResultCallback(ResultCallback<? super R>
callback, long time, TimeUnit
units)
Set the callback here if you want the result to be delivered via a callback
when the result is ready or has timed out waiting for the result.
|
<S extends Result> TransformedResult<S> |
then(ResultTransform<? super R, ? extends S>
transform)
Transforms the result by making another API call.
|
Inherited Method Summary
Public Constructors
public PendingResult ()
Public Methods
public abstract R await ()
Blocks until the task is completed. This is not allowed on the UI thread. The
returned result object can have an additional failure mode of
CommonStatusCodes.INTERRUPTED
.
public abstract R await (long time, TimeUnit units)
Blocks until the task is completed or has timed out waiting for the result. This is
not allowed on the UI thread. The returned result object can have an additional failure
mode of either
CommonStatusCodes.INTERRUPTED
or CommonStatusCodes.TIMEOUT
.
public abstract void cancel ()
Requests that the PendingResult be canceled. If the result is available, but not consumed it will be released. If the result is set after cancelation was requested it is immediately released.
ResultCallback.onResult(Result)
will never be called, await()
will return a failed result with CommonStatusCodes.CANCELED
.
public abstract boolean isCanceled ()
Indicates whether the pending result has been canceled either due to calling
GoogleApiClient.disconnect()
or calling cancel()
directly on the pending result or an enclosing Batch
.
public abstract void setResultCallback (ResultCallback<? super R> callback)
Set the callback here if you want the result to be delivered via a callback when the result is ready.
public abstract void setResultCallback (ResultCallback<? super R> callback, long time, TimeUnit units)
Set the callback here if you want the result to be delivered via a callback when the
result is ready or has timed out waiting for the result. The returned result object can
have an additional failure mode of CommonStatusCodes.TIMEOUT
.
public TransformedResult<S> then (ResultTransform<? super R, ? extends S> transform)
Transforms the result by making another API call.
If the result is successful, then
ResultTransform.onSuccess(R)
will be called to make the additional API call
that yields the transformed result. If the result is a failure, then
ResultTransform.onFailure(Status)
will be called to (optionally) allow
modification of failure status.
If the result implements Releasable
,
then Releasable.release()
will be called once the transform has been applied.
Multiple API calls can be chained together by making subsequent calls to
TransformedResult.then(ResultTransform super R, ? extends S>
)
and the final result can be received by an instance of ResultCallbacks
specified via
TransformedResult.andFinally(ResultCallbacks super R>
)
. For example:
final DriveFolder rootFolder = Drive.DriveApi.getRootFolder(mApiClient); Drive.DriveApi.newDriveContents(mApiClient) .then(new ResultTransform<DriveContentsResult, DriveFileResult>() { @Override public PendingResult<DriveFileResult> onSuccess(DriveContentsResult result) { DriveContents driveContents = result.getDriveContents(); // Write content to DriveContents OutputStream outputStream = driveContents.getOutputStream(); PrintWriter writer = new PrintWriter(outputStream); writer.write("Hello World!"); writer.close(); MetadataChangeSet changeSet = new MetadataChangeSet.Builder() .setTitle("hello.txt") .setMimeType("text/plain") .build(); // Create a file on root folder return rootFolder.createFile(mApiClient, changeSet, driveContents); } }) .then(new ResultTransform<DriveFileResult, MetadataBufferResult>() { @Override public PendingResult<MetadataBufferResult> onSuccess(DriveFileResult result) { // Fetch the updated root folder contents return rootFolder.listChildren(mApiClient) } }) .andFinally(new ResultCallbacks<MetadataBufferResult>() { @Override public void onSuccess(MetadataBufferResult result) { // All API calls were successful. } @Override public void onFailure(Status status) { // An API call failed. } });
All ResultTransform
s
will be run on a worker thread. These transforms therefore must not interact with UI
elements, but they may perform brief background work (not requiring more than a few
seconds). If ResultCallbacks
are specified, these will be called on the thread specified by
GoogleApiClient.Builder.setHandler(Handler)
or on the main thread by
default.
If
GoogleApiClient.disconnect()
is called before a series of transforms
completes the transforms will continue to run in the background until the last one
completes. In this case, ResultCallbacks
will not be called. Note that this may cause memory leaks if background transformations
are long-running. For long background tasks, consider using an IntentService
.
Note: it is an error to use multiple GoogleApiClient
s
for various API calls within subsequent ResultTransform
s.
Behavior is undefined if calls don't use the same GoogleApiClient.