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, 13 insertions, 1 deletions

diff --git a/core/java/android/backup/FileBackupHelper.java b/core/java/android/backup/FileBackupHelper.java
index dacfc8f557dc..68b4d4219f6c 100644
--- a/core/java/android/backup/FileBackupHelper.java
+++ b/core/java/android/backup/FileBackupHelper.java
@@ -23,7 +23,9 @@ import android.util.Log;
 import java.io.File;
 import java.io.FileDescriptor;
 
-/** @hide */
+/**
+ * STOPSHIP: document!  [manages backup of a set of files; restore is totally opaque]
+ */
 public class FileBackupHelper extends FileBackupHelperBase implements BackupHelper {
     private static final String TAG = "FileBackupHelper";
     private static final boolean DEBUG = false;
@@ -32,6 +34,13 @@ public class FileBackupHelper extends FileBackupHelperBase implements BackupHelp
     File mFilesDir;
     String[] mFiles;
 
+    /**
+     * Construct a helper to manage backup/restore of entire files within the
+     * application's data directory hierarchy.
+     *
+     * @param context The backup agent's Context object
+     * @param files A list of the files to be backed up or restored.
+     */
     public FileBackupHelper(Context context, String... files) {
         super(context);
 
@@ -60,6 +69,9 @@ public class FileBackupHelper extends FileBackupHelperBase implements BackupHelp
         performBackup_checked(oldState, data, newState, fullPaths, files);
     }
 
+    /**
+     * Restore one record [representing a single file] from the restore dataset.
+     */
     public void restoreEntity(BackupDataInputStream data) {
         if (DEBUG) Log.d(TAG, "got entity '" + data.getKey() + "' size=" + data.size());
         String key = data.getKey();