drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "docs: revise and add documentation for backup APIs" into froyo

Browse Source
This commit is contained in:
Scott Main
2010-05-04 14:20:02 -07:00
committed by Android (Google) Code Review
parent 70c6bb0d3e d17da43c82
commit 014517569f
10 changed files with 141 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
core/java/android/app/backup/BackupAgent.java
View File

@ -29,42 +29,44 @@ import android.util.Log;
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.

16
core/java/android/app/backup/BackupAgentHelper.java
View File

@ -24,19 +24,19 @@ import java.io.IOException;
* 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

50
core/java/android/app/backup/BackupDataInput.java
View File

@ -20,40 +20,42 @@ import java.io.FileDescriptor;
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>
* while (data.readNextHeader()) {
* String key = data.getKey();
* int dataSize = data.getDataSize();
* public void onRestore(BackupDataInput data, int appVersionCode,
* ParcelFileDescriptor newState) {
* while (data.readNextHeader()) {
* String key = data.getKey();
* int dataSize = data.getDataSize();
*
* if (key.equals(MY_BACKUP_KEY_ONE)) {
* // process this kind of record here
* byte[] buffer = new byte[dataSize];
* data.readEntityData(buffer, 0, dataSize); // reads the entire entity at once
* if (key.equals(MY_BACKUP_KEY_ONE)) {
* // process this kind of record here
* byte[] buffer = new byte[dataSize];
* data.readEntityData(buffer, 0, dataSize); // reads the entire entity at once
*
* // now 'buffer' holds the raw data and can be processed however
* // the agent wishes
* processBackupKeyOne(buffer);
* } else if (key.equals(MY_BACKUP_KEY_TO_IGNORE) {
* // a key we recognize but wish to discard
* data.skipEntityData();
* } // ... etc.
* // now 'buffer' holds the raw data and can be processed however
* // the agent wishes
* processBackupKeyOne(buffer);
* } else if (key.equals(MY_BACKUP_KEY_TO_IGNORE) {
* // a key we recognize but wish to discard
* data.skipEntityData();
* } // ... etc.
* }
* }</pre>
*/
public class BackupDataInput {

12
core/java/android/app/backup/BackupDataInputStream.java
View File

@ -20,17 +20,17 @@ import java.io.InputStream;
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

31
core/java/android/app/backup/BackupDataOutput.java
View File

@ -22,27 +22,28 @@ import java.io.FileDescriptor;
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>:
@ -73,9 +74,9 @@ public class BackupDataOutput {
}
/**
* 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

41
core/java/android/app/backup/BackupHelper.java
View File

@ -19,7 +19,7 @@ package android.app.backup;
import android.os.ParcelFileDescriptor;
/**
* This interface defines the calling interface that {@link BackupAgentHelper} uses
* 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.
@ -43,15 +43,28 @@ public interface BackupHelper {
* 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
* {@link BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)
* onBackup()} &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
* <strong>Note:</strong> The helper should not close or seek either the {@code oldState} or
* the {@code newState} file descriptors.</p>
*
* @param oldState An open, read-only {@link android.os.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 An open, read/write {@link BackupDataOutput}
* 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 {@link android.os.ParcelFileDescriptor} pointing to an
* empty file. The application should record the final backup
* state here after writing the requested data to the <code>data</code>
* output stream.
*/
public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
ParcelFileDescriptor newState);
@ -61,8 +74,11 @@ public interface BackupHelper {
* 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>
* <strong>Note:</strong> Do not close the <code>data</code> stream. Do not read more than
* {@link android.app.backup.BackupDataInputStream#size() size()} bytes from
* <code>data</code>.</p>
*
* @param data An open {@link BackupDataInputStream} from which the backup data can be read.
*/
public void restoreEntity(BackupDataInputStream data);
@ -71,15 +87,18 @@ public interface BackupHelper {
* after a restore operation to write the backup state file corresponding to
* 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.
* {@link #performBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor)
* performBackup()} method.
* <p>
* Note that this method will be called even if the handler's
* {@link #restoreEntity(BackupDataInputStream)} method was never invoked during
* This method will be called even if the handler's
* {@link #restoreEntity(BackupDataInputStream) restoreEntity()} method was never invoked during
* the restore operation.
* <p class="note">
* <em>Note:</em> The helper should not close or seek the {@code newState}
* <strong>Note:</strong> The helper should not close or seek the {@code newState}
* file descriptor.</p>
*
* @param newState A {@link android.os.ParcelFileDescriptor} to which the new state will be
* written.
*/
public void writeNewStateDescription(ParcelFileDescriptor newState);
}

26
core/java/android/app/backup/BackupManager.java
View File

@ -25,9 +25,9 @@ import android.os.ServiceManager;
import android.util.Log;
/**
* The BackupManager class is interface through which an application's user interface
* code will interact with the Android backup service. Applications simply instantiate one
* and then issue calls through that instance.
* The interface through which an application interacts with the Android backup service to
* request backup and restore operations.
* Applications instantiate it using the constructor and issue calls through that instance.
* <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
@ -35,19 +35,16 @@ import android.util.Log;
* calls to {@link #dataChanged()} have no further effect until the backup
* operation actually occurs.
* <p>
* A backup or restore operation begins with the system launching the
* {@link android.app.backup.BackupAgent} subclass declared in your manifest. See the
* A backup or restore operation for your application begins when the system launches the
* {@link android.app.backup.BackupAgent} subclass you've declared in your manifest. See the
* documentation for {@link android.app.backup.BackupAgent} for a detailed description
* of how the operation then proceeds.
* <p>
* <b>XML attributes</b>
* <p>
* Several attributes affecting the operation of the backup and restore mechanism
* can be set on the &lt;application&gt; tag in the application's
* AndroidManifest.xml file. See the documentation on the
* {@link android.R.styleable#AndroidManifestApplication AndroidManifest.xml's application attributes}
* for details.
*
* can be set on the <code><a
* href="{@docRoot}guide/topics/manifest/application-element.html">&lt;application&gt;</a></code>
* tag in your application's AndroidManifest.xml file.
*
* @attr ref android.R.styleable#AndroidManifestApplication_allowBackup
* @attr ref android.R.styleable#AndroidManifestApplication_backupAgent
* @attr ref android.R.styleable#AndroidManifestApplication_killAfterRestore
@ -103,6 +100,8 @@ public class BackupManager {
* This method requires that the application hold the "android.permission.BACKUP"
* permission if the package named in the argument does not run under the same uid
* as the caller.
*
* @param packageName The package name identifying the application to back up.
*/
public static void dataChanged(String packageName) {
checkServiceBinder();
@ -128,6 +127,9 @@ public class BackupManager {
* {@link android.app.backup.BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) onRestore()}
* method.
*
* @param observer The {@link RestoreObserver} to receive callbacks during the restore
* operation. This must not be null.
*
* @return Zero on success; nonzero on error.
*/
public int requestRestore(RestoreObserver observer) {

9
core/java/android/app/backup/FileBackupHelper.java
View File

@ -23,16 +23,17 @@ import android.util.Log;
import java.io.File;
/**
* A helper class which can be used in conjunction with
* A helper class that can be used in conjunction with
* {@link android.app.backup.BackupAgentHelper} 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,
* every file in the list will be backed up. Note that this should only be
* used with small configuration files, not with large binary files.
* will be saved in their entirety. When backup first occurs,
* every file in the list provided to {@link #FileBackupHelper} will be backed up.
* <p>
* During restore, if the helper encounters data for a file that was not
* specified when the FileBackupHelper object was constructed, that data
* will be ignored.
* <p class="note"><strong>Note:</strong> This should be
* used only with small configuration files, not large binary files.
*/
public class FileBackupHelper extends FileBackupHelperBase implements BackupHelper {
private static final String TAG = "FileBackupHelper";

23
core/java/android/app/backup/SharedPreferencesBackupHelper.java
View File

@ -24,18 +24,18 @@ import android.util.Log;
import java.io.File;
/**
* A helper class which can be used in conjunction with
* A helper class that can be used in conjunction with
* {@link android.app.backup.BackupAgentHelper} to manage the backup of
* {@link android.content.SharedPreferences}. Whenever a backup is performed it
* will back up all named shared preferences which have changed since the last
* {@link android.content.SharedPreferences}. Whenever a backup is performed, it
* will back up all named shared preferences that have changed since the last
* backup operation.
* <p>
* To use this class, the application's agent class should extend
* To use this class, the application's backup agent class should extend
* {@link android.app.backup.BackupAgentHelper}. Then, in the agent's
* {@link BackupAgent#onCreate()} method, an instance of this class should be
* allocated and installed as a backup/restore handler within the BackupAgentHelper
* framework. An implementation of an agent supporting backup and restore for
* an application that wishes to back up two groups of {@link android.content.SharedPreferences}
* framework. For example, an agent supporting backup and restore for
* an application with two groups of {@link android.content.SharedPreferences}
* data might look something like this:
* <pre>
* import android.app.backup.BackupAgentHelper;
@ -59,12 +59,12 @@ import java.io.File;
* }
* }</pre>
* <p>
* No further implementation is needed; the BackupAgentHelper mechanism automatically
* No further implementation is needed; the {@link BackupAgentHelper} mechanism automatically
* dispatches the
* {@link BackupAgent#onBackup(android.os.ParcelFileDescriptor, BackupDataOutput, android.os.ParcelFileDescriptor) BackupAgent.onBackup()}
* and
* {@link BackupAgent#onRestore(BackupDataInput, int, android.os.ParcelFileDescriptor) BackupAgent.onRestore()}
* callbacks to the SharedPreferencesBackupHelper as appropriate.
* callbacks to the SharedPreferencesBackupHelper as appropriate.
*/
public class SharedPreferencesBackupHelper extends FileBackupHelperBase implements BackupHelper {
private static final String TAG = "SharedPreferencesBackupHelper";
@ -77,8 +77,9 @@ public class SharedPreferencesBackupHelper extends FileBackupHelperBase implemen
* Construct a helper for backing up and restoring the
* {@link android.content.SharedPreferences} under the given names.
*
* @param context
* @param prefGroups
* @param context The application {@link android.content.Context}
* @param prefGroups The names of each {@link android.content.SharedPreferences} file to
* back up
*/
public SharedPreferencesBackupHelper(Context context, String... prefGroups) {
super(context);
@ -88,7 +89,7 @@ public class SharedPreferencesBackupHelper extends FileBackupHelperBase implemen
}
/**
* Backs up the configured SharedPreferences groups
* Backs up the configured {@link android.content.SharedPreferences} groups.
*/
public void performBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
ParcelFileDescriptor newState) {

6
core/java/android/app/backup/package.html
View File

@ -1,7 +1,9 @@
<HTML>
<BODY>
<p>Package containing the backup and restore functionality available to
applications. All backup management is controlled through
<p>Contains the backup and restore functionality available to
applications. If a user wipes the data on their device or upgrades to a new Android-powered
device, all applications that have enabled backup will restore the user's previous data and/or
preferences. {@more} All backup management is controlled through
{@link android.app.backup.BackupManager}. Individual backup functionality is
implemented through a subclass {@link android.app.backup.BackupAgent} and a
simple and easy-to-use implementation is provided in