Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)
Android APIs
public abstract class

BackupAgent

extends ContextWrapper
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.backup.BackupAgent
Known Direct Subclasses

Class Overview

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 BackupAgent , implement the onBackup() and onRestore() methods, and provide the name of its backup agent class in its AndroidManifest.xml file via the <application> tag's android:backupAgent attribute.

Developer Guides

For more information about using BackupAgent, read the Data Backup developer guide.

Basic Operation

When the application makes changes to data that it wishes to keep backed up, it should call the 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, schedules a backup pass to be performed at an opportune time.

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 being installed, and if so, begins an immediate restore pass to deliver the backup data as part of the installation process.

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 android:backupAgent attribute) is instantiated within that process, and the agent's onCreate() method is invoked. This prepares the agent instance to run the actual backup or restore logic. At this point the agent's onBackup() or onRestore() method will be invoked as appropriate for the operation being performed.

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.

Helper Classes

An extensible agent based on convenient helper classes is available in BackupAgentHelper . That class is particularly suited to handling of simple file or SharedPreferences backup and restore.

See Also

Summary

Constants
int TYPE_DIRECTORY During a full restore, indicates that the file system object being restored is a directory.
int TYPE_FILE During a full restore, indicates that the file system object being restored is an ordinary file.
[Expand]
Inherited Constants
From class android.content.Context
Public Constructors
BackupAgent ()
Public Methods
final void fullBackupFile ( File file, FullBackupDataOutput output)
Write an entire file as part of a full-backup operation.
abstract void onBackup ( ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState)
The application is being asked to write any data changed since the last time it performed a backup operation.
void onCreate ()
Provided as a convenience for agent implementations that need an opportunity to do one-time initialization before the actual backup or restore operation is begun.
void onDestroy ()
Provided as a convenience for agent implementations that need to do some sort of shutdown process after backup or restore is completed.
void onFullBackup ( FullBackupDataOutput data)
The default implementation backs up the entirety of the application's "owned" file system trees to the output.
abstract void onRestore ( BackupDataInput data, int appVersionCode, ParcelFileDescriptor newState)
The application is being restored from backup and should replace any existing data with the contents of the backup.
void onRestoreFile ( ParcelFileDescriptor data, long size, File destination, int type, long mode, long mtime)
Handle the data delivered via the given file descriptor during a full restore operation.
[Expand]
Inherited Methods
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object

Constants

public static final int TYPE_DIRECTORY

Added in API level 14

During a full restore, indicates that the file system object being restored is a directory.

Constant Value: 2 (0x00000002)

public static final int TYPE_FILE

Added in API level 14

During a full restore, indicates that the file system object being restored is an ordinary file.

Constant Value: 1 (0x00000001)

Public Constructors

public BackupAgent ()

Added in API level 8

Public Methods

public final void fullBackupFile ( File file, FullBackupDataOutput output)

Write an entire file as part of a full-backup operation. The file's contents will be delivered to the backup destination along with the metadata necessary to place it with the proper location and permissions on the device where the data is restored.

Parameters
file The file to be backed up. The file must exist and be readable by the caller.
output The destination to which the backed-up file data will be sent.

public abstract void onBackup ( ParcelFileDescriptor oldState, BackupDataOutput data, ParcelFileDescriptor newState)

Added in API level 8

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 file descriptor wrapped in newState .

Each entity written to the BackupDataOutput data stream will be transmitted over the current backup transport and stored in the remote data set under the key supplied as part of the entity. Writing an entity with a negative data size instructs the transport to delete whatever entity currently exists under that key from the remote data set.

Parameters
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.
data A structured wrapper around an open, read/write file descriptor pointing to the backup data destination. Typically the application will use backup helper classes to write to this file.
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 the data output stream.
Throws
IOException

public void onCreate ()

Added in API level 8

Provided as a convenience for agent implementations that need an opportunity to do one-time initialization before the actual backup or restore operation is begun.

Agents do not need to override this method.

public void onDestroy ()

Added in API level 8

Provided as a convenience for agent implementations that need to do some sort of shutdown process after backup or restore is completed.

Agents do not need to override this method.

public void onFullBackup ( FullBackupDataOutput data)

The default implementation backs up the entirety of the application's "owned" file system trees to the output.

Throws
IOException

public abstract void onRestore ( BackupDataInput data, int appVersionCode, ParcelFileDescriptor newState)

Added in API level 8

The application is being restored from backup and should replace any existing data with the contents of the backup. The backup data is provided through the data parameter. Once the restore is finished, the application should write a representation of the final state to the newState file descriptor.

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.

Parameters
data A structured wrapper around an open, read-only file descriptor pointing to a full snapshot of the application's data. The application should consume every entity represented in this data stream.
appVersionCode The value of the android:versionCode manifest attribute, from the application that backed up this particular data set. This makes it possible for an application's agent to distinguish among any possible older data versions when asked to perform the restore operation.
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 the data stream. When a full-backup dataset is being restored, this will be null .
Throws
IOException

public void onRestoreFile ( ParcelFileDescriptor data, long size, File destination, int type, long mode, long mtime)

Handle the data delivered via the given file descriptor during a full restore operation. The agent is given the path to the file's original location as well as its size and metadata.

The file descriptor can only be read for size bytes; attempting to read more data has undefined behavior.

The default implementation creates the destination file/directory and populates it with the data from the file descriptor, then sets the file's access mode and modification time to match the restore arguments.

Parameters
data A read-only file descriptor from which the agent can read size bytes of file data.
size The number of bytes of file content to be restored to the given destination. If the file system object being restored is a directory, size will be zero.
destination The File on disk to be restored with the given data.
type The kind of file system object being restored. This will be either TYPE_FILE or TYPE_DIRECTORY .
mode The access mode to be assigned to the destination after its data is written. This is in the standard format used by chmod() .
mtime The modification time of the file when it was backed up, suitable to be assigned to the file after its data is written.
Throws
IOException