SharedPreferences  |  API reference  |  Android Developers (original) (raw)

Stay organized with collections Save and categorize content based on your preferences.

public interface SharedPreferences
``

android.content.SharedPreferences

Interface for accessing and modifying preference data returned by [Context.getSharedPreferences(String, int)](/reference/android/content/Context#getSharedPreferences%28java.lang.String,%20int%29). For any particular set of preferences, there is a single instance of this class that all clients share. Modifications to the preferences must go through an [Editor](/reference/android/content/SharedPreferences.Editor) object to ensure the preference values remain in a consistent state and control when they are committed to storage. Objects that are returned from the various get methods must be treated as immutable by the application.

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 [committed](/reference/android/content/SharedPreferences.Editor#commit%28%29) or[applied](/reference/android/content/SharedPreferences.Editor#apply%28%29) by [Editor](/reference/android/content/SharedPreferences.Editor)s immediately, potentially before those changes are durably persisted. Under some circumstances such as app crashes or termination these changes may be lost, even if an [OnSharedPreferenceChangeListener](/reference/android/content/SharedPreferences.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, seeRoom orDataStore.

Note: 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 [Editor.commit()](/reference/android/content/SharedPreferences.Editor#commit%28%29) or [Editor.apply()](/reference/android/content/SharedPreferences.Editor#apply%28%29) 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 [Editor.commit()](/reference/android/content/SharedPreferences.Editor#commit%28%29) and[Editor.apply()](/reference/android/content/SharedPreferences.Editor#apply%28%29).

Note: This class does not support use across multiple processes.

Developer Guides

For more information about using SharedPreferences, read theData Storage developer guide.

Summary

Public methods

contains

public abstract boolean contains (String key)

Checks whether the preferences contains a preference.

edit

public abstract SharedPreferences.Editor edit ()

Create a new Editor for these preferences, through which you can make modifications to the data in the preferences and atomically commit those changes back to the SharedPreferences object.

Note that you must call [Editor.commit](/reference/android/content/SharedPreferences.Editor#commit%28%29) to have any changes you perform in the Editor actually show up in the SharedPreferences.

getAll

public abstract Map<String, ?> getAll ()

Retrieve all values from the preferences.

Note that you must not 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.

getBoolean

public abstract boolean getBoolean (String key, boolean defValue)

Retrieve a boolean value from the preferences.

getFloat

public abstract float getFloat (String key, float defValue)

Retrieve a float value from the preferences.

getInt

public abstract int getInt (String key, int defValue)

Retrieve an int value from the preferences.

getLong

public abstract long getLong (String key, long defValue)

Retrieve a long value from the preferences.

getString

public abstract String getString (String key, String defValue)

Retrieve a String value from the preferences.

getStringSet

public abstract Set<String> getStringSet (String key, Set<String> defValues)

Retrieve a set of String values from the preferences.

Note that you must not 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.

registerOnSharedPreferenceChangeListener

public abstract void registerOnSharedPreferenceChangeListener (SharedPreferences.OnSharedPreferenceChangeListener listener)

Registers a callback to be invoked when a change happens to a preference.

Caution: 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.

unregisterOnSharedPreferenceChangeListener

public abstract void unregisterOnSharedPreferenceChangeListener (SharedPreferences.OnSharedPreferenceChangeListener listener)

Unregisters a previous callback.