Android SharedPreferences Best Practices

I've wrote a little article that can also be found here. It describes what SharedPreferences is :

Best Practice: SharedPreferences

Android provides many ways of storing application data. One of those ways leads us to the SharedPreferences object which is used to store private primitive data in key-value pairs.

All logic are based only on three simple classes:

• SharedPreferences
• SharedPreferences.Editor
• SharedPreferences.OnSharedPreferenceChangeListener

SharedPreferences

SharedPreferences is main of them. It's responsible for getting (parsing) stored data, provides interface for getting Editor object and interfaces for adding and removing OnSharedPreferenceChangeListener

• To create SharedPreferences you will need Context object (can be an application Context)
• getSharedPreferences method parses Preference file and creates Map object for it

• You can create it in few modes provided by Context. You should always use MODE_PRIVATE, as all the other modes are deprecated since API level 17.

  // parse Preference file
  SharedPreferences preferences = context.getSharedPreferences("com.example.app", Context.MODE_PRIVATE);
  
  // get values from Map
  preferences.getBoolean("key", defaultValue)
  preferences.get..("key", defaultValue)
  
  // you can get all Map but be careful you must not modify the collection returned by this
  // method, or alter any of its contents.
  Map<String, ?> all = preferences.getAll();
  
  // get Editor object
  SharedPreferences.Editor editor = preferences.edit();
  
  //add on Change Listener
  preferences.registerOnSharedPreferenceChangeListener(mListener);
  
  //remove on Change Listener
  preferences.unregisterOnSharedPreferenceChangeListener(mListener);
  
  // listener example
  SharedPreferences.OnSharedPreferenceChangeListener mOnSharedPreferenceChangeListener
      = new SharedPreferences.OnSharedPreferenceChangeListener() {
    @Override
    public void onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) {
    }
  };
  

Editor

SharedPreferences.Editor is an Interface used for modifying values in a SharedPreferences object. All changes you make in an editor are batched, and not copied back to the original SharedPreferences until you call commit() or apply()

• Use simple interface to put values in Editor
• Save values synchronous with commit() or asynchronous with apply which is faster. In fact of using different threads using commit() is safer. Thats why I prefer to use commit().

• Remove single value with remove() or clear all values with clear()

  // get Editor object
  SharedPreferences.Editor editor = preferences.edit();
  
  // put values in editor
  editor.putBoolean("key", value);
  editor.put..("key", value);
  
  // remove single value by key
  editor.remove("key");
  
  // remove all values
  editor.clear();
  
  // commit your putted values to the SharedPreferences object synchronously
  // returns true if success
  boolean result = editor.commit();
  
  // do the same as commit() but asynchronously (faster but not safely)
  // returns nothing
  editor.apply();
  

Performance & Tips

• SharedPreferences is a Singleton object so you can easily get as many references as you want, it opens file only when you call getSharedPreferences first time, or create only one reference for it.

  // There are 1000 String values in preferences
  
  SharedPreferences first = context.getSharedPreferences("com.example.app", Context.MODE_PRIVATE);
  // call time = 4 milliseconds
  
  SharedPreferences second = context.getSharedPreferences("com.example.app", Context.MODE_PRIVATE);
  // call time = 0 milliseconds
  
  SharedPreferences third = context.getSharedPreferences("com.example.app", Context.MODE_PRIVATE);
  // call time = 0 milliseconds
  

• As SharedPreferences is a Singleton object you can change any of It's instances and not be scared that their data will be different

  first.edit().putInt("key",15).commit();
  
  int firstValue = first.getInt("key",0)); // firstValue is 15
  int secondValue = second.getInt("key",0)); // secondValue is also 15
  

• Remember the larger the Preference object is the longer get, commit, apply, remove and clear operations will be. So it's highly recommended to separate your data in different small objects.

• Your Preferences will not be removed after Application update. So there are cases when you need to create some migration scheme. For example you have Application that parse local JSON in start of application, to do this only after first start you decided to save boolean flag wasLocalDataLoaded. After some time you updated that JSON and released new application version. Users will update their applications but they will not load new JSON because they already done it in first application version.

  public class MigrationManager {
   private final static String KEY_PREFERENCES_VERSION = "key_preferences_version";
   private final static int PREFERENCES_VERSION = 2;
  
   public static void migrate(Context context) {
       SharedPreferences preferences = context.getSharedPreferences("pref", Context.MODE_PRIVATE);
       checkPreferences(preferences);
   }
  
   private static void checkPreferences(SharedPreferences thePreferences) {
       final double oldVersion = thePreferences.getInt(KEY_PREFERENCES_VERSION, 1);
  
       if (oldVersion < PREFERENCES_VERSION) {
           final SharedPreferences.Editor edit = thePreferences.edit();
           edit.clear();
           edit.putInt(KEY_PREFERENCES_VERSION, currentVersion);
           edit.commit();
       }
   }
  }
  

• SharedPreferences are stored in an xml file in the app data folder

  // yours preferences
  /data/data/YOUR_PACKAGE_NAME/shared_prefs/YOUR_PREFS_NAME.xml
  
  // default preferences
  /data/data/YOUR_PACKAGE_NAME/shared_prefs/YOUR_PACKAGE_NAME_preferences.xml
  

Android guide.

Sample Code

public class PreferencesManager {

    private static final String PREF_NAME = "com.example.app.PREF_NAME";
    private static final String KEY_VALUE = "com.example.app.KEY_VALUE";

    private static PreferencesManager sInstance;
    private final SharedPreferences mPref;

    private PreferencesManager(Context context) {
        mPref = context.getSharedPreferences(PREF_NAME, Context.MODE_PRIVATE);
    }

    public static synchronized void initializeInstance(Context context) {
        if (sInstance == null) {
            sInstance = new PreferencesManager(context);
        }
    }

    public static synchronized PreferencesManager getInstance() {
        if (sInstance == null) {
            throw new IllegalStateException(PreferencesManager.class.getSimpleName() +
                    " is not initialized, call initializeInstance(..) method first.");
        }
        return sInstance;
    }

    public void setValue(long value) {
        mPref.edit()
                .putLong(KEY_VALUE, value)
                .commit();
    }

    public long getValue() {
        return mPref.getLong(KEY_VALUE, 0);
    }

    public void remove(String key) {
        mPref.edit()
                .remove(key)
                .commit();
    }

    public boolean clear() {
        return mPref.edit()
                .clear()
                .commit();
    }
}

If you have a large application that is relying on SharedPreferences you could have key duplication, especially in the case of using some third party library that relies on SharedPreferences as well.

Libraries should not use that particular SharedPreferences. The default SharedPreferences should only be used by the application.

This way if you have a class that heavily relies on SharedPreferences you can create a preference file that is used only by your class.

You are certainly welcome to do this. I wouldn't, at the application level, as the primary reason for SharedPreferences is to have them be shared among the components in the application. A development team should have no problem managing this namespace, just as they should have no problem managing names of classes, packages, resources, or other project-level stuff. Moreover, the default SharedPreferences are what your PreferenceActivity will use.

However, going back to your libraries point, reusable libraries should use a separate SharedPreferences for their library only. I would not base it on a class name, because then you are one refactoring away from breaking your app. Instead, pick a name that is unique (e.g., based on the library name, such as "com.commonsware.cwac.wakeful.WakefulIntentService") but stable.

it seems that accesses SharedPreferences should be done off the UI thread which makes sense.

Ideally, yes. I recently released a SharedPreferencesLoader that helps with this.

Are there any other best practices Android developers should be aware of when using SharedPreferences in their applications?

Don't over-rely upon them. They are stored in XML files and are not transactional. A database should be your primary data store, particularly for data you really don't want to lose.