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

1 files changed, 31 insertions, 25 deletions

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