Start Api code

README.md

@@ -0,0 +1 @@
+Do not link against this repo, as it is will be renamed later

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;
     }
 
     /**

src/com/google/android/gms/common/api/Api.java

@@ -1,13 +1,46 @@
 package com.google.android.gms.common.api;
 
-public class Api<O extends Api.ApiOptions> {
-    
+/**
+ * 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.
+ * <p/>
+ * 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.
+ * <p/>
+ * See {@link GoogleApiClient.Builder} for usage examples.
+ */
+public final class Api<O extends Api.ApiOptions> {
+
+    /**
+     * 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 {
         }
     }
 }

src/com/google/android/gms/common/api/PendingResult.java

@@ -1,4 +1,40 @@
 package com.google.android.gms.common.api;
 
-public class PendingResult<T> {
+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.
+ * <p/>
+ * <ul>
+ * <li>via blocking calls to {@link #await()}, or {@link #await(long, TimeUnit)}, or</li>
+ * <li>via a callback by passing in an object implementing interface {@link ResultCallback} to
+ * {@link #setResultCallback(ResultCallback)}.</li>
+ * </ul>
+ * 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.
+ * <p/>
+ * TODO: Docs
+ */
+public interface PendingResult<R extends Result> {
+    /**
+     * 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<R> callback, long time, TimeUnit unit);
+
+    public void setResultCallback(ResultCallback<R> callback);
 }

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();
+}

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();
+}

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<R extends Result> {
+    /**
+     * 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);
 }

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.
+ * <p/>
+ * TODO: content (is this IPC API?)
+ */
+public final class Status implements Result {
+    @Override
+    public Status getStatus() {
+        return this;
+    }
 }