API CHANGE: expose backup/restore to the SDK

The core backup/restore classes [BackupManager, BackupAgent, RestoreSession, and
RestoreObserver] are now published for 3rd party developers, as well as the suite
of helper classes that exist so far to aid authorship of backup/restore agents.

In conjunction with the API change, the restore-time automatic data wipe has now
been removed:  applications are responsible for managing the logic of wipe vs
merge themselves.  If the app's agent onRestore() callback throws, the data
is presumed to be incoherent and a wipe is issued via the Activity Manager;
otherwise, no automatic action is ever taken.

Change-Id: I0b3418b829d4689b58b88be3d9c4ace37a8583a9

1 files changed, 17 insertions, 1 deletions

diff --git a/core/java/android/backup/SharedPreferencesBackupHelper.java b/core/java/android/backup/SharedPreferencesBackupHelper.java
index 6a0bc96..f9c97a3 100644
--- a/core/java/android/backup/SharedPreferencesBackupHelper.java
+++ b/core/java/android/backup/SharedPreferencesBackupHelper.java
@@ -23,7 +23,9 @@ import android.util.Log;
 import java.io.File;
 import java.io.FileDescriptor;
 
-/** @hide */
+/**
+ * STOPSHIP: document!
+ */
 public class SharedPreferencesBackupHelper extends FileBackupHelperBase implements BackupHelper {
     private static final String TAG = "SharedPreferencesBackupHelper";
     private static final boolean DEBUG = false;
@@ -31,6 +33,13 @@ public class SharedPreferencesBackupHelper extends FileBackupHelperBase implemen
     private Context mContext;
     private String[] mPrefGroups;
 
+    /**
+     * Construct a helper for backing up and restoring the
+     * {@link android.content.SharedPreferences} under the given names.
+     *
+     * @param context
+     * @param prefGroups
+     */
     public SharedPreferencesBackupHelper(Context context, String... prefGroups) {
         super(context);
 
@@ -38,6 +47,9 @@ public class SharedPreferencesBackupHelper extends FileBackupHelperBase implemen
         mPrefGroups = prefGroups;
     }
 
+    /**
+     * Backs up the configured SharedPreferences groups
+     */
     public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
             ParcelFileDescriptor newState) {
         Context context = mContext;
@@ -54,6 +66,10 @@ public class SharedPreferencesBackupHelper extends FileBackupHelperBase implemen
         performBackup_checked(oldState, data, newState, files, prefGroups);
     }
 
+    /**
+     * Restores one entity from the restore data stream to its proper shared
+     * preferences file store.
+     */
     public void restoreEntity(BackupDataInputStream data) {
         Context context = mContext;