Merge "Import translations. DO NOT MERGE" into nyc-mr1-dev
diff --git a/core/java/android/app/IntentService.java b/core/java/android/app/IntentService.java
index f33af39..e4a22c4 100644
--- a/core/java/android/app/IntentService.java
+++ b/core/java/android/app/IntentService.java
@@ -46,7 +46,8 @@
* <div class="special reference">
* <h3>Developer Guides</h3>
* <p>For a detailed discussion about how to create services, read the
- * <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer guide.</p>
+ * <a href="{@docRoot}guide/components/services.html">Services</a> developer
+ * guide.</p>
* </div>
*
* @see android.os.AsyncTask
diff --git a/core/java/android/hardware/usb/UsbDeviceConnection.java b/core/java/android/hardware/usb/UsbDeviceConnection.java
index c062b3a..893b954 100644
--- a/core/java/android/hardware/usb/UsbDeviceConnection.java
+++ b/core/java/android/hardware/usb/UsbDeviceConnection.java
@@ -16,8 +16,10 @@
package android.hardware.usb;
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+import android.content.Context;
import android.os.ParcelFileDescriptor;
-
import java.io.FileDescriptor;
@@ -31,6 +33,8 @@
private final UsbDevice mDevice;
+ private Context mContext;
+
// used by the JNI code
private long mNativeContext;
@@ -42,11 +46,22 @@
mDevice = device;
}
- /* package */ boolean open(String name, ParcelFileDescriptor pfd) {
+ /* package */ boolean open(String name, ParcelFileDescriptor pfd, @NonNull Context context) {
+ mContext = context.getApplicationContext();
+
return native_open(name, pfd.getFileDescriptor());
}
/**
+ * @return The application context the connection was created for.
+ *
+ * @hide
+ */
+ public @Nullable Context getContext() {
+ return mContext;
+ }
+
+ /**
* Releases all system resources related to the device.
* Once the object is closed it cannot be used again.
* The client must call {@link UsbManager#openDevice} again
diff --git a/core/java/android/hardware/usb/UsbManager.java b/core/java/android/hardware/usb/UsbManager.java
index 629db06..cb2720a 100644
--- a/core/java/android/hardware/usb/UsbManager.java
+++ b/core/java/android/hardware/usb/UsbManager.java
@@ -330,7 +330,7 @@
ParcelFileDescriptor pfd = mService.openDevice(deviceName);
if (pfd != null) {
UsbDeviceConnection connection = new UsbDeviceConnection(device);
- boolean result = connection.open(deviceName, pfd);
+ boolean result = connection.open(deviceName, pfd, mContext);
pfd.close();
if (result) {
return connection;
diff --git a/core/java/android/os/IRecoverySystem.aidl b/core/java/android/os/IRecoverySystem.aidl
index 12830a4..c5ceecd 100644
--- a/core/java/android/os/IRecoverySystem.aidl
+++ b/core/java/android/os/IRecoverySystem.aidl
@@ -25,4 +25,5 @@
boolean uncrypt(in String packageFile, IRecoverySystemProgressListener listener);
boolean setupBcb(in String command);
boolean clearBcb();
+ void rebootRecoveryWithCommand(in String command);
}
diff --git a/core/java/android/os/RecoverySystem.java b/core/java/android/os/RecoverySystem.java
index 0b3abaa..d48431a 100644
--- a/core/java/android/os/RecoverySystem.java
+++ b/core/java/android/os/RecoverySystem.java
@@ -700,28 +700,22 @@
* @throws IOException if something goes wrong.
*/
private static void bootCommand(Context context, String... args) throws IOException {
- synchronized (sRequestLock) {
- LOG_FILE.delete();
+ LOG_FILE.delete();
- StringBuilder command = new StringBuilder();
- for (String arg : args) {
- if (!TextUtils.isEmpty(arg)) {
- command.append(arg);
- command.append("\n");
- }
+ StringBuilder command = new StringBuilder();
+ for (String arg : args) {
+ if (!TextUtils.isEmpty(arg)) {
+ command.append(arg);
+ command.append("\n");
}
-
- // Write the command into BCB (bootloader control block).
- RecoverySystem rs = (RecoverySystem) context.getSystemService(
- Context.RECOVERY_SERVICE);
- rs.setupBcb(command.toString());
-
- // Having set up the BCB, go ahead and reboot.
- PowerManager pm = (PowerManager) context.getSystemService(Context.POWER_SERVICE);
- pm.reboot(PowerManager.REBOOT_RECOVERY);
-
- throw new IOException("Reboot failed (no permissions?)");
}
+
+ // Write the command into BCB (bootloader control block) and boot from
+ // there. Will not return unless failed.
+ RecoverySystem rs = (RecoverySystem) context.getSystemService(Context.RECOVERY_SERVICE);
+ rs.rebootRecoveryWithCommand(command.toString());
+
+ throw new IOException("Reboot failed (no permissions?)");
}
// Read last_install; then report time (in seconds) and I/O (in MiB) for
@@ -916,6 +910,17 @@
}
/**
+ * Talks to RecoverySystemService via Binder to set up the BCB command and
+ * reboot into recovery accordingly.
+ */
+ private void rebootRecoveryWithCommand(String command) {
+ try {
+ mService.rebootRecoveryWithCommand(command);
+ } catch (RemoteException ignored) {
+ }
+ }
+
+ /**
* Internally, recovery treats each line of the command file as a separate
* argv, so we only need to protect against newlines and nulls.
*/
diff --git a/core/java/android/view/SurfaceView.java b/core/java/android/view/SurfaceView.java
index 754cdd8..4b9a570 100644
--- a/core/java/android/view/SurfaceView.java
+++ b/core/java/android/view/SurfaceView.java
@@ -598,7 +598,9 @@
// surfaceDestroyed and surfaceCreated, we force a disconnect,
// so the next connect will always work if we end up reusing
// the surface.
- mSurface.forceScopedDisconnect();
+ if (mSurface.isValid()) {
+ mSurface.forceScopedDisconnect();
+ }
}
}
diff --git a/core/res/res/values/strings.xml b/core/res/res/values/strings.xml
index 26d24bc..f42c9ed 100644
--- a/core/res/res/values/strings.xml
+++ b/core/res/res/values/strings.xml
@@ -3553,7 +3553,7 @@
<!-- Button text for the edit menu in input method extract mode. [CHAR LIMIT=16] -->
<string name="extract_edit_menu_button">Edit</string>
- <!-- Notification title when data usage has exceeded warning threshold. [CHAR LIMIT=32] -->
+ <!-- Notification title when data usage has exceeded warning threshold. [CHAR LIMIT=50] -->
<string name="data_usage_warning_title">Data usage alert</string>
<!-- Notification body when data usage has exceeded warning threshold. [CHAR LIMIT=32] -->
<string name="data_usage_warning_body">Tap to view usage and settings.</string>
diff --git a/docs/html/_redirects.yaml b/docs/html/_redirects.yaml
index 29a74a0..8cb2ee7 100644
--- a/docs/html/_redirects.yaml
+++ b/docs/html/_redirects.yaml
@@ -430,7 +430,13 @@
- 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 @@
- 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
diff --git a/docs/html/guide/_book.yaml b/docs/html/guide/_book.yaml
index 13c948c..f09fe77 100644
--- a/docs/html/guide/_book.yaml
+++ b/docs/html/guide/_book.yaml
@@ -396,6 +396,13 @@
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
diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs
index 9257a76..8fe3f20 100644
--- a/docs/html/guide/guide_toc.cs
+++ b/docs/html/guide/guide_toc.cs
@@ -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>
diff --git a/docs/html/guide/topics/data/autobackup.jd b/docs/html/guide/topics/data/autobackup.jd
new file mode 100644
index 0000000..3be09d7
--- /dev/null
+++ b/docs/html/guide/topics/data/autobackup.jd
@@ -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 & 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><application></code>
+element of your <code>AndroidManifest.xml</code>. For example:
+
+<pre class="prettyprint"><application ...
+ android:allowBackup="true">
+</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><application></code> element. This attribute points to an XML file that contains backup
+ rules. For example:
+ <pre class="prettyprint"><application ...
+ android:fullBackupContent="@xml/my_backup_rules">
+ </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><include></code> and <code><exclude></code> elements. The following sample backs up all shared preferences except <code>device.xml</code>:
+ <pre><?xml version="1.0" encoding="utf-8"?>
+<full-backup-content>
+ <include domain="sharedpref" path="."/>
+ <exclude domain="sharedpref" path="device.xml"/>
+</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"><full-backup-content>
+ <include domain=["file" | "database" | "sharedpref" | "external" | "root"]
+ path="string" />
+ <exclude domain=["file" | "database" | "sharedpref" | "external" | "root"]
+ path="string" />
+</full-backup-content></pre>
+
+<p>Inside the <code><full-backup-content></code> tag, you can define <code><include></code> and <code><exclude></code>
+elements:
+
+<ul>
+ <li><code><include></code> - Specifies a file or folder to backup. By default, Auto Backup
+includes almost all app files. If you specify an <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 <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><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><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><include></code> elements minus the
+resources named in the <code><exclude></code> elements. In other words,
+<code><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>.
\ No newline at end of file
diff --git a/docs/html/guide/topics/data/backup.jd b/docs/html/guide/topics/data/backup.jd
index 619c790..a688c6e 100644
--- a/docs/html/guide/topics/data/backup.jd
+++ b/docs/html/guide/topics/data/backup.jd
@@ -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
+<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.
-<div id="qv-wrapper">
-<div id="qv">
+<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>.
- <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>
+<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>
- <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—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—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>
-<manifest ... >
- ...
- <application android:label="MyApplication"
- <b>android:backupAgent="MyBackupAgent"</b>>
- <activity ... >
- ...
- </activity>
- </application>
-</manifest>
-</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>
-<application android:label="MyApplication"
- android:backupAgent="MyBackupAgent">
- ...
- <meta-data android:name="com.google.android.backup.api_key"
- android:value="AEdPqrEAAAAIDaYEVgU6DJnyJdBmU7KLH3kszDXLv_4DIsEIyQ" />
-</application>
-</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()}—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—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>
-@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
- @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
- @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>
-@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);
- }
-}
-
-@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 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>.
\ No newline at end of file
diff --git a/docs/html/guide/topics/data/images/backup-framework.png b/docs/html/guide/topics/data/images/backup-framework.png
new file mode 100644
index 0000000..2ba2e612
--- /dev/null
+++ b/docs/html/guide/topics/data/images/backup-framework.png
Binary files differ
diff --git a/docs/html/guide/topics/data/index.jd b/docs/html/guide/topics/data/index.jd
index 3872825..2365f18 100644
--- a/docs/html/guide/topics/data/index.jd
+++ b/docs/html/guide/topics/data/index.jd
@@ -5,21 +5,3 @@
@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>
diff --git a/docs/html/guide/topics/data/keyvaluebackup.jd b/docs/html/guide/topics/data/keyvaluebackup.jd
new file mode 100644
index 0000000..c7c5e2f
--- /dev/null
+++ b/docs/html/guide/topics/data/keyvaluebackup.jd
@@ -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>
+<manifest ... >
+ ...
+ <application android:label="MyApplication"
+ <b>android:backupAgent="MyBackupAgent"</b>>
+ <activity ... >
+ ...
+ </activity>
+ </application>
+</manifest>
+</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>
+<application android:label="MyApplication"
+ android:backupAgent="MyBackupAgent">
+ ...
+ <meta-data android:name="com.google.android.backup.api_key"
+ android:value="AEdPqrEAAAAIDaYEVgU6DJnyJdBmU7KLH3kszDXLv_4DIsEIyQ" />
+</application>
+</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()}—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—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>
+@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
+ @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
+ @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>
+@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);
+ }
+}
+
+@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><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.
\ No newline at end of file
diff --git a/docs/html/guide/topics/data/testingbackup.jd b/docs/html/guide/topics/data/testingbackup.jd
new file mode 100644
index 0000000..6ff5837
--- /dev/null
+++ b/docs/html/guide/topics/data/testingbackup.jd
@@ -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 & 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 <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 <PACKAGE>
+
+---- or ----
+
+V/BackupManagerService: Scheduling immediate backup pass
+D/PerformBackupTask: starting key/value Backup of BackupRequest{pkg=<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 <PACKAGE></code>
+ <li>For Key/Value Backups, schedule and run your backup with the following
+commands:
+ <pre class="prettyprint">$ bmgr backup <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 <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=<PACKAGE> transport=null
+V/RestoreSession: restorePackage pkg=<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 <PACKAGE>, skipping
+
+--- or ---
+
+I/PFTBT: Transport quota exceeded for package: <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.
\ No newline at end of file
diff --git a/docs/html/guide/topics/ui/accessibility/services.jd b/docs/html/guide/topics/ui/accessibility/services.jd
index c6db855..dbc69ef 100644
--- a/docs/html/guide/topics/ui/accessibility/services.jd
+++ b/docs/html/guide/topics/ui/accessibility/services.jd
@@ -79,22 +79,15 @@
as shown in the following sample:</p>
<pre>
-<manifest>
- ...
- <uses-permission ... />
- ...
<application>
- ...
<service android:name=".MyAccessibilityService"
- android:label="@string/accessibility_service_label"
- android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
+ android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"
+ android:label="@string/accessibility_service_label">
<intent-filter>
<action android:name="android.accessibilityservice.AccessibilityService" />
</intent-filter>
</service>
- <uses-permission android:name="android.permission.BIND_ACCESSIBILITY_SERVICE" />
</application>
-</manifest>
</pre>
<p>These declarations are required for all accessibility services deployed on Android 1.6 (API Level
diff --git a/docs/html/topic/performance/_book.yaml b/docs/html/topic/performance/_book.yaml
index ba7c8b5..4021e85 100644
--- a/docs/html/topic/performance/_book.yaml
+++ b/docs/html/topic/performance/_book.yaml
@@ -35,9 +35,9 @@
section:
- title: Reducing Overdraw
path: /topic/performance/rendering/overdraw.html
- - title: Optimizing View Hierarchies
+ - title: Performance and View Hierarchies
path: /topic/performance/rendering/optimizing-view-hierarchies.html
- - title: Using the Profile GPU Tool
+ - title: Analyzing with Profile GPU Rendering
path: /topic/performance/rendering/profile-gpu.html
- title: Intelligent Job-Scheduling
path: /topic/performance/scheduling.html
diff --git a/docs/html/topic/performance/rendering/index.jd b/docs/html/topic/performance/rendering/index.jd
index e04605c..1b16df0 100644
--- a/docs/html/topic/performance/rendering/index.jd
+++ b/docs/html/topic/performance/rendering/index.jd
@@ -38,8 +38,8 @@
</dd>
<dt>
- <strong><a href="profile-gpu.html">
- Optimizing View Hierarchies</a></strong>
+ <strong><a href="optimizing-view-hierarchies.html">
+ Performance and View Hierarchies</a></strong>
</dt>
<dd>
Make sure your layout and measurement are executing efficiently, and
@@ -49,7 +49,7 @@
<dt>
<strong><a href="profile-gpu.html">
- Using the Profile GPU Tool</a></strong>
+ Analyzing with Profile GPU Rendering</a></strong>
</dt>
<dd>
Take advantage of this on-device tool to identify bottlenecks that
diff --git a/docs/html/topic/performance/rendering/profile-gpu.jd b/docs/html/topic/performance/rendering/profile-gpu.jd
index 11c38e4..fc98777 100644
--- a/docs/html/topic/performance/rendering/profile-gpu.jd
+++ b/docs/html/topic/performance/rendering/profile-gpu.jd
@@ -1,4 +1,4 @@
-page.title=Analyzing Rendering with Profile GPU
+page.title=Analyzing with Profile GPU Rendering
page.metaDescription=Use the Profile GPU tool to help you optimize your app's rendering performance.
meta.tags="power"
diff --git a/docs/html/training/_book.yaml b/docs/html/training/_book.yaml
index fa50aa0..47862e2 100644
--- a/docs/html/training/_book.yaml
+++ b/docs/html/training/_book.yaml
@@ -438,16 +438,6 @@
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 @@
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
diff --git a/docs/html/training/backup/autosyncapi.jd b/docs/html/training/backup/autosyncapi.jd
deleted file mode 100644
index e0df7bb..0000000
--- a/docs/html/training/backup/autosyncapi.jd
+++ /dev/null
@@ -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>
-<?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
- xmlns:tools="http://schemas.android.com/tools"
- package="com.my.appexample">
- <uses-sdk android:minSdkVersion="23"/>
- <uses-sdk android:targetSdkVersion="23"/>
- <application ...
-<strong> android:fullBackupContent="@xml/mybackupscheme"></strong>
- </app>
- ...
-</manifest>
-</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>
-<?xml version="1.0" encoding="utf-8"?>
-<full-backup-content>
- <exclude domain="database" path="device_info.db"/>
-</full-backup-content>
-</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>
-<full-backup-content>
- <include domain=["file" | "database" | "sharedpref" | "external" | "root"]
- path="string" />
- <exclude domain=["file" | "database" | "sharedpref" | "external" | "root"]
- path="string" />
-</full-backup-content>
-</pre>
-
-<p>
- The following elements and attributes allow you to specify the files to include in, and exclude
- from, backup:
-</p>
-
-<ul>
- <li>
- <code><include></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><include></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><include></code> elements
- </li>
-
- <li>
- <code><exclude></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><include></code> and <code><exclude></code> elements,
- <code><exclude></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>
-<?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
- xmlns:tools="http://schemas.android.com/tools"
- package="com.my.appexample">
- <uses-sdk android:minSdkVersion="23"/>
- <uses-sdk android:targetSdkVersion="23"/>
- <application ...
-<strong> android:allowBackup="false"></strong>
- </application>
- ...
-</manifest>
-</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><PACKAGE></code> parameter to specify the package name for your app:
-</p>
-
-<pre class="no-pretty-print">
-$ adb shell bmgr fullbackup <PACKAGE></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><PACKAGE></code> parameter to specify the package name for your
- app:
-</p>
-
-<pre class="noprettyprint">
-$ adb shell bmgr restore <PACKAGE>
-</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 > Backup</strong>, factory-resetting the device, or
- executing this command:
-</p>
-
-<pre>$ adb shell bmgr wipe <TRANSPORT> <PACKAGE></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>
diff --git a/docs/html/training/backup/backupapi.jd b/docs/html/training/backup/backupapi.jd
deleted file mode 100644
index 2f3e939..0000000
--- a/docs/html/training/backup/backupapi.jd
+++ /dev/null
@@ -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>
-<meta-data android:name="com.google.android.backup.api_key"
-android:value="ABcDe1FGHij2KlmN3oPQRs4TUvW5xYZ" />
-</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>
-<application android:label="MyApp"
- android:backupAgent="TheBackupAgent">
- ...
- <meta-data android:name="com.google.android.backup.api_key"
- android:value="ABcDe1FGHij2KlmN3oPQRs4TUvW5xYZ" />
- ...
-</application>
-</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
- @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>
-@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>
diff --git a/docs/html/training/backup/index.jd b/docs/html/training/backup/index.jd
deleted file mode 100644
index 4449fde..0000000
--- a/docs/html/training/backup/index.jd
+++ /dev/null
@@ -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>
-
diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs
index 39ca6fb..d2bf881 100644
--- a/docs/html/training/training_toc.cs
+++ b/docs/html/training/training_toc.cs
@@ -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."
diff --git a/media/java/android/mtp/MtpDevice.java b/media/java/android/mtp/MtpDevice.java
index 4082778..e7ea1a5 100644
--- a/media/java/android/mtp/MtpDevice.java
+++ b/media/java/android/mtp/MtpDevice.java
@@ -18,11 +18,13 @@
import android.annotation.NonNull;
import android.annotation.Nullable;
+import android.content.Context;
import android.hardware.usb.UsbDevice;
import android.hardware.usb.UsbDeviceConnection;
import android.os.CancellationSignal;
import android.os.ParcelFileDescriptor;
+import android.os.UserManager;
import com.android.internal.util.Preconditions;
import java.io.IOException;
@@ -62,7 +64,17 @@
* @return true if the device was successfully opened.
*/
public boolean open(UsbDeviceConnection connection) {
- boolean result = native_open(mDevice.getDeviceName(), connection.getFileDescriptor());
+ boolean result = false;
+
+ Context context = connection.getContext();
+ if (context != null) {
+ UserManager userManager = (UserManager) context.getSystemService(Context.USER_SERVICE);
+
+ if (!userManager.hasUserRestriction(UserManager.DISALLOW_USB_FILE_TRANSFER)) {
+ result = native_open(mDevice.getDeviceName(), connection.getFileDescriptor());
+ }
+ }
+
if (!result) {
connection.close();
}
diff --git a/packages/SystemUI/res/values-my-rMM/strings.xml b/packages/SystemUI/res/values-my-rMM/strings.xml
index d01faee..c601fd1 100644
--- a/packages/SystemUI/res/values-my-rMM/strings.xml
+++ b/packages/SystemUI/res/values-my-rMM/strings.xml
@@ -588,7 +588,7 @@
<string name="center" msgid="4327473927066010960">"ဌာန"</string>
<string name="end" msgid="125797972524818282">"ပြီးပါပြီ"</string>
<string name="space" msgid="804232271282109749">"နေရာလွတ်ခြားစနစ်"</string>
- <string name="menu_ime" msgid="4943221416525250684">"မန်နယူး / ကီးဘုတ်ပြောင်းစနစ်"</string>
+ <string name="menu_ime" msgid="4943221416525250684">"မီနူး / ကီးဘုတ်ပြောင်းစနစ်"</string>
<string name="select_button" msgid="1597989540662710653">"ပေါင်းထည့်ရန် ခလုတ်ကိုရွေးပါ"</string>
<string name="add_button" msgid="4134946063432258161">"ခလုတ်ပေါင်းထည့်ပါ"</string>
<string name="save" msgid="2311877285724540644">"သိမ်းရန်"</string>
diff --git a/services/core/java/com/android/server/ConnectivityService.java b/services/core/java/com/android/server/ConnectivityService.java
index b7dfd19..c61a90b 100644
--- a/services/core/java/com/android/server/ConnectivityService.java
+++ b/services/core/java/com/android/server/ConnectivityService.java
@@ -816,7 +816,7 @@
mTestMode = SystemProperties.get("cm.test.mode").equals("true")
&& SystemProperties.get("ro.build.type").equals("eng");
- mTethering = new Tethering(mContext, mNetd, statsService);
+ mTethering = new Tethering(mContext, mNetd, statsService, mPolicyManager);
mPermissionMonitor = new PermissionMonitor(mContext, mNetd);
@@ -3036,12 +3036,6 @@
ConnectivityManager.enforceTetherChangePermission(mContext);
if (isTetheringSupported()) {
final int status = mTethering.tether(iface);
- if (status == ConnectivityManager.TETHER_ERROR_NO_ERROR) {
- try {
- mPolicyManager.onTetheringChanged(iface, true);
- } catch (RemoteException e) {
- }
- }
return status;
} else {
return ConnectivityManager.TETHER_ERROR_UNSUPPORTED;
@@ -3055,12 +3049,6 @@
if (isTetheringSupported()) {
final int status = mTethering.untether(iface);
- if (status == ConnectivityManager.TETHER_ERROR_NO_ERROR) {
- try {
- mPolicyManager.onTetheringChanged(iface, false);
- } catch (RemoteException e) {
- }
- }
return status;
} else {
return ConnectivityManager.TETHER_ERROR_UNSUPPORTED;
diff --git a/services/core/java/com/android/server/MountService.java b/services/core/java/com/android/server/MountService.java
index 0023e4b..8430a0b 100644
--- a/services/core/java/com/android/server/MountService.java
+++ b/services/core/java/com/android/server/MountService.java
@@ -1437,13 +1437,22 @@
* Decide if volume is mountable per device policies.
*/
private boolean isMountDisallowed(VolumeInfo vol) {
- if (vol.type == VolumeInfo.TYPE_PUBLIC || vol.type == VolumeInfo.TYPE_PRIVATE) {
- final UserManager userManager = mContext.getSystemService(UserManager.class);
- return userManager.hasUserRestriction(UserManager.DISALLOW_MOUNT_PHYSICAL_MEDIA,
+ UserManager userManager = mContext.getSystemService(UserManager.class);
+
+ boolean isUsbRestricted = false;
+ if (vol.disk != null && vol.disk.isUsb()) {
+ isUsbRestricted = userManager.hasUserRestriction(UserManager.DISALLOW_USB_FILE_TRANSFER,
Binder.getCallingUserHandle());
- } else {
- return false;
}
+
+ boolean isTypeRestricted = false;
+ if (vol.type == VolumeInfo.TYPE_PUBLIC || vol.type == VolumeInfo.TYPE_PRIVATE) {
+ isTypeRestricted = userManager
+ .hasUserRestriction(UserManager.DISALLOW_MOUNT_PHYSICAL_MEDIA,
+ Binder.getCallingUserHandle());
+ }
+
+ return isUsbRestricted || isTypeRestricted;
}
private void enforceAdminUser() {
diff --git a/services/core/java/com/android/server/RecoverySystemService.java b/services/core/java/com/android/server/RecoverySystemService.java
index 276687f..3c8c699 100644
--- a/services/core/java/com/android/server/RecoverySystemService.java
+++ b/services/core/java/com/android/server/RecoverySystemService.java
@@ -21,6 +21,7 @@
import android.net.LocalSocketAddress;
import android.os.IRecoverySystem;
import android.os.IRecoverySystemProgressListener;
+import android.os.PowerManager;
import android.os.RecoverySystem;
import android.os.RemoteException;
import android.os.SystemProperties;
@@ -50,8 +51,15 @@
// The socket at /dev/socket/uncrypt to communicate with uncrypt.
private static final String UNCRYPT_SOCKET = "uncrypt";
+ // The init services that communicate with /system/bin/uncrypt.
+ private static final String INIT_SERVICE_UNCRYPT = "init.svc.uncrypt";
+ private static final String INIT_SERVICE_SETUP_BCB = "init.svc.setup-bcb";
+ private static final String INIT_SERVICE_CLEAR_BCB = "init.svc.clear-bcb";
+
private static final int SOCKET_CONNECTION_MAX_RETRY = 30;
+ private static final Object sRequestLock = new Object();
+
private Context mContext;
public RecoverySystemService(Context context) {
@@ -69,95 +77,155 @@
public boolean uncrypt(String filename, IRecoverySystemProgressListener listener) {
if (DEBUG) Slog.d(TAG, "uncrypt: " + filename);
- mContext.enforceCallingOrSelfPermission(android.Manifest.permission.RECOVERY, null);
+ synchronized (sRequestLock) {
+ mContext.enforceCallingOrSelfPermission(android.Manifest.permission.RECOVERY, null);
- // Write the filename into UNCRYPT_PACKAGE_FILE to be read by
- // uncrypt.
- RecoverySystem.UNCRYPT_PACKAGE_FILE.delete();
-
- try (FileWriter uncryptFile = new FileWriter(RecoverySystem.UNCRYPT_PACKAGE_FILE)) {
- uncryptFile.write(filename + "\n");
- } catch (IOException e) {
- Slog.e(TAG, "IOException when writing \"" + RecoverySystem.UNCRYPT_PACKAGE_FILE +
- "\": ", e);
- return false;
- }
-
- // Trigger uncrypt via init.
- SystemProperties.set("ctl.start", "uncrypt");
-
- // Connect to the uncrypt service socket.
- LocalSocket socket = connectService();
- if (socket == null) {
- Slog.e(TAG, "Failed to connect to uncrypt socket");
- return false;
- }
-
- // Read the status from the socket.
- DataInputStream dis = null;
- DataOutputStream dos = null;
- try {
- dis = new DataInputStream(socket.getInputStream());
- dos = new DataOutputStream(socket.getOutputStream());
- int lastStatus = Integer.MIN_VALUE;
- while (true) {
- int status = dis.readInt();
- // Avoid flooding the log with the same message.
- if (status == lastStatus && lastStatus != Integer.MIN_VALUE) {
- continue;
- }
- lastStatus = status;
-
- if (status >= 0 && status <= 100) {
- // Update status
- Slog.i(TAG, "uncrypt read status: " + status);
- if (listener != null) {
- try {
- listener.onProgress(status);
- } catch (RemoteException ignored) {
- Slog.w(TAG, "RemoteException when posting progress");
- }
- }
- if (status == 100) {
- Slog.i(TAG, "uncrypt successfully finished.");
- // Ack receipt of the final status code. uncrypt
- // waits for the ack so the socket won't be
- // destroyed before we receive the code.
- dos.writeInt(0);
- break;
- }
- } else {
- // Error in /system/bin/uncrypt.
- Slog.e(TAG, "uncrypt failed with status: " + status);
- // Ack receipt of the final status code. uncrypt waits
- // for the ack so the socket won't be destroyed before
- // we receive the code.
- dos.writeInt(0);
- return false;
- }
+ final boolean available = checkAndWaitForUncryptService();
+ if (!available) {
+ Slog.e(TAG, "uncrypt service is unavailable.");
+ return false;
}
- } catch (IOException e) {
- Slog.e(TAG, "IOException when reading status: ", e);
- return false;
- } finally {
- IoUtils.closeQuietly(dis);
- IoUtils.closeQuietly(dos);
- IoUtils.closeQuietly(socket);
- }
- return true;
+ // Write the filename into UNCRYPT_PACKAGE_FILE to be read by
+ // uncrypt.
+ RecoverySystem.UNCRYPT_PACKAGE_FILE.delete();
+
+ try (FileWriter uncryptFile = new FileWriter(RecoverySystem.UNCRYPT_PACKAGE_FILE)) {
+ uncryptFile.write(filename + "\n");
+ } catch (IOException e) {
+ Slog.e(TAG, "IOException when writing \"" +
+ RecoverySystem.UNCRYPT_PACKAGE_FILE + "\":", e);
+ return false;
+ }
+
+ // Trigger uncrypt via init.
+ SystemProperties.set("ctl.start", "uncrypt");
+
+ // Connect to the uncrypt service socket.
+ LocalSocket socket = connectService();
+ if (socket == null) {
+ Slog.e(TAG, "Failed to connect to uncrypt socket");
+ return false;
+ }
+
+ // Read the status from the socket.
+ DataInputStream dis = null;
+ DataOutputStream dos = null;
+ try {
+ dis = new DataInputStream(socket.getInputStream());
+ dos = new DataOutputStream(socket.getOutputStream());
+ int lastStatus = Integer.MIN_VALUE;
+ while (true) {
+ int status = dis.readInt();
+ // Avoid flooding the log with the same message.
+ if (status == lastStatus && lastStatus != Integer.MIN_VALUE) {
+ continue;
+ }
+ lastStatus = status;
+
+ if (status >= 0 && status <= 100) {
+ // Update status
+ Slog.i(TAG, "uncrypt read status: " + status);
+ if (listener != null) {
+ try {
+ listener.onProgress(status);
+ } catch (RemoteException ignored) {
+ Slog.w(TAG, "RemoteException when posting progress");
+ }
+ }
+ if (status == 100) {
+ Slog.i(TAG, "uncrypt successfully finished.");
+ // Ack receipt of the final status code. uncrypt
+ // waits for the ack so the socket won't be
+ // destroyed before we receive the code.
+ dos.writeInt(0);
+ break;
+ }
+ } else {
+ // Error in /system/bin/uncrypt.
+ Slog.e(TAG, "uncrypt failed with status: " + status);
+ // Ack receipt of the final status code. uncrypt waits
+ // for the ack so the socket won't be destroyed before
+ // we receive the code.
+ dos.writeInt(0);
+ return false;
+ }
+ }
+ } catch (IOException e) {
+ Slog.e(TAG, "IOException when reading status: ", e);
+ return false;
+ } finally {
+ IoUtils.closeQuietly(dis);
+ IoUtils.closeQuietly(dos);
+ IoUtils.closeQuietly(socket);
+ }
+
+ return true;
+ }
}
@Override // Binder call
public boolean clearBcb() {
if (DEBUG) Slog.d(TAG, "clearBcb");
- return setupOrClearBcb(false, null);
+ synchronized (sRequestLock) {
+ return setupOrClearBcb(false, null);
+ }
}
@Override // Binder call
public boolean setupBcb(String command) {
if (DEBUG) Slog.d(TAG, "setupBcb: [" + command + "]");
- return setupOrClearBcb(true, command);
+ synchronized (sRequestLock) {
+ return setupOrClearBcb(true, command);
+ }
+ }
+
+ @Override // Binder call
+ public void rebootRecoveryWithCommand(String command) {
+ if (DEBUG) Slog.d(TAG, "rebootRecoveryWithCommand: [" + command + "]");
+ synchronized (sRequestLock) {
+ if (!setupOrClearBcb(true, command)) {
+ return;
+ }
+
+ // Having set up the BCB, go ahead and reboot.
+ PowerManager pm = (PowerManager) mContext.getSystemService(Context.POWER_SERVICE);
+ pm.reboot(PowerManager.REBOOT_RECOVERY);
+ }
+ }
+
+ /**
+ * Check if any of the init services is still running. If so, we cannot
+ * start a new uncrypt/setup-bcb/clear-bcb service right away; otherwise
+ * it may break the socket communication since init creates / deletes
+ * the socket (/dev/socket/uncrypt) on service start / exit.
+ */
+ private boolean checkAndWaitForUncryptService() {
+ for (int retry = 0; retry < SOCKET_CONNECTION_MAX_RETRY; retry++) {
+ final String uncryptService = SystemProperties.get(INIT_SERVICE_UNCRYPT);
+ final String setupBcbService = SystemProperties.get(INIT_SERVICE_SETUP_BCB);
+ final String clearBcbService = SystemProperties.get(INIT_SERVICE_CLEAR_BCB);
+ final boolean busy = "running".equals(uncryptService) ||
+ "running".equals(setupBcbService) || "running".equals(clearBcbService);
+ if (DEBUG) {
+ Slog.i(TAG, "retry: " + retry + " busy: " + busy +
+ " uncrypt: [" + uncryptService + "]" +
+ " setupBcb: [" + setupBcbService + "]" +
+ " clearBcb: [" + clearBcbService + "]");
+ }
+
+ if (!busy) {
+ return true;
+ }
+
+ try {
+ Thread.sleep(1000);
+ } catch (InterruptedException e) {
+ Slog.w(TAG, "Interrupted:", e);
+ }
+ }
+
+ return false;
}
private LocalSocket connectService() {
@@ -176,7 +244,7 @@
try {
Thread.sleep(1000);
} catch (InterruptedException e) {
- Slog.w(TAG, "Interrupted: ", e);
+ Slog.w(TAG, "Interrupted:", e);
}
}
}
@@ -190,6 +258,12 @@
private boolean setupOrClearBcb(boolean isSetup, String command) {
mContext.enforceCallingOrSelfPermission(android.Manifest.permission.RECOVERY, null);
+ final boolean available = checkAndWaitForUncryptService();
+ if (!available) {
+ Slog.e(TAG, "uncrypt service is unavailable.");
+ return false;
+ }
+
if (isSetup) {
SystemProperties.set("ctl.start", "setup-bcb");
} else {
@@ -232,7 +306,7 @@
return false;
}
} catch (IOException e) {
- Slog.e(TAG, "IOException when communicating with uncrypt: ", e);
+ Slog.e(TAG, "IOException when communicating with uncrypt:", e);
return false;
} finally {
IoUtils.closeQuietly(dis);
diff --git a/services/core/java/com/android/server/am/BroadcastQueue.java b/services/core/java/com/android/server/am/BroadcastQueue.java
index f78f29c..8b8e2c4 100644
--- a/services/core/java/com/android/server/am/BroadcastQueue.java
+++ b/services/core/java/com/android/server/am/BroadcastQueue.java
@@ -227,7 +227,8 @@
public final boolean replaceParallelBroadcastLocked(BroadcastRecord r) {
for (int i = mParallelBroadcasts.size() - 1; i >= 0; i--) {
- if (r.intent.filterEquals(mParallelBroadcasts.get(i).intent)) {
+ final Intent curIntent = mParallelBroadcasts.get(i).intent;
+ if (r.intent.filterEquals(curIntent)) {
if (DEBUG_BROADCAST) Slog.v(TAG_BROADCAST,
"***** DROPPING PARALLEL ["
+ mQueueName + "]: " + r.intent);
diff --git a/services/core/java/com/android/server/am/BroadcastRecord.java b/services/core/java/com/android/server/am/BroadcastRecord.java
index 3437ae6..1e7911a 100644
--- a/services/core/java/com/android/server/am/BroadcastRecord.java
+++ b/services/core/java/com/android/server/am/BroadcastRecord.java
@@ -219,6 +219,9 @@
int _resultCode, String _resultData, Bundle _resultExtras, boolean _serialized,
boolean _sticky, boolean _initialSticky,
int _userId) {
+ if (_intent == null) {
+ throw new NullPointerException("Can't construct with a null intent");
+ }
queue = _queue;
intent = _intent;
targetComp = _intent.getComponent();
diff --git a/services/core/java/com/android/server/connectivity/Tethering.java b/services/core/java/com/android/server/connectivity/Tethering.java
index 927f8f9..50faf3b 100644
--- a/services/core/java/com/android/server/connectivity/Tethering.java
+++ b/services/core/java/com/android/server/connectivity/Tethering.java
@@ -33,6 +33,7 @@
import android.hardware.usb.UsbManager;
import android.net.ConnectivityManager;
import android.net.ConnectivityManager.NetworkCallback;
+import android.net.INetworkPolicyManager;
import android.net.INetworkStatsService;
import android.net.LinkProperties;
import android.net.Network;
@@ -49,6 +50,7 @@
import android.os.Looper;
import android.os.Message;
import android.os.Parcel;
+import android.os.RemoteException;
import android.os.ResultReceiver;
import android.os.SystemProperties;
import android.os.UserHandle;
@@ -123,6 +125,7 @@
private final INetworkManagementService mNMService;
private final INetworkStatsService mStatsService;
+ private final INetworkPolicyManager mPolicyManager;
private final Looper mLooper;
private static class TetherState {
@@ -177,10 +180,11 @@
private boolean mWifiTetherRequested;
public Tethering(Context context, INetworkManagementService nmService,
- INetworkStatsService statsService) {
+ INetworkStatsService statsService, INetworkPolicyManager policyManager) {
mContext = context;
mNMService = nmService;
mStatsService = statsService;
+ mPolicyManager = policyManager;
mPublicSync = new Object();
@@ -622,12 +626,9 @@
}
public void untetherAll() {
- synchronized (mPublicSync) {
- if (DBG) Log.d(TAG, "Untethering " + mTetherStates.keySet());
- for (int i = 0; i < mTetherStates.size(); i++) {
- untether(mTetherStates.keyAt(i));
- }
- }
+ stopTethering(ConnectivityManager.TETHERING_WIFI);
+ stopTethering(ConnectivityManager.TETHERING_USB);
+ stopTethering(ConnectivityManager.TETHERING_BLUETOOTH);
}
public int getLastTetherError(String iface) {
@@ -1908,6 +1909,15 @@
" with error " + error);
}
+ try {
+ // Notify that we're tethering (or not) this interface.
+ // This is how data saver for instance knows if the user explicitly
+ // turned on tethering (thus keeping us from being in data saver mode).
+ mPolicyManager.onTetheringChanged(iface, state == IControlsTethering.STATE_TETHERED);
+ } catch (RemoteException e) {
+ // Not really very much we can do here.
+ }
+
switch (state) {
case IControlsTethering.STATE_UNAVAILABLE:
case IControlsTethering.STATE_AVAILABLE:
