From fd59645ba7d4445b3308489ef07c700aaed85c6f Mon Sep 17 00:00:00 2001 From: Filip Pavlis Date: Wed, 1 Mar 2017 18:50:00 +0000 Subject: [PATCH] JavaDoc improvements as suggested by API council. Bug: b/35813554 Test: Not needed. Change-Id: I009497bab66c9cc624f434f6d2dde0d80381d961 --- core/java/android/preference/Preference.java | 24 +++++++++----- .../preference/PreferenceDataStore.java | 32 +++++++++++++++++-- .../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 089eaeceac551..62c5dca0ada1b 100644 --- a/core/java/android/preference/Preference.java +++ b/core/java/android/preference/Preference.java @@ -410,11 +410,13 @@ public class Preference implements Comparable { /** * Sets a {@link PreferenceDataStore} to be used by this Preference instead of using * {@link android.content.SharedPreferences}. - *

- * The data store will remain assigned even if the Preference is moved between multiple - * instances of {@link PreferenceFragment}. + * + *

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 { * Returns {@link PreferenceDataStore} used by this Preference. Returns {@code null} if * {@link android.content.SharedPreferences} is used instead. * + *

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 { } /** - * Implement this to set the initial value of the Preference. + * Implement this to set the initial value of the Preference. *

- * If restorePersistedValue is true, you should restore the - * Preference value from the {@link android.content.SharedPreferences}. If - * restorePersistedValue is false, you should set the Preference - * value to defaultValue that is given (and possibly store to SharedPreferences + * If restorePersistedValue is true, you should restore the + * Preference value from the {@link android.content.SharedPreferences}. If + * restorePersistedValue is false, you should set the Preference + * value to defaultValue that is given (and possibly store to SharedPreferences * if {@link #shouldPersist()} is true). *

* 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 e1a08acab6b7e..8caa404d98597 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}. + *

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. + * + *

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. + * + *

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. * + *

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. * + *

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. * + *

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. * + *

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. * + *

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. * + *

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 a2f4db6e75223..587c01bb54838 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. * + *

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;