SDK: last of the backup/restore docs content

There is probably still some editing and cleanup to do, but this takes care
of the last of the "need this documented by the time we ship!" material.

Bug #2465360

Change-Id: Ic4ce9e5a07c79aa2b584a18012a2e8fe199c19fd

3 files changed, 118 insertions, 19 deletions

diff --git a/core/java/android/app/backup/BackupAgentHelper.java b/core/java/android/app/backup/BackupAgentHelper.java
index 788b1b53d07d..6d73090f74db 100644
--- a/core/java/android/app/backup/BackupAgentHelper.java
+++ b/core/java/android/app/backup/BackupAgentHelper.java
@@ -21,16 +21,28 @@ import android.os.ParcelFileDescriptor;
 import java.io.IOException;
 
 /**
- * A convenient BackupAgent wrapper class that automatically manages
+ * A convenient {@link 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 BackupAgentHelper implementation process the data.
+ * key prefix.  When processing a backup or restore operation, the BackupAgentHelper
+ * dispatches to one or more installed {@link BackupHelper helpers} objects, each
+ * of which is responsible for a defined subset of the data being processed.
  * <p>
- * STOPSHIP: document!
+ * An application will typically extend this class in their own
+ * backup agent. Then, within the agent's {@link BackupAgent#onCreate() onCreate()}
+ * method, it will call {@link #addHelper(String, BackupHelper)} one or more times to
+ * install the handlers for each kind of data it wishes to manage within its backups.
+ * <p>
+ * The Android framework currently provides two predefined {@link BackupHelper} classes:
+ * {@link FileBackupHelper}, which manages the backup and restore of entire files
+ * within an application's data directory hierarchy; and {@link SharedPreferencesBackupHelper},
+ * which manages the backup and restore of an application's
+ * {@link android.content.SharedPreferences} data.
+ * <p>
+ * An application can also implement its own helper classes to work within the
+ * {@link BackupAgentHelper} framework.  See the {@link BackupHelper} interface
+ * documentation for details.
  *
+ * @see BackupHelper
  * @see FileBackupHelper
  * @see SharedPreferencesBackupHelper
  */
diff --git a/core/java/android/app/backup/BackupDataInputStream.java b/core/java/android/app/backup/BackupDataInputStream.java
index a7f4ba6388fb..465b3b6afef7 100644
--- a/core/java/android/app/backup/BackupDataInputStream.java
+++ b/core/java/android/app/backup/BackupDataInputStream.java
@@ -20,7 +20,21 @@ import java.io.InputStream;
 import java.io.IOException;
 
 /**
- * STOPSHIP: document */
+ * Used by {@link BackupHelper} classes within the {@link BackupAgentHelper} mechanism,
+ * this class provides an {@link java.io.InputStream}-like interface for accessing an
+ * entity's data during a restore operation.
+ * <p>
+ * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity(BackupDataInputStream)}
+ * is called, the current entity's header has already been read from the underlying
+ * {@link BackupDataInput}.  The entity's key string and total data size are available
+ * through this class's {@link #getKey()} and {@link #size()} methods, respectively.
+ * <p class="note">
+ * <em>Note:</em> The caller should take care not to seek or close the underlying data
+ * source, or to read more than {@link #size()} bytes total from the stream.</p>
+ *
+ * @see BackupAgentHelper
+ * @see BackupHelper
+ */
 public class BackupDataInputStream extends InputStream {
 
     String key;
@@ -34,6 +48,13 @@ public class BackupDataInputStream extends InputStream {
         mData = data;
     }
 
+    /**
+     * Read one byte of entity data from the stream, returning it as
+     * an integer value.  If more than {@link #size()} bytes of data
+     * are read from the stream, the output of this method is undefined.
+     *
+     * @return The byte read, or undefined if the end of the stream has been reached.
+     */
     public int read() throws IOException {
         byte[] one = mOneByte;
         if (mOneByte == null) {
@@ -43,18 +64,52 @@ public class BackupDataInputStream extends InputStream {
         return one[0];
     }
 
+    /**
+     * Read up to {@code size} bytes of data into a byte array, beginning at position
+     * {@code offset} within the array.
+     *
+     * @param b Byte array into which the data will be read
+     * @param offset The data will be stored in {@code b} beginning at this index
+     *   within the array.
+     * @param size The number of bytes to read in this operation.  If insufficient
+     *   data exists within the entity to fulfill this request, only as much data
+     *   will be read as is available.
+     * @return The number of bytes of data read, or zero if all of the entity's
+     *   data has already been read.
+     */
     public int read(byte[] b, int offset, int size) throws IOException {
         return mData.readEntityData(b, offset, size);
     }
 
+    /**
+     * Read enough entity data into a byte array to fill the array.
+     *
+     * @param b Byte array to fill with data from the stream.  If the stream does not
+     *   have sufficient data to fill the array, then the contents of the remainder of
+     *   the array will be undefined.
+     * @return The number of bytes of data read, or zero if all of the entity's
+     *   data has already been read.
+     */
     public int read(byte[] b) throws IOException {
         return mData.readEntityData(b, 0, b.length);
     }
 
+    /**
+     * Report the key string associated with this entity within the backup data set.
+     *
+     * @return The key string for this entity, equivalent to calling
+     *   {@link BackupDataInput#getKey()} on the underlying {@link BackupDataInput}.
+     */
     public String getKey() {
         return this.key;
     }
-    
+
+    /**
+     * Report the total number of bytes of data available for the current entity.
+     *
+     * @return The number of data bytes available, equivalent to calling
+     *   {@link BackupDataInput#getDataSize()} on the underlying {@link BackupDataInput}.
+     */
     public int size() {
         return this.dataSize;
     }
diff --git a/core/java/android/app/backup/BackupHelper.java b/core/java/android/app/backup/BackupHelper.java
index 3f41ed24dfca..87b581b0cd43 100644
--- a/core/java/android/app/backup/BackupHelper.java
+++ b/core/java/android/app/backup/BackupHelper.java
@@ -19,11 +19,21 @@ package android.app.backup;
 import android.os.ParcelFileDescriptor;
 
 /**
- * A convenient interface to be used with the
- * {@link android.app.backup.BackupAgentHelper} class to implement backup and restore of
- * arbitrary data types.
+ * This interface defines the calling interface that {@link BackupAgentHelper} uses
+ * when dispatching backup and restore operations to the installed helpers.
+ * Applications can define and install their own helpers as well as using those
+ * provided as part of the Android framework.
  * <p>
- * STOPSHIP: document!
+ * Although multiple helper objects may be installed simultaneously, each helper
+ * is responsible only for handling its own data, and will not see entities
+ * created by other components within the backup system.  Invocations of multiple
+ * helpers are performed sequentially by the {@link BackupAgentHelper}, with each
+ * helper given a chance to access its own saved state from within the state record
+ * produced during the previous backup operation.
+ *
+ * @see BackupAgentHelper
+ * @see FileBackupHelper
+ * @see SharedPreferencesBackupHelper
  */
 public interface BackupHelper {
     /**
@@ -31,24 +41,46 @@ public interface BackupHelper {
      * 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.
+     * <p>
+     * Implementing this method is much like implementing
+     * {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}
+     * &mdash; the method parameters are the same.  When this method is invoked the
+     * {@code oldState} descriptor points to the beginning of the state data
+     * written during this helper's previous backup operation, and the {@code newState}
+     * descriptor points to the file location at which the helper should write its
+     * new state after performing the backup operation.
+     * <p class="note">
+     * <em>Note:</em> The helper should not close or seek either the {@code oldState} or
+     * the {@code newState} file descriptors.</p>
      */
     public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
             ParcelFileDescriptor newState);
 
     /**
      * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper}
-     * to restore one entity from the restore dataset.
-     * <p class=note>
-     * Do not close the <code>data</code> stream.  Do not read more than
-     * <code>data.size()</code> bytes from <code>data</code>.
+     * to restore a single entity from the restore data set.  This method will be
+     * called for each entity in the data set that belongs to this handler.
+     * <p class="note">
+     * <em>Note:</em> Do not close the <code>data</code> stream.  Do not read more than
+     * <code>data.size()</code> bytes from <code>data</code>.</p>
      */
     public void restoreEntity(BackupDataInputStream data);
 
     /**
      * Called by {@link android.app.backup.BackupAgentHelper BackupAgentHelper}
      * after a restore operation to write the backup state file corresponding to
-     * the data as processed by the helper.
+     * the data as processed by the helper.  The data written here will be
+     * available to the helper during the next call to its
+     * {@link #performBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}
+     * method.
+     * <p>
+     * Note that this method will be called even if the handler's
+     * {@link #restoreEntity(BackupDataInputStream)} method was never invoked during
+     * the restore operation.
+     * <p class="note">
+     * <em>Note:</em> The helper should not close or seek the {@code newState}
+     * file descriptor.</p>
      */
-    public void writeNewStateDescription(ParcelFileDescriptor fd);
+    public void writeNewStateDescription(ParcelFileDescriptor newState);
 }