From 8b421638000f30c21a57997bab44f0040b66550b Mon Sep 17 00:00:00 2001 From: mar-v-in Date: Mon, 12 Jan 2015 00:52:58 +0100 Subject: [PATCH] Start Api code --- README.md | 1 + .../android/gms/common/ConnectionResult.java | 7 ++-- .../google/android/gms/common/api/Api.java | 41 +++++++++++++++++-- .../android/gms/common/api/PendingResult.java | 38 ++++++++++++++++- .../android/gms/common/api/Releasable.java | 9 ++++ .../google/android/gms/common/api/Result.java | 8 ++++ .../gms/common/api/ResultCallback.java | 14 ++++++- .../google/android/gms/common/api/Status.java | 11 ++++- 8 files changed, 119 insertions(+), 10 deletions(-) create mode 100644 README.md create mode 100644 src/com/google/android/gms/common/api/Releasable.java create mode 100644 src/com/google/android/gms/common/api/Result.java diff --git a/README.md b/README.md new file mode 100644 index 00000000..6fb94c76 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +Do not link against this repo, as it is will be renamed later diff --git a/src/com/google/android/gms/common/ConnectionResult.java b/src/com/google/android/gms/common/ConnectionResult.java index b32466b6..ae65ae68 100644 --- a/src/com/google/android/gms/common/ConnectionResult.java +++ b/src/com/google/android/gms/common/ConnectionResult.java @@ -2,6 +2,7 @@ package com.google.android.gms.common; import android.app.Activity; import android.app.PendingIntent; +import android.content.Intent; import android.content.IntentSender; import com.google.android.gms.common.api.GoogleApiClient; @@ -130,7 +131,7 @@ public class ConnectionResult { * @return the error code, or {@link #SUCCESS} if no error occurred. */ public int getErrorCode() { - return this.statusCode; + return statusCode; } /** @@ -141,7 +142,7 @@ public class ConnectionResult { * @return The pending intent to resolve the connection failure. */ public PendingIntent getResolution() { - return this.pendingIntent; + return pendingIntent; } /** @@ -160,7 +161,7 @@ public class ConnectionResult { * @return {@code true} if the connection was successful, {@code false} if there was an error. */ public boolean isSuccess() { - return this.statusCode == 0; + return statusCode == 0; } /** diff --git a/src/com/google/android/gms/common/api/Api.java b/src/com/google/android/gms/common/api/Api.java index 6560e667..5d7e45ab 100644 --- a/src/com/google/android/gms/common/api/Api.java +++ b/src/com/google/android/gms/common/api/Api.java @@ -1,13 +1,46 @@ package com.google.android.gms.common.api; -public class Api { - +/** + * Describes a section of the Google Play Services API that should be made available. Instances of + * this should be passed into {@link GoogleApiClient.Builder#addApi(Api)} to enable the appropriate + * parts of Google Play Services. + *

+ * Google APIs are partitioned into sections which allow your application to configure only the + * services it requires. Each Google API provides an API object which can be passed to + * {@link GoogleApiClient.Builder#addApi(Api)} in order to configure and enable that functionality + * in your {@link GoogleApiClient} instance. + *

+ * See {@link GoogleApiClient.Builder} for usage examples. + */ +public final class Api { + + /** + * Base interface for API options. These are used to configure specific parameters for + * individual API surfaces. The default implementation has no parameters. + */ public interface ApiOptions { + /** + * Base interface for {@link ApiOptions} in {@link Api}s that have options. + */ public interface HasOptions extends ApiOptions { - } + + /** + * Base interface for {@link ApiOptions} that are not required, don't exist. + */ public interface NotRequiredOptions extends ApiOptions { - + } + + /** + * {@link ApiOptions} implementation for {@link Api}s that do not take any options. + */ + public class NoOptions implements NotRequiredOptions { + } + + /** + * Base interface for {@link ApiOptions} that are optional. + */ + public interface Optional extends HasOptions, NotRequiredOptions { } } } diff --git a/src/com/google/android/gms/common/api/PendingResult.java b/src/com/google/android/gms/common/api/PendingResult.java index a1ea2473..8845a8d7 100644 --- a/src/com/google/android/gms/common/api/PendingResult.java +++ b/src/com/google/android/gms/common/api/PendingResult.java @@ -1,4 +1,40 @@ package com.google.android.gms.common.api; -public class PendingResult { +import java.util.concurrent.TimeUnit; + +/** + * 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. + *

+ *

+ * After the result has been retrieved using {@link #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 {@link Releasable}, in which case {@link Releasable#release()} should be + * used to free the associated resources. + *

+ * TODO: Docs + */ +public interface PendingResult { + /** + * 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 R await(); + + /** + * 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 R await(long time, TimeUnit unit); + + public void cancel(); + + public boolean isCanceled(); + + public void setResultCallback(ResultCallback callback, long time, TimeUnit unit); + + public void setResultCallback(ResultCallback callback); } diff --git a/src/com/google/android/gms/common/api/Releasable.java b/src/com/google/android/gms/common/api/Releasable.java new file mode 100644 index 00000000..ed3d08c6 --- /dev/null +++ b/src/com/google/android/gms/common/api/Releasable.java @@ -0,0 +1,9 @@ +package com.google.android.gms.common.api; + +/** + * Represents a resource, or a holder of resources, which may be released once they are no longer + * needed. + */ +public interface Releasable { + public void release(); +} diff --git a/src/com/google/android/gms/common/api/Result.java b/src/com/google/android/gms/common/api/Result.java new file mode 100644 index 00000000..d8408112 --- /dev/null +++ b/src/com/google/android/gms/common/api/Result.java @@ -0,0 +1,8 @@ +package com.google.android.gms.common.api; + +/** + * Represents the final result of invoking an API method in Google Play Services. + */ +public interface Result { + public Status getStatus(); +} diff --git a/src/com/google/android/gms/common/api/ResultCallback.java b/src/com/google/android/gms/common/api/ResultCallback.java index 1d925a8d..ef8e8eb2 100644 --- a/src/com/google/android/gms/common/api/ResultCallback.java +++ b/src/com/google/android/gms/common/api/ResultCallback.java @@ -1,4 +1,16 @@ package com.google.android.gms.common.api; -public class ResultCallback { +/** + * An interface for receiving a {@link Result} from a {@link PendingResult} as an asynchronous callback. + */ +public interface ResultCallback { + /** + * Called when the {@link Result} is ready. It is the responsibility of each callback to + * release any resources associated with the result. Some result types may implement + * {@link Releasable}, in which case {@link Releasable#release()} should be used to free the + * associated resources. + * + * @param result The result from the API call. May not be null. + */ + public void onResult(R result); } diff --git a/src/com/google/android/gms/common/api/Status.java b/src/com/google/android/gms/common/api/Status.java index fdd78880..ae65e646 100644 --- a/src/com/google/android/gms/common/api/Status.java +++ b/src/com/google/android/gms/common/api/Status.java @@ -1,4 +1,13 @@ package com.google.android.gms.common.api; -public class Status { +/** + * Represents the results of work. + *

+ * TODO: content (is this IPC API?) + */ +public final class Status implements Result { + @Override + public Status getStatus() { + return this; + } }