Add some backup Javadoc and clean imports
Add a bit more Javadoc to the backup infrastructure and clean up unused
imports.
Change-Id: I8ab7c3fb887ae2e8d2f1bfac42f03cb4b42685ef
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 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 @@
}
/**
- * 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.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 @@
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 @@
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.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.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 @@
}
/**
- * 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 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 @@
}
/**
- * 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
