Summary: Ctors | Methods | Inherited Methods | [Expand All]
public abstract class

# PendingResult

extends Object

java.lang.Object
↳ | com.google.android.gms.common.api.PendingResult<R extends com.google.android.gms.common.api.Result>

Known Direct Subclasses Batch, OptionalPendingResult<R extends Result>
Batch | Handles a batch of `PendingResult` items.
OptionalPendingResult<R extends Result> | OptionalPendingResults are `PendingResult`s with additional support for non-blocking accessors.

## Class Overview

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()`, or `await(long, TimeUnit)`, or
- via a callback by passing in an object implementing interface `ResultCallback` to `setResultCallback(ResultCallback)`.

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 `release()` should be used to free the associated resources.

## Summary

Public Constructors
| PendingResult()

Public Methods
abstract R | await() Blocks until the task is completed.
abstract R | await(long time, TimeUnit units) Blocks until the task is completed or has timed out waiting for the result.
abstract void | cancel() Requests that the PendingResult be canceled.
abstract boolean | isCanceled() Indicates whether the pending result has been canceled either due to calling `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.

[Expand] Inherited Methods
From class java.lang.Object
Object | clone()
boolean | equals(Object arg0)
void | finalize()
final Class<?> | getClass()
int | hashCode()
final void | notify()
final void | notifyAll()
String | toString()
final void | wait(long arg0, int arg1)
final void | wait(long arg0)
final void | wait()

## 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 `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 `INTERRUPTED` or `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.

`onResult(Result)` will never be called, `await()` will return a failed result with `CANCELED`.

#### public abstract boolean isCanceled ()

Indicates whether the pending result has been canceled either due to calling `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 `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 `onSuccess(R)` will be called to make the additional API call that yields the transformed result. If the result is a failure, then `onFailure(Status)` will be called to (optionally) allow modification of failure status.

If the result implements `Releasable`, then `release()` will be called once the transform has been applied.

Multiple API calls can be chained together by making subsequent calls to `then(ResultTransform)` and the final result can be received by an instance of `ResultCallbacks` specified via `andFinally(ResultCallbacks)`. 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 `setHandler(Handler)` or on the main thread by default.

If `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.