Merge change I9161f53d into eclair-sdk

* changes:
  update account manager javadoc

core/java/android/accounts/AbstractAccountAuthenticator.java

@@ -26,9 +26,78 @@ import android.content.Intent;
 import android.Manifest;
 
 /**
- * Base class for creating AccountAuthenticators. This implements the IAccountAuthenticator
- * binder interface and also provides helper libraries to simplify the creation of
- * AccountAuthenticators.
+ * Abstract base class for creating AccountAuthenticators.
+ * In order to be an authenticator one must extend this class, provider implementations for the
+ * abstract methods and write a service that returns the result of {@link #getIBinder()}
+ * in the service's {@link android.app.Service#onBind(android.content.Intent)} when invoked
+ * with an intent with action {@link AccountManager#ACTION_AUTHENTICATOR_INTENT}. This service
+ * must specify the following intent filter and metadata tags in its AndroidManifest.xml file
+ * <pre>
+ *   &lt;intent-filter&gt;
+ *     &lt;action android:name="android.accounts.AccountAuthenticator" /&gt;
+ *   &lt;/intent-filter&gt;
+ *   &lt;meta-data android:name="android.accounts.AccountAuthenticator"
+ *             android:resource="@xml/authenticator" /&gt;
+ * </pre>
+ * The <code>android:resource</code> attribute must point to a resource that looks like:
+ * <pre>
+ * &lt;account-authenticator xmlns:android="http://schemas.android.com/apk/res/android"
+ *    android:accountType="typeOfAuthenticator"
+ *    android:icon="@drawable/icon"
+ *    android:smallIcon="@drawable/miniIcon"
+ *    android:label="@string/label"
+ *    android:accountPreferences="@xml/account_preferences"
+ * /&gt;
+ * </pre>
+ * Replace the icons and labels with your own resources. The <code>android:accountType</code>
+ * attribute must be a string that uniquely identifies your authenticator and will be the same
+ * string that user will use when making calls on the {@link AccountManager} and it also
+ * corresponds to {@link Account#type} for your accounts. One user of the android:icon is the
+ * "Account & Sync" settings page and one user of the android:smallIcon is the Contact Application's
+ * tab panels.
+ * <p>
+ * The preferences attribute points to an PreferenceScreen xml hierarchy that contains
+ * a list of PreferenceScreens that can be invoked to manage the authenticator. An example is:
+ * <pre>
+ * &lt;PreferenceScreen xmlns:android="http://schemas.android.com/apk/res/android"&gt;
+ *    &lt;PreferenceCategory android:title="@string/title_fmt" /&gt;
+ *    &lt;PreferenceScreen
+ *         android:key="key1"
+ *         android:title="@string/key1_action"
+ *         android:summary="@string/key1_summary"&gt;
+ *         &lt;intent
+ *             android:action="key1.ACTION"
+ *             android:targetPackage="key1.package"
+ *             android:targetClass="key1.class" /&gt;
+ *     &lt;/PreferenceScreen&gt;
+ * &lt;/PreferenceScreen&gt;
+ * </pre>
+ *
+ * <p>
+ * The standard pattern for implementing any of the abstract methods is the following:
+ * <ul>
+ * <li> If the supplied arguments are enough for the authenticator to fully satisfy the request
+ * then it will do so and return a {@link Bundle} that contains the results.
+ * <li> If the authenticator needs information from the user to satisfy the request then it
+ * will create an {@link Intent} to an activity that will prompt the user for the information
+ * and then carry out the request. This intent must be returned in a Bundle as key
+ * {@link AccountManager#KEY_INTENT}.
+ * <p>
+ * The activity needs to return the final result when it is complete so the Intent should contain
+ * the {@link AccountAuthenticatorResponse} as {@link AccountManager#KEY_ACCOUNT_MANAGER_RESPONSE}.
+ * The activity must then call {@link AccountAuthenticatorResponse#onResult} or
+ * {@link AccountAuthenticatorResponse#onError} when it is complete.
+ * </ul>
+ * <p>
+ * The following descriptions of each of the abstract authenticator methods will not describe the
+ * possible asynchronous nature of the request handling and will instead just describe the input
+ * parameters and the expected result.
+ * <p>
+ * When writing an activity to satisfy these requests one must pass in the AccountManagerResponse
+ * and return the result via that response when the activity finishes (or whenever else  the
+ * activity author deems it is the correct time to respond).
+ * The {@link AccountAuthenticatorActivity} handles this, so one may wish to extend that when
+ * writing activities to handle these requests.
  */
 public abstract class AbstractAccountAuthenticator {
     private final Context mContext;
@@ -239,19 +308,135 @@ public abstract class AbstractAccountAuthenticator {
      */
     public abstract Bundle editProperties(AccountAuthenticatorResponse response,
             String accountType);
+
+    /**
+     * Adds an account of the specified accountType.
+     * @param response to send the result back to the AccountManager, will never be null
+     * @param accountType the type of account to add, will never be null
+     * @param authTokenType the type of auth token to retrieve after adding the account, may be null
+     * @param requiredFeatures a String array of authenticator-specific features that the added
+     * account must support, may be null
+     * @param options a Bundle of authenticator-specific options, may be null
+     * @return a Bundle result or null if the result is to be returned via the response. The result
+     * will contain either:
+     * <ul>
+     * <li> {@link AccountManager#KEY_INTENT}, or
+     * <li> {@link AccountManager#KEY_ACCOUNT_NAME} and {@link AccountManager#KEY_ACCOUNT_TYPE} of
+     * the account that was added, plus {@link AccountManager#KEY_AUTHTOKEN} if an authTokenType
+     * was supplied, or
+     * <li> {@link AccountManager#KEY_ERROR_CODE} and {@link AccountManager#KEY_ERROR_MESSAGE} to
+     * indicate an error
+     * </ul>
+     * @throws NetworkErrorException if the authenticator could not honor the request due to a
+     * network error
+     */
     public abstract Bundle addAccount(AccountAuthenticatorResponse response, String accountType,
             String authTokenType, String[] requiredFeatures, Bundle options)
             throws NetworkErrorException;
+
+    /**
+     * Checks that the user knows the credentials of an account.
+     * @param response to send the result back to the AccountManager, will never be null
+     * @param account the account whose credentials are to be checked, will never be null
+     * @param options a Bundle of authenticator-specific options, may be null
+     * @return a Bundle result or null if the result is to be returned via the response. The result
+     * will contain either:
+     * <ul>
+     * <li> {@link AccountManager#KEY_INTENT}, or
+     * <li> {@link AccountManager#KEY_BOOLEAN_RESULT}, true if the check succeeded, false otherwise
+     * <li> {@link AccountManager#KEY_ERROR_CODE} and {@link AccountManager#KEY_ERROR_MESSAGE} to
+     * indicate an error
+     * </ul>
+     */
     public abstract Bundle confirmCredentials(AccountAuthenticatorResponse response,
             Account account, Bundle options);
+
+    /**
+     * Gets the authtoken for an account.
+     * @param response to send the result back to the AccountManager, will never be null
+     * @param account the account whose credentials are to be retrieved, will never be null
+     * @param authTokenType the type of auth token to retrieve, will never be null
+     * @param loginOptions a Bundle of authenticator-specific options, may be null
+     * @return a Bundle result or null if the result is to be returned via the response. The result
+     * will contain either:
+     * <ul>
+     * <li> {@link AccountManager#KEY_INTENT}, or
+     * <li> {@link AccountManager#KEY_ACCOUNT_NAME}, {@link AccountManager#KEY_ACCOUNT_TYPE},
+     * and {@link AccountManager#KEY_AUTHTOKEN}, or
+     * <li> {@link AccountManager#KEY_ERROR_CODE} and {@link AccountManager#KEY_ERROR_MESSAGE} to
+     * indicate an error
+     * </ul>
+     * @throws NetworkErrorException if the authenticator could not honor the request due to a
+     * network error
+     */
     public abstract Bundle getAuthToken(AccountAuthenticatorResponse response,
             Account account, String authTokenType, Bundle loginOptions)
             throws NetworkErrorException;
+
+    /**
+     * Ask the authenticator for a localized label for the given authTokenType.
+     * @param authTokenType the authTokenType whose label is to be returned, will never be null
+     * @return the localized label of the auth token type, may be null if the type isn't known
+     */
     public abstract String getAuthTokenLabel(String authTokenType);
+
+    /**
+     * Update the locally stored credentials for an account.
+     * @param response to send the result back to the AccountManager, will never be null
+     * @param account the account whose credentials are to be updated, will never be null
+     * @param authTokenType the type of auth token to retrieve after updating the credentials,
+     * may be null
+     * @param loginOptions a Bundle of authenticator-specific options, may be null
+     * @return a Bundle result or null if the result is to be returned via the response. The result
+     * will contain either:
+     * <ul>
+     * <li> {@link AccountManager#KEY_INTENT}, or
+     * <li> {@link AccountManager#KEY_ACCOUNT_NAME} and {@link AccountManager#KEY_ACCOUNT_TYPE} of
+     * the account that was added, plus {@link AccountManager#KEY_AUTHTOKEN} if an authTokenType
+     * was supplied, or
+     * <li> {@link AccountManager#KEY_ERROR_CODE} and {@link AccountManager#KEY_ERROR_MESSAGE} to
+     * indicate an error
+     * </ul>
+     */
     public abstract Bundle updateCredentials(AccountAuthenticatorResponse response,
             Account account, String authTokenType, Bundle loginOptions);
+    
+    /**
+     * Checks if the account supports all the specified authenticator specific features.
+     * @param response to send the result back to the AccountManager, will never be null
+     * @param account the account to check, will never be null
+     * @param features an array of features to check, will never be null
+     * @return a Bundle result or null if the result is to be returned via the response. The result
+     * will contain either:
+     * <ul>
+     * <li> {@link AccountManager#KEY_INTENT}, or
+     * <li> {@link AccountManager#KEY_BOOLEAN_RESULT}, true if the account has all the features,
+     * false otherwise
+     * <li> {@link AccountManager#KEY_ERROR_CODE} and {@link AccountManager#KEY_ERROR_MESSAGE} to
+     * indicate an error
+     * </ul>
+     * @throws NetworkErrorException if the authenticator could not honor the request due to a
+     * network error
+     */
     public abstract Bundle hasFeatures(AccountAuthenticatorResponse response,
             Account account, String[] features) throws NetworkErrorException;
+
+    /**
+     * Checks if the removal of this account is allowed.
+     * @param response to send the result back to the AccountManager, will never be null
+     * @param account the account to check, will never be null
+     * @return a Bundle result or null if the result is to be returned via the response. The result
+     * will contain either:
+     * <ul>
+     * <li> {@link AccountManager#KEY_INTENT}, or
+     * <li> {@link AccountManager#KEY_BOOLEAN_RESULT}, true if the removal of the account is
+     * allowed, false otherwise
+     * <li> {@link AccountManager#KEY_ERROR_CODE} and {@link AccountManager#KEY_ERROR_MESSAGE} to
+     * indicate an error
+     * </ul>
+     * @throws NetworkErrorException if the authenticator could not honor the request due to a
+     * network error
+     */
     public Bundle getAccountRemovalAllowed(AccountAuthenticatorResponse response,
             Account account) throws NetworkErrorException {
         final Bundle result = new Bundle();

core/java/android/accounts/AccountAuthenticatorActivity.java

@@ -22,21 +22,17 @@ import android.os.Bundle;
 
 /**
  * Base class for implementing an Activity that is used to help implement an
- * AbstractAccountAuthenticator. If the AbstractAccountAuthenticator needs to return an Intent
- * that is to be used to launch an Activity that needs to return results to satisfy an
- * AbstractAccountAuthenticator request, it should store the AccountAuthenticatorResponse
- * inside of the Intent as follows:
- * <p>
+ * AbstractAccountAuthenticator. If the AbstractAccountAuthenticator needs to use an activity
+ * to handle the request then it can have the activity extend AccountAuthenticatorActivity.
+ * The AbstractAccountAuthenticator passes in the response to the intent using the following:
+ * <pre>
  *      intent.putExtra(Constants.ACCOUNT_AUTHENTICATOR_RESPONSE_KEY, response);
- * <p>
- * The activity that it launches should extend the AccountAuthenticatorActivity. If this
- * activity has a result that satisfies the original request it sets it via:
- * <p>
- *       setAccountAuthenticatorResult(result)
- * <p>
+ * </pre>
+ * The activity then sets the result that is to be handed to the response via
+ * {@link #setAccountAuthenticatorResult(android.os.Bundle)}.
  * This result will be sent as the result of the request when the activity finishes. If this
- * is never set or if it is set to null then the request will be canceled when the activity
- * finishes.
+ * is never set or if it is set to null then error {@link AccountManager#ERROR_CODE_CANCELED}
+ * will be called on the response.
  */
 public class AccountAuthenticatorActivity extends Activity {
     private AccountAuthenticatorResponse mAccountAuthenticatorResponse = null;

core/java/android/accounts/AccountManagerFuture.java

@@ -80,29 +80,37 @@ public interface AccountManagerFuture<V> {
     boolean isDone();
 
     /**
-     * Wrapper for {@link java.util.concurrent.Future#get()}. If the get() throws
-     * {@link InterruptedException} then the
-     * {@link AccountManagerFuture} is canceled and
-     * {@link android.accounts.OperationCanceledException} is thrown.
-     * @return the {@link android.os.Bundle} that is returned by get()
-     * @throws android.accounts.OperationCanceledException if get() throws the unchecked
-     * CancellationException
-     * or if the Future was interrupted.
+     * Accessor for the future result the {@link AccountManagerFuture} represents. This
+     * call will block until the result is available. In order to check if the result is
+     * available without blocking, one may call {@link #isDone()} and  {@link #isCancelled()}.
+     * If the request that generated this result fails or is canceled then an exception
+     * will be thrown rather than the call returning normally.
+     * @return the actual result
+     * @throws android.accounts.OperationCanceledException if the request was canceled for any
+     * reason
+     * @throws android.accounts.AuthenticatorException if there was an error communicating with
+     * the authenticator or if the authenticator returned an invalid response
+     * @throws java.io.IOException if the authenticator returned an error response that indicates
+     * that it encountered an IOException while communicating with the authentication server
      */
     V getResult() throws OperationCanceledException, IOException, AuthenticatorException;
 
     /**
-     * Wrapper for {@link java.util.concurrent.Future#get()}. If the get() throws
-     * {@link InterruptedException} then the
-     * {@link AccountManagerFuture} is canceled and
-     * {@link android.accounts.OperationCanceledException} is thrown.
+     * Accessor for the future result the {@link AccountManagerFuture} represents. This
+     * call will block until the result is available. In order to check if the result is
+     * available without blocking, one may call {@link #isDone()} and  {@link #isCancelled()}.
+     * If the request that generated this result fails or is canceled then an exception
+     * will be thrown rather than the call returning normally. If a timeout is specified then
+     * the request will automatically be canceled if it does not complete in that amount of time.
      * @param timeout the maximum time to wait
-     * @param unit the time unit of the timeout argument
-     * @return the {@link android.os.Bundle} that is returned by
-     * {@link java.util.concurrent.Future#get()}
-     * @throws android.accounts.OperationCanceledException if get() throws the unchecked
-     * {@link java.util.concurrent.CancellationException} or if the {@link AccountManagerFuture}
-     * was interrupted.
+     * @param unit the time unit of the timeout argument. This must not be null.
+     * @return the actual result
+     * @throws android.accounts.OperationCanceledException if the request was canceled for any
+     * reason
+     * @throws android.accounts.AuthenticatorException if there was an error communicating with
+     * the authenticator or if the authenticator returned an invalid response
+     * @throws java.io.IOException if the authenticator returned an error response that indicates
+     * that it encountered an IOException while communicating with the authentication server
      */
     V getResult(long timeout, TimeUnit unit)
             throws OperationCanceledException, IOException, AuthenticatorException;

core/java/android/accounts/AuthenticatorDescription.java

@@ -3,15 +3,33 @@ package android.accounts;
 import android.os.Parcelable;
 import android.os.Parcel;
 
+/**
+ * A {@link Parcelable} value type that contains information about an account authenticator.
+ */
 public class AuthenticatorDescription implements Parcelable {
+    /** The string that uniquely identifies an authenticator */
     final public String type;
+
+    /** A resource id of a label for the authenticator that is suitable for displaying */
     final public int labelId;
-    final public int iconId; 
-    final public int smallIconId; 
+
+    /** A resource id of a icon for the authenticator */
+    final public int iconId;
+
+    /** A resource id of a smaller icon for the authenticator */
+    final public int smallIconId;
+
+    /**
+     * A resource id for a hierarchy of PreferenceScreen to be added to the settings page for the
+     * account. See {@link AbstractAccountAuthenticator} for an example.
+     */
     final public int accountPreferencesId;
+
+    /** The package name that can be used to lookup the resources from above. */
     final public String packageName;
 
-    public AuthenticatorDescription(String type, String packageName, int labelId, int iconId, 
+    /** A constructor for a full AuthenticatorDescription */
+    public AuthenticatorDescription(String type, String packageName, int labelId, int iconId,
             int smallIconId, int prefId) {
         if (type == null) throw new IllegalArgumentException("type cannot be null");
         if (packageName == null) throw new IllegalArgumentException("packageName cannot be null");
@@ -23,6 +41,11 @@ public class AuthenticatorDescription implements Parcelable {
         this.accountPreferencesId = prefId;
     }
 
+    /**
+     * A factory method for creating an AuthenticatorDescription that can be used as a key
+     * to identify the authenticator by its type.
+     */
+
     public static AuthenticatorDescription newKey(String type) {
         if (type == null) throw new IllegalArgumentException("type cannot be null");
         return new AuthenticatorDescription(type);
@@ -46,14 +69,17 @@ public class AuthenticatorDescription implements Parcelable {
         this.accountPreferencesId = source.readInt();
     }
 
+    /** @inheritDoc */
     public int describeContents() {
         return 0;
     }
 
+    /** Returns the hashcode of the type only. */
     public int hashCode() {
         return type.hashCode();
     }
 
+    /** Compares the type only, suitable for key comparisons. */
     public boolean equals(Object o) {
         if (o == this) return true;
         if (!(o instanceof AuthenticatorDescription)) return false;
@@ -61,6 +87,7 @@ public class AuthenticatorDescription implements Parcelable {
         return type.equals(other.type);
     }
 
+    /** @inhericDoc */
     public void writeToParcel(Parcel dest, int flags) {
         dest.writeString(type);
         dest.writeString(packageName);
@@ -70,12 +97,15 @@ public class AuthenticatorDescription implements Parcelable {
         dest.writeInt(accountPreferencesId);
     }
 
+    /** Used to create the object from a parcel. */
     public static final Creator<AuthenticatorDescription> CREATOR =
             new Creator<AuthenticatorDescription>() {
+        /** @inheritDoc */
         public AuthenticatorDescription createFromParcel(Parcel source) {
             return new AuthenticatorDescription(source);
         }
 
+        /** @inheritDoc */
         public AuthenticatorDescription[] newArray(int size) {
             return new AuthenticatorDescription[size];
         }