Add sign-in and token retrieval to Blimp

blimp/client/android/java/src/org/chromium/blimp/auth/TokenSource.java

Index: blimp/client/android/java/src/org/chromium/blimp/auth/TokenSource.java
diff --git a/blimp/client/android/java/src/org/chromium/blimp/auth/TokenSource.java b/blimp/client/android/java/src/org/chromium/blimp/auth/TokenSource.java
new file mode 100644
index 0000000000000000000000000000000000000000..1951f5f2ba0f52bfc6d35ad12887550bec0ae167
--- /dev/null
+++ b/blimp/client/android/java/src/org/chromium/blimp/auth/TokenSource.java
@@ -0,0 +1,86 @@
+// Copyright 2015 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+package org.chromium.blimp.auth;
+
+import android.content.Intent;
+
+import com.google.android.gms.common.ConnectionResult;
+
+/**
+ * Interface for an object that can asynchronously retrieve and invalidate user authentication
+ * tokens.
+ */
+public interface TokenSource {
+    /**
+     * Used to get results of {@link TokenSource#getToken()} attempts.
+     */
+    public interface Callback {
+        /**
+         * A token was successfully received.
+         * @param token The token.
+         */
+        void onTokenReceived(String token);
+
+        /**
+         * A token was unable to be retrieved.
+         * @param isTransient Whether or not the failure is recoverable or not.
+         */
+        void onTokenUnavailable(boolean isTransient);

[nyquist, 2015/09/29 23:38:40]

If the error isTransient, maybe we could comment somewhere explaining what the
RetryingTokenSource will do?

[David Trainor- moved to gerrit, 2015/10/05 15:19:07]

isTransient could also be handled by any TokenSource implementer.  Ideally the
RetryingTokenSource would actually expose transient failures after X retries. 
I'll comment on it in the RetryingTokenSource though.

+
+        /**
+         * There is no selected user account on the device.  By triggering {@code intent} with a
+         * result (via {@link android.app.Activity#startActivityForResult(Intent, int)) the calling
+         * {@code android.app.Activity} can show an account chooser to the user.  The resulting
+         * {@link Intent} should be passed to the {@link TokenSource} via
+         * {@link TokenSource#onAccountSelected(Intent)}.
+         * @param intent The {@link Intent} to start to have the user select an account.
+         */
+        void onNeedsAccountToBeSelected(Intent intent);
+    }
+
+    /**
+     * Destroys all internal state and stops (if possible) any outstanding
+     * {@link TokenSource#getToken()} attempts.
+     */
+    void destroy();
+
+    /**
+     * Sets the {@link Callback} that will be notified of the results of {@link getToken()} calls.
+     * @param callback The {@link Callback} to notify.
+     */
+    void setCallback(Callback callback);

[nyquist, 2015/09/29 23:38:40]

Instead of setCallback, could we pass in the callback to getToken(Callback)?
Chances are, there will be the same object that calls setCallback(...) and
getToken(), so it could just pass in |this| or something anyway to
getToken(Callback).

You might have to keep a little bit more state in the TokenSource though, since
you could potentially get multiple calls to getToken(Callback). Either that, or
just keep on passing the |callback| object around.

[David Trainor- moved to gerrit, 2015/10/05 15:19:07]

Sadly this gets more complicated.

+
+    /**
+     * Starts off a process of getting an authentication token for the selected account for this
+     * application.  See {@link Callback} for specific details of each possible callback outcome.
+     * - If no account is selected, {@link Callback#onNeedsAccountToBeSelected(Intent)} will be
+     * called.
+     * - If getting the token fails, {@link Callback#onTokenUnavailable(boolean)} will be called.
+     * - If getting the token is successful, {@link Callback#onTokenReceived(String)} will be
+     * called.
+     */
+    void getToken();
+
+    /**
+     * @return Whether or not this {@link TokenSource} is currently trying to retrieve a token.
+     */
+    boolean isRetrievingToken();
+
+    /**
+     * Notifies this {@link TokenSource} that the token it returned is invalid.  This won't
+     * automatically trigger another {@link #getToken()} attempt.
+     * @param token The token that is invalid and should be removed from the underlying token cache.
+     * @return      The result code of the attempted invalidation (see {@link ConnectionResult}.
+     */
+    int tokenIsInvalid(String token);
+
+    /**
+     * Notifies this {@link TokenSource} of a response from the {@link Intent} sent through
+     * {@link Callback#onNeedsAccountToBeSelected(Intent)}.  The selected account will be parsed and
+     * saved.  This won't automatically trigger another {@link #getToken()} attempt.
+     * @param data The response {@link Intent} data.
+     */
+    void onAccountSelected(Intent data);

[nyquist, 2015/09/29 23:38:40]

Would it be clearer for this interface if either:
A) We would add a comment about there having to be a key
AccountManager.KEY_ACCOUNT_NAME that contains the |account.name|?
B) This method takes |String accountName| as a parameter directly.

[David Trainor- moved to gerrit, 2015/10/05 15:19:07]

I'd rather it be explicit that the user should call startActivityForResult() on
the Callback intent and pass the returned intent directly to this class, that
way I don't expose some of the intent internals.

+}