Understanding SharedPreferences in Android API

[[181260]]

Preference is translated as preference, but in fact it can be regarded as an alias for Setting. The difference between the two names lies in the different objects they target: Setting is more inclined to the attributes of the device, and modifying the setting is to change the function of the device; preference is inclined to the user's personality, and the user differentiates the device based on his or her personal preferences. But in general, they are consistent, both of which change the device experience through user needs.

In the process of Android development, you will see many classes and interfaces with Preference in their names in the APIs used. This article will introduce the functions and uses of these "*Prefere*".

In the API provided by Android, there are two main categories of Preferences: one is SharedPreferences in the android.content package, and the other is Preference in the android.preference package. They implement different functions respectively, but they are interconnected and cooperated to complete the control of Android programs.

Introduction to SharedPreferences

SharedPreferences exists in plural form because it is used to store a collection of key-value pairs in Android. The API contains multiple methods to read the corresponding type of data:

 String getString(String key , String defValue);
 Set <String> getStringSet(String key , Set <String> defValues);
 int getInt(String key , int defValue);
 long getLong(String key , long defValue);
 float getFloat(String key , float defValue);
 boolean getBoolean(String key , boolean defValue);

This also shows that the types that SharedPreferences can store are limited to basic data classes such as String, int, long, float, and boolean. The only collection type is Set, which looks more like an array that cannot have duplicate data.

You can also simply check whether the specified primary key is included, or simply get the Map of all key-value pairs:

 boolean contains (String key );
 Map<String, ?> getAll();

When designing SharedPreferences, Android system engineers put the read function on SharedPreferences, and implemented the write function on its embedded Editor class, and obtained a writer by calling the edit() method. In this way, it is easy to implement a read-only object, just return a null pointer or a non-usable Editor object.

 Editor putString(String key , String value);
 Editor putStringSet(String key , Set <String> values );
 Editor putInt(String key , int value);
 Editor putLong(String key , long value);
 Editor putFloat(String key , float value);
 Editor putBoolean(String key , boolean value);
 Editor remove(String key );

SharedPreferences also has a built-in interface OnSharedPreferenceChangeListener. By implementing its only method onSharedPreferenceChanged(SharedPreferences sharedPreferences, String key) and adding it to the SharedPreferences object through the following method, you can monitor the addition, deletion, and modification of key-value pairs on it:

 void registerOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);
 void unregisterOnSharedPreferenceChangeListener(OnSharedPreferenceChangeListener listener);

Implementation of SharedPreferences in Android system

SharedPreferences and the embedded Editor are actually just interface definitions, and do not implement any methods. It is just used to establish a protocol for storing key-value pairs. The specific implementation method and storage format can be arbitrary. In the Android system, it stores this data in XML format by default, and the implementation class is SharedPreferencesImpl.

The following is the basic format of the saved XML file. It uses the data type as the tag of the XML element. The primary key is the value of the tag name attribute, and the value corresponding to the primary key is the value of the value attribute. However, if it is a String type, it is used as the content under the tag, so that there is no need to escape quotes and line breaks can be better handled. In addition, the structure for storing null values ​​is also quite special. It uses null as the tag, with only a name attribute and no other content.

 <?xml version= '1.0' encoding= 'utf-8' standalone= 'yes' ?>
 <map>
    <string name = "Name" >Ider</string>
    <boolean name = "Android" value= "true" />
 < set   name = "Subsites" >
        <string>code.iderzheng.com</string>
        <string>blog.iderzheng.com</string>
        <string>manual.iderzheng.com</string>
 </ set >
 < int   name = "VersionCode" value= "21" />
    <long name = "VersionNumber" value= "1355" />
 < float   name = "Version" value = "5.0" />
 < null   name = "Null" />
 </map>

The Android system will store the XML file in /data/data/(packagename)/shared_prefs/. Each XML file corresponds to a SharedPreferences object (actually a SharedPreferencesImpl object). However, SharedPreferences is an interface and cannot be used to instantiate objects. SharedPreferencesImpl is a system hidden class and cannot be directly accessed and used. Its constructor is only visible to the package. Therefore, you cannot construct a SharedPreferences through new, but must obtain an instance through getSharedPreferences(String, int) provided by Context.

The first parameter of this method is a string that specifies the XML file name (without the ".xml" suffix). The method will read the corresponding file and create a SharedPreferences object. The second parameter specifies the access rights of the file. There are 4 optional modes. Starting from API 17, MODE_WORLD_READABLE and MODE_WORLD_WRITEABLE have been deprecated for security reasons. Only MODE_PRIVATE and MODE_MULTI_PROCESS can be used. In general, MODE_PRIVATE can be specified.

Reading the value of a specified primary key from SharedPreferences is very fast, because all the key-value information in XML is read and stored in the Map member variable of the SharedPreferences object, so the reading is based on memory access. Writing back to the file using Editor cannot avoid IO operations, so using commit() to submit changes will still take some time. Taking this into account, Android introduced the apply() method in API 9 to asynchronously write the modified content back to the file. Of course, before writing back, the key-value information in the memory will be updated to ensure that the latest content is read.

Since writing back can be asynchronous, multiple calls to getSharedPreferences(String, int) to obtain multiple SharedPreferences and assign them to different variables will not cause inconsistencies in other objects if one variable is modified. In fact, this situation will not occur because all created SharedPreferences are stored in a static member variable of ContextImp:

 /**
 * Map from package name , to preference name , to cached preferences.
 */
 private static ArrayMap<String, ArrayMap<String, SharedPreferencesImpl>> sSharedPrefs;

This is a two-level Map from the package name of the program to the XML file name and then to the SharedPreferences object. Therefore, each time you call getSharedPreferences(String, int), the object you get is actually the same instance, and the modification operations are also performed in the same memory segment to ensure the consistency of all accesses. The apply() method will also automatically queue all modifications and write them back to the file one by one so that unexpected errors will not be overwritten due to sequence errors. Therefore, because of the existence of this caching mechanism, multiple calls to getSharedPreferences(String, int) are very efficient. When writing back, it is recommended to use apply() to implement asynchronous operations instead of using commit() to block the main thread.

SharedPreferences usage and examples

Generally speaking, the names and primary keys of SharedPreferences are fixed, so you can define some final string variables to store these names, and use these constant variables when reading and writing back. The corresponding code for the XML shown above is as follows:

 private static final String IDER_PREFERENCE = "ider-preference" ;
 private static final String IDER_PREFERENCE_KEY_NAME = "Name" ;
 private static final String IDER_PREFERENCE_KEY_SUBSITES = "Subsites" ;
 private static final String IDER_PREFERENCE_KEY_IS_ANDROID = "Android" ;
 private static final String IDER_PREFERENCE_KEY_VERSION = "Version" ;
 private static final String IDER_PREFERENCE_KEY_VERSION_CODE = "VersionCode" ;
 private static final String IDER_PREFERENCE_KEY_VERSION_NUMBER = "VersionNumber" ;
 private static final String IDER_PREFERENCE_KEY_NULL = "Null" ;
 public void write(Context context) {
    final SharedPreferences spref = context.getSharedPreferences(IDER_PREFERENCE, MODE_PRIVATE);
    HashSet<String> strs = new HashSet<String>();
    strs.add ( "blog.iderzheng.com" );
    strs.add ( "code.iderzheng.com" );
    strs.add ( "manual.iderzheng.com" );
    SharedPreferences.Editor editor = spref.edit();
    editor.putString(IDER_PREFERENCE_KEY_NAME, "Ider" );
    editor.putStringSet(IDER_PREFERENCE_KEY_SUBSITES, strs);
    editor.putBoolean(IDER_PREFERENCE_KEY_IS_ANDROID, true );
    editor.putFloat(IDER_PREFERENCE_KEY_VERSION, 5.0f);
    editor.putInt(IDER_PREFERENCE_KEY_VERSION_CODE, 21);
    editor.putLong(IDER_PREFERENCE_KEY_VERSION_NUMBER, 1355);
    editor.putString(IDER_PREFERENCE_KEY_NULL, null );
 editor.apply();
 }
 public void read (Context context) {
    final SharedPreferences spref = context.getSharedPreferences(IDER_PREFERENCE, MODE_PRIVATE);
    String name = spref.getString(IDER_PREFERENCE_KEY_NAME, "" );
 Set <String> strs = spref.getStringSet(IDER_PREFERENCE_KEY_SUBSITES, null );
    boolean isAndroid = spref.getBoolean(IDER_PREFERENCE_KEY_IS_ANDROID, false );
 float version = spref.getFloat(IDER_PREFERENCE_KEY_VERSION, 0);
 int versionCode = spref.getInt(IDER_PREFERENCE_KEY_VERSION_CODE, 0);
    long versionNumber = spref.getLong(IDER_PREFERENCE_KEY_VERSION_NUMBER, 0);
    boolean hasKey = spref. contains (IDER_PREFERENCE_KEY_NULL);
 }

Since the name of SharedPreferences can be given arbitrarily, different files can be created to store different contents in a very targeted way. For example, preference information of different users can be stored in their names, and layout information and visited pages can be saved according to different interfaces. Activity additionally implements the method getPreferences(int) for getting SharedPreferences, which only requires the developer to provide the file opening mode, and automatically uses the Activity class name as the file name.

When SharedPreferences retrieves values, it directly converts the value of the given primary key in the Map into the required value. So if you use putInt to store an integer but use getBoolean() to retrieve it, it will not be automatically converted to a Boolean type, but will directly throw an exception. So be sure to keep the type consistent when using it.

In addition, if a primary key has not been stored, SharedPreferences will return a null value, and for types such as String and Set, null values ​​can also be stored, so it is not certain whether null is really stored data. Therefore, SharedPreferences also provides a contains (String key) method to check whether a given primary key is really stored with null, or whether null is returned because there is no such key-value pair.

Pros and Cons of SharedPreferences

As mentioned before, all the files of SharedPreferences that have been read will be cached in the Map and stored in memory for quick access next time, which is a major advantage of SharedPreferences. However, because they are all cached and the storage format is XML, SharedPreferences should not store too many key-value pairs, and the value content cannot be too large. In addition, SharedPreferences only supports the most basic types, which is enough to store some basic user information.

If you have root access to the device, you can directly access the /data/data/(packagename)/shared_prefs/ directory and export the XML file to view it. Or you can directly use the cat command in the adb shell to observe the data changes, which is very convenient.

In general, SharedPreferences is definitely the best object to store some small and simple data.