docs/html/tools/help/bmgr.jd

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>&lt;package&gt;</em></pre>

<p><code><em>&lt;package&gt;</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>&lt;package&gt;</em></pre>

<p><code><em>&lt;package&gt;</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>&lt;package&gt;</em></pre>

<p><code><em>&lt;package&gt;</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>&lt;boolean&gt;</em></pre>

<p><code><em>&lt;boolean&gt;</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>&lt;name&gt;</em></pre>

<p><code><em>&lt;name&gt;</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.


-->