universum.studios.android.preference

Class PreferencesManager

java.lang.Object

universum.studios.android.preference.PreferencesManager

All Implemented Interfaces:

SharedPreferencesFacade, SharedPreferencesProvider

public class PreferencesManager
extends Object
implements SharedPreferencesFacade, SharedPreferencesProvider

Manager which implements SharedPreferencesFacade along with SharedPreferencesProvider in order to provide a simple API for putting and obtaining of values persisted within SharedPreferences.

Shared preferences

The PreferencesManager is closely associated with SharedPreference. Any implementation of SharedPreference class may be used to represent a concrete preference value to be persisted in shared preferences. Methods listed below may be used to put, get or remove a desired shared preference into or from preferences managed by the preferences manager:

• putPreference(SharedPreference, Object)
• getPreference(SharedPreference)
• containsPreference(SharedPreference)
• removePreference(SharedPreference)

Sample implementation

 public final class AppPreferences extends PreferencesManager {

      private static final String KEY_PREFIX = BuildConfig.APPLICATION_ID = ".PREFERENCE.";
      private static final String KEY_APP_FIRST_LAUNCH = KEY_PREFIX + "AppFirstLaunch";

      public AppPreferences(@NonNull Context context) {
          super(context);
      }

      public void setAppFirstLaunch(boolean firstLaunch) {
          putBoolean(KEY_APP_FIRST_LAUNCH, firstLaunch);
      }

      public boolean isAppFirstLaunch() {
          return getBoolean(KEY_APP_FIRST_LAUNCH, true);
      }
 }
 

Since:

1.0

Author:

Martin Albedinsky

Constructor Summary

Constructors

Constructor and Description
PreferencesManager(Context context) Creates a new instance of PreferencesManager with the specified context.

Method Summary

Modifier and Type	Method and Description
boolean	contains(String key) Checks whether the SharedPreferences hidden behind this facade contain value for the specified key or not.
boolean	containsPreference(SharedPreference preference) Checks whether there is value associated with the specified preference contained within SharedPreferences that are managed by this manager.
boolean	getBoolean(String key, boolean defValue) Retrieves the boolean value for the specified key from SharedPreferences hidden behind this facade.
Context	getContext() Returns the context with which has been this manager created.
float	getFloat(String key, float defValue) Retrieves the float value for the specified key from SharedPreferences hidden behind this facade.
int	getInt(String key, int defValue) Retrieves the integer value for the specified key from SharedPreferences hidden behind this facade.
long	getLong(String key, long defValue) Retrieves the long value for the specified key from SharedPreferences hidden behind this facade.
<T> T	getPreference(SharedPreference<T> preference) Obtains the value for the given preference from SharedPreferences that are managed by this manager.
SharedPreferences	getSharedPreferences() Returns the instance of SharedPreferences provided by this provider.
int	getSharedPreferencesMode() Returns the mode for preferences file specified for this provider.
String	getSharedPreferencesName() Returns the name for preferences file specified for this provider.
String	getString(String key, String defValue) Retrieves the string value for the specified key from SharedPreferences hidden behind this facade.
Set<String>	getStringSet(String key, Set<String> defValues) Retrieves the set of string values for the specified key from SharedPreferences hidden behind this facade.
boolean	isCachingEnabled() Returns flag indicating whether the caching of SharedPreference's values is enabled or not.
String	key(int resId) Returns a string key for the specified resId.
boolean	putBoolean(String key, boolean value) Puts the given boolean value for the specified key into SharedPreferences hidden behind this facade.
boolean	putFloat(String key, float value) Puts the given float value for the specified key into SharedPreferences hidden behind this facade.
boolean	putInt(String key, int value) Puts the given integer value for the specified key into SharedPreferences hidden behind this facade.
boolean	putLong(String key, long value) Puts the given long value for the specified key into SharedPreferences hidden behind this facade.
<T> boolean	putPreference(SharedPreference<T> preference, T value) Persists the given value for the specified preference into SharedPreferences that are managed by this manager.
boolean	putString(String key, String value) Puts the given string value for the specified key into SharedPreferences hidden behind this facade.
boolean	putStringSet(String key, Set<String> values) Puts the given set of string values for the specified key into SharedPreferences hidden behind this facade.
void	registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener) Registers a listener in order to receive a callback whenever a value of preference persisted within the SharedPreferences hidden behind this facade changes.
boolean	remove(String key) Removes a value for the specified key from the SharedPreferences hidden behind this facade.
int	removeAll() Removes all values from the SharedPreferences hidden behind this facade.
boolean	removePreference(SharedPreference preference) Removes a value for the specified preference from SharedPreferences that are managed by this manager.
void	setCachingEnabled(boolean enabled) Enables/disables the caching SharedPreference's values.
void	setSharedPreferencesMode(int mode) Sets a mode for preferences file that is used by this provider to access instance of SharedPreferences via Context.getSharedPreferences(String, int).
void	setSharedPreferencesName(String name) Sets a name for preferences file that is used by this provider to access instance of SharedPreferences via Context.getSharedPreferences(String, int).
void	unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener) Un-registers a previously registered listener in order to not receive further any callbacks about preference changes.

Methods inherited from class java.lang.Object

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

Constructor Detail

PreferencesManager

public PreferencesManager(@NonNull
                          Context context)

Creates a new instance of PreferencesManager with the specified context.

Manager will be created with default name for shared preferences obtained via SharedPreferencesPolicies.defaultPreferencesName(Context) and mode set to SharedPreferencesPolicies.MODE_PRIVATE.

Parameters:

context - Context that is used to obtain instance of SharedPreferences for the new manager via Context.getSharedPreferences(String, int) for the name and mode specified via setSharedPreferencesName(String) and setSharedPreferencesMode(int).

Method Detail

getContext

@NonNull
public final Context getContext()

Returns the context with which has been this manager created.

Returns:

The associated context.

setSharedPreferencesName

public void setSharedPreferencesName(@Nullable
                                     String name)

Description copied from interface: SharedPreferencesProvider

Sets a name for preferences file that is used by this provider to access instance of SharedPreferences via Context.getSharedPreferences(String, int).

Specified by:

setSharedPreferencesName in interface SharedPreferencesProvider

Parameters:

name - The desired preferences name. May be null if this host should use default name provide by the framework.

See Also:

SharedPreferencesProvider.getSharedPreferencesName(), SharedPreferencesProvider.setSharedPreferencesMode(int), SharedPreferencesProvider.getSharedPreferences()

getSharedPreferencesName

@NonNull
public final String getSharedPreferencesName()

Description copied from interface: SharedPreferencesProvider

Returns the name for preferences file specified for this provider.

Default value: PreferenceManager#getDefaultSharedPreferencesName(Context)

Specified by:

getSharedPreferencesName in interface SharedPreferencesProvider

Returns:

Preferences name. If no name has been specified a default one will be returned.

See Also:

SharedPreferencesProvider.setSharedPreferencesName(String), SharedPreferencesProvider.getSharedPreferencesMode(), SharedPreferencesProvider.getSharedPreferences()

setSharedPreferencesMode

public void setSharedPreferencesMode(int mode)

Description copied from interface: SharedPreferencesProvider

Sets a mode for preferences file that is used by this provider to access instance of SharedPreferences via Context.getSharedPreferences(String, int).

Specified by:

setSharedPreferencesMode in interface SharedPreferencesProvider

Parameters:

mode - The desired preferences mode.

See Also:

SharedPreferencesProvider.getSharedPreferencesMode(), SharedPreferencesProvider.setSharedPreferencesName(String), SharedPreferencesProvider.getSharedPreferences()

getSharedPreferencesMode

public final int getSharedPreferencesMode()

Description copied from interface: SharedPreferencesProvider

Returns the mode for preferences file specified for this provider.

Default value: MODE_PRIVATE

Specified by:

getSharedPreferencesMode in interface SharedPreferencesProvider

Returns:

Preferences mode. If no mode has been specified a default one will be returned.

See Also:

SharedPreferencesProvider.setSharedPreferencesMode(int), SharedPreferencesProvider.getSharedPreferencesName(), SharedPreferencesProvider.getSharedPreferences()

getSharedPreferences

@NonNull
public final SharedPreferences getSharedPreferences()

Description copied from interface: SharedPreferencesProvider

Returns the instance of SharedPreferences provided by this provider.

Specified by:

getSharedPreferences in interface SharedPreferencesProvider

Returns:

The associated shared preferences.

See Also:

SharedPreferencesProvider.setSharedPreferencesName(String), SharedPreferencesProvider.setSharedPreferencesMode(int)

setCachingEnabled

public final void setCachingEnabled(boolean enabled)

Enables/disables the caching SharedPreference's values.

Parameters:

enabled - True to enable caching, false to disable.

See Also:

isCachingEnabled()

isCachingEnabled

public final boolean isCachingEnabled()

Returns flag indicating whether the caching of SharedPreference's values is enabled or not.

Returns:

True if caching is enabled, false otherwise.

See Also:

setCachingEnabled(boolean)

key

@NonNull
public final String key(@StringRes
                                 int resId)

Returns a string key for the specified resId.

Parameters:

resId - Resource id of the desired preference key.

Returns:

String key obtained from the context specified for this manager.

registerOnSharedPreferenceChangeListener

public void registerOnSharedPreferenceChangeListener(@NonNull
                                                     SharedPreferences.OnSharedPreferenceChangeListener listener)

Description copied from interface: SharedPreferencesFacade

Registers a listener in order to receive a callback whenever a value of preference persisted within the SharedPreferences hidden behind this facade changes.

Specified by:

registerOnSharedPreferenceChangeListener in interface SharedPreferencesFacade

Parameters:

listener - The desired listener to be registered.

See Also:

SharedPreferencesFacade.unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener), SharedPreferences.registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener)

unregisterOnSharedPreferenceChangeListener

public void unregisterOnSharedPreferenceChangeListener(@NonNull
                                                       SharedPreferences.OnSharedPreferenceChangeListener listener)

Description copied from interface: SharedPreferencesFacade

Un-registers a previously registered listener in order to not receive further any callbacks about preference changes.

Specified by:

unregisterOnSharedPreferenceChangeListener in interface SharedPreferencesFacade

Parameters:

listener - The desired listener to be un-registered.

See Also:

SharedPreferencesFacade.registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener), SharedPreferences.unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener)

contains

public boolean contains(@NonNull
                        String key)

Description copied from interface: SharedPreferencesFacade

Checks whether the SharedPreferences hidden behind this facade contain value for the specified key or not.

Specified by:

contains in interface SharedPreferencesFacade

Parameters:

key - The key of which value's presence to check.

Returns:

True if there is value contained for the specified key, false otherwise.

See Also:

SharedPreferencesFacade.remove(String), SharedPreferences.contains(String)

putString

public boolean putString(@NonNull
                         String key,
                         @Nullable
                         String value)

Description copied from interface: SharedPreferencesFacade

Puts the given string value for the specified key into SharedPreferences hidden behind this facade.

Specified by:

putString in interface SharedPreferencesFacade

Parameters:

key - The key for which to put the value into preferences.

value - The desired value to put into preferences.

Returns:

True if put has been successful, false otherwise.

See Also:

SharedPreferences.edit(), SharedPreferences.Editor#putString(String, String)

getString

@Nullable
public String getString(@NonNull
                                  String key,
                                  @Nullable
                                  String defValue)

Description copied from interface: SharedPreferencesFacade

Retrieves the string value for the specified key from SharedPreferences hidden behind this facade.

Specified by:

getString in interface SharedPreferencesFacade

Parameters:

key - The key for which to retrieve its associated value.

defValue - Default value to be returned in case when there is no value persisted for the specified key.

Returns:

Either persisted or default string value.

See Also:

SharedPreferencesFacade.contains(String), SharedPreferences.getString(String, String)

putStringSet

public boolean putStringSet(@NonNull
                            String key,
                            @Nullable
                            Set<String> values)

Description copied from interface: SharedPreferencesFacade

Puts the given set of string values for the specified key into SharedPreferences hidden behind this facade.

Specified by:

putStringSet in interface SharedPreferencesFacade

Parameters:

key - The key for which to put the values into preferences.

values - The desired values to put into preferences.

Returns:

True if put has been successful, false otherwise.

See Also:

SharedPreferences.edit(), SharedPreferences.Editor#putStringSet(String, Set)

getStringSet

@Nullable
public Set<String> getStringSet(@NonNull
                                          String key,
                                          @Nullable
                                          Set<String> defValues)

Description copied from interface: SharedPreferencesFacade

Retrieves the set of string values for the specified key from SharedPreferences hidden behind this facade.

Specified by:

getStringSet in interface SharedPreferencesFacade

Parameters:

key - The key for which to retrieve its associated values.

defValues - Default values to be returned in case when there are no values persisted for the specified key.

Returns:

Either persisted or default string values.

See Also:

SharedPreferencesFacade.contains(String), SharedPreferences.getStringSet(String, Set)

putInt

public boolean putInt(@NonNull
                      String key,
                      int value)

Description copied from interface: SharedPreferencesFacade

Puts the given integer value for the specified key into SharedPreferences hidden behind this facade.

Specified by:

putInt in interface SharedPreferencesFacade

Parameters:

key - The key for which to put the value into preferences.

value - The desired value to put into preferences.

Returns:

True if put has been successful, false otherwise.

See Also:

SharedPreferences.edit(), SharedPreferences.Editor#putInt(String, int)

getInt

public int getInt(@NonNull
                  String key,
                  int defValue)

Description copied from interface: SharedPreferencesFacade

Retrieves the integer value for the specified key from SharedPreferences hidden behind this facade.

Specified by:

getInt in interface SharedPreferencesFacade

Parameters:

key - The key for which to retrieve its associated value.

defValue - Default value to be returned in case when there is no value persisted for the specified key.

Returns:

Either persisted or default integer value.

See Also:

SharedPreferencesFacade.contains(String), SharedPreferences.getInt(String, int)

putFloat

public boolean putFloat(@NonNull
                        String key,
                        float value)

Description copied from interface: SharedPreferencesFacade

Puts the given float value for the specified key into SharedPreferences hidden behind this facade.

Specified by:

putFloat in interface SharedPreferencesFacade

Parameters:

key - The key for which to put the value into preferences.

value - The desired value to put into preferences.

Returns:

True if put has been successful, false otherwise.

See Also:

SharedPreferences.edit(), SharedPreferences.Editor#putFloat(String, float)

getFloat

public float getFloat(@NonNull
                      String key,
                      float defValue)

Description copied from interface: SharedPreferencesFacade

Retrieves the float value for the specified key from SharedPreferences hidden behind this facade.

Specified by:

getFloat in interface SharedPreferencesFacade

Parameters:

key - The key for which to retrieve its associated value.

defValue - Default value to be returned in case when there is no value persisted for the specified key.

Returns:

Either persisted or default float value.

See Also:

SharedPreferencesFacade.contains(String), SharedPreferences.getFloat(String, float)

putLong

public boolean putLong(@NonNull
                       String key,
                       long value)

Description copied from interface: SharedPreferencesFacade

Puts the given long value for the specified key into SharedPreferences hidden behind this facade.

Specified by:

putLong in interface SharedPreferencesFacade

Parameters:

key - The key for which to put the value into preferences.

value - The desired value to put into preferences.

Returns:

True if put has been successful, false otherwise.

See Also:

SharedPreferences.edit(), SharedPreferences.Editor#putLong(String, long)

getLong

public long getLong(@NonNull
                    String key,
                    long defValue)

Description copied from interface: SharedPreferencesFacade

Retrieves the long value for the specified key from SharedPreferences hidden behind this facade.

Specified by:

getLong in interface SharedPreferencesFacade

Parameters:

key - The key for which to retrieve its associated value.

defValue - Default value to be returned in case when there is no value persisted for the specified key.

Returns:

Either persisted or default long value.

See Also:

SharedPreferencesFacade.contains(String), SharedPreferences.getLong(String, long)

putBoolean

public boolean putBoolean(@NonNull
                          String key,
                          boolean value)

Description copied from interface: SharedPreferencesFacade

Puts the given boolean value for the specified key into SharedPreferences hidden behind this facade.

Specified by:

putBoolean in interface SharedPreferencesFacade

Parameters:

key - The key for which to put the value into preferences.

value - The desired value to put into preferences.

Returns:

True if put has been successful, false otherwise.

See Also:

SharedPreferences.edit(), SharedPreferences.Editor#putBoolean(String, boolean)

getBoolean

public boolean getBoolean(@NonNull
                          String key,
                          boolean defValue)

Description copied from interface: SharedPreferencesFacade

Retrieves the boolean value for the specified key from SharedPreferences hidden behind this facade.

Specified by:

getBoolean in interface SharedPreferencesFacade

Parameters:

key - The key for which to retrieve its associated value.

defValue - Default value to be returned in case when there is no value persisted for the specified key.

Returns:

Either persisted or default boolean value.

See Also:

SharedPreferencesFacade.contains(String), SharedPreferences.getBoolean(String, boolean)

remove

public boolean remove(@NonNull
                      String key)

Description copied from interface: SharedPreferencesFacade

Removes a value for the specified key from the SharedPreferences hidden behind this facade.

Specified by:

remove in interface SharedPreferencesFacade

Parameters:

key - The key for which to remove its associated value.

Returns:

True if removal has been successful, false otherwise.

See Also:

SharedPreferencesFacade.removeAll(), SharedPreferencesFacade.contains(String), SharedPreferences.edit(), SharedPreferences.Editor#remove(String)

removeAll

public int removeAll()

Description copied from interface: SharedPreferencesFacade

Removes all values from the SharedPreferences hidden behind this facade.

Specified by:

removeAll in interface SharedPreferencesFacade

Returns:

A none-negative number determining count of values that has been removed. May be 0 if there are no values persisted.

See Also:

SharedPreferencesFacade.remove(String), SharedPreferences.getAll(), SharedPreferences.edit(), SharedPreferences.Editor#remove(String)

putPreference

public final <T> boolean putPreference(@NonNull
                                       SharedPreference<T> preference,
                                       @Nullable
                                       T value)

Persists the given value for the specified preference into SharedPreferences that are managed by this manager.

Type Parameters:

T - Type of the value associated with the preference.

Parameters:

preference - Preference for which to persist the value.

value - The value to be persisted.

Returns:

True if put has been successful, false otherwise.

See Also:

getPreference(SharedPreference), containsPreference(SharedPreference), removePreference(SharedPreference), SharedPreference.updateValue(Object), SharedPreference.putIntoPreferences(SharedPreferences)

getPreference

@Nullable
public final <T> T getPreference(@NonNull
                                           SharedPreference<T> preference)

Obtains the value for the given preference from SharedPreferences that are managed by this manager.

Type Parameters:

T - Type of the value associated with the preference.

Parameters:

preference - Preference for which to obtain its associated value.

Returns:

Value associated with the preference. May be null if there is no value persisted for the preference yet.

See Also:

putPreference(SharedPreference, Object), contains(String), SharedPreference.getFromPreferences(SharedPreferences)

containsPreference

public final boolean containsPreference(@NonNull
                                        SharedPreference preference)

Checks whether there is value associated with the specified preference contained within SharedPreferences that are managed by this manager.

Parameters:

preference - The desired preference of which value's presence to check.

Returns:

True if there is value contained for key of the specified preference, false otherwise.

See Also:

putPreference(SharedPreference, Object), getPreference(SharedPreference), removePreference(SharedPreference)

removePreference

public final boolean removePreference(@NonNull
                                      SharedPreference preference)

Removes a value for the specified preference from SharedPreferences that are managed by this manager.

Parameters:

preference - The preference for which to remove its associated value.

Returns:

True if removal has been successful, false otherwise.

See Also:

putPreference(SharedPreference, Object), getPreference(SharedPreference), containsPreference(SharedPreference)