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 Deprecated. Use getAccountType() instead.
protected android.content.Context	mContext Deprecated. Use getContext() instead.
protected android.accounts.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(android.content.Context context, String accountType) Creates a new instance of UserAccountManager for the specified accountType.

Method Summary

Modifier and Type	Method and Description
void	clearAccountPassword(android.accounts.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 android.accounts.Account	findAccountForUser(A userAccount) Called to find the Android Account associated with the given userAccount.
String	getAccountData(android.accounts.Account account, String key) Returns the single data for the given account stored under the specified key.
android.os.Bundle	getAccountDataBundle(android.accounts.Account account, String... keys) Returns the bundle with data for the given account.
String	getAccountPassword(android.accounts.Account account) Returns the password for the given account.
String	getAccountType() Returns the type of account that this manager can manage (add, rename, remove).
android.content.Context	getContext() Returns the context with which has been this manager created.
void	invalidateAccountAuthToken(android.accounts.Account account, String authToken) Invalidates the specified authToken for the given account.
boolean	isAccountAuthenticated(android.accounts.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(android.accounts.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(android.accounts.Account account, String authTokenType, String authToken) Sets an authentication token for the given account with the specified authTokenType.
void	setAccountData(android.accounts.Account account, String key, String value) Sets a single data value for the given account with the specified key.
void	setAccountDataBundle(android.accounts.Account account, android.os.Bundle dataBundle) Sets a bundle with data for the given account.
void	setAccountPassword(android.accounts.Account account, String password) Sets a password for the given account.
void	setDataCrypto(Crypto crypto) Sets an implementation of Crypto that should be used by this account manager to perform account data encryption/decryption operations.
void	setKeyEncrypto(Encrypto encrypto) Sets an implementation of Encrypto that should be used by this account manager to perform account data keys encryption operation.
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

mManager

protected final android.accounts.AccountManager mManager

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

mContext

@Deprecated
protected final android.content.Context mContext

Deprecated. Use getContext() instead.

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

mAccountType

@Deprecated
protected final String mAccountType

Deprecated. Use getAccountType() instead.

Type of accounts that can be managed by this manager.

Constructor Detail

UserAccountManager

public UserAccountManager(android.content.Context context,
                          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

getContext

public final android.content.Context getContext()

Returns the context with which has been this manager created.

Returns:

The associated context.

See Also:

UserAccountManager(Context, String)

getAccountType

public final String getAccountType()

Returns the type of account that this manager can manage (add, rename, remove).

Returns:

The associated account type.

See Also:

UserAccountManager(Context, String)

registerWatcher

public void registerWatcher(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(UserAccountManager.AccountWatcher<A> watcher)

Unregisters the given watcher from the registered ones.

Parameters:

watcher - The desired watcher to unregister.

See Also:

registerWatcher(AccountWatcher)

setKeyEncrypto

public final void setKeyEncrypto(Encrypto encrypto)

Sets an implementation of Encrypto that should be used by this account manager to perform account data keys encryption operation.

Parameters:

encrypto - The desired encrypto implementation. May be null to not perform keys encryption.

See Also:

setDataCrypto(Crypto)

setDataCrypto

public final void setDataCrypto(Crypto crypto)

Sets an implementation of Crypto that should be used by this account manager to perform account data encryption/decryption operations.

Note, that if specified, the provided crypto will be also used for password encryption/decryption operations.

Parameters:

crypto - The desired crypto implementation. May be null to not perform data encryption/decryption.

See Also:

setKeyEncrypto(Encrypto), setAccountData(Account, String, String), getAccountData(Account, String), getAccountDataBundle(Account, String...)

createAccountAsync

public void createAccountAsync(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(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(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(android.accounts.Account account,
                                String authTokenType,
                                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(android.accounts.Account account,
                                      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

public String peekAccountAuthToken(android.accounts.Account account,
                                   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(android.accounts.Account account,
                                       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(android.accounts.Account account,
                               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

public String getAccountPassword(android.accounts.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(android.accounts.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(android.accounts.Account account,
                           String key,
                           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

public String getAccountData(android.accounts.Account account,
                             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(android.accounts.Account account,
                                 android.os.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

public android.os.Bundle getAccountDataBundle(android.accounts.Account account,
                                              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(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(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.

Note, that this method may be only invoked from a background thread. If invoked from the main UI thread an exception will be thrown. For none-blocking call use deleteAccountAsync(UserAccount) instead.

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(A userAccount)

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

Note, that invocation of this method need to be always on a background thread otherwise an exception will be thrown.

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

protected android.accounts.Account findAccountForUser(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.