universum.studios.android.officium.account

Class UserAccountManager<A extends UserAccount>

java.lang.Object

universum.studios.android.officium.account.UserAccountManager<A>

Type Parameters:

A - Type of the user account that will be managed by the UserAccountManager subclass.

Direct Known Subclasses:

SingleUserAccountManager

public abstract class UserAccountManager<A extends UserAccount>
extends Object

Wrapper for AccountManager that can be used to simplify management of an Android application accounts. Each instance of UserAccountManager can manage accounts only of a single type that is specified during initialization via UserAccountManager(Context, String) constructor. UserAccountManager can be used for both creation and deletion of Android accounts via createAccount(UserAccount) and deleteAccount(UserAccount) or via theirs asynchronous relatives createAccountAsync(UserAccount) and deleteAccountAsync(UserAccount).

This manager also provides API methods to store and peek authentication tokens for a specific account via setAccountAuthToken(Account, String, String) and peekAccountAuthToken(Account, String) along with account's password management via setAccountPassword(Account, String) and getAccountPassword(Account). Data for a specific account can be stored either as single values via setAccountData(Account, String, String) or as data Bundle via setAccountDataBundle(Account, Bundle) which is basically bulk method for the single value storing method. Stored account data can be than obtained via getAccountData(Account, String) or via getAccountDataBundle(Account, String...).

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	UserAccountManager.AccountWatcher<A extends UserAccount> Watcher that may be used to listen for callbacks fired whenever a new Android Account is created or deleted asynchronously for its associated UserAccount.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ERROR_CREATE_ACCOUNT Error code indicating that an error occurred during asynchronous execution of onCreateAccount(UserAccount) requested via createAccountAsync(UserAccount).
static int	ERROR_DELETE_ACCOUNT Error code indicating that an error occurred during asynchronous execution of onDeleteAccount(UserAccount) requested via deleteAccountAsync(UserAccount).
protected String	mAccountType Type of accounts that can be managed by this manager.
protected Context	mContext Context used to access mManager and other needed application data about accounts.
protected AccountManager	mManager Account manager used to create/update/delete accounts of the type specified for this manager.
protected static String	PERMISSION_AUTHENTICATE_ACCOUNTS Value for Android permission to AUTHENTICATE accounts.
protected static String	PERMISSION_GET_ACCOUNTS Value for Android permission to GET accounts.
protected static String	PERMISSION_MANAGE_ACCOUNTS Value for Android permission to MANAGE accounts.

Constructor Summary

Constructors

Constructor and Description
UserAccountManager(Context context, String accountType) Creates a new instance of UserAccountManager for the specified accountType.

Method Summary

Modifier and Type	Method and Description
void	clearAccountPassword(Account account) Clears the password for the given account.
boolean	createAccount(A userAccount) Creates a new Android Account for the given userAccount.
void	createAccountAsync(A userAccount) Same as createAccount(UserAccount) where creation of the given userAccount will be executed asynchronously using AsyncTask.
boolean	deleteAccount(A userAccount) Deletes an existing Android Account for the given userAccount.
void	deleteAccountAsync(A userAccount) Same as deleteAccount(UserAccount) where deletion of the given userAccount will be executed asynchronously using AsyncTask.
protected Account	findAccountForUser(A userAccount) Called to find the Android Account associated with the given userAccount.
String	getAccountData(Account account, String key) Returns the single data for the given account stored under the specified key.
Bundle	getAccountDataBundle(Account account, String... keys) Returns the bundle with data for the given account.
String	getAccountPassword(Account account) Returns the password for the given account.
void	invalidateAccountAuthToken(Account account, String authToken) Invalidates the specified authToken for the given account.
boolean	isAccountAuthenticated(Account account, String authTokenType) Checks whether the given account is authenticated or not.
protected boolean	onCreateAccount(A userAccount) Invoked whenever createAccount(UserAccount) or createAccountAsync(UserAccount) is called to create new Android Account.
protected boolean	onDeleteAccount(A userAccount) Invoked whenever createAccount(UserAccount) or createAccountAsync(UserAccount) is called to create new Android Account.
String	peekAccountAuthToken(Account account, String authTokenType) Returns the authentication token for the given account stored for the specified authTokenType.
void	registerWatcher(UserAccountManager.AccountWatcher<A> watcher) Registers a watcher to be notified whenever a new user account is created or an old one deleted.
void	setAccountAuthToken(Account account, String authTokenType, String authToken) Sets an authentication token for the given account with the specified authTokenType.
void	setAccountData(Account account, String key, String value) Sets a single data value for the given account with the specified key.
void	setAccountDataBundle(Account account, Bundle dataBundle) Sets a bundle with data for the given account.
void	setAccountPassword(Account account, String password) Sets a password for the given account.
void	unregisterWatcher(UserAccountManager.AccountWatcher<A> watcher) Unregisters the given watcher from the registered ones.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ERROR_CREATE_ACCOUNT

public static final int ERROR_CREATE_ACCOUNT

Error code indicating that an error occurred during asynchronous execution of onCreateAccount(UserAccount) requested via createAccountAsync(UserAccount).

See Also:

Constant Field Values

ERROR_DELETE_ACCOUNT

public static final int ERROR_DELETE_ACCOUNT

Error code indicating that an error occurred during asynchronous execution of onDeleteAccount(UserAccount) requested via deleteAccountAsync(UserAccount).

See Also:

Constant Field Values

PERMISSION_GET_ACCOUNTS

protected static final String PERMISSION_GET_ACCOUNTS

Value for Android permission to GET accounts.

See Also:

Constant Field Values

PERMISSION_MANAGE_ACCOUNTS

protected static final String PERMISSION_MANAGE_ACCOUNTS

Value for Android permission to MANAGE accounts.

See Also:

Constant Field Values

PERMISSION_AUTHENTICATE_ACCOUNTS

protected static final String PERMISSION_AUTHENTICATE_ACCOUNTS

Value for Android permission to AUTHENTICATE accounts.

See Also:

Constant Field Values

mContext

protected final Context mContext

Context used to access mManager and other needed application data about accounts.

mManager

protected final AccountManager mManager

Account manager used to create/update/delete accounts of the type specified for this manager.

mAccountType

protected final String mAccountType

Type of accounts that can be managed by this manager.

Constructor Detail

UserAccountManager

public UserAccountManager(@NonNull
                          Context context,
                          @NonNull
                          String accountType)

Creates a new instance of UserAccountManager for the specified accountType.

Parameters:

context - Context used to access AccountManager.

accountType - The desired type of accounts that can be managed by the new manager.

Method Detail

registerWatcher

public void registerWatcher(@NonNull
                            UserAccountManager.AccountWatcher<A> watcher)

Registers a watcher to be notified whenever a new user account is created or an old one deleted.

Parameters:

watcher - The desired watcher to register.

See Also:

unregisterWatcher(AccountWatcher)

unregisterWatcher

public void unregisterWatcher(@NonNull
                              UserAccountManager.AccountWatcher<A> watcher)

Unregisters the given watcher from the registered ones.

Parameters:

watcher - The desired watcher to unregister.

See Also:

registerWatcher(AccountWatcher)

createAccountAsync

public void createAccountAsync(@NonNull
                               A userAccount)

Same as createAccount(UserAccount) where creation of the given userAccount will be executed asynchronously using AsyncTask. When the creation process is finished the current AccountWatchers (if any) will be notified through UserAccountManager.AccountWatcher.onAccountCreated(UserAccount) callback.

This method requires the caller to hold PERMISSION_GET_ACCOUNTS along with PERMISSION_AUTHENTICATE_ACCOUNTS permissions.

Parameters:

userAccount - The desired user account for which to create a corresponding Android Account.

See Also:

registerWatcher(AccountWatcher), deleteAccountAsync(UserAccount)

createAccount

public boolean createAccount(@NonNull
                             A userAccount)

Creates a new Android Account for the given userAccount.

This method requires the caller to hold PERMISSION_GET_ACCOUNTS along with PERMISSION_AUTHENTICATE_ACCOUNTS permissions.

Parameters:

userAccount - The desired user account for which to create the corresponding Android Account.

Returns:

True if the account has been created, false otherwise.

See Also:

createAccountAsync(UserAccount), deleteAccount(UserAccount), AccountManager.addAccountExplicitly(Account, String, Bundle), AccountManager.setAuthToken(Account, String, String)

onCreateAccount

protected boolean onCreateAccount(@NonNull
                                  A userAccount)

Invoked whenever createAccount(UserAccount) or createAccountAsync(UserAccount) is called to create new Android Account.

Note, that this method can be invoked on a background thread.

Current implementation always returns true.

This method requires the caller to hold PERMISSION_GET_ACCOUNTS along with PERMISSION_AUTHENTICATE_ACCOUNTS permissions.

Parameters:

userAccount - The desired user account for which to create the corresponding Android Account.

Returns:

True if account has been created, false otherwise.

See Also:

onDeleteAccount(UserAccount), AccountManager.addAccountExplicitly(Account, String, Bundle), AccountManager.setAuthToken(Account, String, String)

setAccountAuthToken

public void setAccountAuthToken(@NonNull
                                Account account,
                                @NonNull
                                String authTokenType,
                                @Nullable
                                String authToken)

Sets an authentication token for the given account with the specified authTokenType.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to update its authentication token.

authTokenType - Type of the authentication token to be stored used as key.

authToken - The desired authentication token to be stored.

See Also:

peekAccountAuthToken(Account, String), isAccountAuthenticated(Account, String), AccountManager.setAuthToken(Account, String, String)

isAccountAuthenticated

public boolean isAccountAuthenticated(@NonNull
                                      Account account,
                                      @NonNull
                                      String authTokenType)

Checks whether the given account is authenticated or not.

By default the account is considered authenticated if there is stored authentication token for that account with the specified authTokenType.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to check its authentication state.

authTokenType - Type of the authentication token used to resolve whether the account is authenticated or not.

Returns:

True if there is stored valid authentication token for the account with the specified token type, false otherwise.

See Also:

setAccountAuthToken(Account, String, String), peekAccountAuthToken(Account, String)

peekAccountAuthToken

@Nullable
public String peekAccountAuthToken(@NonNull
                                              Account account,
                                              @NonNull
                                              String authTokenType)

Returns the authentication token for the given account stored for the specified authTokenType.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to peek the requested authentication token.

authTokenType - Type of the requested authentication token to peek.

Returns:

Authentication token or null if there has not been stored token for the requested type yet or the token has been invalidated.

See Also:

setAccountAuthToken(Account, String, String), invalidateAccountAuthToken(Account, String), AccountManager.peekAuthToken(Account, String)

invalidateAccountAuthToken

public void invalidateAccountAuthToken(@NonNull
                                       Account account,
                                       @NonNull
                                       String authToken)

Invalidates the specified authToken for the given account.

This method requires the caller to hold PERMISSION_MANAGE_ACCOUNTS permission.

Parameters:

account - The account for which to invalidate the authentication token.

authToken - The token that should be invalidated.

See Also:

peekAccountAuthToken(Account, String), AccountManager.invalidateAuthToken(String, String)

setAccountPassword

public void setAccountPassword(@NonNull
                               Account account,
                               @Nullable
                               String password)

Sets a password for the given account.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to update its password.

password - The desired password to be stored.

See Also:

getAccountPassword(Account), clearAccountPassword(Account), AccountManager.setPassword(Account, String)

getAccountPassword

@Nullable
public String getAccountPassword(@NonNull
                                            Account account)

Returns the password for the given account.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to obtain the requested password.

Returns:

Requested password or null if there has not been stored any password for the account yet.

See Also:

setAccountPassword(Account, String), clearAccountPassword(Account), AccountManager.getPassword(Account)

clearAccountPassword

public void clearAccountPassword(@NonNull
                                 Account account)

Clears the password for the given account.

This method requires the caller to hold PERMISSION_MANAGE_ACCOUNTS permission.

Parameters:

account - The account for which to clear its password.

See Also:

AccountManager.clearPassword(Account)

setAccountData

public void setAccountData(@NonNull
                           Account account,
                           @NonNull
                           String key,
                           @Nullable
                           String value)

Sets a single data value for the given account with the specified key.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to update its data.

key - The key under which will be the desired value stored.

value - The desired data value to be stored.

See Also:

getAccountData(Account, String), setAccountDataBundle(Account, Bundle), AccountManager.setUserData(Account, String, String)

getAccountData

@Nullable
public String getAccountData(@NonNull
                                        Account account,
                                        @NonNull
                                        String key)

Returns the single data for the given account stored under the specified key.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to obtain its data.

key - The key for which to obtain the requested account data.

Returns:

Requested account data or null if there are no data stored for the requested key.

See Also:

setAccountData(Account, String, String), AccountManager.getUserData(Account, String)

setAccountDataBundle

public void setAccountDataBundle(@NonNull
                                 Account account,
                                 @NonNull
                                 Bundle dataBundle)

Sets a bundle with data for the given account.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to update its data bundle.

dataBundle - Bundle with the desired data.

See Also:

getAccountDataBundle(Account, String...), setAccountData(Account, String, String)

getAccountDataBundle

@NonNull
public Bundle getAccountDataBundle(@NonNull
                                             Account account,
                                             @NonNull
                                             String... keys)

Returns the bundle with data for the given account.

This method requires the caller to hold PERMISSION_AUTHENTICATE_ACCOUNTS permission.

Parameters:

account - The account for which to obtain its data bundle.

keys - Set of keys for which to obtain the desired data.

Returns:

Bundle with account data for the requested keys. May be empty if the specified keys are also empty.

See Also:

setAccountDataBundle(Account, Bundle), getAccountData(Account, String)

deleteAccountAsync

public void deleteAccountAsync(@NonNull
                               A userAccount)

Same as deleteAccount(UserAccount) where deletion of the given userAccount will be executed asynchronously using AsyncTask. When the deletion process is finished the current AccountWatchers (if any) will be notified through UserAccountManager.AccountWatcher.onAccountDeleted(UserAccount) callback.

This method requires the caller to hold PERMISSION_GET_ACCOUNTS along with PERMISSION_AUTHENTICATE_ACCOUNTS permissions.

Parameters:

userAccount - The desired user account for which to delete the corresponding Android Account.

See Also:

registerWatcher(AccountWatcher), deleteAccount(UserAccount), createAccountAsync(UserAccount)

deleteAccount

public boolean deleteAccount(@NonNull
                             A userAccount)

Deletes an existing Android Account for the given userAccount.

This method requires the caller to hold PERMISSION_GET_ACCOUNTS along with PERMISSION_AUTHENTICATE_ACCOUNTS permissions.

Parameters:

userAccount - The desired user account for which to delete the corresponding Android Account.

Returns:

True if the account has been deleted, false otherwise.

See Also:

deleteAccountAsync(UserAccount), createAccount(UserAccount), AccountManager.removeAccount(Account, AccountManagerCallback, Handler), AccountManager.invalidateAuthToken(String, String)

onDeleteAccount

protected boolean onDeleteAccount(@NonNull
                                  A userAccount)

Invoked whenever createAccount(UserAccount) or createAccountAsync(UserAccount) is called to create new Android Account.

Note, that this method can be invoked on a background thread.

Current implementation returns true whenever there has been found Android account to be deleted for the given user account, false otherwise.

This method requires the caller to hold PERMISSION_GET_ACCOUNTS along with PERMISSION_AUTHENTICATE_ACCOUNTS permissions.

Parameters:

userAccount - The desired user account for which to delete the corresponding Android Account.

Returns:

True if account has been deleted, false otherwise.

See Also:

onCreateAccount(UserAccount)

findAccountForUser

@Nullable
protected Account findAccountForUser(@NonNull
                                                A userAccount)

Called to find the Android Account associated with the given userAccount.

Default implementation retrieves all current accounts by the account type specified for this manager and searches for one that has same name specified as the given user account. See UserAccount.getName() and Account.name for additional information.

This method requires the caller to hold PERMISSION_GET_ACCOUNTS permission.

Parameters:

userAccount - The user account for which to find the corresponding Android account.

Returns:

Android account that has been previously created for the given user account or null if there is no account created for the requested user account.