| page.title=bmgr |
| @jd:body |
| |
| <!-- quickview box content here --> |
| |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>bmgr quickview</h2> |
| <p><code>bmgr</code> lets you inspect and control the backup/restore system on an Android device. |
| |
| <h2>In this document</h2> |
| <ol> |
| <li><a href="#transports">About backup transports</a></li> |
| <li><a href="#restoresets">About restore sets</a></li> |
| <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> |
| |
| </div> |
| </div> |
| |
| <!-- normal page content here --> |
| |
| <p><code>bmgr</code> is a shell tool that developers can use to interact with the Backup Manager |
| on Android devices supporting API version 8 or later. It provides commands for inducing backup |
| and restore operations on demand so that you do not need to repeatedly wipe data or take similar |
| intrusive steps to test the operation of an application's backup agent. These commands are |
| accessed via the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> shell. |
| |
| <p>There are a couple of basic concepts used by the Backup Manager that are built into the way |
| that <code>bmgr</code> operates. These are <a href="#transports">backup transports</a> and |
| <a href="#restoresets">restore sets</a>. |
| |
| |
| <a name="transports"></a> |
| <h2>About backup transports</h2> |
| |
| <p>A <em>backup transport</em> 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>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>adb shell bmgr transport NAME</pre> |
| |
| <p>where <code>NAME</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. |
| |
| |
| <a name="restoresets"></a> |
| <h2>About restore sets</h2> |
| |
| <p>All of the application data that a device has written to a given backup transport is tracked |
| together, and is collectively sometimes called a <em>restore set,</em> because the typical use |
| of the data set is during restore operations. Each time a device is initially provisioned, a |
| new data set is established. The user can get a listing of all the data sets that can be |
| restored through the current transport by running this shell command: |
| |
| <pre>adb shell bmgr list sets</pre> |
| |
| <p>The output is listing of available restore sets, one per line. The first item on each line is |
| a <em>token,</em> a number in hexadecimal that identifies the restore set to the transport. After |
| that is a string that may provide some brief identifying information about the restore set. Only |
| the token is actually used within the backup and restore mechanism. |
| |
| |
| <a name="backup"></a> |
| <h2>Forcing a backup operation</h2> |
| |
| <p>Normally, applications notify the backup manager directly that their data has changed, in |
| response to which the backup manager will make sure to invoke that application's agent when the |
| next backup operation is run. You can simulate this manually from the command line if you wish, |
| by running this shell command: |
| |
| <pre>adb shell bmgr backup PACKAGE</pre> |
| |
| <p><code>PACKAGE</code> is the formal package name of the application you wish to schedule for |
| backup. At this point you know that the application's agent will be invoked for backup at some |
| point in the future, though there is no hard guarantee of when that will occur. You can force |
| all pending backup operations to run immediately by using the following command: |
| |
| <pre>adb shell bmgr run</pre> |
| |
| <p>This causes a backup pass to execute immediately, invoking the agents of all applications that |
| had called <code>BackupManager.dataChanged()</code> since the time of the last backup operation, |
| plus any applications which had been manually scheduled for backup via |
| <code>bmgr backup PACKAGE</code>. |
| |
| |
| <a name="restore"></a> |
| <h2>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 restores an entire device with the data from a given restore set. This |
| is typically only performed when a device is first provisioned, to replicate settings and other |
| such saved state from the user's previous device. The second kind of restore operation restores |
| a single application from the <em>active</em> data set; that is, from the data set currently |
| being written to by backup operations. This second form is available as part of the public API. |
| It allows applications to abandon their current data and revert to the last-known-good data as |
| represented in their current backup image. |
| |
| <p>A full-system restore operation can be initiated with this shell command: |
| |
| <pre>adb shell bmgr restore TOKEN</pre> |
| |
| <p>where <code>TOKEN</code> is the desired restore set's token as printed out by the <code>bmgr |
| list sets</code> command. <strong>Warning!</strong> This operation will <em>replace</em> the |
| data of all backup-enabled applications with the contents of the given restore set. Be careful, |
| and be aware of the potential consequences. |
| |
| <p>A single-application restore operation does not reference a restore set token; it always uses |
| the data from the currently active data set. You can induce such an operation from the command |
| line like this: |
| |
| <pre>adb shell bmgr restore PACKAGE</pre> |
| |
| <p><code>PACKAGE</code> is the formal package name of an application that is participating in the |
| backup/restore mechanism. The backup manager will immediately instantiate the application's |
| agent and invoke it for restore. |
| |
| <a name="other"></a> |
| <h2>Other commands</h2> |
| |
| <p>The data for a single application can be erased from the active data set on demand. This is |
| very useful during development of backup agents, in case bugs lead you to write corrupt data |
| or saved state information. The shell command for wiping an application's data is this: |
| |
| <pre>adb shell bmgr wipe PACKAGE</pre> |
| |
| <p><code>PACKAGE</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. |
| |
| <p>You can see whether the backup manager is operational at all by running this command: |
| |
| <pre>adb shell bmgr enabled</pre> |
| |
| <p>This might be useful if your application's agent is never being invoked for backup, to verify |
| whether the operating system thinks it should be performing such operations at all. You can also |
| directly disable or enable the backup manager with this command: |
| |
| <pre>adb shell bmgr enable BOOLEAN</pre> |
| |
| <p>where <code>BOOLEAN</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. |
| <strong>Warning!</strong> When backup is disabled, the current transport will explicitly wipe |
| the entire active data set from its backend storage. This is so that when a user says that no, |
| they do not 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). |
| |