| page.title=bmgr |
| parent.title=Tools |
| parent.link=index.html |
| @jd:body |
| |
| <!-- quickview box content here --> |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#backup">Forcing a Backup Operation</a></li> |
| <li><a href="#restore">Forcing a Restore Operation</a></li> |
| <li><a href="#other">Other Commands</a></li> |
| </ol> |
| |
| <h2>See also</h2> |
| <ol> |
| <li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li> |
| </ol> |
| |
| </div> |
| </div> |
| |
| <!-- normal page content here --> |
| |
| <p><code>bmgr</code> is a shell tool you can use to interact with the Backup Manager |
| on Android devices supporting API Level 8 or greater. It provides commands to induce backup |
| and restore operations so that you don't need to repeatedly wipe data or take similar |
| intrusive steps in order to test your application's backup agent. These commands are |
| accessed via the <a href="{@docRoot}tools/help/adb.html">adb</a> shell. |
| |
| <p>For information about adding support for backup in your application, read <a |
| href="{@docRoot}guide/topics/data/backup.html">Data Backup</a>, which includes a guide to testing |
| your application using {@code bmgr}.</p> |
| |
| |
| <h2 id="backup">Forcing a Backup Operation</h2> |
| |
| <p>Normally, your application must notify the Backup Manager when its data has changed, via {@link |
| android.app.backup.BackupManager#dataChanged()}. The Backup Manager will then invoke your |
| backup agent's {@link |
| android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) |
| onBackup()} implementation at some time in the future. However, instead of calling {@link |
| android.app.backup.BackupManager#dataChanged()}, you can invoke a backup request from the command |
| line by running the <code>bmgr backup</code> command: |
| |
| <pre class="no-pretty-print">adb shell bmgr backup <em><package></em></pre> |
| |
| <p><code><em><package></em></code> is the formal package name of the application you wish to |
| schedule for |
| backup. When you execute this backup command, your application's backup agent will be invoked to |
| perform a backup operation at some time in the future (via your {@link |
| android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) |
| onBackup()} method), though there is no guarantee when it will occur. However, you can force all |
| pending backup operations to run immediately by using the <code>bmgr run</code> command: |
| |
| <pre class="no-pretty-print">adb shell bmgr run</pre> |
| |
| <p>This causes a backup pass to execute immediately, invoking the backup agents of all applications |
| that had previously called {@link android.app.backup.BackupManager#dataChanged()} since the |
| last backup operation, plus any applications which had been manually scheduled for |
| backup via <code>bmgr backup</code>. |
| |
| |
| |
| <h2 id="restore">Forcing a Restore Operation</h2> |
| |
| <p>Unlike backup operations, which are batched together and run on an occasional basis, restore |
| operations execute immediately. The Backup Manager currently provides two kinds of restore |
| operations. The first kind restores an entire device with the data that has been backed up. This |
| is typically performed only when a device is first provisioned (to replicate settings and other |
| saved state from the user's previous device) and is an operation that only the system can |
| perform. The second kind of restore operation restores |
| a single application to its "active" data set; that is, the application will abandon its current |
| data and revert to the last-known-good data that is held in the current backup image. You can |
| invoke this second restore operation with the {@link |
| android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method. The |
| Backup Manager will then invoke your backup agent's {@link |
| android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) |
| onRestore()} implementation. |
| |
| <p>While testing your application, you can immediately invoke the restore operation (bypassing the |
| {@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method) |
| for your application by using the <code>bmgr restore</code> command: |
| |
| <pre class="no-pretty-print">adb shell bmgr restore <em><package></em></pre> |
| |
| <p><code><em><package></em></code> is the formal Java-style package name of the application |
| participating in the backup/restore mechanism, which you would like to restore. The Backup |
| Manager will immediately instantiate the application's backup agent and invoke it for restore. This |
| will happen even if your application is not currently running. |
| |
| |
| |
| |
| |
| <h2 id="other">Other Commands</h2> |
| |
| <h3>Wiping data</h3> |
| |
| <p>The data for a single application can be erased from the active data set on demand. This is |
| very useful while you're developing a backup agent, in case bugs lead you to write corrupt data |
| or saved state information. You can wipe an application's data with the <code>bmgr wipe</code> |
| command: |
| |
| <pre class="no-pretty-print">adb shell bmgr wipe <em><package></em></pre> |
| |
| <p><code><em><package></em></code> is the formal package name of the application whose data |
| you wish to |
| erase. The next backup operation that the application's agent processes will look as |
| though the application had never backed anything up before. |
| |
| |
| <h3>Enabling and disabling backup</h3> |
| |
| <p>You can see whether the Backup Manager is operational at all with the <code>bmgr |
| enabled</code> command: |
| |
| <pre class="no-pretty-print">adb shell bmgr enabled</pre> |
| |
| <p>This might be useful if your application's backup agent is never being invoked for backup, to |
| verify whether the operating system thinks it should be performing such operations at all.</p> |
| |
| <p>You can also directly disable or enable the Backup Manager with this command: |
| |
| <pre class="no-pretty-print">adb shell bmgr enable <em><boolean></em></pre> |
| |
| <p><code><em><boolean></em></code> is either <code>true</code> or <code>false</code>. |
| This is equivalent to disabling or enabling backup in the device's main Settings UI.</p> |
| |
| <p class="warning"><strong>Warning!</strong> When backup is disabled, the current backup transport |
| will explicitly wipe |
| the entire active data set from its backend storage. This is so that when a user says |
| they do <em>not</em> want their data backed up, the Backup Manager respects that wish. No further |
| data will be saved from the device, and no restore operations will be possible, unless the Backup |
| Manager is re-enabled (either through Settings or through the above <code>bmgr</code> command). |
| |
| |
| |
| |
| <!-- The following is not useful to applications, but may be some useful information some day... |
| |
| |
| <h2 id="transports">Applying a Backup Transport</h2> |
| |
| <p>A "backup transport" is the code module responsible for moving backup and restore data |
| to and from some storage location. A device can have multipe transports installed, though only |
| one is active at any given time. Transports are identified by name. You can see what |
| transports are available on your device or emulator by running the |
| <code>bmgr list transports</code> command: |
| |
| <pre class="no-pretty-print">adb shell bmgr list transports</pre> |
| |
| <p>The output of this command is a list of the transports available on the device. The currently |
| active transport is flagged with a <code>*</code> character. Transport names may look like |
| component names (for example, <code>android/com.android.internal.backup.LocalTransport</code>), |
| but they need not be, and the strings are never used as direct class references. The use of |
| a component-like naming scheme is simply for purposes of preventing name collisions. |
| |
| <p>You can change which transport is currently active from the command line as well: |
| |
| <pre class="no-pretty-print">adb shell bmgr transport <em><name></em></pre> |
| |
| <p><code><em><name></em></code> is one of the names as printed by the <code>bmgr list |
| transports</code> |
| command. From this point forward, backup and restore operations will be directed through the |
| newly-selected transport. Backup state tracking is managed separately for each transport, so |
| switching back and forth between them will not corrupt the saved state. |
| |
| |
| |
| |
| <h2 id="restoresets">Viewing Restore Sets</h2> |
| |
| <p>All of the application data that a device has written to its backup transport is tracked |
| as a group that is collectively called a "restore set," because each data set is |
| most often manipulated during a restore operation. When a device is provisioned for the first |
| time, a new restore set is established. You can get a listing of all the restore sets available to |
| the current transport by running the <code>bmgr list sets</code> command: |
| |
| <pre class="no-pretty-print">adb shell bmgr list sets</pre> |
| |
| <p>The output is a listing of available restore sets, one per line. The first item on each line is |
| a token (a hexadecimal value that identifies the restore set to the transport). Following |
| the token is a string that briefly identifies the restore set. |
| Only the token is used within the backup and restore mechanism. |
| |
| |
| --> |