Merge "Add instrumentation for BackupManager during restore."

4 files changed, 156 insertions, 17 deletions

diff --git a/core/java/android/app/backup/BackupManager.java b/core/java/android/app/backup/BackupManager.java
index f5c223522213..59bd01f94592 100644
--- a/core/java/android/app/backup/BackupManager.java
+++ b/core/java/android/app/backup/BackupManager.java
@@ -258,16 +258,46 @@ public class BackupManager {
      * @return Zero on success; nonzero on error.
      */
     public int requestRestore(RestoreObserver observer) {
+        return requestRestore(observer, null);
+    }
+
+    // system APIs start here
+
+    /**
+     * 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.
+     *
+     * @param observer The {@link RestoreObserver} to receive callbacks during the restore
+     * operation. This must not be null.
+     *
+     * @param monitor the {@link BackupManagerMonitor} to receive callbacks during the restore
+     * operation.
+     *
+     * @return Zero on success; nonzero on error.
+     *
+     * @hide
+     */
+    @SystemApi
+    public int requestRestore(RestoreObserver observer, BackupManagerMonitor monitor) {
         int result = -1;
         checkServiceBinder();
         if (sService != null) {
             RestoreSession session = null;
             try {
                 IRestoreSession binder = sService.beginRestoreSession(mContext.getPackageName(),
-                        null);
+                    null);
                 if (binder != null) {
                     session = new RestoreSession(mContext, binder);
-                    result = session.restorePackage(mContext.getPackageName(), observer);
+                    result = session.restorePackage(mContext.getPackageName(), observer, monitor);
                 }
             } catch (RemoteException e) {
                 Log.e(TAG, "restoreSelf() unable to contact service");
@@ -280,8 +310,6 @@ public class BackupManager {
         return result;
     }
 
-    // system APIs start here
-
     /**
      * Begin the process of restoring data from backup.  See the
      * {@link android.app.backup.RestoreSession} class for documentation on that process.
diff --git a/core/java/android/app/backup/BackupManagerMonitor.java b/core/java/android/app/backup/BackupManagerMonitor.java
index b937886e2032..099878b310c5 100644
--- a/core/java/android/app/backup/BackupManagerMonitor.java
+++ b/core/java/android/app/backup/BackupManagerMonitor.java
@@ -57,6 +57,8 @@ public class BackupManagerMonitor {
   // TODO complete this list with all log messages. And document properly.
   public static final int LOG_EVENT_ID_FULL_BACKUP_TIMEOUT = 4;
   public static final int LOG_EVENT_ID_KEY_VALUE_BACKUP_TIMEOUT = 21;
+  public static final int LOG_EVENT_ID_KEY_VALUE_RESTORE_TIMEOUT = 31;
+  public static final int LOG_EVENT_ID_FULL_RESTORE_TIMEOUT = 45;
   public static final int LOG_EVENT_ID_NO_PACKAGES = 49;
 
 
diff --git a/core/java/android/app/backup/IRestoreSession.aidl b/core/java/android/app/backup/IRestoreSession.aidl
index 14731ee62cf0..b9e94856b69e 100644
--- a/core/java/android/app/backup/IRestoreSession.aidl
+++ b/core/java/android/app/backup/IRestoreSession.aidl
@@ -18,7 +18,7 @@ package android.app.backup;
 
 import android.app.backup.RestoreSet;
 import android.app.backup.IRestoreObserver;
-
+import android.app.backup.IBackupManagerMonitor;
 /**
  * Binder interface used by clients who wish to manage a restore operation.  Every
  * method in this interface requires the android.permission.BACKUP permission.
@@ -31,10 +31,11 @@ interface IRestoreSession {
      *
      * @param observer This binder points to an object whose onRestoreSetsAvailable()
      *   method will be called to supply the results of the transport's lookup.
+     * @param monitor If non null the binder will send important events to this monitor.
      * @return Zero on success; nonzero on error.  The observer will only receive a
      *   result callback if this method returned zero.
      */
-    int getAvailableRestoreSets(IRestoreObserver observer);
+    int getAvailableRestoreSets(IRestoreObserver observer, IBackupManagerMonitor monitor);
 
     /**
      * Restore the given set onto the device, replacing the current data of any app
@@ -48,8 +49,9 @@ interface IRestoreSession {
      *   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.
+     * @param monitor If non null the binder will send important events to this monitor.
      */
-    int restoreAll(long token, IRestoreObserver observer);
+    int restoreAll(long token, IRestoreObserver observer, IBackupManagerMonitor monitor);
 
     /**
      * Restore select packages from the given set onto the device, replacing the
@@ -67,8 +69,10 @@ interface IRestoreSession {
      * @param packages The set of packages for which to attempt a restore.  Regardless of
      *   the contents of the actual back-end dataset named by {@code token}, only
      *   applications mentioned in this list will have their data restored.
+     * @param monitor If non null the binder will send important events to this monitor.
      */
-    int restoreSome(long token, IRestoreObserver observer, in String[] packages);
+    int restoreSome(long token, IRestoreObserver observer, IBackupManagerMonitor monitor,
+            in String[] packages);
 
     /**
      * Restore a single application from backup.  The data will be restored from the
@@ -84,8 +88,10 @@ interface IRestoreSession {
      *   permission must be held.
      * @param observer If non-null, this binder points to an object that will receive
      *   progress callbacks during the restore operation.
+     * @param monitor If non null the binder will send important events to this monitor.
      */
-    int restorePackage(in String packageName, IRestoreObserver observer);
+    int restorePackage(in String packageName, IRestoreObserver observer,
+          IBackupManagerMonitor monitor);
 
     /**
      * End this restore session.  After this method is called, the IRestoreSession binder
diff --git a/core/java/android/app/backup/RestoreSession.java b/core/java/android/app/backup/RestoreSession.java
index 0a885b6e720f..94fac17c99a3 100644
--- a/core/java/android/app/backup/RestoreSession.java
+++ b/core/java/android/app/backup/RestoreSession.java
@@ -22,6 +22,7 @@ import android.app.backup.RestoreSet;
 import android.app.backup.IRestoreObserver;
 import android.app.backup.IRestoreSession;
 import android.content.Context;
+import android.os.Bundle;
 import android.os.Handler;
 import android.os.Message;
 import android.os.RemoteException;
@@ -46,14 +47,16 @@ public class RestoreSession {
      *   be called on the application's main thread in order to supply the results of
      *   the restore set lookup by the backup transport.  This parameter must not be
      *   null.
+     * @param monitor a BackupManagerMonitor object will supply data about important events.
      * @return Zero on success, nonzero on error.  The observer's restoreSetsAvailable()
      *   method will only be called if this method returned zero.
      */
-    public int getAvailableRestoreSets(RestoreObserver observer) {
+    public int getAvailableRestoreSets(RestoreObserver observer, BackupManagerMonitor monitor) {
         int err = -1;
         RestoreObserverWrapper obsWrapper = new RestoreObserverWrapper(mContext, observer);
+        BackupManagerMonitorWrapper monitorWrapper = new BackupManagerMonitorWrapper(monitor);
         try {
-            err = mBinder.getAvailableRestoreSets(obsWrapper);
+            err = mBinder.getAvailableRestoreSets(obsWrapper, monitorWrapper);
         } catch (RemoteException e) {
             Log.d(TAG, "Can't contact server to get available sets");
         }
@@ -61,6 +64,20 @@ public class RestoreSession {
     }
 
     /**
+     * Ask the current transport what the available restore sets are.
+     *
+     * @param observer a RestoreObserver object whose restoreSetsAvailable() method will
+     *   be called on the application's main thread in order to supply the results of
+     *   the restore set lookup by the backup transport.  This parameter must not be
+     *   null.
+     * @return Zero on success, nonzero on error.  The observer's restoreSetsAvailable()
+     *   method will only be called if this method returned zero.
+     */
+    public int getAvailableRestoreSets(RestoreObserver observer) {
+        return getAvailableRestoreSets(observer, null);
+    }
+
+    /**
      * Restore the given set onto the device, replacing the current data of any app
      * contained in the restore set with the data previously backed up.
      *
@@ -72,16 +89,19 @@ 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.
+     * @param monitor If non-null, this binder points to an object that will receive
+     *   progress callbacks during the restore operation.
      */
-    public int restoreAll(long token, RestoreObserver observer) {
+    public int restoreAll(long token, RestoreObserver observer, BackupManagerMonitor monitor) {
         int err = -1;
         if (mObserver != null) {
             Log.d(TAG, "restoreAll() called during active restore");
             return -1;
         }
         mObserver = new RestoreObserverWrapper(mContext, observer);
+        BackupManagerMonitorWrapper monitorWrapper = new BackupManagerMonitorWrapper(monitor);
         try {
-            err = mBinder.restoreAll(token, mObserver);
+            err = mBinder.restoreAll(token, mObserver, monitorWrapper);
         } catch (RemoteException e) {
             Log.d(TAG, "Can't contact server to restore");
         }
@@ -89,6 +109,23 @@ public class RestoreSession {
     }
 
     /**
+     * Restore the given set onto the device, replacing the current data of any app
+     * contained in the restore set with the data previously backed up.
+     *
+     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
+     *
+     * @return Zero on success; nonzero on error.  The observer will only receive
+     *   progress callbacks if this method returned zero.
+     * @param token The token from {@link #getAvailableRestoreSets()} corresponding to
+     *   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.
+     */
+    public int restoreAll(long token, RestoreObserver observer) {
+        return restoreAll(token, observer, null);
+    }
+
+    /**
      * Restore select packages from the given set onto the device, replacing the
      * current data of any app contained in the set with the data previously
      * backed up.
@@ -101,21 +138,25 @@ 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.
+     * @param monitor If non-null, this binder points to an object that will receive
+     *   progress callbacks during the restore operation.
      * @param packages The set of packages for which to attempt a restore.  Regardless of
      *   the contents of the actual back-end dataset named by {@code token}, only
      *   applications mentioned in this list will have their data restored.
      *
      * @hide
      */
-    public int restoreSome(long token, RestoreObserver observer, String[] packages) {
+    public int restoreSome(long token, RestoreObserver observer, BackupManagerMonitor monitor,
+            String[] packages) {
         int err = -1;
         if (mObserver != null) {
             Log.d(TAG, "restoreAll() called during active restore");
             return -1;
         }
         mObserver = new RestoreObserverWrapper(mContext, observer);
+        BackupManagerMonitorWrapper monitorWrapper = new BackupManagerMonitorWrapper(monitor);
         try {
-            err = mBinder.restoreSome(token, mObserver, packages);
+            err = mBinder.restoreSome(token, mObserver, monitorWrapper, packages);
         } catch (RemoteException e) {
             Log.d(TAG, "Can't contact server to restore packages");
         }
@@ -123,6 +164,29 @@ public class RestoreSession {
     }
 
     /**
+     * Restore select packages from the given set onto the device, replacing the
+     * current data of any app contained in the set with the data previously
+     * backed up.
+     *
+     * <p>Callers must hold the android.permission.BACKUP permission to use this method.
+     *
+     * @return Zero on success, nonzero on error. The observer will only receive
+     *   progress callbacks if this method returned zero.
+     * @param token The token from {@link getAvailableRestoreSets()} corresponding to
+     *   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.
+     * @param packages The set of packages for which to attempt a restore.  Regardless of
+     *   the contents of the actual back-end dataset named by {@code token}, only
+     *   applications mentioned in this list will have their data restored.
+     *
+     * @hide
+     */
+    public int restoreSome(long token, RestoreObserver observer, String[] packages) {
+        return restoreSome(token, observer, null, packages);
+    }
+
+    /**
      * Restore a single application from backup.  The data will be restored from the
      * current backup dataset if the given package has stored data there, or from
      * the dataset used during the last full device setup operation if the current
@@ -136,22 +200,48 @@ public class RestoreSession {
      *   permission must be held.
      * @param observer If non-null, this binder points to an object that will receive
      *   progress callbacks during the restore operation.
+     *
+     * @param monitor If non-null, this binder points to an object that will receive
+     *   event callbacks during the restore operation.
      */
-    public int restorePackage(String packageName, RestoreObserver observer) {
+    public int restorePackage(String packageName, RestoreObserver observer,
+            BackupManagerMonitor monitor) {
         int err = -1;
         if (mObserver != null) {
             Log.d(TAG, "restorePackage() called during active restore");
             return -1;
         }
         mObserver = new RestoreObserverWrapper(mContext, observer);
+        BackupManagerMonitorWrapper monitorWrapper = new BackupManagerMonitorWrapper(monitor);
+
         try {
-            err = mBinder.restorePackage(packageName, mObserver);
+            err = mBinder.restorePackage(packageName, mObserver, monitorWrapper);
         } catch (RemoteException e) {
             Log.d(TAG, "Can't contact server to restore package");
         }
         return err;
     }
 
+
+    /**
+     * Restore a single application from backup.  The data will be restored from the
+     * current backup dataset if the given package 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 package
+     * in either source, a nonzero value will be returned.
+     *
+     * @return Zero on success; nonzero on error.  The observer will only receive
+     *   progress callbacks if this method returned zero.
+     * @param packageName The name of the package whose data to restore.  If this is
+     *   not the name of the caller's own package, then the android.permission.BACKUP
+     *   permission must be held.
+     * @param observer If non-null, this binder points to an object that will receive
+     *   progress callbacks during the restore operation.
+     */
+    public int restorePackage(String packageName, RestoreObserver observer) {
+        return restorePackage(packageName, observer, null);
+    }
+
     /**
      * End this restore session.  After this method is called, the RestoreSession
      * object is no longer valid.
@@ -236,4 +326,17 @@ public class RestoreSession {
                     mHandler.obtainMessage(MSG_RESTORE_FINISHED, error, 0));
         }
     }
+
+    private class BackupManagerMonitorWrapper extends IBackupManagerMonitor.Stub {
+        final BackupManagerMonitor mMonitor;
+
+        BackupManagerMonitorWrapper(BackupManagerMonitor monitor) {
+            mMonitor = monitor;
+        }
+
+        @Override
+        public void onEvent(final Bundle event) throws RemoteException {
+            mMonitor.onEvent(event);
+        }
+    }
 }