SharedPreferencesBackupHelper.java revision 4e14a829129feee14ebe453f61a124784c870610 
1/*
2 * Copyright (C) 2009 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.app.backup;
18
19import android.content.Context;
20import android.content.SharedPreferences;
21import android.os.ParcelFileDescriptor;
22import android.util.Log;
23
24import java.io.File;
25
26/**
27 * A helper class which can be used in conjunction with
28 * {@link android.app.backup.BackupAgentHelper} to manage the backup of
29 * {@link android.content.SharedPreferences}. Whenever a backup is performed it
30 * will back up all named shared preferences which have changed since the last
31 * backup operation.
32 * <p>
33 * To use this class, the application's agent class should extend
34 * {@link android.app.backup.BackupAgentHelper}.  Then, in the agent's
35 * {@link BackupAgent#onCreate()} method, an instance of this class should be
36 * allocated and installed as a backup/restore handler within the BackupAgentHelper
37 * framework.  An implementation of an agent supporting backup and restore for
38 * an application that wishes to back up two groups of {@link android.content.SharedPreferences}
39 * data might look something like this:
40 * <pre>
41 * import android.app.backup.BackupAgentHelper;
42 * import android.app.backup.SharedPreferencesBackupHelper;
43 *
44 * public class MyBackupAgent extends BackupAgentHelper {
45 *     // The names of the SharedPreferences groups that the application maintains.  These
46 *     // are the same strings that are passed to {@link Context#getSharedPreferences(String, int)}.
47 *     static final String PREFS_DISPLAY = "displayprefs";
48 *     static final String PREFS_SCORES = "highscores";
49 *
50 *     // An arbitrary string used within the BackupAgentHelper implementation to
51 *     // identify the SharedPreferenceBackupHelper's data.
52 *     static final String MY_PREFS_BACKUP_KEY = "myprefs";
53 *
54 *     // Simply allocate a helper and install it
55 *     void onCreate() {
56 *         SharedPreferencesBackupHelper helper =
57 *                 new SharedPreferencesBackupHelper(this, PREFS_DISPLAY, PREFS_SCORES);
58 *         addHelper(MY_PREFS_BACKUP_KEY, helper);
59 *     }
60 * }</pre>
61 * <p>
62 * No further implementation is needed; the BackupAgentHelper mechanism automatically
63 * dispatches the
64 * {@link BackupAgent#onBackup(android.os.ParcelFileDescriptor, BackupDataOutput, android.os.ParcelFileDescriptor) BackupAgent.onBackup()}
65 * and
66 * {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) BackupAgent.onRestore()}
67 * callbacks to the SharedPreferencesBackupHelper as appropriate.
68 */
69public class SharedPreferencesBackupHelper extends FileBackupHelperBase implements BackupHelper {
70    private static final String TAG = "SharedPreferencesBackupHelper";
71    private static final boolean DEBUG = false;
72
73    private Context mContext;
74    private String[] mPrefGroups;
75
76    /**
77     * Construct a helper for backing up and restoring the
78     * {@link android.content.SharedPreferences} under the given names.
79     *
80     * @param context
81     * @param prefGroups
82     */
83    public SharedPreferencesBackupHelper(Context context, String... prefGroups) {
84        super(context);
85
86        mContext = context;
87        mPrefGroups = prefGroups;
88    }
89
90    /**
91     * Backs up the configured SharedPreferences groups
92     */
93    public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
94            ParcelFileDescriptor newState) {
95        Context context = mContext;
96
97        // make filenames for the prefGroups
98        String[] prefGroups = mPrefGroups;
99        final int N = prefGroups.length;
100        String[] files = new String[N];
101        for (int i=0; i<N; i++) {
102            files[i] = context.getSharedPrefsFile(prefGroups[i]).getAbsolutePath();
103        }
104
105        // go
106        performBackup_checked(oldState, data, newState, files, prefGroups);
107    }
108
109    /**
110     * Restores one entity from the restore data stream to its proper shared
111     * preferences file store.
112     */
113    public void restoreEntity(BackupDataInputStream data) {
114        Context context = mContext;
115
116        String key = data.getKey();
117        if (DEBUG) Log.d(TAG, "got entity '" + key + "' size=" + data.size());
118
119        if (isKeyInList(key, mPrefGroups)) {
120            File f = context.getSharedPrefsFile(key).getAbsoluteFile();
121            writeFile(f, data);
122        }
123    }
124}
125
126