Android Tutorial: SharedPreferences

 ·  · 

1 What is SharedPreferences

Instead of saving raw file directly, Android provided SharedPreferences to save key-value pairs. SharedPreferences is usually used to cache application private data, usually, such as username, password, theme settings, counter or other application settings.

For example, assume that your application has a user login Activity, when user checks on "remember me", you can save the user name and password using SharedPreferences. And then read and preload the saved user name and password when user enters the login Activity next time.

Android SharedPreferences will store data as XML file in the directory /data/data/<YOUR_APP_PACKAGE>/shared_prefs/.

Furthermore, SharedPreferences only allow application to save primitive Java data types: int, float, long, boolean and String.

 

2 How to use SharedPreferences

2.1 SharedPreferences Object

To store data using SharedPreferences, first of all, you should get a reference of SharedPreferences object by calling the getSharedPreferences() method.

If you only have a single SharedPreferences file, call getSharedPreferences() and pass mode parameter.

getSharedPreferences(int mode)

If you have several SharedPreferences files, call getSharedPreferences() and pass file name and mode parameters.

getSharedPreferences(String name, int mode)

Available values for mode parameter:

  • MODE_PRIVATE: only your current application itself can access the SharedPreferences file;
  • MODE_WORLD_READABLE: all applications can read the SharedPreferences file. Deprecated, DO NOT use it now;
  • MODE_WORLD_WRITEABLE: all applications can write to the SharedPreferences file. Deprecated, DO NOT use it now;
  • MODE_MULTI_PROCESS: multiple processes can modify the same SharedPreferences file. Deprecated, use ContentProvider instead;

2.2 Steps to store data

The 1st step: get a reference of SharedPreferences object;

The 2nd step: obtain a new instance of SharedPreferences.Editor interface.

The 3rd step: use the editor to store your data with a key.

The 4th step: commit preferences changes back from editor to the SharedPreferences object.

2.3 Steps to retrieve data

The 1st step: get a reference of SharedPreferences object;

The 2nd step: use the key provided earlier to get the saved data. Supply a default value if the data is not found.

 

3 SharedPreferences Example

3.1 Save Demo

Using SharedPreferences is just as using a Map data structure. SharedPreferences will save your key-value pairs into an XML file.

import android.content.SharedPreferences;
import android.widget.Toast;

private void saveDemo() {
    // data/data/<YOUR_APP_PACKAGE>/shared_prefs/demo.xml
    SharedPreferences sp = getSharedPreferences("demo", MODE_PRIVATE);
    SharedPreferences.Editor ed = sp.edit();
    ed.putString("name", "Jack");
    ed.putInt("age", 20);
    ed.commit();

    Toast.makeText(this, "Save SharedPreferences Successfully!", Toast.LENGTH_LONG).show();
}

SharedPreferences will save the key-value pairs as XML file into folder: /data/data/<YOUR_APP_PACKAGE>/shared_prefs/.

android_SharedPreferences_saved_xml

The saved XML file looks like as follow.

<?xml version='1.0' encoding='utf-8' standalone='yes' ?>
<map>
    <string name="name">Jack</string>
    <int name="age" value="20" />
</map>

3.2 Read Demo

Read key-value data from SharedPreferences saved XML file:

private void readDemo() {
    SharedPreferences sp = getSharedPreferences("demo", MODE_PRIVATE);

    // The 2nd param is a default value if "get" fails
    String name = sp.getString("name", "a default name");
    int age = sp.getInt("age", 18);

    Toast.makeText(this, "name: " + name + "; age: " + age, Toast.LENGTH_LONG).show();
}

4 Common scenarios of using SharedPreferences

  1. Check if user is first time using your application;
  2. Remember or cache data of user details, for example, username, password, age, location and so on;
  3. Remember or cache user custom settings, for example, application font size, font color and so on;
  4. Check application version or update information.