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

6 files changed, 81 insertions, 53 deletions

diff --git a/api/current.xml b/api/current.xml
index 70a4c57..91b7340 100644
--- a/api/current.xml
+++ b/api/current.xml
@@ -42859,6 +42859,17 @@
  visibility="public"
 >
 </field>
+<field name="FLAG_ALLOW_BACKUP"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="32768"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 <field name="FLAG_ALLOW_CLEAR_USER_DATA"
  type="int"
  transient="false"
@@ -42914,6 +42925,17 @@
  visibility="public"
 >
 </field>
+<field name="FLAG_KILL_AFTER_RESTORE"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="65536"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 <field name="FLAG_PERSISTENT"
  type="int"
  transient="false"
@@ -42936,6 +42958,17 @@
  visibility="public"
 >
 </field>
+<field name="FLAG_RESTORE_ANY_VERSION"
+ type="int"
+ transient="false"
+ volatile="false"
+ value="131072"
+ static="true"
+ final="true"
+ deprecated="not deprecated"
+ visibility="public"
+>
+</field>
 <field name="FLAG_SUPPORTS_LARGE_SCREENS"
  type="int"
  transient="false"
@@ -74310,7 +74343,7 @@
  type="float"
  transient="false"
  volatile="false"
- value="0.001f"
+ value="0.0010f"
  static="true"
  final="true"
  deprecated="not deprecated"
@@ -214714,7 +214747,7 @@
  deprecated="not deprecated"
  visibility="public"
 >
-<parameter name="t" type="T">
+<parameter name="arg0" type="T">
 </parameter>
 </method>
 </interface>
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
diff --git a/services/java/com/android/server/BackupManagerService.java b/services/java/com/android/server/BackupManagerService.java
index ffba4ad..dae7f9c 100644
--- a/services/java/com/android/server/BackupManagerService.java
+++ b/services/java/com/android/server/BackupManagerService.java
@@ -819,8 +819,6 @@ class BackupManagerService extends IBackupManager.Stub {
                         + " uid=" + p.applicationInfo.uid
                         + " killAfterRestore="
                         + (((p.applicationInfo.flags & ApplicationInfo.FLAG_KILL_AFTER_RESTORE) != 0) ? "true" : "false")
-                        + " restoreNeedsApplication="
-                        + (((p.applicationInfo.flags & ApplicationInfo.FLAG_RESTORE_NEEDS_APPLICATION) != 0) ? "true" : "false")
                         );
             }
         }
@@ -1677,17 +1675,10 @@ class BackupManagerService extends IBackupManager.Stub {
                             + "] is compatible with installed version ["
                             + packageInfo.versionCode + "]");
 
-                    // Then set up and bind the agent (with a restricted Application object
-                    // unless the application says otherwise)
-                    boolean useRealApp = (packageInfo.applicationInfo.flags
-                            & ApplicationInfo.FLAG_RESTORE_NEEDS_APPLICATION) != 0;
-                    if (DEBUG && useRealApp) {
-                        Slog.v(TAG, "agent requires real Application subclass for restore");
-                    }
+                    // Then set up and bind the agent
                     IBackupAgent agent = bindToAgentSynchronous(
                             packageInfo.applicationInfo,
-                            (useRealApp ? IApplicationThread.BACKUP_MODE_INCREMENTAL
-                                    : IApplicationThread.BACKUP_MODE_RESTORE));
+                            IApplicationThread.BACKUP_MODE_INCREMENTAL);
                     if (agent == null) {
                         Slog.w(TAG, "Can't find backup agent for " + packageName);
                         EventLog.writeEvent(EventLogTags.RESTORE_AGENT_FAILURE, packageName,