universum.studios.android.preference

Class PreferencesManager

java.lang.Object

universum.studios.android.preference.SimpleSharedPreferencesFacade

universum.studios.android.preference.PreferencesManager

All Implemented Interfaces:

SharedPreferencesFacade

public class PreferencesManager
extends SimpleSharedPreferencesFacade

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:

• SimpleSharedPreferencesFacade.putInt(String, int) - SimpleSharedPreferencesFacade.getInt(String, int)
• SimpleSharedPreferencesFacade.putFloat(String, float) - SimpleSharedPreferencesFacade.getInt(String, int)
• SimpleSharedPreferencesFacade.putLong(String, long) - SimpleSharedPreferencesFacade.getLong(String, long)
• SimpleSharedPreferencesFacade.putBoolean(String, boolean) - SimpleSharedPreferencesFacade.getBoolean(String, boolean)
• SimpleSharedPreferencesFacade.putString(String, String) - SimpleSharedPreferencesFacade.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 class	PreferencesManager.Builder Builder that may be used to creates new instances of PreferencesManager with a desired configuration.
static interface	PreferencesManager.Mode Deprecated. Use @SharedPreferencesPolicy.FileMode instead.

Field Summary

Fields

Modifier and Type	Field and Description
protected android.content.Context	mContext Context that has been specified during initialization of this manager instance.
static int	MODE_APPEND Deprecated. Use SharedPreferencesPolicy.FILE_MODE_APPEND instead.
static int	MODE_ENABLE_WRITE_AHEAD_LOGGING Deprecated. This flag is appropriate only for database files.
static int	MODE_MULTI_PROCESS Deprecated. Deprecated due to deprecation in the framework. See Context.MODE_MULTI_PROCESS.
static int	MODE_PRIVATE Deprecated. Use SharedPreferencesPolicy.FILE_MODE_PRIVATE instead.

Constructor Summary

Constructors

Modifier	Constructor and Description
	PreferencesManager(android.content.Context context) Deprecated. Use PreferencesManager(Builder) instead.
	PreferencesManager(android.content.Context context, String preferencesName) Deprecated. Use PreferencesManager(Builder) instead.
	PreferencesManager(android.content.Context context, String preferencesName, int preferencesFileMode) Deprecated. Use PreferencesManager(Builder) instead.
protected	PreferencesManager(PreferencesManager.Builder builder) todo:

Method Summary

Modifier and Type	Method and Description
boolean	containsPreference(SharedPreference preference) Checks whether there is value associated with the specified preference contained within SharedPreferences that are managed by this manager.
static String	defaultSharedPreferencesName(android.content.Context context) Deprecated. Use SharedPreferencesPolicy.defaultPreferencesName(Context) instead.
protected int	getMode() Deprecated. Use getPreferencesFileMode() instead.
<T> T	getPreference(SharedPreference<T> preference) Obtains the value for the given preference from SharedPreferences that are managed by this manager.
int	getPreferencesFileMode() Returns the file mode of SharedPreferences that are managed by this manager.
String	getPreferencesName() Returns the name of SharedPreferences that are managed by this manager.
android.content.SharedPreferences	getSharedPreferences() Deprecated. Use SimpleSharedPreferencesFacade.getPreferences() instead.
protected String	getSharedPreferencesName() Deprecated. Use getPreferencesName() instead.
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.
<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	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.
protected void	setMode(int mode) Deprecated. The new implementation of preferences manager does not support changing of preferences file mode after the manager has been initialized.
protected void	setSharedPreferencesName(String name) Deprecated. The new implementation of preferences manager does not support changing of preferences name after the manager has been initialized.

Methods inherited from class universum.studios.android.preference.SimpleSharedPreferencesFacade

contains, getBoolean, getFloat, getInt, getLong, getPreferences, getString, getStringSet, putBoolean, putFloat, putInt, putLong, putString, putStringSet, registerOnSharedPreferenceChangeListener, remove, removeAll, unregisterOnSharedPreferenceChangeListener

Methods inherited from class java.lang.Object

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

Field Detail

MODE_PRIVATE

@Deprecated
public static final int MODE_PRIVATE

Deprecated. Use SharedPreferencesPolicy.FILE_MODE_PRIVATE instead.

This constant has been deprecated and will be removed in the next release.

Wrapped mode: Context.MODE_PRIVATE

See Also:

Constant Field Values

MODE_MULTI_PROCESS

@Deprecated
public static final int MODE_MULTI_PROCESS

Deprecated. Deprecated due to deprecation in the framework. See Context.MODE_MULTI_PROCESS.

This constant has been deprecated and will be removed in the next release.

Wrapped mode: Context.MODE_MULTI_PROCESS

See Also:

Constant Field Values

MODE_ENABLE_WRITE_AHEAD_LOGGING

@Deprecated
public static final int MODE_ENABLE_WRITE_AHEAD_LOGGING

Deprecated. This flag is appropriate only for database files.

This constant has been deprecated and will be removed in the next release.

Wrapped mode: Context.MODE_ENABLE_WRITE_AHEAD_LOGGING

See Also:

Constant Field Values

MODE_APPEND

@Deprecated
public static final int MODE_APPEND

Deprecated. Use SharedPreferencesPolicy.FILE_MODE_APPEND instead.

This constant has been deprecated and will be removed in the next release.

Wrapped mode: Context.MODE_APPEND

See Also:

Constant Field Values

mContext

protected final android.content.Context mContext

Context that has been specified during initialization of this manager instance.

Constructor Detail

PreferencesManager

@Deprecated
public PreferencesManager(android.content.Context context)

Deprecated. Use PreferencesManager(Builder) instead.

This constructor has been deprecated and will be removed in the next release.

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

PreferencesManager

@Deprecated
public PreferencesManager(android.content.Context context,
                                      String preferencesName)

Deprecated. Use PreferencesManager(Builder) instead.

This constructor has been deprecated and will be removed in the next release.

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

PreferencesManager

@Deprecated
public PreferencesManager(android.content.Context context,
                                      String preferencesName,
                                      int preferencesFileMode)

Deprecated. Use PreferencesManager(Builder) instead.

This constructor has been deprecated and will be removed in the next release.

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.

preferencesFileMode - Shared preferences will be created in this mode.

PreferencesManager

protected PreferencesManager(PreferencesManager.Builder builder)

todo:

Parameters:

builder -

Method Detail

getPreferencesName

public final String getPreferencesName()

Returns the name of SharedPreferences that are managed by this manager.

Returns:

The associated preference's name.

See Also:

PreferencesManager.Builder.preferencesName(String), SimpleSharedPreferencesFacade.getPreferences(), getPreferencesFileMode()

getPreferencesFileMode

public final int getPreferencesFileMode()

Returns the file mode of SharedPreferences that are managed by this manager.

Returns:

The associated preference's file mode.

See Also:

PreferencesManager.Builder.preferencesFileMode(int), SimpleSharedPreferencesFacade.getPreferences(), getPreferencesName()

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

protected final String key(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.

putPreference

public final <T> boolean putPreference(SharedPreference<T> preference,
                                       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

public final <T> T getPreference(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), SimpleSharedPreferencesFacade.contains(String), SharedPreference.getFromPreferences(SharedPreferences)

containsPreference

public final boolean containsPreference(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(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)

defaultSharedPreferencesName

@Deprecated
public static String defaultSharedPreferencesName(android.content.Context context)

Deprecated. Use SharedPreferencesPolicy.defaultPreferencesName(Context) instead.

This method has been deprecated and will be removed in the next release.

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.

setMode

@Deprecated
protected final void setMode(int mode)

Deprecated. The new implementation of preferences manager does not support changing of preferences file mode after the manager has been initialized.

This method has been deprecated and will be removed in the next release.

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

getMode

@Deprecated
protected final int getMode()

Deprecated. Use getPreferencesFileMode() instead.

This method has been deprecated and will be removed in the next release.

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)

setSharedPreferencesName

@Deprecated
protected final void setSharedPreferencesName(String name)

Deprecated. The new implementation of preferences manager does not support changing of preferences name after the manager has been initialized.

This method has been deprecated and will be removed in the next release.

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

@Deprecated
protected final String getSharedPreferencesName()

Deprecated. Use getPreferencesName() instead.

This method has been deprecated and will be removed in the next release.

Returns the actual name for shared preferences.

Returns:

Name used to retrieve shared preferences.

See Also:

setSharedPreferencesName(String)

getSharedPreferences

@Deprecated
public android.content.SharedPreferences getSharedPreferences()

Deprecated. Use SimpleSharedPreferencesFacade.getPreferences() instead.

This method has been deprecated and will be removed in the next release.

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)