diff options
| -rw-r--r-- | core/java/android/preference/Preference.java | 24 | ||||
| -rw-r--r-- | core/java/android/preference/PreferenceDataStore.java | 32 | ||||
| -rw-r--r-- | core/java/android/preference/PreferenceManager.java | 13 |
3 files changed, 55 insertions, 14 deletions
diff --git a/core/java/android/preference/Preference.java b/core/java/android/preference/Preference.java index 089eaeceac55..62c5dca0ada1 100644 --- a/core/java/android/preference/Preference.java +++ b/core/java/android/preference/Preference.java @@ -410,11 +410,13 @@ public class Preference implements Comparable<Preference> { /** * Sets a {@link PreferenceDataStore} to be used by this Preference instead of using * {@link android.content.SharedPreferences}. - * <p> - * The data store will remain assigned even if the Preference is moved between multiple - * instances of {@link PreferenceFragment}. + * + * <p>The data store will remain assigned even if the Preference is moved around the preference + * hierarchy. It will also override a data store propagated from the {@link PreferenceManager} + * that owns this Preference. * * @param dataStore The {@link PreferenceDataStore} to be used by this Preference. + * @see PreferenceManager#setPreferenceDataStore(PreferenceDataStore) */ public void setPreferenceDataStore(PreferenceDataStore dataStore) { mPreferenceDataStore = dataStore; @@ -424,6 +426,12 @@ public class Preference implements Comparable<Preference> { * Returns {@link PreferenceDataStore} used by this Preference. Returns {@code null} if * {@link android.content.SharedPreferences} is used instead. * + * <p>By default preferences always use {@link android.content.SharedPreferences}. To make this + * preference to use the {@link PreferenceDataStore} you need to assign your implementation + * to the Preference itself via {@link #setPreferenceDataStore(PreferenceDataStore)} or to its + * {@link PreferenceManager} via + * {@link PreferenceManager#setPreferenceDataStore(PreferenceDataStore)}. + * * @return The {@link PreferenceDataStore} used by this Preference or {@code null} if none. */ @Nullable @@ -1457,12 +1465,12 @@ public class Preference implements Comparable<Preference> { } /** - * Implement this to set the initial value of the Preference. + * Implement this to set the initial value of the Preference. * <p> - * If <var>restorePersistedValue</var> is true, you should restore the - * Preference value from the {@link android.content.SharedPreferences}. If - * <var>restorePersistedValue</var> is false, you should set the Preference - * value to defaultValue that is given (and possibly store to SharedPreferences + * If <var>restorePersistedValue</var> is true, you should restore the + * Preference value from the {@link android.content.SharedPreferences}. If + * <var>restorePersistedValue</var> is false, you should set the Preference + * value to defaultValue that is given (and possibly store to SharedPreferences * if {@link #shouldPersist()} is true). * <p> * This may not always be called. One example is if it should not persist diff --git a/core/java/android/preference/PreferenceDataStore.java b/core/java/android/preference/PreferenceDataStore.java index e1a08acab6b7..8caa404d9859 100644 --- a/core/java/android/preference/PreferenceDataStore.java +++ b/core/java/android/preference/PreferenceDataStore.java @@ -21,16 +21,32 @@ import android.annotation.Nullable; import java.util.Set; /** - * A data store interface to be implemented and provided to the Preferences framework. + * A data store interface to be implemented and provided to the Preferences framework. This can be + * used to replace the default {@link android.content.SharedPreferences}, if needed. * - * Use this to replace the default {@link android.content.SharedPreferences}. By default, all "put" - * methods throw {@link UnsupportedOperationException}. + * <p>In most cases you want to use {@link android.content.SharedPreferences} as it is automatically + * backed up and migrated to new devices. However, providing custom data store to preferences can be + * useful if your app stores its preferences in a local db, cloud or they are device specific like + * "Developer settings". It might be also useful when you want to use the preferences UI but + * the data are not supposed to be stored at all because they are valid per session only. + * + * <p>Once a put method is called it is full responsibility of the data store implementation to + * safely store the given values. Time expensive operations need to be done in the background to + * prevent from blocking the UI. You also need to have a plan on how to serialize the data in case + * the activity holding this object gets destroyed. + * + * <p>By default, all "put" methods throw {@link UnsupportedOperationException}. + * + * @see Preference#setPreferenceDataStore(PreferenceDataStore) + * @see PreferenceManager#setPreferenceDataStore(PreferenceDataStore) */ public interface PreferenceDataStore { /** * Set a String value to the data store. * + * <p>Once the value is set the data store is responsible for holding it. + * * @param key The name of the preference to modify. * @param value The new value for the preference. * @see #getString(String, String) @@ -42,6 +58,8 @@ public interface PreferenceDataStore { /** * Set a set of String value to the data store. * + * <p>Once the value is set the data store is responsible for holding it. + * * @param key The name of the preference to modify. * @param values The set of new values for the preference. * @see #getStringSet(String, Set) @@ -53,6 +71,8 @@ public interface PreferenceDataStore { /** * Set an int value to the data store. * + * <p>Once the value is set the data store is responsible for holding it. + * * @param key The name of the preference to modify. * @param value The new value for the preference. * @see #getInt(String, int) @@ -64,6 +84,8 @@ public interface PreferenceDataStore { /** * Set a long value to the data store. * + * <p>Once the value is set the data store is responsible for holding it. + * * @param key The name of the preference to modify. * @param value The new value for the preference. * @see #getLong(String, long) @@ -75,6 +97,8 @@ public interface PreferenceDataStore { /** * Set a float value to the data store. * + * <p>Once the value is set the data store is responsible for holding it. + * * @param key The name of the preference to modify. * @param value The new value for the preference. * @see #getFloat(String, float) @@ -86,6 +110,8 @@ public interface PreferenceDataStore { /** * Set a boolean value to the data store. * + * <p>Once the value is set the data store is responsible for holding it. + * * @param key The name of the preference to modify. * @param value The new value for the preference. * @see #getBoolean(String, boolean) diff --git a/core/java/android/preference/PreferenceManager.java b/core/java/android/preference/PreferenceManager.java index 756c3f482120..257037436802 100644 --- a/core/java/android/preference/PreferenceManager.java +++ b/core/java/android/preference/PreferenceManager.java @@ -208,10 +208,13 @@ public class PreferenceManager { /** * Sets a {@link PreferenceDataStore} to be used by all Preferences associated with this manager - * that don't have a custom {@link PreferenceDataStore} assigned. Also if the data store is set, - * the Preferences will no longer use {@link android.content.SharedPreferences}. + * that don't have a custom {@link PreferenceDataStore} assigned via + * {@link Preference#setPreferenceDataStore(PreferenceDataStore)}. Also if the data store is + * set, the child preferences won't use {@link android.content.SharedPreferences} as long as + * they are assigned to this manager. * * @param dataStore The {@link PreferenceDataStore} to be used by this manager. + * @see Preference#setPreferenceDataStore(PreferenceDataStore) */ public void setPreferenceDataStore(PreferenceDataStore dataStore) { mPreferenceDataStore = dataStore; @@ -219,9 +222,10 @@ public class PreferenceManager { /** * Returns the {@link PreferenceDataStore} associated with this manager or {@code null} if - * {@link android.content.SharedPreferences} are used instead. + * the default {@link android.content.SharedPreferences} are used instead. * * @return The {@link PreferenceDataStore} associated with this manager or {@code null} if none. + * @see #setPreferenceDataStore(PreferenceDataStore) */ @Nullable public PreferenceDataStore getPreferenceDataStore() { @@ -358,8 +362,11 @@ public class PreferenceManager { * Sets the name of the SharedPreferences file that preferences managed by this * will use. * + * <p>If custom {@link PreferenceDataStore} is set, this won't override its usage. + * * @param sharedPreferencesName The name of the SharedPreferences file. * @see Context#getSharedPreferences(String, int) + * @see #setPreferenceDataStore(PreferenceDataStore) */ public void setSharedPreferencesName(String sharedPreferencesName) { mSharedPreferencesName = sharedPreferencesName; |