Most visited

Recently visited

Added in API level 8

BackupAgent

public abstract class BackupAgent
extends ContextWrapper

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


提供应用程序和Android数据备份基础架构之间的中心界面。 希望参与备份和恢复机制的应用程序将声明BackupAgent的子类,实现onBackup()onRestore()方法,并通过<application>标记的android:backupAgent属性在其AndroidManifest.xml文件中提供其备份代理类的名称。

Developer Guides

有关使用BackupAgent的更多信息,请阅读 Data Backup开发人员指南。

Basic Operation

当应用程序对希望保留备份的数据进行更改时,应调用BackupManager.dataChanged()方法。 这会通知Android备份管理器该应用程序需要更新其备份映像的机会。 备份管理器反过来安排在适当的时候执行备份。

恢复操作通常仅在应用程序首次安装在设备上时执行。 此时,操作系统会检查是否有先前保存的数据集可用于正在安装的应用程序,如果是,则开始即时还原传递以在安装过程中传输备份数据。

当运行备份或还原过程时,启动应用程序的进程(如果尚未运行),清单声明的备份代理类(在android:backupAgent属性中)在该进程中实例化,并调用代理的onCreate()方法。 这使代理实例准备好运行实际的备份或恢复逻辑。 此时,代理的onBackup()onRestore()方法将根据正在执行的操作调用。

备份数据集由一个或多个“实体”组成,每个扁平化二进制数据记录用数据集内唯一的键字符串标识。 向活动数据集添加记录或更新现有记录是通过在所需密钥下简单写入新实体数据完成的。 从数据集中删除一个实体是通过在指定负数据大小的标题下编写一个实体并且没有实际的实体数据来完成的。

助手类

基于方便助手类的可扩展代理可在BackupAgentHelperBackupAgentHelper 该类特别适合处理简单文件或SharedPreferences备份和恢复。

也可以看看:

Summary

Constants

int TYPE_DIRECTORY

在完整还原期间,指示正在还原的文件系统对象是目录。

int TYPE_FILE

在完全还原期间,指示正在还原的文件系统对象是普通文件。

Inherited constants

From class android.content.Context

Public constructors

BackupAgent()

Public methods

final void fullBackupFile(File file, FullBackupDataOutput output)

作为完整备份操作的一部分写入整个文件。

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

要求应用程序写入自上次执行备份操作以来更改的任何数据。

void onCreate()

为实际备份或恢复操作开始之前需要机会进行一次性初始化的代理实现提供便利。

void onDestroy()

为备份或恢复完成后需要执行某种关闭过程的代理实现提供便利。

void onFullBackup(FullBackupDataOutput data)

应用程序正在备份其整个文件系统内容。

void onQuotaExceeded(long backupDataBytes, long quotaBytes)

通知应用程序的当前备份操作导致其超过传输所允许的最大大小。

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

应用程序正在从备份中恢复,并应将所有现有数据替换为备份的内容。

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

在完全恢复操作期间处理通过给定文件描述符传送的数据。

void onRestoreFinished()

应用程序的还原操作已完成。

Inherited methods

From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object

Constants

TYPE_DIRECTORY

Added in API level 14
int TYPE_DIRECTORY

在完整还原期间,指示正在还原的文件系统对象是目录。

常量值:2(0x00000002)

TYPE_FILE

Added in API level 14
int TYPE_FILE

在完全还原期间,指示正在还原的文件系统对象是普通文件。

常数值:1(0x00000001)

Public constructors

BackupAgent

Added in API level 8
BackupAgent ()

Public methods

fullBackupFile

Added in API level 14
void fullBackupFile (File file, 
                FullBackupDataOutput output)

作为完整备份操作的一部分写入整个文件。 该文件的内容将被传送到备份目标以及必要的元数据,以便将其置于恢复数据的设备上的正确位置和权限。

尝试备份备份系统忽略的目录中的文件将不起作用。 例如,如果应用程序使用getNoBackupFilesDir()目录中的文件调用此方法,则它将被忽略。 有关从备份中排除哪些目录的详细信息,请参阅{@link #onFullBackup(FullBackupDataOutput)。

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

onBackup

Added in API level 8
void onBackup (ParcelFileDescriptor oldState, 
                BackupDataOutput data, 
                ParcelFileDescriptor newState)

要求应用程序写入自上次执行备份操作以来更改的任何数据。 上次备份过程中记录的状态数据在oldState文件描述符中提供。 如果oldStatenull ,则不存在旧状态,应用程序应执行完整备份。 在这两种情况下,此通道之后的最终备份状态的表示应写入由newStatenewState的文件描述符指向的文件。

写入BackupDataOutput data流的每个实体将通过当前的备份传输器传输,并存储在作为实体一部分提供的密钥下的远程数据集中。 编写一个负数据大小的实体指示传输从远程数据集中删除该密钥下当前存在的任何实体。

Parameters
oldState ParcelFileDescriptor: 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 BackupDataOutput: 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 ParcelFileDescriptor: 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

onCreate

Added in API level 8
void onCreate ()

为实际备份或恢复操作开始之前需要机会进行一次性初始化的代理实现提供便利。

onDestroy

Added in API level 8
void onDestroy ()

为备份或恢复完成后需要执行某种关闭过程的代理实现提供便利。

代理不需要重写此方法。

onFullBackup

Added in API level 14
void onFullBackup (FullBackupDataOutput data)

应用程序正在备份其整个文件系统内容。 data指向备份目标,并且应用程序有机会选择要存储哪些文件。 要将文件作为备份的一部分提交,请调用fullBackupFile(File, FullBackupDataOutput)辅助方法。 将所有文件数据写入输出后,代理将从此方法返回并完成备份操作。

即使应用程序明确将它们发送到输出,也不会备份应用程序数据的某些部分:

此方法的默认实现将整个应用程序的“拥有”文件系统树备份到输出,而不是上面列出的少数例外。 应用程序只需要覆盖此方法,如果他们需要对哪些文件超出getNoBackupFilesDir()提供的控件存储特殊限制。 或者,他们可以提供一个xml资源来指定要包含或排除的数据。

Parameters
data FullBackupDataOutput: A structured wrapper pointing to the backup destination.
Throws
IOException
IOException

也可以看看:

onQuotaExceeded

Added in API level 24
void onQuotaExceeded (long backupDataBytes, 
                long quotaBytes)

通知应用程序的当前备份操作导致其超过传输所允许的最大大小。 正在进行的备份操作将暂停并回滚:以前的备份操作存储的任何数据仍保持不变。 在通过网络实际传输任何数据之前,通常会检测配额超出状态。

quotaBytes值是此应用程序当前允许的总数据大小。 如果需要,应用程序可以使用它作为确定要存储多少数据的提示。 例如,消息传递应用程序可能会选择仅存储最新的消息,将足够多的旧内容放在配额下。

请注意,应用程序的最大配额可能随时间而改变。 特别是在未来,配额可能会增加。 在决定要存储什么数据时适应配额的应用程序应该意识到这一点,并以可以利用额外配额的方式实现其数据存储机制。

Parameters
backupDataBytes long: The amount of data measured while initializing the backup operation, if the total exceeds the app's alloted quota. If initial measurement suggested that the data would fit but then too much data was actually submitted as part of the operation, then this value is the amount of data that had been streamed into the transport at the time the quota was reached.
quotaBytes long: The maximum data size that the transport currently permits this application to store as a backup.

onRestore

Added in API level 8
void onRestore (BackupDataInput data, 
                int appVersionCode, 
                ParcelFileDescriptor newState)

应用程序正在从备份中恢复,并应将所有现有数据替换为备份的内容。 备份数据通过data参数提供。 恢复完成后,应用程序应将最终状态的表示写入newState文件描述符。

应用程序负责正确删除其旧数据,并用提供给此方法的数据替换它。 操作系统不会自动执行“清除用户数据”操作。 这种情况的例外是在尝试恢复失败的情况下:如果onRestore()抛出异常,操作系统将假定应用程序的数据现在可能处于非连贯状态,并且在继续之前将清除它。

Parameters
data BackupDataInput: 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 int: 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 ParcelFileDescriptor: 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

onRestoreFile

Added in API level 14
void onRestoreFile (ParcelFileDescriptor data, 
                long size, 
                File destination, 
                int type, 
                long mode, 
                long mtime)

在完全恢复操作期间处理通过给定文件描述符传送的数据。 该代理将获得文件原始位置的路径以及其大小和元数据。

文件描述符只能读取size字节; 试图读取更多数据有未定义的行为。

默认实现创建目标文件/目录,并使用文件描述符中的数据填充目标文件/目录,然后设置文件的访问模式和修改时间以匹配恢复参数。

Parameters
data ParcelFileDescriptor: A read-only file descriptor from which the agent can read size bytes of file data.
size long: 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 File: The File on disk to be restored with the given data.
type int: The kind of file system object being restored. This will be either TYPE_FILE or TYPE_DIRECTORY.
mode long: The access mode to be assigned to the destination after its data is written. This is in the standard format used by chmod().
mtime long: 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

onRestoreFinished

Added in API level 21
void onRestoreFinished ()

应用程序的还原操作已完成。 在将所有可用数据传递到应用程序进行还原(通过onRestore()onRestoreFile()回调)之后调用此方法。 这为应用程序提供了稳定的恢复结束机会,以对刚刚传送的数据执行任何适当的后处理。

也可以看看:

Hooray!