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

4 files changed, 57 insertions, 14 deletions

diff --git a/core/java/android/app/backup/BackupManager.java b/core/java/android/app/backup/BackupManager.java
index 2da8b56..dff0695 100644
--- a/core/java/android/app/backup/BackupManager.java
+++ b/core/java/android/app/backup/BackupManager.java
@@ -115,8 +115,45 @@ public class BackupManager {
     }
 
     /**
+     * Restore the calling application from backup.  The data will be restored from the
+     * current backup dataset if the application has stored data there, or from
+     * the dataset used during the last full device setup operation if the current
+     * backup dataset has no matching data.  If no backup data exists for this application
+     * in either source, a nonzero value will be returned.
+     *
+     * <p>If this method returns zero (meaning success), the OS will attempt to retrieve
+     * a backed-up dataset from the remote transport, instantiate the application's
+     * backup agent, and pass the dataset to the agent's
+     * {@link android.app.backup.BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()}
+     * method.
+     *
+     * @return Zero on success; nonzero on error.
+     */
+    public int requestRestore(RestoreObserver observer) {
+        int result = -1;
+        checkServiceBinder();
+        if (sService != null) {
+            RestoreSession session = null;
+            try {
+                String transport = sService.getCurrentTransport();
+                IRestoreSession binder = sService.beginRestoreSession(transport);
+                session = new RestoreSession(mContext, binder);
+                result = session.restorePackage(mContext.getPackageName(), observer);
+            } catch (RemoteException e) {
+                Log.w(TAG, "restoreSelf() unable to contact service");
+            } finally {
+                if (session != null) {
+                    session.endRestoreSession();
+                }
+            }
+        }
+        return result;
+    }
+
+    /**
      * Begin the process of restoring data from backup.  See the
      * {@link android.app.backup.RestoreSession} class for documentation on that process.
+     * @hide
      */
     public RestoreSession beginRestoreSession() {
         RestoreSession session = null;
diff --git a/core/java/android/app/backup/IRestoreObserver.aidl b/core/java/android/app/backup/IRestoreObserver.aidl
index 75d0d17..ec85683 100644
--- a/core/java/android/app/backup/IRestoreObserver.aidl
+++ b/core/java/android/app/backup/IRestoreObserver.aidl
@@ -37,8 +37,9 @@ interface IRestoreObserver {
      *
      * @param nowBeingRestored The index, between 1 and the numPackages parameter
      *   to the restoreStarting() callback, of the package now being restored.
+     * @param currentPackage The name of the package now being restored.
      */
-    void onUpdate(int nowBeingRestored);
+    void onUpdate(int nowBeingRestored, String curentPackage);
 
     /**
      * The restore operation has completed.
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.
diff --git a/core/java/android/app/backup/RestoreSession.java b/core/java/android/app/backup/RestoreSession.java
index 730a21f..da2778b 100644
--- a/core/java/android/app/backup/RestoreSession.java
+++ b/core/java/android/app/backup/RestoreSession.java
@@ -27,7 +27,8 @@ import android.os.RemoteException;
 import android.util.Log;
 
 /**
- * Interface for applications to use when managing a restore session.
+ * Interface for managing a restore session.
+ * @hide
  */
 public class RestoreSession {
     static final String TAG = "RestoreSession";
@@ -44,8 +45,6 @@ public class RestoreSession {
      *   and a String array under the key "names" whose entries are the user-meaningful
      *   text corresponding to the backup sets at each index in the tokens array.
      *   On error, returns null.
-     *
-     * {@hide}
      */
     public RestoreSet[] getAvailableRestoreSets() {
         try {
@@ -68,8 +67,6 @@ public class RestoreSession {
      *   the restore set that should be used.
      * @param observer If non-null, this binder points to an object that will receive
      *   progress callbacks during the restore operation.
-     *
-     * {@hide}
      */
     public int restoreAll(long token, RestoreObserver observer) {
         int err = -1;
@@ -164,7 +161,7 @@ public class RestoreSession {
                         mAppObserver.restoreStarting(msg.arg1);
                         break;
                     case MSG_UPDATE:
-                        mAppObserver.onUpdate(msg.arg1);
+                        mAppObserver.onUpdate(msg.arg1, (String)msg.obj);
                         break;
                     case MSG_RESTORE_FINISHED:
                         mAppObserver.restoreFinished(msg.arg1);
@@ -181,9 +178,9 @@ public class RestoreSession {
                     mHandler.obtainMessage(MSG_RESTORE_STARTING, numPackages, 0));
         }
 
-        public void onUpdate(int nowBeingRestored) {
+        public void onUpdate(int nowBeingRestored, String currentPackage) {
             mHandler.sendMessage(
-                    mHandler.obtainMessage(MSG_UPDATE, nowBeingRestored, 0));
+                    mHandler.obtainMessage(MSG_UPDATE, nowBeingRestored, 0, currentPackage));
         }
 
         public void restoreFinished(int error) {