API CHANGE: expose the backup-related ApplicationInfo flag masks

Fixes bug #2507582 by doing the following:

- Un-@hide the FLAG_ALLOW_BACKUP, FLAG_KILL_AFTER_RESTORE, and
  FLAG_RESTORE_ANY_VERSION mask constants in ApplicationInfo.  These
  correspond, respectively, to the <application> manifest tag's
  android:allowBackup, android:killAfterRestore, and
  android:restoreAnyVersion attributes.

- Remove the android:restoreNeedsApplication attribute and the
  corresponding FLAG_RESTORE_NEEDS_APPLICATION constant [which was still
  marked @hide].  We now always use the application's own Application
  class when performing a normal restore.  In the future when we support
  an externalized full-filesystem backup/restore operation, we will use
  an OS-defined agent class with a base-class Application instance, but
  this will not happen until a future release.

Also expands real documentation on the above ApplicationInfo constants;
that work is part of bug #2465360

Change-Id: I735d07a963ae80a01343637d83bef84e4c23fdcc

4 files changed, 44 insertions, 40 deletions

diff --git a/core/java/android/app/backup/BackupManager.java b/core/java/android/app/backup/BackupManager.java
index 12d4daf..2da8b56 100644
--- a/core/java/android/app/backup/BackupManager.java
+++ b/core/java/android/app/backup/BackupManager.java
@@ -52,8 +52,6 @@ import android.util.Log;
  * 
  * @attr ref android.R.styleable#AndroidManifestApplication_allowBackup
  * @attr ref android.R.styleable#AndroidManifestApplication_backupAgent
- * @attr ref
- *       android.R.styleable#AndroidManifestApplication_restoreNeedsApplication
  * @attr ref android.R.styleable#AndroidManifestApplication_killAfterRestore
  */
 public class BackupManager {
diff --git a/core/java/android/content/pm/ApplicationInfo.java b/core/java/android/content/pm/ApplicationInfo.java
index ca2887a..32cd2d5 100644
--- a/core/java/android/content/pm/ApplicationInfo.java
+++ b/core/java/android/content/pm/ApplicationInfo.java
@@ -200,34 +200,53 @@ public class ApplicationInfo extends PackageItemInfo implements Parcelable {
     public static final int FLAG_VM_SAFE_MODE = 1<<14;
 
     /**
-     * Value for {@link #flags}: this is false if the application has set
-     * its android:allowBackup to false, true otherwise.
+     * Value for {@link #flags}: set to <code>false</code> if the application does not wish
+     * to permit any OS-driven backups of its data; <code>true</code> otherwise.
      * 
-     * {@hide}
+     * <p>Comes from the
+     * {@link android.R.styleable#AndroidManifestApplication_allowBackup android:allowBackup}
+     * attribute of the &lt;application&gt; tag.
      */
     public static final int FLAG_ALLOW_BACKUP = 1<<15;
 
     /**
-     * Value for {@link #flags}: this is false if the application has set
-     * its android:killAfterRestore to false, true otherwise.
+     * Value for {@link #flags}: set to <code>false</code> if the application must be kept
+     * in memory following a full-system restore operation; <code>true</code> otherwise.
+     * Ordinarily, during a full system restore operation each application is shut down
+     * following execution of its agent's onRestore() method.  Setting this attribute to
+     * <code>false</code> prevents this.  Most applications will not need to set this attribute.
      *
-     * <p>If android:allowBackup is set to false or no android:backupAgent
+     * <p>If
+     * {@link android.R.styleable#AndroidManifestApplication_allowBackup android:allowBackup}
+     * is set to <code>false</code> or no
+     * {@link android.R.styleable#AndroidManifestApplication_backupAgent android:backupAgent}
      * is specified, this flag will be ignored.
      *
-     * {@hide}
+     * <p>Comes from the
+     * {@link android.R.styleable#AndroidManifestApplication_killAfterRestore android:killAfterRestore}
+     * attribute of the &lt;application&gt; tag.
      */
     public static final int FLAG_KILL_AFTER_RESTORE = 1<<16;
 
     /**
-     * Value for {@link #flags}: this is true if the application has set
-     * its android:restoreNeedsApplication to true, false otherwise.
+     * Value for {@link #flags}: Set to <code>true</code> if the application's backup
+     * agent claims to be able to handle restore data even "from the future,"
+     * i.e. from versions of the application with a versionCode greater than
+     * the one currently installed on the device.  <i>Use with caution!</i>  By default
+     * this attribute is <code>false</code> and the Backup Manager will ensure that data
+     * from "future" versions of the application are never supplied during a restore operation.
      *
-     * <p>If android:allowBackup is set to false or no android:backupAgent
+     * <p>If
+     * {@link android.R.styleable#AndroidManifestApplication_allowBackup android:allowBackup}
+     * is set to <code>false</code> or no
+     * {@link android.R.styleable#AndroidManifestApplication_backupAgent android:backupAgent}
      * is specified, this flag will be ignored.
      *
-     * {@hide}
+     * <p>Comes from the
+     * {@link android.R.styleable#AndroidManifestApplication_restoreAnyVersion android:restoreAnyVersion}
+     * attribute of the &lt;application&gt; tag.
      */
-    public static final int FLAG_RESTORE_NEEDS_APPLICATION = 1<<17;
+    public static final int FLAG_RESTORE_ANY_VERSION = 1<<17;
 
     /**
      * Value for {@link #flags}: this is true if the application has set
@@ -264,19 +283,6 @@ public class ApplicationInfo extends PackageItemInfo implements Parcelable {
     public static final int FLAG_NATIVE_DEBUGGABLE = 1<<21;
 
     /**
-     * Value for {@link #flags}: Set to true if the application's backup
-     * agent claims to be able to handle restore data even "from the future,"
-     * i.e. from versions of the application with a versionCode greater than
-     * the one currently installed on the device.
-     *
-     * <p>If android:allowBackup is set to false or no android:backupAgent
-     * is specified, this flag will be ignored.
-     *
-     * {@hide}
-     */
-    public static final int FLAG_RESTORE_ANY_VERSION = 1<<22;
-
-    /**
      * Flags associated with the application.  Any combination of
      * {@link #FLAG_SYSTEM}, {@link #FLAG_DEBUGGABLE}, {@link #FLAG_HAS_CODE},
      * {@link #FLAG_PERSISTENT}, {@link #FLAG_FACTORY_TEST}, and
diff --git a/core/java/android/content/pm/PackageParser.java b/core/java/android/content/pm/PackageParser.java
index 9736b01..c33f305 100644
--- a/core/java/android/content/pm/PackageParser.java
+++ b/core/java/android/content/pm/PackageParser.java
@@ -1448,8 +1448,8 @@ public class PackageParser {
         if (allowBackup) {
             ai.flags |= ApplicationInfo.FLAG_ALLOW_BACKUP;
 
-            // backupAgent, killAfterRestore, restoreNeedsApplication, and restoreAnyVersion
-            // are only relevant if backup is possible for the given application.
+            // backupAgent, killAfterRestore, and restoreAnyVersion are only relevant
+            // if backup is possible for the given application.
             String backupAgent = sa.getNonConfigurationString(
                     com.android.internal.R.styleable.AndroidManifestApplication_backupAgent, 0);
             if (backupAgent != null) {
@@ -1465,11 +1465,6 @@ public class PackageParser {
                     ai.flags |= ApplicationInfo.FLAG_KILL_AFTER_RESTORE;
                 }
                 if (sa.getBoolean(
-                        com.android.internal.R.styleable.AndroidManifestApplication_restoreNeedsApplication,
-                        false)) {
-                    ai.flags |= ApplicationInfo.FLAG_RESTORE_NEEDS_APPLICATION;
-                }
-                if (sa.getBoolean(
                         com.android.internal.R.styleable.AndroidManifestApplication_restoreAnyVersion,
                         false)) {
                     ai.flags |= ApplicationInfo.FLAG_RESTORE_ANY_VERSION;
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index d66f513..f00572d 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -589,7 +589,7 @@
     <attr name="reqFiveWayNav" format="boolean" />
 
     <!-- The name of the class implementing <code>BackupAgent</code> to manage
-         backup and restore of the application's settings to external storage. -->
+         backup and restore of application data on external storage. -->
     <attr name="backupAgent" format="string" />
 
     <!-- Whether to allow the application to participate in backup
@@ -600,13 +600,18 @@
     <attr name="allowBackup" format="boolean" />
 
     <!-- Whether the application in question should be terminated after its
-         settings have been restored.  The default is <code>true</code>,
-         which means to do so. -->
+         settings have been restored during a full-system restore operation.
+         Single-package restore operations will never cause the application to
+         be shut down.  Full-system restore operations typically only occur once,
+         when the phone is first set up.  Third-party applications will not usually
+         need to use this attribute.
+
+         <p>The default is <code>true</code>, which means that after the application
+         has finished processing its data during a full-system restore, it will be
+         terminated. -->
     <attr name="killAfterRestore" format="boolean" />
 
-    <!-- Whether the application needs to have its own Application subclass
-         active during restore.  The default is to run restore with a minimal
-         Application class to avoid interference with application logic. -->
+    <!-- @deprecated This attribute is not used by the Android operating system. -->
     <attr name="restoreNeedsApplication" format="boolean" />
 
     <!-- Indicate that the application is prepared to attempt a restore of any