From 9c593f27ad5e5fdf22efac28edfc3a447acd8a89 Mon Sep 17 00:00:00 2001 From: Benjamin Miller Date: Mon, 28 May 2018 16:11:22 +0000 Subject: [PATCH] docs: Backup requestRestore() doesn't kill app during restore. Doc-only change to note that requestRestore() doesn't behave as expected and kill the app as part of the restore operation. Fixed formatting of first paragraph running into deprecation notice. Also removed dupe versioning info from deprecation notice--see staged version. Staged at: http://go/dac-stage/reference/android/app/backup/BackupManager#requestrestore Bug: 29255593 Test: make ds-docs and staged output. Visual inspection and manual link test. Change-Id: I8baae2216f23bd63510f8b445fcdd8090354b0df --- .../android/app/backup/BackupManager.java | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/core/java/android/app/backup/BackupManager.java b/core/java/android/app/backup/BackupManager.java index 30f340c50e327..43f69e1c98f78 100644 --- a/core/java/android/app/backup/BackupManager.java +++ b/core/java/android/app/backup/BackupManager.java @@ -253,20 +253,27 @@ public class BackupManager { } /** - * @deprecated Since Android P app can no longer request restoring of its backup. + * @deprecated Applications shouldn't request a restore operation using this method. In Android + * P and later, this method is a no-op. * - * Restore the calling application from backup. The data will be restored from the + *

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. + * in either source, a non-zero value is returned. * - *

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 + *

If this method returns zero (meaning success), the OS attempts 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. * + *

Unlike other restore operations, this method doesn't terminate the + * application after the restore. The application continues running to receive the + * {@link RestoreObserver} callbacks on the {@code observer} argument. Full backups use an + * {@link android.app.Application Application} base class while key-value backups use the + * application subclass declared in the AndroidManifest.xml {@code } tag. + * * @param observer The {@link RestoreObserver} to receive callbacks during the restore * operation. This must not be null. * @@ -282,7 +289,7 @@ public class BackupManager { /** * @deprecated Since Android P app can no longer request restoring of its backup. * - * Restore the calling application from backup. The data will be restored from the + *

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 @@ -635,7 +642,7 @@ public class BackupManager { } return false; } - + /** * Request an immediate backup, providing an observer to which results of the backup operation * will be published. The Android backup system will decide for each package whether it will