API CHANGE: Backup/restore API changes requested by the API Council

* @hide the android.app.backup.RestoreSession class and functionality

* Provide a public method on android.app.backup.BackupManager that apps
  can use to request a restore pass of their last-known-good dataset.
  The new method is called requestRestore().

* Provide the name of the package being restored, not just its ordinal,
  in the RestoreObserver's onUpdate() callback.

Part of bug #2545514

Change-Id: I9689bf8d6e2b808b4ee412424a36a835be0a5ca8

1 files changed, 13 insertions, 5 deletions

diff --git a/core/java/android/app/backup/RestoreObserver.java b/core/java/android/app/backup/RestoreObserver.java
index 7a5e10b..0a4ea17 100644
--- a/core/java/android/app/backup/RestoreObserver.java
+++ b/core/java/android/app/backup/RestoreObserver.java
@@ -16,6 +16,8 @@
 
 package android.app.backup;
 
+import java.lang.String;
+
 /**
  * Callback class for receiving progress reports during a restore operation.  These
  * methods will all be called on your application's main thread.
@@ -32,17 +34,23 @@ public abstract class RestoreObserver {
 
     /**
      * An indication of which package is being restored currently, out of the
-     * total number provided in the restoreStarting() callback.  This method
-     * is not guaranteed to be called.
+     * total number provided in the {@link #restoreStarting(int)} callback.  This method
+     * is not guaranteed to be called: if the transport is unable to obtain
+     * data for one or more of the requested packages, no onUpdate() call will
+     * occur for those packages.
      *
      * @param nowBeingRestored The index, between 1 and the numPackages parameter
-     *   to the restoreStarting() callback, of the package now being restored.
+     *   to the {@link #restoreStarting(int)} callback, of the package now being
+     *   restored.  This may be non-monotonic; it is intended purely as a rough
+     *   indication of the backup manager's progress through the overall restore process.
+     * @param currentPackage The name of the package now being restored.
      */
-    void onUpdate(int nowBeingRestored) {
+    void onUpdate(int nowBeingRestored, String currentPackage) {
     }
 
     /**
-     * The restore operation has completed.
+     * The restore process has completed.  This method will always be called,
+     * even if no individual package restore operations were attempted.
      *
      * @param error Zero on success; a nonzero error code if the restore operation
      *   as a whole failed.