am 5c16039a: am 01451756: Merge "docs: revise and add documentation for backup APIs" into froyo

import java.io.IOException;

/**

 * {@link android.app.backup.BackupAgent} is the central interface between an

 * Provides the central interface between an

 * application and Android's data backup infrastructure.  An application that wishes

 * to participate in the backup and restore mechanism will declare a subclass of

 * {@link android.app.backup.BackupAgent}, implement the

 * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)}

 * and {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor)} methods,

 * and provide the name of its agent class in the AndroidManifest.xml file via

 * the <application> tag's android:backupAgent attribute.

 * <p>

 * <b>Basic Operation</b>

 * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) onBackup()}

 * and {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor) onRestore()} methods,

 * and provide the name of its backup agent class in its {@code AndroidManifest.xml} file via

 * the <code><a

 * href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>

 * tag's {@code android:backupAgent} attribute.

 * <h3>Basic Operation</h3>

 * <p>

 * When the application makes changes to data that it wishes to keep backed up,

 * it should call the

 * {@link android.app.backup.BackupManager#dataChanged() BackupManager.dataChanged()} method.

 * This notifies the Android backup manager that the application needs an opportunity

 * to update its backup image.  The backup manager, in turn, will then schedule a

 * This notifies the Android Backup Manager that the application needs an opportunity

 * to update its backup image.  The Backup Manager, in turn, schedules a

 * backup pass to be performed at an opportune time.

 * <p>

 * Restore operations are typically only performed when applications are first

 * Restore operations are typically performed only when applications are first

 * installed on a device.  At that time, the operating system checks to see whether

 * there is a previously-saved data set available for the application, and if so,

 * begins an immediate restore pass to deliver that data as part of the installation

 * there is a previously-saved data set available for the application being installed, and if so,

 * begins an immediate restore pass to deliver the backup data as part of the installation

 * process.

 * <p>

 * When a backup or restore pass is run, the application's process will be launched

 * (if not already running), the manifest-declared agent class instantiated within

 * that process, and the agent's {@link #onCreate()} method invoked.  This prepares the

 * When a backup or restore pass is run, the application's process is launched

 * (if not already running), the manifest-declared backup agent class (in the {@code

 * android:backupAgent} attribute) is instantiated within

 * that process, and the agent's {@link #onCreate()} method is invoked.  This prepares the

 * agent instance to run the actual backup or restore logic.  At this point the

 * agent's

 * {@link #onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) onBackup()} or

 * {@link #onRestore(BackupDataInput, int, ParcelFileDescriptor) onRestore()} method will be

 * invoked as appropriate for the operation being performed.

 * <p>

 * A backup data set consists of one or more "entities," flattened binary data records

 * that are each identified with a key string unique within the data set.  Adding a

 * record to the active data set, or updating an existing record, are done by simply

 * A backup data set consists of one or more "entities," flattened binary data

 * records that are each identified with a key string unique within the data set.  Adding a

 * record to the active data set or updating an existing record is done by simply

 * writing new entity data under the desired key.  Deleting an entity from the data set

 * is done by writing an entity under that key with header specifying a negative data

 * size, and no actual entity data.

 * A convenient {@link BackupAgent} wrapper class that automatically manages

 * heterogeneous data sets within the backup data, each identified by a unique

 * key prefix.  When processing a backup or restore operation, the BackupAgentHelper

 * dispatches to one or more installed {@link BackupHelper helpers} objects, each

 * dispatches to one or more installed {@link BackupHelper} objects, each

 * of which is responsible for a defined subset of the data being processed.

 * <p>

 * An application will typically extend this class in their own

 * An application will typically extend this class in its 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

 * method, it will call {@link #addHelper(String, BackupHelper) addHelper()} 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.

 * The Android framework currently provides two predefined {@link BackupHelper} classes:</p>

 * <ul><li>{@link FileBackupHelper} - Manages the backup and restore of entire files

 * within an application's data directory hierarchy.</li>

 * <li>{@link SharedPreferencesBackupHelper} - Manages the backup and restore of an

 * application's {@link android.content.SharedPreferences} data.</li></ul>

 * <p>

 * An application can also implement its own helper classes to work within the

 * {@link BackupAgentHelper} framework.  See the {@link BackupHelper} interface

import java.io.IOException;

/**

 * BackupDataInput is the structured interface used for passing the contents of

 * a backup data set to an application's {@link BackupAgent} class in its

 * {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor)}

 * Provides the structured interface through which a {@link BackupAgent} reads

 * information from the backup data set, via its

 * {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()}

 * method.  The data is presented as a set of "entities," each

 * representing one named record as previously stored by the agent's

 * {@link BackupAgent#onBackup(android.os.ParcelFileDescriptor, BackupDataOutput, android.os.ParcelFileDescriptor)}

 * implementation.  An entity is composed of a descriptive header plus a

 * byte array that holds its raw data.

 * {@link BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)

 * onBackup()} implementation.  An entity is composed of a descriptive header plus a

 * byte array that holds the raw data saved in the remote backup.

 * <p>

 * The agent must consume every entity in the data stream, otherwise the

 * restored state of the application will be incomplete.

 * <p>

 * <b>Example</b>

 * <h3>Example</h3>

 * <p>

 * A typical

 * {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) BackupAgent.onRestore(data, appVersionCode, newState)}

 * implementation might be structured something like this:

 * {@link BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)

 * onRestore()} implementation might be structured something like this:

 * <pre>

 * public void onRestore(BackupDataInput data, int appVersionCode,

 *                       ParcelFileDescriptor newState) {

 *     while (data.readNextHeader()) {

 *         String key = data.getKey();

 *         int dataSize = data.getDataSize();

 *             // a key we recognize but wish to discard

 *             data.skipEntityData();

 *         } // ... etc.

 *    }

 * }</pre>

 */

public class BackupDataInput {

import java.io.IOException;

/**

 * 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.

 * Provides an {@link java.io.InputStream}-like interface for accessing an

 * entity's data during a restore operation. Used by {@link BackupHelper} classes within the {@link

 * BackupAgentHelper} mechanism.

 * <p>

 * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity(BackupDataInputStream)}

 * When {@link BackupHelper#restoreEntity(BackupDataInputStream) BackupHelper.restoreEntity()}

 * 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>

 * <strong>Note:</strong> The caller should take care not to seek or close the underlying data

 * source, nor read more than {@link #size()} bytes from the stream.</p>

 *

 * @see BackupAgentHelper

 * @see BackupHelper

import java.io.IOException;

/**

 * This class is the structured conduit through which a {@link BackupAgent} commits

 * information to the current backup data set.  Data written for backup is presented

 * Provides the structured interface through which a {@link BackupAgent} commits

 * information to the backup data set, via its {@link

 * BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)

 * onBackup()} method.  Data written for backup is presented

 * as a set of "entities," key/value pairs in which each binary data record "value" is

 * named with a string "key."

 * <p>

 * To commit a data record to the backup transport, the agent's

 * {@link BackupAgent#onBackup(android.os.ParcelFileDescriptor, BackupDataOutput, android.os.ParcelFileDescriptor)}

 * method first writes an "entity header" that supplies the key string for the record

 * {@link BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)

 * onBackup()} method first writes an "entity header" that supplies the key string for the record

 * and the total size of the binary value for the record.  After the header has been

 * written the agent then writes the binary entity value itself.  The entity value can

 * written, the agent then writes the binary entity value itself.  The entity value can

 * be written in multiple chunks if desired, as long as the total count of bytes written

 * matches what was supplied to {@link #writeEntityHeader(String, int)}.

 * matches what was supplied to {@link #writeEntityHeader(String, int) writeEntityHeader()}.

 * <p>

 * Entity key strings are considered to be unique within a given application's backup

 * data set.  If a new entity is written under an existing key string, its value will

 * replace any previous value in the transport's remote data store.  A record can be

 * removed entirely from the remote data set by writing a new entity header using the

 * data set. If a backup agent writes a new entity under an existing key string, its value will

 * replace any previous value in the transport's remote data store.  You can remove a record

 * entirely from the remote data set by writing a new entity header using the

 * existing record's key, but supplying a negative <code>dataSize</code> parameter.

 * When doing this the agent does not need to call {@link #writeEntityData(byte[], int)}.

 * <p>

 * <b>Example</b>

 * When you do so, the agent does not need to call {@link #writeEntityData(byte[], int)}.

 * <h3>Example</h3>

 * <p>

 * Here is an example illustrating a way to back up the value of a String variable

 * called <code>mStringToBackUp</code>:

    }

    /**

     * Mark the beginning of one record in the backup data stream.

     *

     * @param key

     * Mark the beginning of one record in the backup data stream. This must be called before

     * {@link #writeEntityData}.

     * @param key A string key that uniquely identifies the data record within the application

     * @param dataSize The size in bytes of this record's data.  Passing a dataSize

     *    of -1 indicates that the record under this key should be deleted.

     * @return The number of bytes written to the backup stream