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
diff --git a/api/current.xml b/api/current.xml
index 1ac6812..f9470d9 100644
--- a/api/current.xml
+++ b/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"
diff --git a/cmds/bmgr/src/com/android/commands/bmgr/Bmgr.java b/cmds/bmgr/src/com/android/commands/bmgr/Bmgr.java
index d040b44..fa8a7c8 100644
--- a/cmds/bmgr/src/com/android/commands/bmgr/Bmgr.java
+++ b/cmds/bmgr/src/com/android/commands/bmgr/Bmgr.java
@@ -278,8 +278,8 @@
System.out.println("restoreStarting: " + numPackages + " packages");
}
- public void onUpdate(int nowBeingRestored) {
- System.out.println("onUpdate: " + nowBeingRestored);
+ public void onUpdate(int nowBeingRestored, String currentPackage) {
+ System.out.println("onUpdate: " + nowBeingRestored + " = " + currentPackage);
}
public void restoreFinished(int error) {
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 @@
}
/**
+ * 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 @@
*
* @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 @@
/**
* 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.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 @@
* 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 @@
* 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 @@
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 @@
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) {
diff --git a/services/java/com/android/server/BackupManagerService.java b/services/java/com/android/server/BackupManagerService.java
index dae7f9c..7607c74 100644
--- a/services/java/com/android/server/BackupManagerService.java
+++ b/services/java/com/android/server/BackupManagerService.java
@@ -1618,7 +1618,7 @@
if (mObserver != null) {
try {
- mObserver.onUpdate(count);
+ mObserver.onUpdate(count, packageName);
} catch (RemoteException e) {
Slog.d(TAG, "Restore observer died in onUpdate");
mObserver = null;
