universum.studios.android.preference

Class PreferencesManager

java.lang.Object

universum.studios.android.preference.PreferencesManager

public abstract class PreferencesManager
extends Object

Manager that may be used to simplify management (storing + obtaining) of values presented within a SharedPreferences of an Android application.

Primitive types

The following methods can be used to store primitive types within shared preferences:

• putInt(String, int) - getInt(String, int)
• putFloat(String, float) - getInt(String, int)
• putLong(String, long) - getLong(String, long)
• putBoolean(String, boolean) - getBoolean(String, boolean)
• putString(String, String) - getString(String, String)

Arrays + Lists

See ArrayPreference and ListPreference.

Shared preferences

The PreferencesManager is closely related with SharedPreference. You can use any implementation of SharedPreference class to represent any of your shared preference values. The following methods can be used to store/retrieve actual values of these preferences:

• putPreference(SharedPreference, Object) - getPreference(SharedPreference)

Sample implementation

 public class AppPreferences extends PreferencesManager {

      // Key for the first app launch preference.
      private static final String KEY_APP_FIRST_LAUNCH = ".AppFirstLaunch";

      // Name of the shared preferences.
      private final String mPrefsName;

      // Creates a new instance of AppPreferences manager.
      public AppPreferences(Context context) {
          super(context);
          this.mPrefsName = getSharedPreferencesName();
      }

      // Stores a boolean flag into shared preferences indicating whether this is a first launch
      // of this app or not.
      public void saveIsAppFirstLaunch(boolean first) {
          putBoolean(mPrefsName + KEY_APP_FIRST_LAUNCH, first);
      }

      // Returns a boolean flag from shared preferences indicating whether this is a first launch
      // of this app or not.
      public boolean isAppFirstLaunch() {
          return getBoolean(mPrefsName + KEY_APP_FIRST_LAUNCH, true);
      }
 }
 

Author:

Martin Albedinsky

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	PreferencesManager.Mode Defines an annotation for determining set of allowed flags for setMode(int) method.

Field Summary

Fields

Modifier and Type	Field and Description
protected Context	mContext Application context used to access preferences.
static int	MODE_APPEND Wrapped mode: Context.MODE_APPEND
static int	MODE_ENABLE_WRITE_AHEAD_LOGGING Wrapped mode: Context.MODE_ENABLE_WRITE_AHEAD_LOGGING
static int	MODE_MULTI_PROCESS Wrapped mode: Context.MODE_MULTI_PROCESS
static int	MODE_PRIVATE Wrapped mode: Context.MODE_PRIVATE

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PreferencesManager(Context context) Same as PreferencesManager(Context, String) with default name for preferences (like the one provided by Android framework).
protected	PreferencesManager(Context context, String preferencesName) Same as PreferencesManager(Context, String, int) with Context.MODE_PRIVATE creation mode.
protected	PreferencesManager(Context context, String preferencesName, int mode) Creates a new instance of PreferencesManager with the given shared preferences name and preferences file creation mode.

Method Summary

Modifier and Type	Method and Description
boolean	contains(String key) Checks whether there is contained some value for the specified key in the share preferences.
boolean	containsPreference(SharedPreference preference) Checks whether value of the given preference is contained within the shared preferences.
static String	defaultSharedPreferencesName(Context context) Creates a default name for shared preferences (like the one created by PreferenceManager).
boolean	getBoolean(String key, boolean defValue) Returns the boolean value mapped in the shared preferences under the given key.
float	getFloat(String key, float defValue) Returns the float value mapped in the shared preferences under the given key.
int	getInt(String key, int defValue) Returns the int value mapped in the shared preferences under the given key.
long	getLong(String key, long defValue) Returns the long value mapped in the shared preferences under the given key.
protected int	getMode() Returns the actual file creation mode for shared preferences.
<Type> Type	getPreference(SharedPreference<Type> preference) Obtains the value of the given preference from shared preferences.
SharedPreferences	getSharedPreferences() Returns the instance of SharedPreferences depends on the current file creation mode and preferences name.
protected String	getSharedPreferencesName() Returns the actual name for shared preferences.
String	getString(String key, String defValue) Returns the String value mapped in the shared preferences under the given key.
protected boolean	isCachingEnabled() Returns flag indicating whether the caching of SharedPreference's values is enabled or not.
protected String	key(int resId) Returns a string key for the specified resId.
boolean	putBoolean(String key, boolean value) Saves the given boolean value into shared preferences.
boolean	putFloat(String key, float value) Saves the given float value into shared preferences.
boolean	putInt(String key, int value) Saves the given int value into shared preferences.
boolean	putLong(String key, long value) Saves the given long value into shared preferences.
<Type> boolean	putPreference(SharedPreference<Type> preference, Type value) Saves the given value using the specified preference into shared preferences.
boolean	putString(String key, String value) Saves the given String value into shared preferences.
void	registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener) Same as SharedPreferences.registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener).
boolean	remove(String key) Removes current value of a preference with the specified key from the shared preferences.
boolean	removePreference(SharedPreference preference) Removes current value of the given preference from the shared preferences.
protected void	setCachingEnabled(boolean enabled) Enables/disables the caching SharedPreference's values.
protected void	setMode(int mode) Sets the actual file creation mode for shared preferences.
protected void	setSharedPreferencesName(String name) Sets the actual name for shared preferences.
void	unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener listener) Same as SharedPreferences.unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener).

Methods inherited from class java.lang.Object

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

Field Detail

MODE_PRIVATE

public static final int MODE_PRIVATE

Wrapped mode: Context.MODE_PRIVATE

See Also:

Constant Field Values

MODE_MULTI_PROCESS

public static final int MODE_MULTI_PROCESS

Wrapped mode: Context.MODE_MULTI_PROCESS

See Also:

Constant Field Values

MODE_ENABLE_WRITE_AHEAD_LOGGING

public static final int MODE_ENABLE_WRITE_AHEAD_LOGGING

Wrapped mode: Context.MODE_ENABLE_WRITE_AHEAD_LOGGING

See Also:

Constant Field Values

MODE_APPEND

public static final int MODE_APPEND

Wrapped mode: Context.MODE_APPEND

See Also:

Constant Field Values

mContext

protected final Context mContext

Application context used to access preferences.

Constructor Detail

PreferencesManager

protected PreferencesManager(@NonNull
                             Context context)

Same as PreferencesManager(Context, String) with default name for preferences (like the one provided by Android framework).

PreferencesManager

protected PreferencesManager(@NonNull
                             Context context,
                             @NonNull
                             String preferencesName)

Same as PreferencesManager(Context, String, int) with Context.MODE_PRIVATE creation mode.

PreferencesManager

protected PreferencesManager(@NonNull
                             Context context,
                             @NonNull
                             String preferencesName,
                             int mode)

Creates a new instance of PreferencesManager with the given shared preferences name and preferences file creation mode.

Parameters:

context - Valid context to access shared preferences.

preferencesName - Name for shared preferences file.

mode - Shared preferences will be created in this mode.

Method Detail

defaultSharedPreferencesName

@NonNull
public static String defaultSharedPreferencesName(@NonNull
                                                            Context context)

Creates a default name for shared preferences (like the one created by PreferenceManager).

Parameters:

context - Context for which the name should be created.

Returns:

Default name for shared preferences.

getMode

protected final int getMode()

Returns the actual file creation mode for shared preferences.

Returns:

The shared preferences file creation mode. MODE_PRIVATE by default.

See Also:

Context, setMode(int)

setMode

protected final void setMode(int mode)

Sets the actual file creation mode for shared preferences. This mode is used whenever the instance of shared preferences is obtained to put/retrieve data to/from them.

Parameters:

mode - Preferences creation mode.

See Also:

getMode()

setSharedPreferencesName

protected final void setSharedPreferencesName(@Nullable
                                              String name)

Sets the actual name for shared preferences. This name is used whenever the instance of shared preferences is needed to put/retrieve data to/from it.

Note, that you can set this to null to retrieve always default shared preferences.

Parameters:

name - The desired name for shared preferences.

See Also:

getSharedPreferencesName(), getSharedPreferences()

getSharedPreferencesName

@Nullable
protected final String getSharedPreferencesName()

Returns the actual name for shared preferences.

Returns:

Name used to retrieve shared preferences.

See Also:

setSharedPreferencesName(String)

getSharedPreferences

@NonNull
public SharedPreferences getSharedPreferences()

Returns the instance of SharedPreferences depends on the current file creation mode and preferences name. If there is not currently provided name for shared preferences, the default one will be used.

Returns:

Instance of shared preferences.

See Also:

setMode(int), setSharedPreferencesName(String)

setCachingEnabled

protected 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

protected 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
protected 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 current context.

registerOnSharedPreferenceChangeListener

public void registerOnSharedPreferenceChangeListener(@NonNull
                                                     SharedPreferences.OnSharedPreferenceChangeListener listener)

Same as SharedPreferences.registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener).

Parameters:

listener - Listener callback to register up on the current shared preferences.

See Also:

getSharedPreferences(), unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener)

unregisterOnSharedPreferenceChangeListener

public void unregisterOnSharedPreferenceChangeListener(@NonNull
                                                       SharedPreferences.OnSharedPreferenceChangeListener listener)

Same as SharedPreferences.unregisterOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener).

Parameters:

listener - Listener callback to un-register up on the current shared preferences.

See Also:

getSharedPreferences(), registerOnSharedPreferenceChangeListener(SharedPreferences.OnSharedPreferenceChangeListener)

putInt

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

Saves the given int value into shared preferences.

Parameters:

key - The key under which will be the specified value mapped in the shared preferences.

value - Value to save.

Returns:

True if saving succeeded, false otherwise.

See Also:

getInt(String, int), contains(String), remove(String)

getInt

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

Returns the int value mapped in the shared preferences under the given key.

Parameters:

key - The key under which is the requested value mapped in the shared preferences.

defValue - Default value to return if there is no mapping for the specified key yet.

Returns:

int value obtained from the shared preferences or defValue if there is no mapping for the given key.

See Also:

putInt(String, int)

putFloat

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

Saves the given float value into shared preferences.

Parameters:

key - The key under which will be the specified value mapped in the shared preferences.

value - Value to save.

Returns:

True if saving succeeded, false otherwise.

See Also:

getFloat(String, float), contains(String), remove(String)

getFloat

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

Returns the float value mapped in the shared preferences under the given key.

Parameters:

key - The key under which is the requested value mapped in the shared preferences.

defValue - Default value to return if there is no mapping for the specified key yet.

Returns:

float value obtained from the shared preferences or defValue if there is no mapping for the specified key.

See Also:

putFloat(String, float)

putLong

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

Saves the given long value into shared preferences.

Parameters:

key - The key under which will be the specified value mapped in the shared preferences.

value - Value to save.

Returns:

True if saving succeeded, false otherwise.

See Also:

getLong(String, long), contains(String), remove(String)

getLong

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

Returns the long value mapped in the shared preferences under the given key.

Parameters:

key - The key under which is the requested value mapped in the shared preferences.

defValue - Default value to return if there is no mapping for the specified key yet.

Returns:

long value obtained from the shared preferences or defValue if there is no mapping for the specified key.

See Also:

putLong(String, long)

putBoolean

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

Saves the given boolean value into shared preferences.

Parameters:

key - The key under which will be the specified value mapped in the shared preferences.

value - Value to save.

Returns:

True if saving succeeded, false otherwise.

See Also:

getBoolean(String, boolean), contains(String), remove(String)

getBoolean

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

Returns the boolean value mapped in the shared preferences under the given key.

Parameters:

key - The key under which is the requested value mapped in the shared preferences.

defValue - Default value to return if there is no mapping for the specified key yet.

Returns:

boolean value obtained from the shared preferences or defValue if there is no mapping for the specified key.

See Also:

putBoolean(String, boolean)

putString

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

Saves the given String value into shared preferences.

Parameters:

key - The key under which will be the specified value mapped in the shared preferences.

value - Value to save.

Returns:

True if saving succeeded, false otherwise.

See Also:

getString(String, String), contains(String), remove(String)

getString

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

Returns the String value mapped in the shared preferences under the given key.

Parameters:

key - The key under which is the requested value mapped in the shared preferences.

defValue - Default value to return if there is no mapping for the specified key yet.

Returns:

String value obtained from the shared preferences or defValue if there is no mapping for the specified key.

See Also:

putString(String, String)

contains

public final boolean contains(@NonNull
                              String key)

Checks whether there is contained some value for the specified key in the share preferences.

Parameters:

key - Key of the desired preference of which value to check.

Returns:

True if some value for the requested key is stored, false otherwise.

See Also:

remove(String)

remove

public final boolean remove(@NonNull
                            String key)

Removes current value of a preference with the specified key from the shared preferences.

Parameters:

key - Key of the desired preference of which value (entry) should be removed.

Returns:

True if current value of shared preference has been removed, false if some error occurred.

See Also:

contains(String)

putPreference

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

Saves the given value using the specified preference into shared preferences.

Parameters:

preference - Preference of which value should be saved.

value - The value of preference to save into shared preferences.

Returns:

True if save operation succeeded, false otherwise.

See Also:

getPreference(SharedPreference), containsPreference(SharedPreference), removePreference(SharedPreference)

getPreference

public final <Type> Type getPreference(@NonNull
                                       SharedPreference<Type> preference)

Obtains the value of the given preference from shared preferences.

Parameters:

preference - Preference of which value should be obtained.

Returns:

Value of the given shared preference.

See Also:

putPreference(SharedPreference, Object)

containsPreference

public final boolean containsPreference(@NonNull
                                        SharedPreference preference)

Checks whether value of the given preference is contained within the shared preferences.

Parameters:

preference - The desired preference of which value to check.

Returns:

True if some value for the specified preference is stored, false otherwise.

See Also:

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

removePreference

public final boolean removePreference(@NonNull
                                      SharedPreference preference)

Removes current value of the given preference from the shared preferences.

Parameters:

preference - The desired preference of which value (entry) should be removed.

Returns:

True if current value of shared preference has been removed, false if some error occurred.

See Also:

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