Document immutable requirement of SharedPreferences return objects

In particular, make it quite clear that the set returned by
getStringSet() must not be modfied by the app, period; and
add a similar caution about the map returned via getAll().

Also, fix a bug that could lead to unexpected data being committed
if the set instance passed to putStringSet() was mutated by the
app after that call (including mutations after commit() was
invoked).

Bug 7312641

Change-Id: If9a1be1b0669ac879ff7a7dc67a8805548ea10cc

Author: Christopher Tate

core/java/android/app/SharedPreferencesImpl.java

@@ -312,7 +312,8 @@ public Editor putString(String key, String value) {
         }
         public Editor putStringSet(String key, Set<String> values) {
             synchronized (this) {
-                mModified.put(key, values);
+                mModified.put(key,
+                        (values == null) ? null : new HashSet<String>(values));
                 return this;
             }
         }

core/java/android/content/SharedPreferences.java

@@ -25,7 +25,8 @@
  * there is a single instance of this class that all clients share.
  * Modifications to the preferences must go through an {@link Editor} object
  * to ensure the preference values remain in a consistent state and control
- * when they are committed to storage.
+ * when they are committed to storage.  Objects that are returned from the
+ * various <code>get</code> methods must be treated as immutable by the application.
  *
  * <p><em>Note: currently this class does not support use across multiple
  * processes.  This will be added later.</em>
@@ -226,6 +227,10 @@ public interface Editor {
     /**
      * Retrieve all values from the preferences.
      *
+     * <p>Note that you <em>must not</em> modify the collection returned
+     * by this method, or alter any of its contents.  The consistency of your
+     * stored data is not guaranteed if you do.
+     *
      * @return Returns a map containing a list of pairs key/value representing
      * the preferences.
      *
@@ -250,6 +255,10 @@ public interface Editor {
     /**
      * Retrieve a set of String values from the preferences.
      * 
+     * <p>Note that you <em>must not</em> modify the set instance returned
+     * by this call.  The consistency of the stored data is not guaranteed
+     * if you do, nor is your ability to modify the instance at all.
+     *
      * @param key The name of the preference to retrieve.
      * @param defValues Values to return if this preference does not exist.
      *