Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit f524c8d1 authored by Adam Powell's avatar Adam Powell
Browse files

Update SharedPreferences documentation with behavior info 

Add information about tradeoffs made by SharedPreferences that reflect
changes eagerly before persistence has completed and recommendations
for other options if these tradeoffs are undesirable.

Change-Id: Ie88ef66b244ec3b89f6ad193508c593f422f480f
parent 751f3d53

core/java/android/content/SharedPreferences.java

+21 −4
Original line number Diff line number Diff line
@@ -30,10 +30,27 @@ import java.util.Set; 
 * 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>Note: This class provides strong consistency guarantees. It is using expensive operations

 * which might slow down an app. Frequently changing properties or properties where loss can be

 * tolerated should use other mechanisms. For more details read the comments on

 * {@link Editor#commit()} and {@link Editor#apply()}.

 * <p>SharedPreferences is best suited to storing data about how the user prefers

 * to experience the app, for example, whether the user prefers a particular UI theme

 * or whether they prefer viewing particular content in a list vs. a grid. To this end,

 * SharedPreferences reflects changes {@link Editor#commit() committed} or

 * {@link Editor#apply() applied} by {@link Editor}s <em>immediately</em>, potentially

 * before those changes are durably persisted.

 * Under some circumstances such as app crashes or termination these changes may be lost,

 * even if an {@link OnSharedPreferenceChangeListener} reported the change was successful.

 * SharedPreferences is not recommended for storing data that is sensitive to this

 * kind of rollback to a prior state such as user security or privacy settings.

 * For other high-level data persistence options, see

 * <a href="https://d.android.com/room">Room</a> or

 * <a href="https://d.android.com/datastore">DataStore</a>.

 *

 * <p><em>Note:</em> Common implementations guarantee that outstanding edits to preference

 * files are persisted to disk when host Activities become stopped. In some situations

 * (e.g. performing many {@link Editor#commit()} or {@link Editor#apply()}

 * operations just prior to navigating away from the host Activity) this can lead

 * to blocking the main thread during lifecycle transition events and associated

 * ANR errors. For more details see the documentation for {@link Editor#commit()} and

 * {@link Editor#apply()}.

 *

 * <p><em>Note: This class does not support use across multiple processes.</em>

 *