Merge "Add some backup Javadoc and clean imports"

13 files changed, 170 insertions, 102 deletions

diff --git a/core/java/android/app/BackupAgent.java b/core/java/android/app/BackupAgent.java
index a2bfc76..4695c21 100644
--- a/core/java/android/app/BackupAgent.java
+++ b/core/java/android/app/BackupAgent.java
@@ -31,10 +31,18 @@ import android.util.Log;
 import java.io.IOException;
 
 /**
- * This is the central interface between an application and Android's
- * settings backup mechanism.
- *
- * <p>STOPSHIP write more documentation about the backup process here.
+ * This is the central interface between an application and Android's settings
+ * backup mechanism. Any implementation of a backup agent should perform backup
+ * and restore actions in
+ * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}
+ * and {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor)}
+ * respectively.
+ * <p>
+ * A backup agent based on convenient helper classes is available in
+ * {@link android.backup.BackupHelperAgent} for less complex implementation
+ * requirements.
+ * <p>
+ * STOPSHIP write more documentation about the backup process here.
  */
 public abstract class BackupAgent extends ContextWrapper {
     private static final String TAG = "BackupAgent";
@@ -51,51 +59,58 @@ public abstract class BackupAgent extends ContextWrapper {
     }
 
     /**
-     * The application is being asked to write any data changed since the
-     * last time it performed a backup operation.  The state data recorded
-     * during the last backup pass is provided in the oldState file descriptor.
-     * If oldState is null, no old state is available and the application should perform
-     * a full backup.  In both cases, a representation of the final backup state after
-     * this pass should be written to the file pointed to by the newStateFd file descriptor.
-     *
-     * @param oldState An open, read-only ParcelFileDescriptor pointing to the last backup
-     *                 state provided by the application.  May be null, in which
-     *                 case no prior state is being provided and the application should
-     *                 perform a full backup.
-     * @param data A structured wrapper around an open, read/write ParcelFileDescriptor
-     *             pointing to the backup data destination.  Typically the application will use
-     *             backup helper classes to write to this file.
-     * @param newState An open, read/write ParcelFileDescriptor pointing to an empty
-     *                 file.  The application should record the final backup state
-     *                 here after writing the requested data to dataFd.
+     * The application is being asked to write any data changed since the last
+     * time it performed a backup operation. The state data recorded during the
+     * last backup pass is provided in the <code>oldState</code> file
+     * descriptor. If <code>oldState</code> is <code>null</code>, no old state
+     * is available and the application should perform a full backup. In both
+     * cases, a representation of the final backup state after this pass should
+     * be written to the file pointed to by the file descriptor wrapped in
+     * <code>newState</code>.
+     * 
+     * @param oldState An open, read-only ParcelFileDescriptor pointing to the
+     *            last backup state provided by the application. May be
+     *            <code>null</code>, in which case no prior state is being
+     *            provided and the application should perform a full backup.
+     * @param data A structured wrapper around an open, read/write
+     *            ParcelFileDescriptor pointing to the backup data destination.
+     *            Typically the application will use backup helper classes to
+     *            write to this file.
+     * @param newState An open, read/write ParcelFileDescriptor pointing to an
+     *            empty file. The application should record the final backup
+     *            state here after writing the requested data to dataFd.
      */
     public abstract void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
              ParcelFileDescriptor newState) throws IOException;
-    
+
     /**
-     * The application is being restored from backup, and should replace any
-     * existing data with the contents of the backup.  The backup data is
-     * provided in the file pointed to by the dataFd file descriptor.  Once
-     * the restore is finished, the application should write a representation
-     * of the final state to the newStateFd file descriptor,
-     *
-     * <p>The application is responsible for properly erasing its old data and
-     * replacing it with the data supplied to this method.  No "clear user data"
-     * operation will be performed automatically by the operating system.  The
-     * exception to this is in the case of a failed restore attempt:  if onRestore()
-     * throws an exception, the OS will assume that the application's data may now
-     * be in an incoherent state, and will clear it before proceeding.
-     *
-     * @param data A structured wrapper around an open, read-only ParcelFileDescriptor
-     *             pointing to a full snapshot of the application's data.  Typically the
-     *             application will use helper classes to read this data.
-     * @param appVersionCode The android:versionCode value of the application that backed
-     *        up this particular data set.  This makes it easier for an application's
-     *        agent to distinguish among several possible older data versions when
-     *        asked to perform the restore operation.
-     * @param newState An open, read/write ParcelFileDescriptor pointing to an empty
-     *                 file.  The application should record the final backup state
-     *                 here after restoring its data from dataFd.
+     * The application is being restored from backup and should replace any
+     * existing data with the contents of the backup. The backup data is
+     * provided in the file descriptor pointed to by the
+     * {@link android.backup.BackupDataInput} instance <code>data</code>. Once
+     * the restore is finished, the application should write a representation of
+     * the final state to the <code>newState</code> file descriptor.
+     * <p>
+     * The application is responsible for properly erasing its old data and
+     * replacing it with the data supplied to this method. No "clear user data"
+     * operation will be performed automatically by the operating system. The
+     * exception to this is in the case of a failed restore attempt: if
+     * onRestore() throws an exception, the OS will assume that the
+     * application's data may now be in an incoherent state, and will clear it
+     * before proceeding.
+     * 
+     * @param data A structured wrapper around an open, read-only
+     *            ParcelFileDescriptor pointing to a full snapshot of the
+     *            application's data. Typically the application will use helper
+     *            classes to read this data.
+     * @param appVersionCode The android:versionCode value of the application
+     *            that backed up this particular data set. This makes it easier
+     *            for an application's agent to distinguish among several
+     *            possible older data versions when asked to perform the restore
+     *            operation.
+     * @param newState An open, read/write ParcelFileDescriptor pointing to an
+     *            empty file. The application should record the final backup
+     *            state here after restoring its data from dataFd.
      */
     public abstract void onRestore(BackupDataInput data, int appVersionCode,
             ParcelFileDescriptor newState)
diff --git a/core/java/android/backup/AbsoluteFileBackupHelper.java b/core/java/android/backup/AbsoluteFileBackupHelper.java
index 6bf848f..5a8034b 100644
--- a/core/java/android/backup/AbsoluteFileBackupHelper.java
+++ b/core/java/android/backup/AbsoluteFileBackupHelper.java
@@ -21,7 +21,6 @@ import android.os.ParcelFileDescriptor;
 import android.util.Log;
 
 import java.io.File;
-import java.io.FileDescriptor;
 
 /**
  * Like FileBackupHelper, but takes absolute paths for the files instead of
diff --git a/core/java/android/backup/BackupDataInput.java b/core/java/android/backup/BackupDataInput.java
index 295dc66..a08ee75 100644
--- a/core/java/android/backup/BackupDataInput.java
+++ b/core/java/android/backup/BackupDataInput.java
@@ -16,8 +16,6 @@
 
 package android.backup;
 
-import android.content.Context;
-
 import java.io.FileDescriptor;
 import java.io.IOException;
 
diff --git a/core/java/android/backup/BackupDataOutput.java b/core/java/android/backup/BackupDataOutput.java
index 672d01f..34879d8 100644
--- a/core/java/android/backup/BackupDataOutput.java
+++ b/core/java/android/backup/BackupDataOutput.java
@@ -16,8 +16,6 @@
 
 package android.backup;
 
-import android.content.Context;
-
 import java.io.FileDescriptor;
 import java.io.IOException;
 
diff --git a/core/java/android/backup/BackupHelper.java b/core/java/android/backup/BackupHelper.java
index fc48cf2..7eedd01 100644
--- a/core/java/android/backup/BackupHelper.java
+++ b/core/java/android/backup/BackupHelper.java
@@ -18,16 +18,19 @@ package android.backup;
 
 import android.os.ParcelFileDescriptor;
 
-import java.io.InputStream;
-
 /**
- * STOPSHIP: document!
+ * A convenient interface to be used with the
+ * {@link android.backup.BackupHelperAgent} to implement backup and restore of
+ * arbitrary data types.
+ * <p>
+ * STOPSHOP: document!
  */
 public interface BackupHelper {
     /**
-     * Based on oldState, determine which of the files from the application's data directory
-     * need to be backed up, write them to the data stream, and fill in newState with the
-     * state as it exists now.
+     * Based on <code>oldState</code>, determine which of the files from the
+     * application's data directory need to be backed up, write them to
+     * <code>data</code>, and fill in <code>newState</code> with the state as it
+     * exists now.
      */
     public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
             ParcelFileDescriptor newState);
diff --git a/core/java/android/backup/BackupHelperAgent.java b/core/java/android/backup/BackupHelperAgent.java
index dc17154f..7fb44f4 100644
--- a/core/java/android/backup/BackupHelperAgent.java
+++ b/core/java/android/backup/BackupHelperAgent.java
@@ -17,24 +17,19 @@
 package android.backup;
 
 import android.app.BackupAgent;
-import android.backup.BackupHelper;
-import android.backup.BackupHelperDispatcher;
-import android.backup.BackupDataInput;
-import android.backup.BackupDataOutput;
 import android.os.ParcelFileDescriptor;
-import android.util.Log;
 
 import java.io.IOException;
 
 /**
- * A convenient BackupAgent wrapper class that automatically manages heterogeneous
- * data sets within the backup data, each identified by a unique key prefix.  An
- * application will typically extend this class in their own backup agent.  Then,
- * within the agent's onBackup() and onRestore() methods, it will call
- * {@link #addHelper(String, BackupHelper)} one or more times to specify the data
- * sets, then invoke super.onBackup() or super.onRestore() to have the BackupHelperAgent
- * implementation process the data.
- *
+ * A convenient BackupAgent wrapper class that automatically manages
+ * heterogeneous data sets within the backup data, each identified by a unique
+ * key prefix. An application will typically extend this class in their own
+ * backup agent. Then, within the agent's onBackup() and onRestore() methods, it
+ * will call {@link #addHelper(String, BackupHelper)} one or more times to
+ * specify the data sets, then invoke super.onBackup() or super.onRestore() to
+ * have the BackupHelperAgent implementation process the data.
+ * <p>
  * STOPSHIP: document!
  */
 public class BackupHelperAgent extends BackupAgent {
diff --git a/core/java/android/backup/BackupHelperDispatcher.java b/core/java/android/backup/BackupHelperDispatcher.java
index bf2c44d..68076db 100644
--- a/core/java/android/backup/BackupHelperDispatcher.java
+++ b/core/java/android/backup/BackupHelperDispatcher.java
@@ -19,12 +19,10 @@ package android.backup;
 import android.os.ParcelFileDescriptor;
 import android.util.Log;
 
-import java.io.DataInputStream;
-import java.io.DataOutputStream;
-import java.io.IOException;
 import java.io.FileDescriptor;
-import java.util.TreeMap;
+import java.io.IOException;
 import java.util.Map;
+import java.util.TreeMap;
 
 /** @hide */
 public class BackupHelperDispatcher {
diff --git a/core/java/android/backup/BackupManager.java b/core/java/android/backup/BackupManager.java
index 07c08ff..2dff975 100644
--- a/core/java/android/backup/BackupManager.java
+++ b/core/java/android/backup/BackupManager.java
@@ -23,26 +23,36 @@ import android.os.ServiceManager;
 import android.util.Log;
 
 /**
- * BackupManager is the interface to the system's backup service.
- * Applications simply instantiate one, and then use that instance
- * to communicate with the backup infrastructure.
- *
- * <p>When your application has made changes to data it wishes to have
- * backed up, call {@link #dataChanged()} to notify the backup service.
- * The system will then schedule a backup operation to occur in the near
- * future.  Repeated calls to {@link #dataChanged()} have no further effect
- * until the backup operation actually occurs.
- *
- * <p>The backup operation itself begins with the system launching the
- * {@link android.app.BackupAgent} subclass declared in your manifest.  See the
+ * BackupManager is the interface to the system's backup service. Applications
+ * simply instantiate one, and then use that instance to communicate with the
+ * backup infrastructure.
+ * <p>
+ * When an application has made changes to data which should be backed up, a
+ * call to {@link #dataChanged()} will notify the backup service. The system
+ * will then schedule a backup operation to occur in the near future. Repeated
+ * calls to {@link #dataChanged()} have no further effect until the backup
+ * operation actually occurs.
+ * <p>
+ * The backup operation itself begins with the system launching the
+ * {@link android.app.BackupAgent} subclass declared in your manifest. See the
  * documentation for {@link android.app.BackupAgent} for a detailed description
  * of how the backup then proceeds.
- *
- * <p>STOPSHIP more documentation here!  Include the attributes:
- *    android:backupAgent
- *    android:allowBackup
- *    android:restoreNeedsApplication
- *    android:killAfterRestore
+ * <p>
+ * A simple implementation of a BackupAgent useful for backing up Preferences
+ * and files is available by using {@link android.backup.BackupHelperAgent}.
+ * <p>
+ * STOPSHIP: more documentation!
+ * <p>
+ * <b>XML attributes</b>
+ * <p>
+ * See {@link android.R.styleable#AndroidManifestApplication 
+ * AndroidManifest.xml's application attributes}
+ * 
+ * @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 {
     private static final String TAG = "BackupManager";
diff --git a/core/java/android/backup/FileBackupHelper.java b/core/java/android/backup/FileBackupHelper.java
index 68b4d42..cc859e2 100644
--- a/core/java/android/backup/FileBackupHelper.java
+++ b/core/java/android/backup/FileBackupHelper.java
@@ -21,10 +21,23 @@ import android.os.ParcelFileDescriptor;
 import android.util.Log;
 
 import java.io.File;
-import java.io.FileDescriptor;
 
 /**
- * STOPSHIP: document!  [manages backup of a set of files; restore is totally opaque]
+ * A helper class which can be used in conjunction with
+ * {@link android.backup.BackupHelperAgent} to manage the backup of a set of
+ * files. Whenever backup is performed, all files changed since the last backup
+ * will be saved in their entirety. During the first time the backup happens,
+ * all the files in the list will be backed up. Note that this should only be
+ * used with small configuration files and not with large binary files.
+ * <p>
+ * Any files not present in the list of files during the restore procedure will
+ * be ignored. If files present in a previous version of an application are
+ * removed in subsequent versions, it is the responsibility of the developer to
+ * design a mechanism to remove those files. Otherwise files no longer needed
+ * will linger and consume space on the device.
+ * <p>
+ * STOPSHIP: document! [manages backup of a set of files; restore is totally
+ * opaque]
  */
 public class FileBackupHelper extends FileBackupHelperBase implements BackupHelper {
     private static final String TAG = "FileBackupHelper";
@@ -50,9 +63,16 @@ public class FileBackupHelper extends FileBackupHelperBase implements BackupHelp
     }
 
     /**
-     * Based on oldState, determine which of the files from the application's data directory
-     * need to be backed up, write them to the data stream, and fill in newState with the
-     * state as it exists now.
+     * Based on <code>oldState</code>, determine which of the files from the
+     * application's data directory need to be backed up, write them to the data
+     * stream, and fill in <code>newState</code> with the state as it exists
+     * now. When <code>oldState</code> is <code>null</code>, all the files will
+     * be backed up.
+     * <p>
+     * This should be called from {@link android.backup.BackupHelperAgent}
+     * directly. See
+     * {@link android.app.BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}
+     * for a description of parameter meanings.
      */
     public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
             ParcelFileDescriptor newState) {
diff --git a/core/java/android/backup/FileBackupHelperBase.java b/core/java/android/backup/FileBackupHelperBase.java
index a0ff38b..7cb1ccc 100644
--- a/core/java/android/backup/FileBackupHelperBase.java
+++ b/core/java/android/backup/FileBackupHelperBase.java
@@ -22,10 +22,12 @@ import android.util.Log;
 
 import java.io.File;
 import java.io.FileDescriptor;
-import java.io.FileOutputStream;
 
+/**
+ * Base class for the {@link android.backup.FileBackupHelper} implementation.
+ */
 class FileBackupHelperBase {
-    private static final String TAG = "RestoreHelperBase";
+    private static final String TAG = "FileBackupHelperBase";
 
     int mPtr;
     Context mContext;
@@ -45,8 +47,8 @@ class FileBackupHelperBase {
     }
 
     /**
-     * Check the parameters so the native code doens't have to throw all the exceptions
-     * since it's easier to do that from java.
+     * Check the parameters so the native code doesn't have to throw all the exceptions
+     * since it's easier to do that from Java.
      */
     static void performBackup_checked(ParcelFileDescriptor oldState, BackupDataOutput data,
             ParcelFileDescriptor newState, String[] files, String[] keys) {
diff --git a/core/java/android/backup/SharedPreferencesBackupHelper.java b/core/java/android/backup/SharedPreferencesBackupHelper.java
index f9c97a3..7ba80db 100644
--- a/core/java/android/backup/SharedPreferencesBackupHelper.java
+++ b/core/java/android/backup/SharedPreferencesBackupHelper.java
@@ -17,13 +17,19 @@
 package android.backup;
 
 import android.content.Context;
+import android.content.SharedPreferences;
 import android.os.ParcelFileDescriptor;
 import android.util.Log;
 
 import java.io.File;
-import java.io.FileDescriptor;
 
 /**
+ * A helper class which can be used in conjunction with
+ * {@link android.backup.BackupHelperAgent} to manage the backup of
+ * {@link android.content.SharedPreferences}. Whenever backup is performed it
+ * will back up all named shared preferences which have changed since the last
+ * backup.
+ * <p>
  * STOPSHIP: document!
  */
 public class SharedPreferencesBackupHelper extends FileBackupHelperBase implements BackupHelper {
diff --git a/core/java/android/backup/package.html b/core/java/android/backup/package.html
new file mode 100644
index 0000000..13c0eb8
--- /dev/null
+++ b/core/java/android/backup/package.html
@@ -0,0 +1,22 @@
+<HTML>
+<BODY>
+<p>Package containing the backup and restore functionality available to
+applications. All backup management is controlled through
+{@link android.backup.BackupManager}.  Individual backup functionality is
+implemented through a subclass {@link android.app.BackupAgent} and a
+simple and easy-to-use implementation is provided in
+{@link android.backup.BackupHelperAgent}.</p>
+
+<p>STOPSHIP: add more documenation and remove Dev Guide link if not written!</p>
+
+<p>The backup APIs let applications:</p>
+<ul>
+  <li>Perform backup of arbitrary data</li>
+  <li>Easily perform backup of Preferences and files</li>
+  <li>Handle restore of data</li>
+</ul>
+
+<p>For a detailed guide to using the backup APIs, see the <a
+href="{@docRoot}guide/topics/backup.html">Backup Dev Guide topic</a>.</p>
+</BODY>
+</HTML>
diff --git a/core/res/res/values/attrs_manifest.xml b/core/res/res/values/attrs_manifest.xml
index 33b509b..430c4b8 100644
--- a/core/res/res/values/attrs_manifest.xml
+++ b/core/res/res/values/attrs_manifest.xml
@@ -592,7 +592,9 @@
          backup and restore of the application's settings to external storage. -->
     <attr name="backupAgent" format="string" />
 
-    <!-- This is not the attribute you are looking for. -->
+    <!-- Whether to allow the application to participate in backup
+         infrastructure.
+         STOPSHIP: more explanation -->
     <attr name="allowBackup" format="boolean" />
 
     <!-- Whether the application in question should be terminated after its