Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Updates to backup documentation

Browse Source 
Change-Id: I9349e5f8585687b1159f13029b6c13b89dafd8c9
This commit is contained in:
Mark Lu
2016-09-29 18:11:38 -07:00
parent d780260f10
commit f0968050f6
14 changed files with 1379 additions and 1596 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/html/_redirects.yaml
View File

@@ -430,7 +430,13 @@ redirects:
- from: /training/cloudsync/aesync.html
to: /google/gcm/index.html
- from: /training/cloudsync/index.html
to: /training/backup/index.html
to: /guide/topics/data/backup.html
- from: /training/backup/index.html
to: /guide/topics/data/backup.html
- from: /training/backup/autosyncapi.html
to: /guide/topics/data/autobackup.html
- from: /training/backup/backupapi.html
to: /guide/topics/data/keyvaluebackup.html
- from: /training/basics/location/...
to: /training/location/...
- from: /training/monetization/index.html
@@ -796,7 +802,7 @@ redirects:
- from: /preview/features/app-linking.html
to: /training/app-links/index.html
- from: /preview/backup/index.html
to: /training/backup/autosyncapi.html
to: /guide/topics/data/backup/autobackup.html
- from: /preview/features/power-mgmt.html
to: /training/monitoring-device-state/doze-standby.html
- from: /preview/dev-community

7
docs/html/guide/_book.yaml
View File

@@ -396,6 +396,13 @@ toc:
path: /guide/topics/data/data-storage.html
- title: Data Backup
path: /guide/topics/data/backup.html
section:
- title: Auto Backup
path: /guide/topics/data/autobackup.html
- title: Key/Value Backup
path: /guide/topics/data/keyvaluebackup.html
- title: Testing Backup and Restore
path: /guide/topics/data/testingbackup.html
- title: App Install Location
path: /guide/topics/data/install-location.html

11
docs/html/guide/guide_toc.cs
View File

@@ -545,9 +545,16 @@
<li><a href="<?cs var:toroot ?>guide/topics/data/data-storage.html">
<span class="en">Storage Options</span>
</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/data/backup.html">
<li class="nav-section">
<div class="nav-section-header"><a href="<?cs var:toroot ?>guide/topics/data/backup.html">
<span class="en">Data Backup</span>
</a></li>
</a></div>
<ul>
<li><a href="<?cs var:toroot ?>guide/topics/data/autobackup.html">Auto Backup</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/data/keyvaluebackup.html">Key/Value Backup</a></li>
<li><a href="<?cs var:toroot ?>guide/topics/data/testingbackup.html">Testing Backup and Restore</a></li>
</ul>
</li>
<li><a href="<?cs var:toroot ?>guide/topics/data/install-location.html">
<span class="en">App Install Location</span>
</a></li>

257
docs/html/guide/topics/data/autobackup.jd Normal file
View File

@@ -0,0 +1,257 @@
page.title=Auto Backup for Apps
page.tags=backup, marshmallow, androidm
page.keywords=backup, autobackup
page.image=images/cards/card-auto-backup_2x.png
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#Files">Files that are backed up</a></li>
<li><a href="#BackupLocation">Backup location</a></li>
<li><a href="#BackupSchedule">Backup schedule</a></li>
<li><a href="#RestoreSchedule">Restore schedule</a></li>
<li><a href="#EnablingAutoBackup">Enabling and disabling Auto Backup</a></li>
<li><a href="#IncludingFiles">Including and excluding files</a><ul>
<li><a href="#XMLSyntax">XML config syntax</a></li>
</ul></li>
<li><a href="#ImplementingBackupAgent">Implementing BackupAgent</a></li>
</ol>
<h2>Key classes</h2>
<ol>
<li>{@link android.app.backup.BackupAgent}</li>
<li><a href="{@docRoot}reference/android/R.attr.html">R.attr</a></li>
</ol>
</div>
</div>
Since Android 6.0 (API 23), Android has offered the <em>Auto Backup for Apps</em> feature as
a way for developers to quickly add backup functionality to their apps. Auto
Backup preserves app data by uploading it to the user’s Google Drive account.
The amount of data is limited to 25MB per user of your app and there is no
charge for storing backup data.
<h2 id="Files">Files that are backed up</h2>
<p>By default, Auto Backup includes files in most of the directories that are
assigned to your app by the system:
<ul>
<li>Shared preferences files.
<li>Files in the directory returned by {@link android.content.Context#getFilesDir()}.
<li>Files in the directory returned by {@link android.content.Context#getDatabasePath(String)},
which also includes files created with the
{@link android.database.sqlite.SQLiteOpenHelper} class.
<li>Files in directories created with {@link android.content.Context#getDir(String,int)}.
<li>Files on external storage in the directory returned by
{@link android.content.Context#getExternalFilesDir(String)}.</li></ul>
<p>Auto Backup excludes files in directories returned by
{@link android.content.Context#getCacheDir()},
{@link android.content.Context#getCodeCacheDir()}, or
{@link android.content.Context#getNoBackupFilesDir()}. The files saved
in these locations are only needed temporarily, or are intentionally
excluded from backup operations.
<p>You can configure your app to include and exclude particular files.
For more information, see the <a href="#IncludingFiles">Include and exclude files</a>
section.
<h2 id="BackupLocation">Backup location</h2>
<p>Backup data is stored in a private folder in the user's Google Drive account,
limited to 25MB per app. The saved data does not count towards the user's
personal Google Drive quota. Only the most recent backup is stored. When a
backup is made, the previous backup (if one exists) is deleted.
<p>Users can see a list of apps that have been backed up in the Google Drive app under
<strong>Settings -> Auto Backup for apps -> Manage backup</strong>. The
backup data cannot be read by the user or other applications on the device.
<p>Backups from each device-setup-lifetime are stored in separate datasets
as shown in the following examples:
<ul>
<li>If the user owns two devices, then a backup dataset exists for each device.
<li>If the user factory resets a device and then sets up the device with the
same account, the backup is stored in a new dataset. Obsolete datasets are
automatically deleted after a period of inactivity.</li></ul>
<p class="caution"><strong>Caution:</strong> Once the amount of data reaches
25MB, the app is banned from sending data to the
cloud, even if the amount of data later falls under the 25MB threshold. The ban
affects only the offending device (not other devices that the user owns) and
lasts for the entire device-setup-lifetime. For example, if the user removes and
reinstalls the application, the ban is still in effect. The ban is lifted when
the user performs factory reset on the device.
<h2 id="BackupSchedule">Backup schedule</h2>
<p>Backups occur automatically when all of the following conditions are met:
<ul>
<li>The user has enabled backup on the device in <strong>Settings</strong> >
<strong>Backup &amp; Reset</strong>.
<li>At least 24 hours have elapsed since the last backup.
<li>The device is idle and charging.
<li>The device is connected to a Wi-Fi network. If the device is never connected
to a wifi network, then Auto Backup never occurs.</li></ul>
<p>In practice, these conditions occur roughly every night. To conserve network
bandwidth, upload takes place only if app data has changed.
<p>During Auto Backup, the system shuts down the app to make sure it is no longer
writing to the file system. By default, the backup system ignores apps that are
running in the foreground because users would notice their apps being shut down.
You can override the default behavior by setting the
<a href="{@docRoot}reference/android/R.attr.html#backupInForeground">backupInForeground</a>
attribute to true.
<p>To simplify testing, Android includes tools that let you manually initiate
a backup of your app. For more information, see
<a href="{@docRoot}guide/topics/data/testingbackup.html">Testing Backup and Restore</a>.
<h2 id="RestoreSchedule">Restore schedule</h2>
<p>Data is restored whenever the app is installed, either from the Play store,
during device setup (when the system installs previously installed apps), or
from running adb install. The restore operation occurs after the APK is
installed, but before the app is available to be launched by the user.
<p>During the initial device setup wizard, the user is shown a list of available backup
datasets and is asked which one to restore the data from. Whichever backup
dataset is selected becomes the ancestral dataset for the device. The device can
restore from either its own backups or the ancestral dataset. The device
prioritize its own backup if backups from both sources are available. If the
user didn't go through the device setup wizard, then the device can restore only from
its own backups.
<p>To simplify testing, Android includes tools that let you manually initiate
a restore of your app. For more information, see
<a href="{@docRoot}guide/topics/data/testingbackup.html">Testing Backup and Restore</a>.
<h2 id="EnablingAutoBackup">Enabling and disabling backup</h2>
<p>Apps that target Android 6.0 (API level 23) or higher automatically participate
in Auto Backup. This is because the
<a href="{@docRoot}reference/android/R.attr.html#allowBackup">android:allowBackup</a>
attribute, which enables/disables backup, defaults to <code>true</code> if omitted.
To avoid confusion, we recommend you explicitly set the attribute in the <code>&lt;application></code>
element of your <code>AndroidManifest.xml</code>. For example:
<pre class="prettyprint">&lt;application ...
android:allowBackup="true">
&lt;/app></pre>
<p>To disable Auto Backup, add either of the following attributes to the
application element in your manifest file:
<ul>
<li>set <code>android:allowBackup</code> to <code>false</code>. This completely disables data
backup. You may want to disable backups when your app can recreate its state
through some other mechanism or when your app deals with sensitive
information that should not be backed up.</li>
<li>set <code>android:allowBackup</code> to <code>true</code> and
<code>android:fullBackupOnly</code> to <code>false</code>. With these settings,
your app always participates in Key/Value Backup, even when running on devices that
support Auto Backup.</li></ul>
<h2 id="IncludingFiles">Including and excluding files</h2>
<p>By default, the system backs up almost all app data. For more information,
see <a href="#Files">Files that are backed up</a>. This section shows you how to
define custom XML rules to control what gets backed up.
<ol>
<li>In <code>AndroidManifest.xml</code>, add the <a href="{@docRoot}reference/android/R.attr.html#fullBackupContent">android:fullBackupContent</a> attribute to the
<code>&lt;application></code> element. This attribute points to an XML file that contains backup
rules. For example:
<pre class="prettyprint">&lt;application ...
android:fullBackupContent="@xml/my_backup_rules">
&lt;/app></pre></li>
<li>Create an XML file called <code>my_backup_rules.xml</code> in the <code>res/xml/</code> directory. Inside the file, add rules with the <code>&lt;include></code> and <code>&lt;exclude></code> elements. The following sample backs up all shared preferences except <code>device.xml</code>:
<pre>&lt;?xml version="1.0" encoding="utf-8"?>
&lt;full-backup-content>
&lt;include domain="sharedpref" path="."/>
&lt;exclude domain="sharedpref" path="device.xml"/>
&lt;/full-backup-content></pre></li>
<h3 id="XMLSyntax">XML Config Syntax</h3>
<p>The XML syntax for the configuration file is shown below:
<pre class="prettyprint">&lt;full-backup-content>
&lt;include domain=["file" | "database" | "sharedpref" | "external" | "root"]
path="string" />
&lt;exclude domain=["file" | "database" | "sharedpref" | "external" | "root"]
path="string" />
&lt;/full-backup-content></pre>
<p>Inside the <code>&lt;full-backup-content></code> tag, you can define <code>&lt;include></code> and <code>&lt;exclude></code>
elements:
<ul>
<li><code>&lt;include></code> - Specifies a file or folder to backup. By default, Auto Backup
includes almost all app files. If you specify an &lt;include> element, the system
no longer includes any files by default and backs up <em>only the files
specified</em>. To include multiple files, use multiple &lt;include> elements.
<p>note: Files in directories returned by <code>getCacheDir()</code>, <code>getCodeCacheDir()</code>, or
<code>getNoBackupFilesDir()</code> are always excluded even if you try to include them.</li>
<li><code>&lt;exclude></code> - Specifies a file or folder to exclude during backup. Here are
some files that are typically excluded from backup: <ul>
<li>Files that have device specific identifiers, either issued by a server or
generated on the device. For example, <a href="https://developers.google.com/cloud-messaging/android/start">Google Cloud Messaging (GCM)</a> needs to
generate a registration token every time a user installs your app on a new
device. If the old registration token is restored, the app may behave
unexpectedly.
<li>Account credentials or other sensitive information. Consider asking the
user to reauthenticate the first time they launch a restored app rather than
allowing for storage of such information in the backup.
<li>Files related to app debugging, such as <a href="{@docRoot}studio/run/index.html#instant-run">instant run files</a>. To exclude instant run files, add the rule <code>&lt;exclude
domain="file" path="instant-run"/></code>
<li>Large files that cause the app to exceed the 25MB backup quota.</li> </ul>
</li> </ul>
<p class="note"><strong>Note:</strong> If your configuration file specifies both elements, then the
backup contains everything captured by the <code>&lt;include></code> elements minus the
resources named in the <code>&lt;exclude></code> elements. In other words,
<code>&lt;exclude></code> takes precedence.
<p>Each element must include the following two attributes:
<ul>
<li><code>domain</code> - specifies the location of resource. Valid values for this attribute
include the following: <ul>
<li><code>root</code> - the directory on the filesystem where all private files belonging to
this app are stored.
<li><code>file</code> - directories returned by {@link android.content.Context#getFilesDir()}.
<li><code>database</code> - directories returned by {@link android.content.Context#getDatabasePath(String) getDatabasePath()}.
Databases created with {@link android.database.sqlite.SQLiteOpenHelper}
are stored here.
<li><code>sharedpref</code> - the directory where {@link android.content.SharedPreferences}
are stored.
<li><code>external</code> the directory returned by {@link android.content.Context#getExternalFilesDir(String) getExternalFilesDir()}
<p>Note: You cannot backup files outside of these locations.</li></ul>
<li><code>path</code>: Specifies a file or folder to include in or exclude from backup. Note
that: <ul>
<li>This attribute does not support wildcard or regex syntax.
<li>You can use <code>.</code> to reference the current directory, however, you cannot
reference the parent directory <code>..</code> for security reasons.
<li>If you specify a directory, then the rule applies to all files in the
directory and recursive sub-directories.</li></ul></li></ul>
<h2 id="ImplementingBackupAgent">Implementing BackupAgent</h2>
<p>Apps that implement Auto Backup do not need to implement {@link android.app.backup.BackupAgent}. However, you can optionally implement a custom {@link android.app.backup.BackupAgent}. Typically, there are two reasons for doing this:
<ul>
<li>You want to receive notification of backup events such as,
{@link android.app.backup.BackupAgent#onRestoreFinished()} or {@link android.app.backup.BackupAgent#onQuotaExceeded(long,long)}. These callback methods are executed
even if the app is not running.
<li>You can't easily express the set of files you want to backup with XML rules.
In these very rare cases, you can implement a BackupAgent that overrides {@link android.app.backup.BackupAgent#onFullBackup(FullBackupDataOutput)} to
store what you want. To retain the system's default implementation, call the
corresponding method on the superclass with <code>super.onFullBackup()</code>.</li></ul>
<p class="note"><strong>Note:</strong> Your <code>BackupAgent</code> must
implement the abstract methods
{@link android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) onBackup()}
and {@link android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}.
Those methods are used for Key/Value Backup. So if
you are not using Key/Value Backup, implement those methods and leave them blank.
<p>For more information, see
<a href="{@docRoot}guide/topics/data/keyvaluebackup.html#BackupAgent">Extending
BackupAgent</a>.

960
docs/html/guide/topics/data/backup.jd
View File

@@ -1,930 +1,34 @@
page.title=Data Backup
page.title=Backing up App Data to the Cloud
page.tags=cloud,sync,backup
startpage=true
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>Quickview</h2>
<ul>
<li>Back up the user's data to the cloud in case the user loses it</li>
<li>If the user upgrades to a new Android-powered device, your app can restore the user's
data onto the new device</li>
<li>Easily back up SharedPreferences and private files with BackupAgentHelper</li>
<li>Requires API Level 8</li>
</ul>
<h2>In this document</h2>
<ol>
<li><a href="#Basics">The Basics</a></li>
<li><a href="#BackupManifest">Declaring the Backup Agent in Your Manifest</a></li>
<li><a href="#BackupKey">Registering for Android Backup Service</a></li>
<li><a href="#BackupAgent">Extending BackupAgent</a>
<ol>
<li><a href="#RequiredMethods">Required Methods</a></li>
<li><a href="#PerformingBackup">Performing backup</a></li>
<li><a href="#PerformingRestore">Performing restore</a></li>
</ol>
</li>
<li><a href="#BackupAgentHelper">Extending BackupAgentHelper</a>
<ol>
<li><a href="#SharedPreferences">Backing up SharedPreferences</a></li>
<li><a href="#Files">Backing up Private Files</a></li>
</ol>
</li>
<li><a href="#RestoreVersion">Checking the Restore Data Version</a></li>
<li><a href="#RequestingBackup">Requesting Backup</a></li>
<li><a href="#RequestingRestore">Requesting Restore</a></li>
<li><a href="#Testing">Testing Your Backup Agent</a></li>
</ol>
<h2>Key classes</h2>
<ol>
<li>{@link android.app.backup.BackupManager}</li>
<li>{@link android.app.backup.BackupAgent}</li>
<li>{@link android.app.backup.BackupAgentHelper}</li>
</ol>
<h2>See also</h2>
<ol>
<li><a href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a></li>
</ol>
</div>
</div>
<p>Android's {@link android.app.backup backup} service allows you to copy your persistent
application data to remote "cloud" storage, in order to provide a restore point for the
application data and settings. If a user performs a factory reset or converts to a new
Android-powered device, the system automatically restores your backup data when the application
is re-installed. This way, your users don't need to reproduce their previous data or
application settings. This process is completely transparent to the user and does not affect the
functionality or user experience in your application.</p>
<p>During a backup operation (which your application can request), Android's Backup Manager ({@link
android.app.backup.BackupManager}) queries your application for backup data, then hands it to
a backup transport, which then delivers the data to the cloud storage. During a
restore operation, the Backup Manager retrieves the backup data from the backup transport and
returns it to your application so your application can restore the data to the device. It's
possible for your application to request a restore, but that shouldn't be necessary&mdash;Android
automatically performs a restore operation when your application is installed and there exists
backup data associated with the user. The primary scenario in which backup data is restored is when
a user resets their device or upgrades to a new device and their previously installed
applications are re-installed.</p>
<p class="note"><strong>Note:</strong> The backup service is <em>not</em> designed for
synchronizing application data with other clients or saving data that you'd like to access during
the normal application lifecycle. You cannot read or write backup data on demand and cannot access
it in any way other than through the APIs provided by the Backup Manager.</p>
<p>The backup transport is the client-side component of Android's backup framework, which is
customizable by
the device manufacturer and service provider. The backup transport may differ from device to device
and which backup transport is available on any given device is transparent to your application. The
Backup Manager APIs isolate your application from the actual backup transport available on a given
device&mdash;your application communicates with the Backup Manager through a fixed set of APIs,
regardless of the underlying transport.</p>
<p>Data backup is <em>not</em> guaranteed to be available on all Android-powered
devices. However, your application is not adversely affected in the event
that a device does not provide a backup transport. If you believe that users will benefit from data
backup in your application, then you can implement it as described in this document, test it, then
publish your application without any concern about which devices actually perform backup. When your
application runs on a device that does not provide a backup transport, your application operates
normally, but will not receive callbacks from the Backup Manager to backup data.</p>
<p>Although you cannot know what the current transport is, you are always assured that your
backup data cannot be read by other applications on the device. Only the Backup Manager and backup
transport have access to the data you provide during a backup operation.</p>
<p class="caution"><strong>Caution:</strong> Because the cloud storage and transport service can
differ from device to device, Android makes no guarantees about the security of your data while
using backup. You should always be cautious about using backup to store sensitive data, such as
usernames and passwords.</p>
<h2 id="Basics">The Basics</h2>
<p>To backup your application data, you need to implement a backup agent. Your backup
agent is called by the Backup Manager to provide the data you want to back up. It is also called
to restore your backup data when the application is re-installed. The Backup Manager handles all
your data transactions with the cloud storage (using the backup transport) and your backup agent
handles all your data transactions on the device.</p>
<p>To implement a backup agent, you must:</p>
<ol>
<li>Declare your backup agent in your manifest file with the <a
href="{@docRoot}guide/topics/manifest/application-element.html#agent">{@code
android:backupAgent}</a> attribute.</li>
<li>Register your application with a backup service. Google offers <a
href="http://code.google.com/android/backup/index.html">Android Backup Service</a> as a backup
service for most Android-powered devices, which requires that you register your application in
order for it to work. Any other backup services available might also require you to register
in order to store your data on their servers.</li>
<li>Define a backup agent by either:</p>
<ol type="a">
<li><a href="#BackupAgent">Extending BackupAgent</a>
<p>The {@link android.app.backup.BackupAgent} class provides the central interface with
which your application communicates with the Backup Manager. If you extend this class
directly, you must override {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} to handle the backup and restore operations for your data.</p>
<p><em>Or</em></p>
<li><a href="#BackupAgentHelper">Extending BackupAgentHelper</a>
<p>The {@link android.app.backup.BackupAgentHelper} class provides a convenient
wrapper around the {@link android.app.backup.BackupAgent} class, which minimizes the amount of code
you need to write. In your {@link android.app.backup.BackupAgentHelper}, you must use one or more
"helper" objects, which automatically backup and restore certain types of data, so that you do not
need to implement {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}.</p>
<p>Android currently provides backup helpers that will backup and restore complete files
from {@link android.content.SharedPreferences} and <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>.</p>
</li>
</ol>
</li>
</ol>
<h2 id="BackupManifest">Declaring the Backup Agent in Your Manifest</h2>
<p>This is the easiest step, so once you've decided on the class name for your backup agent, declare
it in your manifest with the <a
href="{@docRoot}guide/topics/manifest/application-element.html#agent">{@code
android:backupAgent}</a> attribute in the <a
href="{@docRoot}guide/topics/manifest/application-element.html">{@code
<application>}</a> tag.</p>
<p>For example:</p>
<pre>
&lt;manifest ... &gt;
...
&lt;application android:label="MyApplication"
<b>android:backupAgent="MyBackupAgent"</b>&gt;
&lt;activity ... &gt;
...
&lt;/activity&gt;
&lt;/application&gt;
&lt;/manifest&gt;
</pre>
<p>Another attribute you might want to use is <a
href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code
android:restoreAnyVersion}</a>. This attribute takes a boolean value to indicate whether you
want to restore the application data regardless of the current application version compared to the
version that produced the backup data. (The default value is "{@code false}".) See <a
href="#RestoreVersion">Checking the Restore Data Version</a> for more information.</p>
<p class="note"><strong>Note:</strong> The backup service and the APIs you must use are
available only on devices running API Level 8 (Android 2.2) or greater, so you should also
set your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
attribute to "8".</p>
<h2 id="BackupKey">Registering for Android Backup Service</h2>
<p>Google provides a backup transport with <a
href="http://code.google.com/android/backup/index.html">Android Backup Service</a> for most
Android-powered devices running Android 2.2 or greater.</p>
<p>In order for your application to perform backup using Android Backup Service, you must
register your application with the service to receive a Backup Service Key, then
declare the Backup Service Key in your Android manifest.</p>
<p>To get your Backup Service Key, <a
href="http://code.google.com/android/backup/signup.html">register for Android Backup Service</a>.
When you register, you will be provided a Backup Service Key and the appropriate {@code
<meta-data>} XML code for your Android manifest file, which you must include as a child of the
{@code <application>} element. For example:</p>
<pre>
&lt;application android:label="MyApplication"
android:backupAgent="MyBackupAgent"&gt;
...
&lt;meta-data android:name="com.google.android.backup.api_key"
android:value="AEdPqrEAAAAIDaYEVgU6DJnyJdBmU7KLH3kszDXLv_4DIsEIyQ" /&gt;
&lt;/application&gt;
</pre>
<p>The <code>android:name</code> must be <code>"com.google.android.backup.api_key"</code> and
the <code>android:value</code> must be the Backup Service Key received from the Android Backup
Service registration.</p>
<p>If you have multiple applications, you must register each one, using the respective package
name.</p>
<p class="note"><strong>Note:</strong> The backup transport provided by Android Backup Service is
not guaranteed to be available
on all Android-powered devices that support backup. Some devices might support backup
using a different transport, some devices might not support backup at all, and there is no way for
your application to know what transport is used on the device. However, if you implement backup for
your application, you should always include a Backup Service Key for Android Backup Service so
your application can perform backup when the device uses the Android Backup Service transport. If
the device does not use Android Backup Service, then the {@code <meta-data>} element with the
Backup Service Key is ignored.</p>
<h2 id="BackupAgent">Extending BackupAgent</h2>
<p>Most applications shouldn't need to extend the {@link android.app.backup.BackupAgent} class
directly, but should instead <a href="#BackupAgentHelper">extend BackupAgentHelper</a> to take
advantage of the built-in helper classes that automatically backup and restore your files. However,
you might want to extend {@link android.app.backup.BackupAgent} directly if you need to:</p>
<ul>
<li>Version your data format. For instance, if you anticipate the need to revise the
format in which you write your application data, you can build a backup agent to cross-check your
application version during a restore operation and perform any necessary compatibility work if the
version on the device is different than that of the backup data. For more information, see <a
href="#RestoreVersion">Checking the Restore Data Version</a>.</li>
<li>Instead of backing up an entire file, you can specify the portions of data the should be
backed up and how each portion is then restored to the device. (This can also help you manage
different versions, because you read and write your data as unique entities, rather than
complete files.)</li>
<li>Back up data in a database. If you have an SQLite database that you want to restore when
the user re-installs your application, you need to build a custom {@link
android.app.backup.BackupAgent} that reads the appropriate data during a backup operation, then
create your table and insert the data during a restore operation.</li>
</ul>
<p>If you don't need to perform any of the tasks above and want to back up complete files from
{@link android.content.SharedPreferences} or <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>, you
should skip to <a href="#BackupAgentHelper">Extending BackupAgentHelper</a>.</p>
<h3 id="RequiredMethods">Required Methods</h3>
<p>When you create a backup agent by extending {@link android.app.backup.BackupAgent}, you
must implement the following callback methods:</p>
<dl>
<dt>{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()}</dt>
<dd>The Backup Manager calls this method after you <a href="#RequestingBackup">request a
backup</a>. In this method, you read your application data from the device and pass the data you
want to back up to the Backup Manager, as described below in <a href="#PerformingBackup">Performing
backup</a>.</dd>
<dt>{@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}</dt>
<dd>The Backup Manager calls this method during a restore operation (you can <a
href="#RequestingRestore">request a restore</a>, but the system automatically performs restore when
the user re-installs your application). When it calls this method, the Backup Manager delivers your
backup data, which you then restore to the device, as described below in <a
href="#PerformingRestore">Performing restore</a>.</dd>
</dl>
<h3 id="PerformingBackup">Performing backup</h3>
<p>When it's time to back up your application data, the Backup Manager calls your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method. This is where you must provide your application data to the Backup Manager so
it can be saved to cloud storage.</p>
<p>Only the Backup Manager can call your backup agent's {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method. Each time that your application data changes and you want to perform a backup,
you must request a backup operation by calling {@link
android.app.backup.BackupManager#dataChanged()} (see <a href="#RequestingBackup">Requesting
Backup</a> for more information). A backup request does not result in an immediate call to your
{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method. Instead, the Backup Manager waits for an appropriate time, then performs
backup for all applications that have requested a backup since the last backup was performed.</p>
<p class="note"><strong>Tip:</strong> While developing your application, you can initiate an
immediate backup operation from the Backup Manager with the <a
href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p>
<p>When the Backup Manager calls your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method, it passes three parameters:</p>
<dl>
<dt>{@code oldState}</dt>
<dd>An open, read-only {@link android.os.ParcelFileDescriptor} pointing to the last backup
state provided by your application. This is not the backup data from cloud storage, but a
local representation of the data that was backed up the last time {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} was called (as defined by {@code newState}, below, or from {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}&mdash;more about this in the next section). Because {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} does not allow you to read existing backup data in
the cloud storage, you can use this local representation to determine whether your data has changed
since the last backup.</dd>
<dt>{@code data}</dt>
<dd>A {@link android.app.backup.BackupDataOutput} object, which you use to deliver your backup
data to the Backup Manager.</dd>
<dt>{@code newState}</dt>
<dd>An open, read/write {@link android.os.ParcelFileDescriptor} pointing to a file in which
you must write a representation of the data that you delivered to {@code data} (a representation
can be as simple as the last-modified timestamp for your file). This object is
returned as {@code oldState} the next time the Backup Manager calls your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method. If you do not write your backup data to {@code newState}, then {@code oldState}
will point to an empty file next time Backup Manager calls {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()}.</dd>
</dl>
<p>Using these parameters, you should implement your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method to do the following:</p>
<ol>
<li>Check whether your data has changed since the last backup by comparing {@code oldState} to
your current data. How you read data in {@code oldState} depends on how you originally wrote it to
{@code newState} (see step 3). The easiest way to record the state of a file is with its
last-modified timestamp. For example, here's how you can read and compare a timestamp from {@code
oldState}:
<pre>
// Get the oldState input stream
FileInputStream instream = new FileInputStream(oldState.getFileDescriptor());
DataInputStream in = new DataInputStream(instream);
try {
// Get the last modified timestamp from the state file and data file
long stateModified = in.readLong();
long fileModified = mDataFile.lastModified();
if (stateModified != fileModified) {
// The file has been modified, so do a backup
// Or the time on the device changed, so be safe and do a backup
} else {
// Don't back up because the file hasn't changed
return;
}
} catch (IOException e) {
// Unable to read state file... be safe and do a backup
}
</pre>
<p>If nothing has changed and you don't need to back up, skip to step 3.</p>
</li>
<li>If your data has changed, compared to {@code oldState}, write the current data to
{@code data} to back it up to the cloud storage.
<p>You must write each chunk of data as an "entity" in the {@link
android.app.backup.BackupDataOutput}. An entity is a flattened binary data
record that is identified by a unique key string. Thus, the data set that you back up is
conceptually a set of key-value pairs.</p>
<p>To add an entity to your backup data set, you must:</p>
<ol>
<li>Call {@link android.app.backup.BackupDataOutput#writeEntityHeader(String,int)
writeEntityHeader()}, passing a unique string key for the data you're about to write and the data
size.</li>
<li>Call {@link android.app.backup.BackupDataOutput#writeEntityData(byte[],int)
writeEntityData()}, passing a byte buffer that contains your data and the number of bytes to write
from the buffer (which should match the size passed to {@link
android.app.backup.BackupDataOutput#writeEntityHeader(String,int) writeEntityHeader()}).</li>
</ol>
<p>For example, the following code flattens some data into a byte stream and writes it into a
single entity:</p>
<pre>
// Create buffer stream and data output stream for our data
ByteArrayOutputStream bufStream = new ByteArrayOutputStream();
DataOutputStream outWriter = new DataOutputStream(bufStream);
// Write structured data
outWriter.writeUTF(mPlayerName);
outWriter.writeInt(mPlayerScore);
// Send the data to the Backup Manager via the BackupDataOutput
byte[] buffer = bufStream.toByteArray();
int len = buffer.length;
data.writeEntityHeader(TOPSCORE_BACKUP_KEY, len);
data.writeEntityData(buffer, len);
</pre>
<p>Perform this for each piece of data that you want to back up. How you divide your data into
entities is up to you (and you might use just one entity).</p>
</li>
<li>Whether or not you perform a backup (in step 2), write a representation of the current data to
the {@code newState} {@link android.os.ParcelFileDescriptor}. The Backup Manager retains this object
locally as a representation of the data that is currently backed up. It passes this back to you as
{@code oldState} the next time it calls {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} so you can determine whether another backup is necessary (as handled in step 1). If you
do not write the current data state to this file, then
{@code oldState} will be empty during the next callback.
<p>The following example saves a representation of the current data into {@code newState} using
the file's last-modified timestamp:</p>
<pre>
FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor());
DataOutputStream out = new DataOutputStream(outstream);
long modified = mDataFile.lastModified();
out.writeLong(modified);
</pre>
</li>
</ol>
<p class="caution"><strong>Caution:</strong> If your application data is saved to a file, make sure
that you use synchronized statements while accessing the file so that your backup agent does not
read the file while an Activity in your application is also writing the file.</p>
<h3 id="PerformingRestore">Performing restore</h3>
<p>When it's time to restore your application data, the Backup Manager calls your backup
agent's {@link android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} method. When it calls this method, the Backup Manager delivers your backup data so
you can restore it onto the device.</p>
<p>Only the Backup Manager can call {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}, which happens automatically when the system installs your application and
finds existing backup data. However, you can request a restore operation for
your application by calling {@link
android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} (see <a
href="#RequestingRestore">Requesting restore</a> for more information).</p>
<p class="note"><strong>Note:</strong> While developing your application, you can also request a
restore operation with the <a href="{@docRoot}tools/help/bmgr.html">{@code bmgr}
tool</a>.</p>
<p>When the Backup Manager calls your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} method, it passes three parameters:</p>
<dl>
<dt>{@code data}</dt>
<dd>A {@link android.app.backup.BackupDataInput}, which allows you to read your backup
data.</dd>
<dt>{@code appVersionCode}</dt>
<dd>An integer representing the value of your application's <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a>
manifest attribute, as it was when this data was backed up. You can use this to cross-check the
current application version and determine if the data format is compatible. For more
information about using this to handle different versions of restore data, see the section
below about <a href="#RestoreVersion">Checking the Restore Data Version</a>.</dd>
<dt>{@code newState}</dt>
<dd>An open, read/write {@link android.os.ParcelFileDescriptor} pointing to a file in which
you must write the final backup state that was provided with {@code data}. This object is
returned as {@code oldState} the next time {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} is called. Recall that you must also write the same {@code newState} object in the
{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} callback&mdash;also doing it here ensures that the {@code oldState} object given to
{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} is valid even the first time {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} is called after the device is restored.</dd>
</dl>
<p>In your implementation of {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}, you should call {@link android.app.backup.BackupDataInput#readNextHeader()} on the
{@code data} to iterate
through all entities in the data set. For each entity found, do the following:</p>
<ol>
<li>Get the entity key with {@link android.app.backup.BackupDataInput#getKey()}.</li>
<li>Compare the entity key to a list of known key values that you should have declared as static
final strings inside your {@link android.app.backup.BackupAgent} class. When the key matches one of
your known key strings, enter into a statement to extract the entity data and save it to the device:
<ol>
<li>Get the entity data size with {@link
android.app.backup.BackupDataInput#getDataSize()} and create a byte array of that size.</li>
<li>Call {@link android.app.backup.BackupDataInput#readEntityData(byte[],int,int)
readEntityData()} and pass it the byte array, which is where the data will go, and specify the
start offset and the size to read.</li>
<li>Your byte array is now full and you can read the data and write it to the device
however you like.</li>
</ol>
</li>
<li>After you read and write your data back to the device, write the state of your data to the
{@code newState} parameter the same as you do during {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()}.
</ol>
<p>For example, here's how you can restore the data backed up by the example in the previous
section:</p>
<pre>
&#64;Override
public void onRestore(BackupDataInput data, int appVersionCode,
ParcelFileDescriptor newState) throws IOException {
// There should be only one entity, but the safest
// way to consume it is using a while loop
while (data.readNextHeader()) {
String key = data.getKey();
int dataSize = data.getDataSize();
// If the key is ours (for saving top score). Note this key was used when
// we wrote the backup entity header
if (TOPSCORE_BACKUP_KEY.equals(key)) {
// Create an input stream for the BackupDataInput
byte[] dataBuf = new byte[dataSize];
data.readEntityData(dataBuf, 0, dataSize);
ByteArrayInputStream baStream = new ByteArrayInputStream(dataBuf);
DataInputStream in = new DataInputStream(baStream);
// Read the player name and score from the backup data
mPlayerName = in.readUTF();
mPlayerScore = in.readInt();
// Record the score on the device (to a file or something)
recordScore(mPlayerName, mPlayerScore);
} else {
// We don't know this entity key. Skip it. (Shouldn't happen.)
data.skipEntityData();
}
}
// Finally, write to the state blob (newState) that describes the restored data
FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor());
DataOutputStream out = new DataOutputStream(outstream);
out.writeUTF(mPlayerName);
out.writeInt(mPlayerScore);
}
</pre>
<p>In this example, the {@code appVersionCode} parameter passed to {@link
android.app.backup.BackupAgent#onRestore onRestore()} is not used. However, you might want to use
it if you've chosen to perform backup when the user's version of the application has actually moved
backward (for example, the user went from version 1.5 of your app to 1.0). For more information, see
the section about <a href="#RestoreVersion">Checking the Restore Data Version</a>.</p>
<div class="special">
<p>For an example implementation of {@link android.app.backup.BackupAgent}, see the <a
href="{@docRoot}resources/samples/BackupRestore/src/com/example/android/backuprestore/ExampleAgent.html">{@code
ExampleAgent}</a> class in the <a
href="{@docRoot}resources/samples/BackupRestore/index.html">Backup and Restore</a> sample
application.</p>
</div>
<h2 id="BackupAgentHelper">Extending BackupAgentHelper</h2>
<p>You should build your backup agent using {@link android.app.backup.BackupAgentHelper} if you want
to back up complete files (from either {@link android.content.SharedPreferences} or <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>).
Building your backup agent with {@link android.app.backup.BackupAgentHelper} requires far less
code than extending {@link android.app.backup.BackupAgent}, because you don't have to implement
{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}.</p>
<p>Your implementation of {@link android.app.backup.BackupAgentHelper} must
use one or more backup helpers. A backup helper is a specialized
component that {@link android.app.backup.BackupAgentHelper} summons to perform backup and
restore operations for a particular type of data. The Android framework currently provides two
different helpers:</p>
<ul>
<li>{@link android.app.backup.SharedPreferencesBackupHelper} to backup {@link
android.content.SharedPreferences} files.</li>
<li>{@link android.app.backup.FileBackupHelper} to backup files from <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>.</li>
</ul>
<p>You can include multiple helpers in your {@link android.app.backup.BackupAgentHelper}, but only
one helper is needed for each data type. That is, if you have multiple {@link
android.content.SharedPreferences} files, then you need only one {@link
android.app.backup.SharedPreferencesBackupHelper}.</p>
<p>For each helper you want to add to your {@link android.app.backup.BackupAgentHelper}, you must do
the following during your {@link android.app.backup.BackupAgent#onCreate()} method:</p>
<ol>
<li>Instantiate in instance of the desired helper class. In the class constructor, you must
specify the appropriate file(s) you want to backup.</li>
<li>Call {@link android.app.backup.BackupAgentHelper#addHelper(String,BackupHelper) addHelper()}
to add the helper to your {@link android.app.backup.BackupAgentHelper}.</li>
</ol>
<p>The following sections describe how to create a backup agent using each of the available
helpers.</p>
<h3 id="SharedPreferences">Backing up SharedPreferences</h3>
<p>When you instantiate a {@link android.app.backup.SharedPreferencesBackupHelper}, you must
include the name of one or more {@link android.content.SharedPreferences} files.</p>
<p>For example, to back up a {@link android.content.SharedPreferences} file named
"user_preferences", a complete backup agent using {@link android.app.backup.BackupAgentHelper} looks
like this:</p>
<pre>
public class MyPrefsBackupAgent extends BackupAgentHelper {
// The name of the SharedPreferences file
static final String PREFS = "user_preferences";
// A key to uniquely identify the set of backup data
static final String PREFS_BACKUP_KEY = "prefs";
// Allocate a helper and add it to the backup agent
&#64;Override
public void onCreate() {
SharedPreferencesBackupHelper helper =
new SharedPreferencesBackupHelper(this, PREFS);
addHelper(PREFS_BACKUP_KEY, helper);
}
}
</pre>
<p>That's it! That's your entire backup agent. The {@link
android.app.backup.SharedPreferencesBackupHelper} includes all the code
needed to backup and restore a {@link android.content.SharedPreferences} file.</p>
<p>When the Backup Manager calls {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}, {@link android.app.backup.BackupAgentHelper} calls your backup helpers to perform
backup and restore for your specified files.</p>
<p class="note"><strong>Note:</strong> {@link android.content.SharedPreferences} are threadsafe, so
you can safely read and write the shared preferences file from your backup agent and
other activities.</p>
<h3 id="Files">Backing up other files</h3>
<p>When you instantiate a {@link android.app.backup.FileBackupHelper}, you must include the name of
one or more files that are saved to your application's <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>
(as specified by {@link android.content.ContextWrapper#getFilesDir()}, which is the same
location where {@link android.content.Context#openFileOutput(String,int) openFileOutput()} writes
files).</p>
<p>For example, to backup two files named "scores" and "stats," a backup agent using {@link
android.app.backup.BackupAgentHelper} looks like this:</p>
<pre>
public class MyFileBackupAgent extends BackupAgentHelper {
// The name of the file
static final String TOP_SCORES = "scores";
static final String PLAYER_STATS = "stats";
// A key to uniquely identify the set of backup data
static final String FILES_BACKUP_KEY = "myfiles";
// Allocate a helper and add it to the backup agent
&#64;Override
public void onCreate() {
FileBackupHelper helper = new FileBackupHelper(this,
TOP_SCORES, PLAYER_STATS);
addHelper(FILES_BACKUP_KEY, helper);
}
}
</pre>
<p>The {@link android.app.backup.FileBackupHelper} includes all the code necessary to backup and
restore files that are saved to your application's <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>..</p>
<p>However, reading and writing to files on internal storage is <strong>not threadsafe</strong>. To
ensure that your backup agent does not read or write your files at the same time as your activities,
you must use synchronized statements each time you perform a read or write. For example,
in any Activity where you read and write the file, you need an object to use as the intrinsic
lock for the synchronized statements:</p>
<pre>
// Object for intrinsic lock
static final Object sDataLock = new Object();
</pre>
<p>Then create a synchronized statement with this lock each time you read or write the files. For
example, here's a synchronized statement for writing the latest score in a game to a file:</p>
<pre>
try {
synchronized (MyActivity.sDataLock) {
File dataFile = new File({@link android.content.Context#getFilesDir()}, TOP_SCORES);
RandomAccessFile raFile = new RandomAccessFile(dataFile, "rw");
raFile.writeInt(score);
}
} catch (IOException e) {
Log.e(TAG, "Unable to write to file");
}
</pre>
<p>You should synchronize your read statements with the same lock.</p>
<p>Then, in your {@link android.app.backup.BackupAgentHelper}, you must override {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} to synchronize the backup and restore operations with the same
intrinsic lock. For example, the {@code MyFileBackupAgent} example from above needs the following
methods:</p>
<pre>
&#64;Override
public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
ParcelFileDescriptor newState) throws IOException {
// Hold the lock while the FileBackupHelper performs backup
synchronized (MyActivity.sDataLock) {
super.onBackup(oldState, data, newState);
}
}
&#64;Override
public void onRestore(BackupDataInput data, int appVersionCode,
ParcelFileDescriptor newState) throws IOException {
// Hold the lock while the FileBackupHelper restores the file
synchronized (MyActivity.sDataLock) {
super.onRestore(data, appVersionCode, newState);
}
}
</pre>
<p>That's it. All you need to do is add your {@link android.app.backup.FileBackupHelper} in the
{@link android.app.backup.BackupAgent#onCreate()} method and override {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} to synchronize read and write operations.</p>
<div class="special">
<p>For an example implementation of {@link
android.app.backup.BackupAgentHelper} with {@link android.app.backup.FileBackupHelper}, see the
{@code FileHelperExampleAgent} class in the <a
href="{@docRoot}resources/samples/BackupRestore/index.html">Backup and Restore</a> sample
application.</p>
</div>
<h2 id="RestoreVersion">Checking the Restore Data Version</h2>
<p>When the Backup Manager saves your data to cloud storage, it automatically includes the version
of your application, as defined by your manifest file's <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a>
attribute. Before the Backup Manager calls your backup agent to restore your data, it
looks at the <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code
android:versionCode}</a> of the installed application and compares it to the value
recorded in the restore data set. If the version recorded in the restore data set is
<em>newer</em> than the application version on the device, then the user has downgraded their
application. In this case, the Backup Manager will abort the restore operation for your application
and not call your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
method, because the restore set is considered meaningless to an older version.</p>
<p>You can override this behavior with the <a
href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code
android:restoreAnyVersion}</a> attribute. This attribute is either "{@code true}" or "{@code
false}" to indicate whether you want to restore the application regardless of the restore set
version. The default value is "{@code false}". If you define this to be "{@code true}" then the
Backup Manager will ignore the <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a>
and call your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
method in all cases. In doing so, you can manually check for the version difference in your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
method and take any steps necessary to make the data compatible if the versions conflict.</p>
<p>To help you handle different versions during a restore operation, the {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
method passes you the version code included with the restore data set as the {@code appVersionCode}
parameter. You can then query the current application's version code with the {@link
android.content.pm.PackageInfo#versionCode PackageInfo.versionCode} field. For example:</p>
<pre>
PackageInfo info;
try {
String name = {@link android.content.ContextWrapper#getPackageName() getPackageName}();
info = {@link android.content.ContextWrapper#getPackageManager
getPackageManager}().{@link android.content.pm.PackageManager#getPackageInfo(String,int)
getPackageInfo}(name,0);
} catch (NameNotFoundException nnfe) {
info = null;
}
int version;
if (info != null) {
version = info.versionCode;
}
</pre>
<p>Then simply compare the {@code version} acquired from {@link android.content.pm.PackageInfo}
to the {@code appVersionCode} passed into {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}.
</p>
<p class="caution"><strong>Caution:</strong> Be certain you understand the consequences of setting
<a href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code
android:restoreAnyVersion}</a> to "{@code true}" for your application. If each version of your
application that supports backup does not properly account for variations in your data format during
{@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()},
then the data on the device could be saved in a format incompatible with the version currently
installed on the device.</p>
<h2 id="RequestingBackup">Requesting Backup</h2>
<p>You can request a backup operation at any time by calling {@link
android.app.backup.BackupManager#dataChanged()}. This method notifies the Backup Manager that you'd
like to backup your data using your backup agent. The Backup Manager then calls your backup
agent's {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method at an opportune time in the future. Typically, you should
request a backup each time your data changes (such as when the user changes an application
preference that you'd like to back up). If you call {@link
android.app.backup.BackupManager#dataChanged()} several times consecutively, before the Backup
Manager requests a backup from your agent, your agent still receives just one call to {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()}.</p>
<p class="note"><strong>Note:</strong> While developing your application, you can request a
backup and initiate an immediate backup operation with the <a
href="{@docRoot}tools/help/bmgr.html">{@code bmgr}
tool</a>.</p>
<h2 id="RequestingRestore">Requesting Restore</h2>
<p>During the normal life of your application, you shouldn't need to request a restore operation.
They system automatically checks for backup data and performs a restore when your application is
installed. However, you can manually request a restore operation by calling {@link
android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()}, if necessary. In
which case, the Backup Manager calls your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
implementation, passing the data from the current set of backup data.</p>
<p class="note"><strong>Note:</strong> While developing your application, you can request a
restore operation with the <a href="{@docRoot}tools/help/bmgr.html">{@code bmgr}
tool</a>.</p>
<h2 id="Testing">Testing Your Backup Agent</h2>
<p>Once you've implemented your backup agent, you can test the backup and restore functionality
with the following procedure, using <a
href="{@docRoot}tools/help/bmgr.html">{@code bmgr}</a>.</p>
<ol>
<li>Install your application on a suitable Android system image
<ul>
<li>If using the emulator, create and use an AVD with Android 2.2 (API Level 8).</li>
<li>If using a device, the device must be running Android 2.2 or greater and have Google
Play built in.</li>
</ul>
</li>
<li>Ensure that backup is enabled
<ul>
<li>If using the emulator, you can enable backup with the following command from your SDK
{@code tools/} path:
<pre class="no-pretty-print">adb shell bmgr enable true</pre>
</li>
<li>If using a device, open the system <b>Settings</b>, select
<b>Backup & reset</b>, then enable
<b>Back up my data</b> and <b>Automatic restore</b>.</li>
</ul>
</li>
<li>Open your application and initialize some data
<p>If you've properly implemented backup in your application, then it should request a
backup each time the data changes. For example, each time the user changes some data, your app
should call {@link android.app.backup.BackupManager#dataChanged()}, which adds a backup request to
the Backup Manager queue. For testing purposes, you can also make a request with the following
{@code bmgr} command:</p>
<pre class="no-pretty-print">adb shell bmgr backup <em>your.package.name</em></pre>
</li>
<li>Initiate a backup operation:
<pre class="no-pretty-print">adb shell bmgr run</pre>
<p>This forces the Backup Manager to perform all backup requests that are in its
queue.</p>
<li>Uninstall your application:
<pre class="no-pretty-print">adb uninstall <em>your.package.name</em></pre>
</li>
<li>Re-install your application.</li>
</ol>
<p>If your backup agent is successful, all the data you initialized in step 4 is restored.</p>
<p>Users often invest significant time and effort creating data and setting
preferences within apps. Preserving that data for users if they replace a broken
device or upgrade to a new one is an important part of ensuring a great user
experience. This section covers techniques for backing up data to the cloud so
that users can restore their data.
<p>Android provides two ways for apps to backup their data to the cloud:
<a href="{@docRoot}guide/topics/data/autobackup.html">Auto Backup for Apps</a> and
<a href="{@docRoot}guide/topics/data/keyvaluebackup.html">Key/Value Backup</a>.
Auto Backup, which is available starting API 23, preserves app data by uploading
it to the user’s Google Drive account. The Key/Value Backup feature (formerly
known as the Backup API and the Android Backup Service) preserves app data by
uploading it to the <a href="{@docRoot}google/backup/index.html">Android Backup Service</a>.
<p>Generally, we recommend Auto Backup because it requires no work to implement.
Apps that target Android 6.0 (API level 23) or higher are automatically enabled
for Auto Backup. The Auto Backup feature does have some limitations in terms of
what data it can backup and it's availability on Android 6.0 and higher devices.
Consider using the Key/Value Backup feature if you have more specific needs for
backing up your app data. For more information, see <a href="{@docRoot}guide/topics/data/keyvaluebackup.html#Comparison">Comparison of Key/Value and Auto Backup</a></p>
<p class="note"><strong>Note:</strong> These data backup features are not designed for synchronizing app data with other clients or
saving data that you'd like to access during the normal application lifecycle.
You cannot read or write backup data on demand. For synchronizing app data, see
<a href="{@docRoot}training/sync-adapters/index.html">Transferring
Data Using Sync Adapters</a> or <a href="https://developers.google.com/drive/android/">Google Drive Android
API</a>.

BIN
docs/html/guide/topics/data/images/backup-framework.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 42 KiB

18
docs/html/guide/topics/data/index.jd
View File

@@ -5,21 +5,3 @@ page.landing.image=
@jd:body
<div class="landing-docs">
<div class="col-12">
<h3>Training</h3>
<a href="{@docRoot}training/backup/index.html">
<h4>Backing up App Data to the Cloud</h4>
<p>
This class covers techniques for backing up data to the cloud so that
users can restore their data when recovering from a data loss (such as a
factory reset) or installing your application on a new device.
</p>
</a>
</div>
</div>

884
docs/html/guide/topics/data/keyvaluebackup.jd Normal file
View File

@@ -0,0 +1,884 @@
page.title=Key/Value Backup
page.tags=backup, marshmallow, androidm
page.keywords=backup, kvbackup
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#Comparison">Comparison to Auto Backup</a></li>
<li><a href="#ImplementingBackup">Implementing Key/Value Backup</a></li>
<li><a href="#BackupManifest">Declaring the backup agent in your manifest</a></li>
<li><a href="#BackupKey">Registering for Android Backup Service</a></li>
<li><a href="#BackupAgent">Extending BackupAgent</a>
<ol>
<li><a href="#RequiredMethods">Required methods</a></li>
<li><a href="#PerformingBackup">Performing backup</a></li>
<li><a href="#PerformingRestore">Performing restore</a></li>
</ol>
</li>
<li><a href="#BackupAgentHelper">Extending BackupAgentHelper</a>
<ol>
<li><a href="#SharedPreferences">Backing up SharedPreferences</a></li>
<li><a href="#Files">Backing up private files</a></li>
</ol>
</li>
<li><a href="#RestoreVersion">Checking the restore data version</a></li>
<li><a href="#RequestingBackup">Requesting backup</a></li>
<li><a href="#RequestingRestore">Requesting restore</a></li>
<li><a href="#Migrating">Migrating to Auto Backup</a></li>
</ol>
<h2>Key classes</h2>
<ol>
<li>{@link android.app.backup.BackupManager}</li>
<li>{@link android.app.backup.BackupAgent}</li>
<li>{@link android.app.backup.BackupAgentHelper}</li>
</ol>
</div>
</div>
<p>Since Android 2.2 (API 8), Android has offered the <em>Key/Value Backup</em>
feature as a way for developers to backup app data to the cloud. The Key/Value
Backup feature (formerly known as the Backup API and the Android Backup Service)
preserves app data by uploading it to
<a href="{@docRoot}google/backup/index.html">Android Backup Service</a>.
The amount of data is limited to 5MB per user of your app and there is
no charge for storing backup data.
<p class="note"><strong>Note:</strong> If your app implements Key/Value Backup
and targets API 23 or higher, you should set
<a href="{@docRoot}reference/android/R.attr.html#fullBackupOnly">android:fullBackupOnly</a>.
This attribute indicates whether or not to use Auto Backup on devices where it is available.
<h2 id="Comparison">Comparison to Auto Backup</h2>
<p>Like Auto Backup, Key/Value Backups are restored automatically whenever the app
is installed. The following table describes some of the key differences between Key/Value Backup and Auto Backup:
<table>
<tr>
<th>Key/Value Backup</th>
<th>Auto Backup</th>
</tr>
<tr>
<td>Available in API 8, Android 2.2</td>
<td>Available in API 23, Android 6.0</td>
</tr>
<tr>
<td>Apps must implement a {@link android.app.backup.BackupAgent}. The backup agent defines what data to backup and how to
restore data.</td>
<td>By default, Auto Backup includes almost all of the app's files. You can
use XML to include and exclude files. Under the hood, Auto Backup relies on a
backup agent that is built into the framework.</td>
</tr>
<tr>
<td>Apps must issue a request when there is data
that is ready to be backed up. Requests
from multiple apps are batched and executed every few hours.</td>
<td>Backups happen automatically roughly once a day.</td>
</tr>
<tr>
<td>Backup data can be transmitted via wifi or cellular data.</td>
<td>Backup data is tranmitted only via wifi. If the device is never connected to a
wifi network, then Auto Backup never occurs.</td>
</tr>
<tr>
<td>Apps are not shut down during backup.</td>
<td>The system shuts down the app during backup.</td>
</tr>
<tr>
<td>Backup data is stored in <a href="{@docRoot}google/backup/index.html">Android Backup Service</a> limited to 5MB per app.</td>
<td>Backup data is stored in the user's Google Drive limited to 25MB per app.</td>
</tr>
<tr>
<td>Related API methods are not filed based:<ul>
<li>{@link android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput, ParcelFileDescriptor) onBackup()}
<li>{@link android.app.backup.BackupAgent#onRestore(BackupDataInput, int, ParcelFileDescriptor) onRestore()}</ul></td>
<td>Related API methods are filed based:<ul>
<li>{@link android.app.backup.BackupAgent#onFullBackup(FullBackupDataOutput) onFullBackup()}
<li>{@link android.app.backup.BackupAgent#onRestoreFile(ParcelFileDescriptor,long,File,int,long,long) onRestoreFile()}</ul></td>
</tr>
</table>
<h2 id="ImplementingBackup">Implementing Key/Value Backup</h2>
<p>To backup your application data, you need to implement a backup agent. Your backup
agent is called by the Backup Manager both during backup and restore.</p>
<p>To implement a backup agent, you must:</p>
<ol>
<li>Declare your backup agent in your manifest file with the <a
href="{@docRoot}guide/topics/manifest/application-element.html#agent">{@code
android:backupAgent}</a> attribute.</li>
<li>Register your application with <a href="{@docRoot}google/backup/index.html">Android
Backup Service</a></li>
<li>Define a backup agent by either:</p>
<ol type="a">
<li><a href="#BackupAgent">Extending BackupAgent</a>
<p>The {@link android.app.backup.BackupAgent} class provides the central interface with
which your application communicates with the Backup Manager. If you extend this class
directly, you must override {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} to handle the backup and restore operations for your data.</p>
<p><em>Or</em></p>
<li><a href="#BackupAgentHelper">Extending BackupAgentHelper</a>
<p>The {@link android.app.backup.BackupAgentHelper} class provides a convenient
wrapper around the {@link android.app.backup.BackupAgent} class, which minimizes the amount of code
you need to write. In your {@link android.app.backup.BackupAgentHelper}, you must use one or more
"helper" objects, which automatically backup and restore certain types of data, so that you do not
need to implement {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}.</p>
<p>Android currently provides backup helpers that will backup and restore complete files
from {@link android.content.SharedPreferences} and <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>.</p>
</li>
</ol>
</li>
</ol>
<h2 id="BackupManifest">Declaring the backup agent in your manifest</h2>
<p>This is the easiest step, so once you've decided on the class name for your backup agent, declare
it in your manifest with the <a
href="{@docRoot}guide/topics/manifest/application-element.html#agent">{@code
android:backupAgent}</a> attribute in the <a
href="{@docRoot}guide/topics/manifest/application-element.html">{@code
<application>}</a> tag.</p>
<p>For example:</p>
<pre>
&lt;manifest ... &gt;
...
&lt;application android:label="MyApplication"
<b>android:backupAgent="MyBackupAgent"</b>&gt;
&lt;activity ... &gt;
...
&lt;/activity&gt;
&lt;/application&gt;
&lt;/manifest&gt;
</pre>
<p>Another attribute you might want to use is <a
href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code
android:restoreAnyVersion}</a>. This attribute takes a boolean value to indicate whether you
want to restore the application data regardless of the current application version compared to the
version that produced the backup data. (The default value is "{@code false}".) See <a
href="#RestoreVersion">Checking the Restore Data Version</a> for more information.</p>
<p class="note"><strong>Note:</strong> The backup service and the APIs you must use are
available only on devices running API Level 8 (Android 2.2) or greater, so you should also
set your <a
href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a>
attribute to "8".</p>
<h2 id="BackupKey">Registering for Android Backup Service</h2>
<p>Google provides a backup transport with <a
href="{@docRoot}google/backup/index.html">Android Backup Service</a> for most
Android-powered devices running Android 2.2 or greater.</p>
<p>In order for your application to perform backup using Android Backup Service, you must
register your application with the service to receive a Backup Service Key, then
declare the Backup Service Key in your Android manifest.</p>
<p>To get your Backup Service Key, <a
href="{@docRoot}google/backup/signup.html">register for Android Backup Service</a>.
When you register, you will be provided a Backup Service Key and the appropriate {@code
<meta-data>} XML code for your Android manifest file, which you must include as a child of the
{@code <application>} element. For example:</p>
<pre>
&lt;application android:label="MyApplication"
android:backupAgent="MyBackupAgent"&gt;
...
&lt;meta-data android:name="com.google.android.backup.api_key"
android:value="AEdPqrEAAAAIDaYEVgU6DJnyJdBmU7KLH3kszDXLv_4DIsEIyQ" /&gt;
&lt;/application&gt;
</pre>
<p>The <code>android:name</code> must be <code>"com.google.android.backup.api_key"</code> and
the <code>android:value</code> must be the Backup Service Key received from the Android Backup
Service registration.</p>
<p>If you have multiple applications, you must register each one, using the respective package
name.</p>
<p class="note"><strong>Note:</strong> The backup transport provided by Android Backup Service is
not guaranteed to be available
on all Android-powered devices that support backup. Some devices might support backup
using a different transport, some devices might not support backup at all, and there is no way for
your application to know what transport is used on the device. However, if you implement backup for
your application, you should always include a Backup Service Key for Android Backup Service so
your application can perform backup when the device uses the Android Backup Service transport. If
the device does not use Android Backup Service, then the {@code <meta-data>} element with the
Backup Service Key is ignored.</p>
<h2 id="BackupAgent">Extending BackupAgent</h2>
<p>Most applications shouldn't need to extend the {@link android.app.backup.BackupAgent} class
directly, but should instead <a href="#BackupAgentHelper">extend BackupAgentHelper</a> to take
advantage of the built-in helper classes that automatically backup and restore your files. However,
you might want to extend {@link android.app.backup.BackupAgent} directly if you need to:</p>
<ul>
<li>Version your data format. For instance, if you anticipate the need to revise the
format in which you write your application data, you can build a backup agent to cross-check your
application version during a restore operation and perform any necessary compatibility work if the
version on the device is different than that of the backup data. For more information, see <a
href="#RestoreVersion">Checking the Restore Data Version</a>.</li>
<li>Instead of backing up an entire file, you can specify the portions of data the should be
backed up and how each portion is then restored to the device. (This can also help you manage
different versions, because you read and write your data as unique entities, rather than
complete files.)</li>
<li>Back up data in a database. If you have an SQLite database that you want to restore when
the user re-installs your application, you need to build a custom {@link
android.app.backup.BackupAgent} that reads the appropriate data during a backup operation, then
create your table and insert the data during a restore operation.</li>
</ul>
<p>If you don't need to perform any of the tasks above and want to back up complete files from
{@link android.content.SharedPreferences} or <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>, you
should skip to <a href="#BackupAgentHelper">Extending BackupAgentHelper</a>.</p>
<h3 id="RequiredMethods">Required methods</h3>
<p>When you create a backup agent by extending {@link android.app.backup.BackupAgent}, you
must implement the following callback methods:</p>
<dl>
<dt>{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()}</dt>
<dd>The Backup Manager calls this method after you <a href="#RequestingBackup">request a
backup</a>. In this method, you read your application data from the device and pass the data you
want to back up to the Backup Manager, as described below in <a href="#PerformingBackup">Performing
backup</a>.</dd>
<dt>{@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}</dt>
<dd>The Backup Manager calls this method during a restore operation (you can <a
href="#RequestingRestore">request a restore</a>, but the system automatically performs restore when
the user re-installs your application). When it calls this method, the Backup Manager delivers your
backup data, which you then restore to the device, as described below in <a
href="#PerformingRestore">Performing restore</a>.</dd>
</dl>
<h3 id="PerformingBackup">Performing backup</h3>
<p>When it's time to back up your application data, the Backup Manager calls your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method. This is where you must provide your application data to the Backup Manager so
it can be saved to cloud storage.</p>
<p>Only the Backup Manager can call your backup agent's {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method. Each time that your application data changes and you want to perform a backup,
you must request a backup operation by calling {@link
android.app.backup.BackupManager#dataChanged()} (see <a href="#RequestingBackup">Requesting
Backup</a> for more information). A backup request does not result in an immediate call to your
{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method. Instead, the Backup Manager waits for an appropriate time, then performs
backup for all applications that have requested a backup since the last backup was performed.</p>
<p class="note"><strong>Tip:</strong> While developing your application, you can initiate an
immediate backup operation from the Backup Manager with the <a
href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p>
<p>When the Backup Manager calls your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method, it passes three parameters:</p>
<dl>
<dt>{@code oldState}</dt>
<dd>An open, read-only {@link android.os.ParcelFileDescriptor} pointing to the last backup
state provided by your application. This is not the backup data from cloud storage, but a
local representation of the data that was backed up the last time {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} was called (as defined by {@code newState}, below, or from {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}&mdash;more about this in the next section). Because {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} does not allow you to read existing backup data in
the cloud storage, you can use this local representation to determine whether your data has changed
since the last backup.</dd>
<dt>{@code data}</dt>
<dd>A {@link android.app.backup.BackupDataOutput} object, which you use to deliver your backup
data to the Backup Manager.</dd>
<dt>{@code newState}</dt>
<dd>An open, read/write {@link android.os.ParcelFileDescriptor} pointing to a file in which
you must write a representation of the data that you delivered to {@code data} (a representation
can be as simple as the last-modified timestamp for your file). This object is
returned as {@code oldState} the next time the Backup Manager calls your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method. If you do not write your backup data to {@code newState}, then {@code oldState}
will point to an empty file next time Backup Manager calls {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()}.</dd>
</dl>
<p>Using these parameters, you should implement your {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method to do the following:</p>
<ol>
<li>Check whether your data has changed since the last backup by comparing {@code oldState} to
your current data. How you read data in {@code oldState} depends on how you originally wrote it to
{@code newState} (see step 3). The easiest way to record the state of a file is with its
last-modified timestamp. For example, here's how you can read and compare a timestamp from {@code
oldState}:
<pre>
// Get the oldState input stream
FileInputStream instream = new FileInputStream(oldState.getFileDescriptor());
DataInputStream in = new DataInputStream(instream);
try {
// Get the last modified timestamp from the state file and data file
long stateModified = in.readLong();
long fileModified = mDataFile.lastModified();
if (stateModified != fileModified) {
// The file has been modified, so do a backup
// Or the time on the device changed, so be safe and do a backup
} else {
// Don't back up because the file hasn't changed
return;
}
} catch (IOException e) {
// Unable to read state file... be safe and do a backup
}
</pre>
<p>If nothing has changed and you don't need to back up, skip to step 3.</p>
</li>
<li>If your data has changed, compared to {@code oldState}, write the current data to
{@code data} to back it up to the cloud storage.
<p>You must write each chunk of data as an "entity" in the {@link
android.app.backup.BackupDataOutput}. An entity is a flattened binary data
record that is identified by a unique key string. Thus, the data set that you back up is
conceptually a set of key-value pairs.</p>
<p>To add an entity to your backup data set, you must:</p>
<ol>
<li>Call {@link android.app.backup.BackupDataOutput#writeEntityHeader(String,int)
writeEntityHeader()}, passing a unique string key for the data you're about to write and the data
size.</li>
<li>Call {@link android.app.backup.BackupDataOutput#writeEntityData(byte[],int)
writeEntityData()}, passing a byte buffer that contains your data and the number of bytes to write
from the buffer (which should match the size passed to {@link
android.app.backup.BackupDataOutput#writeEntityHeader(String,int) writeEntityHeader()}).</li>
</ol>
<p>For example, the following code flattens some data into a byte stream and writes it into a
single entity:</p>
<pre>
// Create buffer stream and data output stream for our data
ByteArrayOutputStream bufStream = new ByteArrayOutputStream();
DataOutputStream outWriter = new DataOutputStream(bufStream);
// Write structured data
outWriter.writeUTF(mPlayerName);
outWriter.writeInt(mPlayerScore);
// Send the data to the Backup Manager via the BackupDataOutput
byte[] buffer = bufStream.toByteArray();
int len = buffer.length;
data.writeEntityHeader(TOPSCORE_BACKUP_KEY, len);
data.writeEntityData(buffer, len);
</pre>
<p>Perform this for each piece of data that you want to back up. How you divide your data into
entities is up to you (and you might use just one entity).</p>
</li>
<li>Whether or not you perform a backup (in step 2), write a representation of the current data to
the {@code newState} {@link android.os.ParcelFileDescriptor}. The Backup Manager retains this object
locally as a representation of the data that is currently backed up. It passes this back to you as
{@code oldState} the next time it calls {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} so you can determine whether another backup is necessary (as handled in step 1). If you
do not write the current data state to this file, then
{@code oldState} will be empty during the next callback.
<p>The following example saves a representation of the current data into {@code newState} using
the file's last-modified timestamp:</p>
<pre>
FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor());
DataOutputStream out = new DataOutputStream(outstream);
long modified = mDataFile.lastModified();
out.writeLong(modified);
</pre>
</li>
</ol>
<p class="caution"><strong>Caution:</strong> If your application data is saved to a file, make sure
that you use synchronized statements while accessing the file so that your backup agent does not
read the file while an Activity in your application is also writing the file.</p>
<h3 id="PerformingRestore">Performing restore</h3>
<p>When it's time to restore your application data, the Backup Manager calls your backup
agent's {@link android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} method. When it calls this method, the Backup Manager delivers your backup data so
you can restore it onto the device.</p>
<p>Only the Backup Manager can call {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}, which happens automatically when the system installs your application and
finds existing backup data. However, you can request a restore operation for
your application by calling {@link
android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} (see <a
href="#RequestingRestore">Requesting restore</a> for more information).</p>
<p class="note"><strong>Note:</strong> While developing your application, you can also request a
restore operation with the <a href="{@docRoot}tools/help/bmgr.html">{@code bmgr}
tool</a>.</p>
<p>When the Backup Manager calls your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} method, it passes three parameters:</p>
<dl>
<dt>{@code data}</dt>
<dd>A {@link android.app.backup.BackupDataInput}, which allows you to read your backup
data.</dd>
<dt>{@code appVersionCode}</dt>
<dd>An integer representing the value of your application's <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a>
manifest attribute, as it was when this data was backed up. You can use this to cross-check the
current application version and determine if the data format is compatible. For more
information about using this to handle different versions of restore data, see the section
below about <a href="#RestoreVersion">Checking the Restore Data Version</a>.</dd>
<dt>{@code newState}</dt>
<dd>An open, read/write {@link android.os.ParcelFileDescriptor} pointing to a file in which
you must write the final backup state that was provided with {@code data}. This object is
returned as {@code oldState} the next time {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} is called. Recall that you must also write the same {@code newState} object in the
{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} callback&mdash;also doing it here ensures that the {@code oldState} object given to
{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} is valid even the first time {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} is called after the device is restored.</dd>
</dl>
<p>In your implementation of {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}, you should call {@link android.app.backup.BackupDataInput#readNextHeader()} on the
{@code data} to iterate
through all entities in the data set. For each entity found, do the following:</p>
<ol>
<li>Get the entity key with {@link android.app.backup.BackupDataInput#getKey()}.</li>
<li>Compare the entity key to a list of known key values that you should have declared as static
final strings inside your {@link android.app.backup.BackupAgent} class. When the key matches one of
your known key strings, enter into a statement to extract the entity data and save it to the device:
<ol>
<li>Get the entity data size with {@link
android.app.backup.BackupDataInput#getDataSize()} and create a byte array of that size.</li>
<li>Call {@link android.app.backup.BackupDataInput#readEntityData(byte[],int,int)
readEntityData()} and pass it the byte array, which is where the data will go, and specify the
start offset and the size to read.</li>
<li>Your byte array is now full and you can read the data and write it to the device
however you like.</li>
</ol>
</li>
<li>After you read and write your data back to the device, write the state of your data to the
{@code newState} parameter the same as you do during {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()}.
</ol>
<p>For example, here's how you can restore the data backed up by the example in the previous
section:</p>
<pre>
&#64;Override
public void onRestore(BackupDataInput data, int appVersionCode,
ParcelFileDescriptor newState) throws IOException {
// There should be only one entity, but the safest
// way to consume it is using a while loop
while (data.readNextHeader()) {
String key = data.getKey();
int dataSize = data.getDataSize();
// If the key is ours (for saving top score). Note this key was used when
// we wrote the backup entity header
if (TOPSCORE_BACKUP_KEY.equals(key)) {
// Create an input stream for the BackupDataInput
byte[] dataBuf = new byte[dataSize];
data.readEntityData(dataBuf, 0, dataSize);
ByteArrayInputStream baStream = new ByteArrayInputStream(dataBuf);
DataInputStream in = new DataInputStream(baStream);
// Read the player name and score from the backup data
mPlayerName = in.readUTF();
mPlayerScore = in.readInt();
// Record the score on the device (to a file or something)
recordScore(mPlayerName, mPlayerScore);
} else {
// We don't know this entity key. Skip it. (Shouldn't happen.)
data.skipEntityData();
}
}
// Finally, write to the state blob (newState) that describes the restored data
FileOutputStream outstream = new FileOutputStream(newState.getFileDescriptor());
DataOutputStream out = new DataOutputStream(outstream);
out.writeUTF(mPlayerName);
out.writeInt(mPlayerScore);
}
</pre>
<p>In this example, the {@code appVersionCode} parameter passed to {@link
android.app.backup.BackupAgent#onRestore onRestore()} is not used. However, you might want to use
it if you've chosen to perform backup when the user's version of the application has actually moved
backward (for example, the user went from version 1.5 of your app to 1.0). For more information, see
the section about <a href="#RestoreVersion">Checking the Restore Data Version</a>.</p>
<div class="special">
<p>For an example implementation of {@link android.app.backup.BackupAgent}, see the <a
href="{@docRoot}resources/samples/BackupRestore/src/com/example/android/backuprestore/ExampleAgent.html">{@code
ExampleAgent}</a> class in the <a
href="{@docRoot}resources/samples/BackupRestore/index.html">Backup and Restore</a> sample
application.</p>
</div>
<h2 id="BackupAgentHelper">Extending BackupAgentHelper</h2>
<p>You should build your backup agent using {@link android.app.backup.BackupAgentHelper} if you want
to back up complete files (from either {@link android.content.SharedPreferences} or <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>).
Building your backup agent with {@link android.app.backup.BackupAgentHelper} requires far less
code than extending {@link android.app.backup.BackupAgent}, because you don't have to implement
{@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}.</p>
<p>Your implementation of {@link android.app.backup.BackupAgentHelper} must
use one or more backup helpers. A backup helper is a specialized
component that {@link android.app.backup.BackupAgentHelper} summons to perform backup and
restore operations for a particular type of data. The Android framework currently provides two
different helpers:</p>
<ul>
<li>{@link android.app.backup.SharedPreferencesBackupHelper} to backup {@link
android.content.SharedPreferences} files.</li>
<li>{@link android.app.backup.FileBackupHelper} to backup files from <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>.</li>
</ul>
<p>You can include multiple helpers in your {@link android.app.backup.BackupAgentHelper}, but only
one helper is needed for each data type. That is, if you have multiple {@link
android.content.SharedPreferences} files, then you need only one {@link
android.app.backup.SharedPreferencesBackupHelper}.</p>
<p>For each helper you want to add to your {@link android.app.backup.BackupAgentHelper}, you must do
the following during your {@link android.app.backup.BackupAgent#onCreate()} method:</p>
<ol>
<li>Instantiate in instance of the desired helper class. In the class constructor, you must
specify the appropriate file(s) you want to backup.</li>
<li>Call {@link android.app.backup.BackupAgentHelper#addHelper(String,BackupHelper) addHelper()}
to add the helper to your {@link android.app.backup.BackupAgentHelper}.</li>
</ol>
<p>The following sections describe how to create a backup agent using each of the available
helpers.</p>
<h3 id="SharedPreferences">Backing up SharedPreferences</h3>
<p>When you instantiate a {@link android.app.backup.SharedPreferencesBackupHelper}, you must
include the name of one or more {@link android.content.SharedPreferences} files.</p>
<p>For example, to back up a {@link android.content.SharedPreferences} file named
"user_preferences", a complete backup agent using {@link android.app.backup.BackupAgentHelper} looks
like this:</p>
<pre>
public class MyPrefsBackupAgent extends BackupAgentHelper {
// The name of the SharedPreferences file
static final String PREFS = "user_preferences";
// A key to uniquely identify the set of backup data
static final String PREFS_BACKUP_KEY = "prefs";
// Allocate a helper and add it to the backup agent
&#64;Override
public void onCreate() {
SharedPreferencesBackupHelper helper =
new SharedPreferencesBackupHelper(this, PREFS);
addHelper(PREFS_BACKUP_KEY, helper);
}
}
</pre>
<p>That's it! That's your entire backup agent. The {@link
android.app.backup.SharedPreferencesBackupHelper} includes all the code
needed to backup and restore a {@link android.content.SharedPreferences} file.</p>
<p>When the Backup Manager calls {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()}, {@link android.app.backup.BackupAgentHelper} calls your backup helpers to perform
backup and restore for your specified files.</p>
<p class="note"><strong>Note:</strong> The methods of {@link android.content.SharedPreferences}
are threadsafe, so
you can safely read and write the shared preferences file from your backup agent and
other activities.</p>
<h3 id="Files">Backing up other files</h3>
<p>When you instantiate a {@link android.app.backup.FileBackupHelper}, you must include the name of
one or more files that are saved to your application's <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>
(as specified by {@link android.content.ContextWrapper#getFilesDir()}, which is the same
location where {@link android.content.Context#openFileOutput(String,int) openFileOutput()} writes
files).</p>
<p>For example, to backup two files named "scores" and "stats," a backup agent using {@link
android.app.backup.BackupAgentHelper} looks like this:</p>
<pre>
public class MyFileBackupAgent extends BackupAgentHelper {
// The name of the file
static final String TOP_SCORES = "scores";
static final String PLAYER_STATS = "stats";
// A key to uniquely identify the set of backup data
static final String FILES_BACKUP_KEY = "myfiles";
// Allocate a helper and add it to the backup agent
&#64;Override
public void onCreate() {
FileBackupHelper helper = new FileBackupHelper(this,
TOP_SCORES, PLAYER_STATS);
addHelper(FILES_BACKUP_KEY, helper);
}
}
</pre>
<p>The {@link android.app.backup.FileBackupHelper} includes all the code necessary to backup and
restore files that are saved to your application's <a
href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>..</p>
<p>However, reading and writing to files on internal storage is <strong>not threadsafe</strong>. To
ensure that your backup agent does not read or write your files at the same time as your activities,
you must use synchronized statements each time you perform a read or write. For example,
in any Activity where you read and write the file, you need an object to use as the intrinsic
lock for the synchronized statements:</p>
<pre>
// Object for intrinsic lock
static final Object sDataLock = new Object();
</pre>
<p>Then create a synchronized statement with this lock each time you read or write the files. For
example, here's a synchronized statement for writing the latest score in a game to a file:</p>
<pre>
try {
synchronized (MyActivity.sDataLock) {
File dataFile = new File({@link android.content.Context#getFilesDir()}, TOP_SCORES);
RandomAccessFile raFile = new RandomAccessFile(dataFile, "rw");
raFile.writeInt(score);
}
} catch (IOException e) {
Log.e(TAG, "Unable to write to file");
}
</pre>
<p>You should synchronize your read statements with the same lock.</p>
<p>Then, in your {@link android.app.backup.BackupAgentHelper}, you must override {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} to synchronize the backup and restore operations with the same
intrinsic lock. For example, the {@code MyFileBackupAgent} example from above needs the following
methods:</p>
<pre>
&#64;Override
public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data,
ParcelFileDescriptor newState) throws IOException {
// Hold the lock while the FileBackupHelper performs backup
synchronized (MyActivity.sDataLock) {
super.onBackup(oldState, data, newState);
}
}
&#64;Override
public void onRestore(BackupDataInput data, int appVersionCode,
ParcelFileDescriptor newState) throws IOException {
// Hold the lock while the FileBackupHelper restores the file
synchronized (MyActivity.sDataLock) {
super.onRestore(data, appVersionCode, newState);
}
}
</pre>
<p>That's it. All you need to do is add your {@link android.app.backup.FileBackupHelper} in the
{@link android.app.backup.BackupAgent#onCreate()} method and override {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} and {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
onRestore()} to synchronize read and write operations.</p>
<div class="special">
<p>For an example implementation of {@link
android.app.backup.BackupAgentHelper} with {@link android.app.backup.FileBackupHelper}, see the
{@code FileHelperExampleAgent} class in the <a
href="{@docRoot}resources/samples/BackupRestore/index.html">Backup and Restore</a> sample
application.</p>
</div>
<h2 id="RestoreVersion">Checking the restore data version</h2>
<p>When the Backup Manager saves your data to cloud storage, it automatically includes the version
of your application, as defined by your manifest file's <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a>
attribute. Before the Backup Manager calls your backup agent to restore your data, it
looks at the <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code
android:versionCode}</a> of the installed application and compares it to the value
recorded in the restore data set. If the version recorded in the restore data set is
<em>newer</em> than the application version on the device, then the user has downgraded their
application. In this case, the Backup Manager will abort the restore operation for your application
and not call your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
method, because the restore set is considered meaningless to an older version.</p>
<p>You can override this behavior with the <a
href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code
android:restoreAnyVersion}</a> attribute. This attribute is either "{@code true}" or "{@code
false}" to indicate whether you want to restore the application regardless of the restore set
version. The default value is "{@code false}". If you define this to be "{@code true}" then the
Backup Manager will ignore the <a
href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a>
and call your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
method in all cases. In doing so, you can manually check for the version difference in your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
method and take any steps necessary to make the data compatible if the versions conflict.</p>
<p>To help you handle different versions during a restore operation, the {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
method passes you the version code included with the restore data set as the {@code appVersionCode}
parameter. You can then query the current application's version code with the {@link
android.content.pm.PackageInfo#versionCode PackageInfo.versionCode} field. For example:</p>
<pre>
PackageInfo info;
try {
String name = {@link android.content.ContextWrapper#getPackageName() getPackageName}();
info = {@link android.content.ContextWrapper#getPackageManager
getPackageManager}().{@link android.content.pm.PackageManager#getPackageInfo(String,int)
getPackageInfo}(name,0);
} catch (NameNotFoundException nnfe) {
info = null;
}
int version;
if (info != null) {
version = info.versionCode;
}
</pre>
<p>Then simply compare the {@code version} acquired from {@link android.content.pm.PackageInfo}
to the {@code appVersionCode} passed into {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}.
</p>
<p class="caution"><strong>Caution:</strong> Be certain you understand the consequences of setting
<a href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code
android:restoreAnyVersion}</a> to "{@code true}" for your application. If each version of your
application that supports backup does not properly account for variations in your data format during
{@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()},
then the data on the device could be saved in a format incompatible with the version currently
installed on the device.</p>
<h2 id="RequestingBackup">Requesting backup</h2>
<p>You can request a backup operation at any time by calling {@link
android.app.backup.BackupManager#dataChanged()}. This method notifies the Backup Manager that you'd
like to backup your data using your backup agent. The Backup Manager then calls your backup
agent's {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()} method at an opportune time in the future. Typically, you should
request a backup each time your data changes (such as when the user changes an application
preference that you'd like to back up). If you call {@link
android.app.backup.BackupManager#dataChanged()} several times consecutively, before the Backup
Manager requests a backup from your agent, your agent still receives just one call to {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
onBackup()}.</p>
<p class="note"><strong>Note:</strong> While developing your application, you can request a
backup and initiate an immediate backup operation with the <a
href="{@docRoot}tools/help/bmgr.html">{@code bmgr}
tool</a>.</p>
<h2 id="RequestingRestore">Requesting restore</h2>
<p>During the normal life of your application, you shouldn't need to request a restore operation.
They system automatically checks for backup data and performs a restore when your application is
installed. However, you can manually request a restore operation by calling {@link
android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()}, if necessary. In
which case, the Backup Manager calls your {@link
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}
implementation, passing the data from the current set of backup data.</p>
<p class="note"><strong>Note:</strong> While developing your application, you can request a
restore operation with the <a href="{@docRoot}tools/help/bmgr.html">{@code bmgr}
tool</a>.</p>
<h2 id="Migrating">Migrating to Auto Backup</h2>
<p>You can transition your app to full-data backups by setting <a href="{@docRoot}reference/android/R.attr.html#fullBackupOnly">android:fullBackupOnly</a> to <code>true</code> in the <code>&lt;application></code> element in the manifest file. When
running on a device with Android 5.1 (API level 22) or lower, your app ignores
this value in the manifest, and continues performing Key/Value Backups. When
running on a device with Android 6.0 (API level 23) or higher, your app performs
Auto Backup instead of Key/Value Backup.

181
docs/html/guide/topics/data/testingbackup.jd Normal file
View File

@@ -0,0 +1,181 @@
page.title=Testing Backup and Restore
page.tags=backup, marshmallow, androidm
page.keywords=backup, restore, testing
@jd:body
<div id="qv-wrapper">
<div id="qv">
<h2>In this document</h2>
<ol>
<li><a href="#HowBackupWorks">How backup works</a></li>
<li><a href="#Prerequisites">Prerequisites</a></li>
<li><a href="#Preparing">Preparing your device or emulator</a></li>
<li><a href="#TestingBackup">Testing backup</a></li>
<li><a href="#TestingRestore">Testing restore</a></li>
<li><a href="#Troubleshooting">Troubleshooting</a></li>
</ol>
</div>
</div>
<p>This page shows you how to manually trigger Auto Backup, Key/Value Backup, and restore operations to
ensure your app saves and restores data properly.
<h2 id="HowBackupWorkso">How backup works</h2>
<p>The section describes various pieces in the Android backup framework and how they
interact with apps that support Auto Backup and Key/Value Backup. During the app
development phase, most of the inner working of the framework were abstracted away, so you didn't need to know this information. However, during the
testing phase, an understanding of these concepts is important.
<p>The following diagram illustrates how data flows during backup and restore:
<img src="images/backup-framework.png" alt="backup-framework">
<p>The <em>Backup Manager Service</em> is an Android system
service which orchestrates and initiates backup and restore operations. The service
is accessible through the {@link android.app.backup.BackupManager}
API. During a backup operation, the service queries your app for backup data,
then hands it to the <em>backup transport</em>, which then archives the data.
During a restore operation, the backup manager service retrieves the backup data
from the backup transport and restores the data to the device.
<p><em>Backup Transports</em> are Android components that are responsible
for storing and retrieving backups. An Android device can have zero or more
backup transports, but only one of those transports can be marked active. The
available backup transports may differ from device to device (due to
customizations by device manufacturers and service providers), but most Google
Play enabled devices ship with the following transports:
</p><ul>
<li><strong>Google GMS Transport</strong>(default) - the active backup
transport on most devices, part of <a href="https://www.android.com/gms/">Google Mobile Services</a>. This documentation assumes that users are using the
Google GMS transport. This transport stores Auto Backup data in a private folder in the
user's Google Drive account. Key/Value Backup data is stored in the <a href="{@docRoot}google/backup/index.html">Android Backup Service</a>.
<li><strong>Local Transport</strong> - stores backup data locally on the device.
This transport is typically used for development/debugging purposes and is not
useful in the real world.</li></ul>
<p>If a device does not have any backup transports, then the data cannot be
backed up. Your app is not adversely affected.
<p class="caution"><strong>Caution:</strong> Because the backup transport
can differ from device to device, Android cannot guarantee the security
of your data while using backup. Be cautious about using backup to store
sensitive data, such as usernames and passwords.
<h2 id="Prerequisites">Prerequisites</h2>
<p>You need to know a bit about the following tools:
<ul>
<li><a href="{@docRoot}studio/command-line/adb.html">adb</a>
- to run commands on the device or emulator
<li><a href="{@docRoot}studio/command-line/bmgr.html">bmgr</a> - to
perform various backup and restore operations
<li><a href="{@docRoot}studio/command-line/logcat.html">logcat</a>
- to see the output of backup and restore operations.</li></ul>
<h2 id="Preparing">Preparing your device or
emulator</h2>
<p>Prepare your device or emulator for backup testing by working through the
following checklist:
<ul>
<li>For Auto Backup, check that you are using a device or emulator running
Android 6.0 (API level 23) or higher.</li>
<li>For Key/Value Backup, check that you are using a device or emulator running
Android 2.2 (API level 8) or higher.</li>
<li>Check that backup and restore is enabled on the device or emulator. There
are two ways to check: <ul>
<li>On the device, go to <strong>Settings -> Backup &amp; Restore</strong>.
<li>From adb shell, run <code>bmgr enable</code></li></ul>
<p>On physical devices, backup and restore is typically enabled during the
initial setup wizard. Emulators do not run the setup wizard, so don't forget to
enable backup and specify a backup account in device settings.
<li>Make sure the GMS Backup Transport is available and active by running the
command from adb shell:
<pre class="prettyprint">$ bmgr list transports</pre>
<p>Then, check the console for the following output:
<pre class="prettyprint">android/com.android.internal.backup.LocalTransport
* com.google.android.gms/.backup.BackupTransportService</pre>
<p>Physical devices without Google Play and emulators without Google APIs
might not include the GMS Backup Transport. This article assumes you are using
the GMS Backup Transport. You can test backup and restore with other backup
transports, but the procedure and output can differ.
</ul>
<h2 id="TestingBackup">Testing backup</h2>
<p>To initiate a backup of your app, run the following command:
<pre class="prettyprint">$ bmgr backupnow &lt;PACKAGE></pre>
<p>The <code>backupnow</code> command runs either a Key/Value Backup or Auto Backup depending on
the package's manifest declarations. Check logcat to see the output of the
backup procedure. For example:
<pre class="prettyprint">D/BackupManagerService: fullTransportBackup()
I/GmsBackupTransport: Attempt to do full backup on &lt;PACKAGE>
---- or ----
V/BackupManagerService: Scheduling immediate backup pass
D/PerformBackupTask: starting key/value Backup of BackupRequest{pkg=&lt;PACKAGE>}
</pre>
<p>If the <code>backupnow</code> command is not available on your device, you need to run one
of the following commands:
<ul>
<li>For Auto Backups, run: <code>bmgr fullbackup &lt;PACKAGE></code>
<li>For Key/Value Backups, schedule and run your backup with the following
commands:
<pre class="prettyprint">$ bmgr backup &lt;PACKAGE>
$ bmgr run</pre>
<p><code>bmgr backup</code> adds your app to the Backup Manager's queue. <code>bmgr run</code> initiates the
backup operation, which forces the Backup Manager to perform all backup requests
that are in its queue.
</li></ul>
<h2 id="TestingRestore">Testing restore</h2>
<p>To manually initiate a restore, run the following command:
<pre class="prettyprint">$ bmgr restore &lt;PACKAGE></pre>
<p>Warning: This action stops your app and wipes its data before performing the
restore operation.
<p>Then, check logcat to see the output of the restore procedure. For example:
<pre class="prettyprint">V/BackupManagerService: beginRestoreSession: pkg=&lt;PACKAGE> transport=null
V/RestoreSession: restorePackage pkg=&lt;PACKAGE> token=368abb4465c5c683
...
I/BackupManagerService: Restore complete.
</pre>
<p>You also can test automatic restore for your app by uninstalling and
reinstalling your app either with <code>adb</code> or through the Google
Play Store app.
<h2 id="Troubleshooting">Troubleshooting</h2>
<p><strong>Exceeded Quota</strong>
<p>If you see the the following messages in logcat:
<pre class="prettyprint">I/PFTBT: Transport rejected backup of &lt;PACKAGE>, skipping
--- or ---
I/PFTBT: Transport quota exceeded for package: &lt;PACKAGE>
</pre>
<p>Your app has exceeded the quota and has been banned from backing up
data on this device. To lift the ban, either factory reset your device or change
the backup account.
<p><strong>Full Backup Not Possible</strong>
<p>If you see the the following message in logcat:
<pre class="prettyprint">I/BackupManagerService: Full backup not currently possible -- key/value backup not yet run?
</pre>
<p>The fullbackup operation failed because no Key/Value Backup operation has yet
occurred on the device. Trigger a Key/Value Backup with the command <code>bmgr
run </code>and then try again.

12
docs/html/training/_book.yaml
View File

@@ -438,16 +438,6 @@ toc:
path: /training/efficient-downloads/redundant_redundant.html
- title: Modifying Patterns Based on the Connectivity Type
path: /training/efficient-downloads/connectivity_patterns.html
- title: Backing up App Data to the Cloud
path: /training/backup/index.html
path_attributes:
- name: description
value: How to sync and back up app and user data to remote web services in the cloud and how to restore the data back to multiple devices.
section:
- title: Configuring Auto Backup
path: /training/backup/autosyncapi.html
- title: Using the Backup API
path: /training/backup/backupapi.html
- title: Resolving Cloud Save Conflicts
path: /training/cloudsave/conflict-res.html
path_attributes:
@@ -1156,7 +1146,7 @@ toc:
value: 维护兼容性
- name: zh-tw-lang
value: 維持相容性
- title: Selecting Colors with the Palette API
- title: Selecting Colors with the Palette API
path: /training/material/palette-colors.html
- title: Best Practices for User Input

370
docs/html/training/backup/autosyncapi.jd
View File

@@ -1,370 +0,0 @@
page.title=Configuring Auto Backup for Apps
page.tags=backup, marshmallow, androidm
page.keywords=backup, autobackup
page.image=images/cards/card-auto-backup_2x.png
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#configuring">Configure Data Backup</a></li>
<li><a href="#previous-androids">Support Lower Versions of Android</a></li>
<li><a href="#testing">Test Backup Configuration</a></li>
<li><a href="#issues">Handle Google Cloud Messaging</a></li>
</ol>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li>
<li><a href="{@docRoot}training/backup/backupapi.html">Using the Backup API</a>
</li>
</ul>
</div>
</div>
<p>
Users frequently invest time and effort to configure apps just the way they like them. Switching
to a new device can cancel out all that careful configuration. For apps whose <a href=
"{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">target SDK version</a>
is Android 6.0 (API level 23) and higher, devices running Android 6.0 and higher automatically
back up app data to the cloud. The system performs this automatic backup
for nearly all app data by default, and does so without your having to write any additional app
code.
</p>
<p class="note">
<strong>Note:</strong> To protect user privacy, the device user must have opted in to Google
services for Auto Backup to work. The Google services opt-in dialog appears when the user goes
through the Setup Wizard or configures the first Google account on the device.
</p>
<p>
When a user installs your app on
a new device, or reinstalls your app on one (for example, after a factory reset), the system
automatically restores the app data from the cloud. This lesson provides information about how to
configure the Auto Backup for Apps feature, explaining its default behavior and how to
exclude data that you don't want the system to back up.
</p>
<p>
The automatic backup feature preserves the data your app creates on a user device by uploading it
to the user’s Google Drive account and encrypting it. There is no charge to you or the user for
data storage, and the saved data does not count towards the user's personal Google Drive quota.
Each app can store up to 25MB. Once its backed-up data reaches 25MB, the app no longer sends
data to the cloud. If the system performs a data restore, it uses the last data snapshot that
the app had sent to the cloud.
</p>
<p>Automatic backups occur when the following conditions are met:</p>
<ul>
<li>The device is idle.</li>
<li>The device is charging.</li>
<li>The device is connected to a Wi-Fi network.</li>
<li>At least 24 hours have elapsed since the last backup.</li>
</ul>
</p>
<h2 id="configuring">Configure Data Backup</h2>
<p>
On devices running Android 6.0 (API level 23) or higher, the default system behavior is to back up
almost all data that an app creates. The exception is <a href="#auto-exclude">
automatically excluded data files</a>. This section explains how you can use settings in
your app <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">manifest</a> to further
limit and configure what data the system backs up.
</p>
<h3 id="include-exclude">Including or excluding data</h3>
<p>
Depending on what data your app needs and how you save it, you may need to set specific
rules for including or excluding certain files or directories. Auto Backup for Apps
lets you set these backup rules through the app manifest, in which you specify a backup scheme
configuration XML file. For example:
</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.my.appexample"&gt;
&lt;uses-sdk android:minSdkVersion="23"/&gt;
&lt;uses-sdk android:targetSdkVersion="23"/&gt;
&lt;application ...
<strong> android:fullBackupContent="&#64;xml/mybackupscheme"&gt;</strong>
&lt;/app&gt;
...
&lt;/manifest&gt;
</pre>
<p>
In this example, the <code>android:fullBackupContent</code> attribute specifies an XML file
called {@code mybackupscheme.xml}, which resides in the <code>res/xml/</code> directory of your
app development project. This configuration file contains rules controlling which files are backed
up. The following example code shows a configuration file that excludes a specific file,
{@code device_info.db}:
</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;full-backup-content&gt;
&lt;exclude domain="database" path="device_info.db"/&gt;
&lt;/full-backup-content&gt;
</pre>
<h3 id="auto-exclude">Automatically excluded data files</h3>
<p>
Most apps do not need to, and in fact should not, back up all data. For example, the system
should not back up temporary files and caches. For this reason, the automatic backup
service excludes certain data files by default:
</p>
<ul>
<li>Files in the directories to which the
{@link android.content.Context#getCacheDir getCacheDir()} and
{@link android.content.Context#getCodeCacheDir getCodeCacheDir()} methods refer.
</li>
<li>Files located on external storage, unless they reside in the directory to which the
{@link android.content.Context#getExternalFilesDir getExternalFilesDir()} method refers.
</li>
<li>Files located in the directory to which the
{@link android.content.Context#getNoBackupFilesDir getNoBackupFilesDir()} method refers.
</li>
</ul>
<h3>Backup Configuration Syntax</h3>
<p>
The backup service configuration allows you to specify what files to include or exclude from
backup. The syntax for the data backup configuration XML file is as follows:
</p>
<pre>
&lt;full-backup-content&gt;
&lt;include domain=["file" | "database" | "sharedpref" | "external" | "root"]
path="string" /&gt;
&lt;exclude domain=["file" | "database" | "sharedpref" | "external" | "root"]
path="string" /&gt;
&lt;/full-backup-content&gt;
</pre>
<p>
The following elements and attributes allow you to specify the files to include in, and exclude
from, backup:
</p>
<ul>
<li>
<code>&lt;include&gt;</code>: Specifies a set of resources to
back up, instead of having the system back up all data in your app by default. If you specify
an <code>&lt;include&gt;</code> element, the system backs up <em>only the resources specified</em>
with this element. You can specify multiple sets of resources to back up by using multiple
<code>&lt;include&gt;</code> elements
</li>
<li>
<code>&lt;exclude&gt;</code>: Specifies any data you want the system to exclude
when it does a full backup. If you target the same set of resources with both the
<code>&lt;include&gt;</code> and <code>&lt;exclude&gt;</code> elements,
<code>&lt;exclude&gt;</code> takes precedence.
</li>
<li>
<code>domain</code>: Specifies the type of resource you want to include in,
or exclude from, backup. Valid values for this attribute include:
<ul>
<li>
<code>root</code>: Specifies that the resource is in the app’s root directory.
</li>
<li>
<code>file</code>: Specifies a resource in the directory returned by the
{@link android.content.Context#getFilesDir getFilesDir()} method.
</li>
<li>
<code>database</code>: Specifies a database that the
{@link android.content.Context#getDatabasePath getDatabasePath()} method returns, or that
the app interacts with via the {@link android.database.sqlite.SQLiteOpenHelper} class.
</li>
<li>
<code>sharedpref</code>: Specifies a {@link android.content.SharedPreferences} object
that the {@link android.content.Context#getSharedPreferences getSharedPreferences()}
method returns.
</li>
<li>
<code>external</code>: Specifies that the resource is in external storage, and corresponds
to a file in the directory that the
{@link android.content.Context#getExternalFilesDir getExternalFilesDir()} method returns.
</li>
</ul>
</li>
<li>
<code>path</code>: Specifies the file path to a resource that you want to include in, or
exclude from, backup.
</li>
</li>
</ul>
<h3 id="disabling">Disabling data backups</h3>
<p>
You can choose to prevent automatic backups of any of your app data by setting the
<code>android:allowBackup</code> attribute to <code>false</code> in the {@code app} element of
your manifest. This setting is illustrated in the following example:
</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools"
package="com.my.appexample"&gt;
&lt;uses-sdk android:minSdkVersion="23"/&gt;
&lt;uses-sdk android:targetSdkVersion="23"/&gt;
&lt;application ...
<strong> android:allowBackup="false"&gt;</strong>
&lt;/application&gt;
...
&lt;/manifest&gt;
</pre>
<h2 id="previous-androids">Support Lower Versions of Android</h2>
<p>There are two scenarios in which you may also need to support versions of Android lower
than 6.0 (API level 23): You may be updating your existing app to take advantage of the
new auto backup functionality in Android 6.0, while wanting
to continue supporting earlier versions of Android. Or you may be releasing a new app, but
want to make sure devices running on versions of Android predating 6.0 also have backup
functionality.</p>
<h3 id="updating">Updating an existing app to support auto backup</h3>
<p>Earlier versions of Android supported a key/value-pair-based backup mechanism, in which the app
defines a subclass of {@link android.app.backup.BackupAgent} and sets
<a href="{@docRoot}guide/topics/manifest/application-element.html#agent">
{@code android:backupAgent}</a> in its
<a href="{@docRoot}guide/topics/manifest/application-element.html">app manifest</a>. If your app
used this legacy approach, you can transition to full-data backups by adding the
{@code android:fullBackupOnly="true"} attribute to the
<a href="{@docRoot}guide/topics/manifest/application-element.html">{@code <application/>}</a>
element in the manifest. When running on a device with Android 5.1
(API level 22) or lower, your app ignores this value in the manifest, and continues performing
backups in the previous manner.</p>
<p>Even if you’re not using key/value backups, you can still use the approach described above to do
any custom processing in {@link android.app.Activity#onCreate(android.os.Bundle) onCreate()}
or {@link android.app.backup.BackupAgent#onFullBackup onFullBackup()}. You can also use that
approach to receive a notification when a restore operation happens in
{@link android.app.backup.BackupAgent#onRestoreFinished onRestoreFinished()}. If you want to retain
the system's default implementation of
<a href="#include-exclude">XML include/exclude rules handling</a>, call
{@link android.app.backup.BackupAgent#onFullBackup super.onFullBackup()}.</p>
<h3 id="lower-versions">Giving your new app support for lower versions of Android</h3>
<p>If you are creating a new app that targets Android 6.0, but you also want to enable cloud backup
for devices running on Android 5.1 (API level 22) and lower, you must also
<a href="{@docRoot}training/backup/backupapi.html">implement the Backup API</a>.</p>
<h2 id="testing">Test Backup Configuration</h2>
<p>
Once you have created a backup configuration, you should test it to make sure your app saves data
and can restore it properly.
</p>
<h3>Enabling Backup Logging</h3>
<p>
To help determine how the backup feature is parsing your XML file, enable logging before
performing a test backup:
</p>
<pre class="no-pretty-print">
$ adb shell setprop log.tag.BackupXmlParserLogging VERBOSE
</pre>
<h3>Testing Backup</h3>
<p>To manually run a backup, first initialize the Backup Manager by executing the following
command:
</p>
<pre class="no-pretty-print">
$ adb shell bmgr run
</pre>
<p>
Next, manually back up your application using the following command. Use the
<code>&lt;PACKAGE&gt;</code> parameter to specify the package name for your app:
</p>
<pre class="no-pretty-print">
$ adb shell bmgr fullbackup &lt;PACKAGE&gt;</pre>
<h3>Testing restore</h3>
<p>
To manually initiate a restore after the system has backed up your app data, execute the following
command, using the <code>&lt;PACKAGE&gt;</code> parameter to specify the package name for your
app:
</p>
<pre class="noprettyprint">
$ adb shell bmgr restore &lt;PACKAGE&gt;
</pre>
<p class="warning">
<b>Warning:</b> This action stops your app and wipes its data before performing the restore
operation.
</p>
<p>
You can test automatic restore for your app by uninstalling and reinstalling your app. The app
data is automatically restored from the cloud once the app installation is complete.
</p>
<h3>Troubleshooting backups</h3>
<p>
If backup fails, you can clear the backup data and associated metadata either by turning backup
off and on in <strong>Settings &gt; Backup</strong>, factory-resetting the device, or
executing this command:
</p>
<pre>$ adb shell bmgr wipe &lt;TRANSPORT&gt; &lt;PACKAGE&gt;</pre>
<p>
You must prepend <code>com.google.android.gms</code> to the {@code <TRANSPORT>} value.
To get the list of <a href="{@docRoot}google/backup/index.html">transports</a>, execute the
following command:
</p>
<pre>$ adb shell bmgr list transports</pre>
<h2 id="gcm">Handle Google Cloud Messaging</h2>
<p>
For apps that use <a href="https://developers.google.com/cloud-messaging/gcm">Google Cloud
Messaging</a> (GCM) for push notifications, backing up the registration
token that Google Cloud Messaging registration returned can cause unexpected behavior in
notifications for the restored app. This is because when a user installs your app on a new device,
the app must <a href="https://developers.google.com/cloud-messaging/android/client#sample-register">
query the GCM API for a new registration token</a>. If the old registration is present, because the
system had backed it up and restored it, the app doesn't seek the new token. To prevent this issue
from arising, exclude the registration token from the set of backed-up files.
</p>

200
docs/html/training/backup/backupapi.jd
View File

@@ -1,200 +0,0 @@
page.title=Using the Backup API
parent.title=Backing up App Data to the Cloud
parent.link=index.html
trainingnavtop=true
next.title=Making the Most of Google Cloud Messaging
next.link=gcm.html
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>This lesson teaches you to</h2>
<ol>
<li><a href="#register">Register for the Android Backup Service</a></li>
<li><a href="#manifest">Configure Your Manifest</a></li>
<li><a href="#agent">Write Your Backup Agent</a></li>
<li><a href="#backup">Request a Backup</a></li>
<li><a href="#restore">Restore from a Backup</a></li>
</ol>
<h2>You should also read</h2>
<ul>
<li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li>
<li><a href="{@docRoot}training/backup/autosyncapi.html">Configuring Auto Backup for Apps</a>
(Android 6.0 (API level 23) and higher)</li>
</ul>
</div>
</div>
<p>When a user purchases a new device or resets their existing one, they might
expect that when Google Play restores your app back to their device during the
initial setup, the previous data associated with the app restores as well. On versions of Android
prior to 6.0 (API level 23), app data is not restored by default, and all the user's accomplishments
or settings in your app are lost.</p>
<p>For situations where the volume of data is relatively light (less than a
megabyte), like the user's preferences, notes, game high scores or other
stats, the Backup API provides a lightweight solution. This lesson walks you
through integrating the Backup API into your application, and restoring data to
new devices using the Backup API.
<p class="note">
<strong>Note:</strong> Devices running Android 6.0 and higher
<a href="{@docRoot}training/backup/autosyncapi.html">automatically back up</a>
nearly all data by default.
</p>
<h2 id="register">Register for the Android Backup Service</h2>
<p>This lesson requires the use of the <a
href="{@docRoot}google/backup/index.html">Android Backup
Service</a>, which requires registration. Go ahead and <a
href="http://code.google.com/android/backup/signup.html">register here</a>. Once
that's done, the service pre-populates an XML tag for insertion in your Android
Manifest, which looks like this:</p>
<pre>
&lt;meta-data android:name="com.google.android.backup.api_key"
android:value="ABcDe1FGHij2KlmN3oPQRs4TUvW5xYZ" /&gt;
</pre>
<p>Note that each backup key works with a specific package name. If you have
different applications, register separate keys for each one.</p>
<h2 id="manifest">Configure Your Manifest</h2>
<p>Use of the Android Backup Service requires two additions to your application
manifest. First, declare the name of the class that acts as your backup agent,
then add the snippet above as a child element of the Application tag. Assuming
your backup agent is going to be called {@code TheBackupAgent}, here's an example of
what the manifest looks like with this tag included:</p>
<pre>
&lt;application android:label="MyApp"
android:backupAgent="TheBackupAgent"&gt;
...
&lt;meta-data android:name="com.google.android.backup.api_key"
android:value="ABcDe1FGHij2KlmN3oPQRs4TUvW5xYZ" /&gt;
...
&lt;/application&gt;
</pre>
<h2 id="agent">Write Your Backup Agent</h2>
<p>The easiest way to create your backup agent is by extending the wrapper class
{@link android.app.backup.BackupAgentHelper}. Creating this helper class is
actually a very simple process. Just create a class with the same name as you
used in the manifest in the previous step (in this example, {@code
TheBackupAgent}),
and extend {@code BackupAgentHelper}. Then override the {@link
android.app.backup.BackupAgent#onCreate()}.</p>
<p>Inside the {@link android.app.backup.BackupAgent#onCreate()} method, create a {@link
android.app.backup.BackupHelper}. These helpers are
specialized classes for backing up certain kinds of data. The Android framework
currently includes two such helpers: {@link
android.app.backup.FileBackupHelper} and {@link
android.app.backup.SharedPreferencesBackupHelper}. After you create the helper
and point it at the data you want to back up, just add it to the
BackupAgentHelper using the {@link android.app.backup.BackupAgentHelper#addHelper(String, BackupHelper) addHelper()}
method, adding a key which is used to
retrieve the data later. In most cases the entire
implementation is perhaps 10 lines of code.</p>
<p>Here's an example that backs up a high scores file.</p>
<pre>
import android.app.backup.BackupAgentHelper;
import android.app.backup.FileBackupHelper;
public class TheBackupAgent extends BackupAgentHelper {
// The name of the SharedPreferences file
static final String HIGH_SCORES_FILENAME = "scores";
// A key to uniquely identify the set of backup data
static final String FILES_BACKUP_KEY = "myfiles";
// Allocate a helper and add it to the backup agent
&#64;Override
void onCreate() {
FileBackupHelper helper = new FileBackupHelper(this, HIGH_SCORES_FILENAME);
addHelper(FILES_BACKUP_KEY, helper);
}
}
</pre>
<p>For added flexibility, {@link android.app.backup.FileBackupHelper}'s
constructor can take a variable number of filenames. You could just as easily
have backed up both a high scores file and a game progress file just by adding
an extra parameter, like this:</p>
<pre>
&#64;Override
void onCreate() {
FileBackupHelper helper = new FileBackupHelper(this, HIGH_SCORES_FILENAME, PROGRESS_FILENAME);
addHelper(FILES_BACKUP_KEY, helper);
}
</pre>
<p>Backing up preferences is similarly easy. Create a {@link
android.app.backup.SharedPreferencesBackupHelper} the same way you did a {@link
android.app.backup.FileBackupHelper}. In this case, instead of adding filenames
to the constructor, add the names of the shared preference groups being used by
your application. Here's an example of how your backup agent helper might look if
high scores are implemented as preferences instead of a flat file:</p>
<pre>
import android.app.backup.BackupAgentHelper;
import android.app.backup.SharedPreferencesBackupHelper;
public class TheBackupAgent extends BackupAgentHelper {
// The names of the SharedPreferences groups that the application maintains. These
// are the same strings that are passed to getSharedPreferences(String, int).
static final String PREFS_DISPLAY = "displayprefs";
static final String PREFS_SCORES = "highscores";
// An arbitrary string used within the BackupAgentHelper implementation to
// identify the SharedPreferencesBackupHelper's data.
static final String MY_PREFS_BACKUP_KEY = "myprefs";
// Simply allocate a helper and install it
void onCreate() {
SharedPreferencesBackupHelper helper =
new SharedPreferencesBackupHelper(this, PREFS_DISPLAY, PREFS_SCORES);
addHelper(MY_PREFS_BACKUP_KEY, helper);
}
}
</pre>
<p>You can add as many backup helper instances to your backup agent helper as you
like, but remember that you only need one of each type. One {@link
android.app.backup.FileBackupHelper} handles all the files that you need to back up, and one
{@link android.app.backup.SharedPreferencesBackupHelper} handles all the shared
preferencegroups you need backed up.
</p>
<h2 id="backup">Request a Backup</h2>
<p>In order to request a backup, just create an instance of the {@link
android.app.backup.BackupManager}, and call it's {@link
android.app.backup.BackupManager#dataChanged()} method.</p>
<pre>
import android.app.backup.BackupManager;
...
public void requestBackup() {
BackupManager bm = new BackupManager(this);
bm.dataChanged();
}
</pre>
<p>This call notifies the backup manager that there is data ready to be backed
up to the cloud. At some point in the future, the backup manager then calls
your backup agent's {@link
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor, BackupDataOutput,
ParcelFileDescriptor) onBackup()} method. You can make
the call whenever your data has changed, without having to worry about causing
excessive network activity. If you request a backup twice before a backup
occurs, the backup only occurs once.</p>
<h2 id="restore">Restore from a Backup</h2>
<p>Typically you shouldn't ever have to manually request a restore, as it
happens automatically when your application is installed on a device. However,
if it <em>is</em> necessary to trigger a manual restore, just call the
{@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method.</p>

47
docs/html/training/backup/index.jd
View File

@@ -1,47 +0,0 @@
page.title=Backing up App Data to the Cloud
page.tags=cloud,sync,backup
trainingnavtop=true
startpage=true
@jd:body
<div id="tb-wrapper">
<div id="tb">
<h2>Dependencies and prerequisites</h2>
<ul>
<li>Android 2.2 (API level 8) and higher</li>
</ul>
</div>
</div>
<p>Users often invest significant time and effort creating data and setting
preferences within apps. Preserving that data for users if they replace a broken
device or upgrade to a new one is an important part of ensuring a great user
experience.</p>
<p>This class covers techniques for backing up data to the cloud so that
users can restore their data when recovering from a data loss (such as a factory
reset) or installing your application on a new device.</p>
<p>It is important to note that the API for cloud backup changed with the
release of Android 6.0 (API level 23). For your app to support backup both
on devices running Android 6.0, and those running Android 5.1 (API level
22) and lower, you must implement both techniques that this class explains.</p>
<h2>Lessons</h2>
<dl>
<dt><strong><a href="autosyncapi.html">Configuring Auto Backup for Apps</a></strong></dt>
<dd>This lesson applies to Android 6.0 (API level 23) and higher. Learn how to accomplish
seamless app data backup and restore with zero additional lines of application code.</dd>
</dl>
<dl>
<dt><strong><a href="backupapi.html">Using the Backup API</a></strong></dt>
<dd>This lesson applies to Android 5.1 (API level 22) and lower. Learn how to integrate the Backup
API into your Android app, so all of that app's user data, such as preferences, notes, and high
scores, updates seamlessly across all devices linked to that Google account.</dd>
</dl>

18
docs/html/training/training_toc.cs
View File

@@ -649,25 +649,7 @@
</li>
</ul>
</li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>training/backup/index.html"
description=
"How to sync and back up app and user data to remote web services in the
cloud and how to restore the data back to multiple devices."
>Backing up App Data to the Cloud</a>
</div>
<ul>
<li><a href="<?cs var:toroot ?>training/backup/autosyncapi.html">
Configuring Auto Backup
</a>
</li>
<li><a href="<?cs var:toroot ?>training/backup/backupapi.html">
Using the Backup API
</a>
</li>
</ul>
<li><a href="<?cs var:toroot ?>training/cloudsave/conflict-res.html"
description=
"How to design a robust conflict resolution strategy for apps that save data to the cloud."