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

api/current.xml

@@ -27412,17 +27412,6 @@
 <parameter name="context" type="android.content.Context">
 </parameter>
 </constructor>
-<method name="beginRestoreSession"
- return="android.app.backup.RestoreSession"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
 <method name="dataChanged"
  return="void"
  abstract="false"
@@ -27447,6 +27436,19 @@
 <parameter name="packageName" type="java.lang.String">
 </parameter>
 </method>
+<method name="requestRestore"
+ return="int"
+ abstract="false"
+ native="false"
+ synchronized="false"
+ static="false"
+ final="false"
+ deprecated="not deprecated"
+ visibility="public"
+>
+<parameter name="observer" type="android.app.backup.RestoreObserver">
+</parameter>
+</method>
 </class>
 <class name="FileBackupHelper"
  extends="android.app.backup.FileBackupHelperBase"
@@ -27540,41 +27542,6 @@
 >
 </constructor>
 </class>
-<class name="RestoreSession"
- extends="java.lang.Object"
- abstract="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<method name="endRestoreSession"
- return="void"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-</method>
-<method name="restorePackage"
- return="int"
- abstract="false"
- native="false"
- synchronized="false"
- static="false"
- final="false"
- deprecated="not deprecated"
- visibility="public"
->
-<parameter name="packageName" type="java.lang.String">
-</parameter>
-<parameter name="observer" type="android.app.backup.RestoreObserver">
-</parameter>
-</method>
-</class>
 <class name="SharedPreferencesBackupHelper"
  extends="android.app.backup.FileBackupHelperBase"
  abstract="false"

cmds/bmgr/src/com/android/commands/bmgr/Bmgr.java

@@ -278,8 +278,8 @@ public final class Bmgr {
             System.out.println("restoreStarting: " + numPackages + " packages");
         }
 
-        public void onUpdate(int nowBeingRestored) {
+        public void onUpdate(int nowBeingRestored, String currentPackage) {
-            System.out.println("onUpdate: " + nowBeingRestored);
+            System.out.println("onUpdate: " + nowBeingRestored + " = " + currentPackage);
         }
 
         public void restoreFinished(int error) {

core/java/android/app/backup/BackupManager.java

@@ -114,9 +114,46 @@ 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;

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.

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
+     * total number provided in the {@link #restoreStarting(int)} callback.  This method
-     * is not guaranteed to be called.
+     * 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.

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) {

services/java/com/android/server/BackupManagerService.java

@@ -1618,7 +1618,7 @@ class BackupManagerService extends IBackupManager.Stub {
 
                     if (mObserver != null) {
                         try {
-                            mObserver.onUpdate(count);
+                            mObserver.onUpdate(count, packageName);
                         } catch (RemoteException e) {
                             Slog.d(TAG, "Restore observer died in onUpdate");
                             mObserver = null;