Noted that OnSharedPreferenceChangeListener does not store a strong reference

to the listener.

Because of this, the listener is susceptible to garbage collection unless the
caller preserves a strong reference to it. We suggest that the caller store a
reference to the listener in an instance field of an object that will exist as
long as the listener is needed.

Also fixed code sample formatting in Settings.jd (some lines were overlong).

Docs are staged in:

http://asolovay.mtv:8901/guide/topics/ui/settings.html#Listening

http://asolovay.mtv:8901/reference/android/content/SharedPreferences.html#registerOnSharedPreferenceChangeListener(android.content.SharedPreferences.OnSharedPreferenceChangeListener)

Bug: 10437648
Change-Id: I48f5b87fa2ca7a240661d0cc00114d225819d54d

1 files changed, 8 insertions, 1 deletions

diff --git a/core/java/android/content/SharedPreferences.java b/core/java/android/content/SharedPreferences.java
index d4f7f06b008d..00c2d8f78055 100644
--- a/core/java/android/content/SharedPreferences.java
+++ b/core/java/android/content/SharedPreferences.java
@@ -355,7 +355,14 @@ public interface SharedPreferences {
     
     /**
      * Registers a callback to be invoked when a change happens to a preference.
-     * 
+     *
+     * <p class="caution"><strong>Caution:</strong> The preference manager does
+     * not currently store a strong reference to the listener. You must store a
+     * strong reference to the listener, or it will be susceptible to garbage
+     * collection. We recommend you keep a reference to the listener in the
+     * instance data of an object that will exist as long as you need the
+     * listener.</p>
+     *
      * @param listener The callback that will run.
      * @see #unregisterOnSharedPreferenceChangeListener
      */