Skip to content

Commit cd8f7bd

Browse files
scottamainAndroid (Google) Code Review
scottamain
authored and
Android (Google) Code Review
committed
Merge "docs: editorial revisions to the bmgr tool doc" into froyo
2 parents 794cd64 + ff8c7ad commit cd8f7bd

File tree

2 files changed

+121
-107
lines changed

2 files changed

+121
-107
lines changed

‎docs/html/guide/developing/tools/bmgr.jd‎

Lines changed: 119 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -6,160 +6,173 @@ page.title=bmgr
66
<div id="qv-wrapper">
77
<div id="qv">
88
<h2>bmgr quickview</h2>
9-
<p><code>bmgr</code> lets you inspect and control the backup/restore system on an Android device.
9+
<p><code>bmgr</code> lets you control the backup/restore system on an Android device.
1010

1111
<h2>In this document</h2>
1212
<ol>
13-
<li><a href="#transports">About backup transports</a></li>
14-
<li><a href="#restoresets">About restore sets</a></li>
15-
<li><a href="#backup">Forcing a backup operation</a></li>
16-
<li><a href="#restore">Forcing a restore operation</a></li>
17-
<li><a href="#other">Other commands</a></li>
13+
<li><a href="#backup">Forcing a Backup Operation</a></li>
14+
<li><a href="#restore">Forcing a Restore Operation</a></li>
15+
<li><a href="#other">Other Commands</a></li>
1816
</ol>
1917

2018
</div>
2119
</div>
2220

2321
<!-- normal page content here -->
2422

25-
<p><code>bmgr</code> is a shell tool that developers can use to interact with the Backup Manager
26-
on Android devices supporting API version 8 or later. It provides commands for inducing backup
27-
and restore operations on demand so that you do not need to repeatedly wipe data or take similar
28-
intrusive steps to test the operation of an application's backup agent. These commands are
23+
<p><code>bmgr</code> is a shell tool you can use to interact with the Backup Manager
24+
on Android devices supporting API Level 8 or greater. It provides commands to induce backup
25+
and restore operations so that you don't need to repeatedly wipe data or take similar
26+
intrusive steps in order to test your application's backup agent. These commands are
2927
accessed via the <a href="{@docRoot}guide/developing/tools/adb.html">adb</a> shell.
3028

31-
<p>There are a couple of basic concepts used by the Backup Manager that are built into the way
32-
that <code>bmgr</code> operates. These are <a href="#transports">backup transports</a> and
33-
<a href="#restoresets">restore sets</a>.
3429

3530

36-
<a name="transports"></a>
37-
<h2>About backup transports</h2>
31+
<h2 id="backup">Forcing a Backup Operation</h2>
3832

39-
<p>A <em>backup transport</em> is the code module responsible for moving backup and restore data
40-
to and from some storage location. A device can have multipe transports installed, though only
41-
one is active at any given time. Transports are identified by name. You can see what
42-
transports are available on your device or emulator by running the
43-
<code>bmgr list transports</code> command:
33+
<p>Normally, your application must notify the Backup Manager when its data has changed, via {@link
34+
android.app.backup.BackupManager#dataChanged()}. The Backup Manager will then invoke your
35+
backup agent's {@link
36+
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
37+
onBackup()} implementation at some time in the future. However, instead of calling {@link
38+
android.app.backup.BackupManager#dataChanged()}, you can invoke a backup request from the command
39+
line by running the <code>bmgr backup</code> command:
4440

45-
<pre>adb shell bmgr list transports</pre>
41+
<pre class="no-pretty-print">adb shell bmgr backup <em>&lt;package&gt;</em></pre>
4642

47-
<p>The output of this command is a list of the transports available on the device. The currently
48-
active transport is flagged with a <code>*</code> character. Transport names may look like
49-
component names -- for example, <code>android/com.android.internal.backup.LocalTransport</code> --
50-
but they need not be, and the strings are never used as direct class references. The use of
51-
a component-like naming scheme is simply for purposes of preventing name collisions.
43+
<p><code><em>&lt;package&gt;</em></code> is the formal package name of the application you wish to
44+
schedule for
45+
backup. When you execute this backup command, your application's backup agent will be invoked to
46+
perform a backup operation at some time in the future (via your {@link
47+
android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor)
48+
onBackup()} method), though there is no guarantee when it will occur. However, you can force all
49+
pending backup operations to run immediately by using the <code>bmgr run</code> command:
5250

53-
<p>You can change which transport is currently active from the command line as well:
51+
<pre class="no-pretty-print">adb shell bmgr run</pre>
5452

55-
<pre>adb shell bmgr transport NAME</pre>
53+
<p>This causes a backup pass to execute immediately, invoking the backup agents of all applications
54+
that had previously called {@link android.app.backup.BackupManager#dataChanged()} since the
55+
last backup operation, plus any applications which had been manually scheduled for
56+
backup via <code>bmgr backup</code>.
5657

57-
<p>where <code>NAME</code> is one of the names as printed by the <code>bmgr list transports</code>
58-
command. From this point forward, backup and restore operations will be directed through the
59-
newly-selected transport. Backup state tracking is managed separately for each transport, so
60-
switching back and forth between them will not corrupt the saved state.
6158

6259

63-
<a name="restoresets"></a>
64-
<h2>About restore sets</h2>
60+
<h2 id="restore">Forcing a Restore Operation</h2>
6561

66-
<p>All of the application data that a device has written to a given backup transport is tracked
67-
together, and is collectively sometimes called a <em>restore set,</em> because the typical use
68-
of the data set is during restore operations. Each time a device is initially provisioned, a
69-
new data set is established. The user can get a listing of all the data sets that can be
70-
restored through the current transport by running this shell command:
62+
<p>Unlike backup operations, which are batched together and run on an occasional basis, restore
63+
operations execute immediately. The Backup Manager currently provides two kinds of restore
64+
operations. The first kind restores an entire device with the data that has been backed up. This
65+
is typically performed only when a device is first provisioned (to replicate settings and other
66+
saved state from the user's previous device) and is an operation that only the system can
67+
perform. The second kind of restore operation restores
68+
a single application to its "active" data set; that is, the application will abandon its current
69+
data and revert to the last-known-good data that is held in the current backup image. You can
70+
invoke this second restore operation with the {@link
71+
android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method. The
72+
Backup Manager will then invoke your backup agent's {@link
73+
android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor)
74+
onRestore()} implementation.
7175

72-
<pre>adb shell bmgr list sets</pre>
76+
<p>While testing your application, you can immediately invoke the restore operation (bypassing the
77+
{@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method)
78+
for your application by using the <code>bmgr restore</code> command:
7379

74-
<p>The output is listing of available restore sets, one per line. The first item on each line is
75-
a <em>token,</em> a number in hexadecimal that identifies the restore set to the transport. After
76-
that is a string that may provide some brief identifying information about the restore set. Only
77-
the token is actually used within the backup and restore mechanism.
80+
<pre class="no-pretty-print">adb shell bmgr restore <em>&lt;package&gt;</em></pre>
7881

82+
<p><code><em>&lt;package&gt;</em></code> is the formal Java-style package name of the application
83+
participating in the backup/restore mechanism, which you would like to restore. The Backup
84+
Manager will immediately instantiate the application's backup agent and invoke it for restore. This
85+
will happen even if your application is not currently running.
7986

80-
<a name="backup"></a>
81-
<h2>Forcing a backup operation</h2>
8287

83-
<p>Normally, applications notify the backup manager directly that their data has changed, in
84-
response to which the backup manager will make sure to invoke that application's agent when the
85-
next backup operation is run. You can simulate this manually from the command line if you wish,
86-
by running this shell command:
8788

88-
<pre>adb shell bmgr backup PACKAGE</pre>
8989

90-
<p><code>PACKAGE</code> is the formal package name of the application you wish to schedule for
91-
backup. At this point you know that the application's agent will be invoked for backup at some
92-
point in the future, though there is no hard guarantee of when that will occur. You can force
93-
all pending backup operations to run immediately by using the following command:
9490

95-
<pre>adb shell bmgr run</pre>
91+
<h2 id="other">Other Commands</h2>
9692

97-
<p>This causes a backup pass to execute immediately, invoking the agents of all applications that
98-
had called <code>BackupManager.dataChanged()</code> since the time of the last backup operation,
99-
plus any applications which had been manually scheduled for backup via
100-
<code>bmgr backup PACKAGE</code>.
93+
<p>The data for a single application can be erased from the active data set on demand. This is
94+
very useful while you're developing a backup agent, in case bugs lead you to write corrupt data
95+
or saved state information. You can wipe an application's data with the <code>bmgr wipe</code>
96+
command:
10197

98+
<pre class="no-pretty-print">adb shell bmgr wipe <em>&lt;package&gt;</em></pre>
10299

103-
<a name="restore"></a>
104-
<h2>Forcing a restore operation</h2>
100+
<p><code><em>&lt;package&gt;</em></code> is the formal package name of the application whose data
101+
you wish to
102+
erase. The next backup operation that the application's agent processes will look as
103+
though the application had never backed anything up before.
105104

106-
<p>Unlike backup operations, which are batched together and run on an occasional basis, restore
107-
operations execute immediately. The backup manager currently provides two kinds of restore
108-
operations. The first restores an entire device with the data from a given restore set. This
109-
is typically only performed when a device is first provisioned, to replicate settings and other
110-
such saved state from the user's previous device. The second kind of restore operation restores
111-
a single application from the <em>active</em> data set; that is, from the data set currently
112-
being written to by backup operations. This second form is available as part of the public API.
113-
It allows applications to abandon their current data and revert to the last-known-good data as
114-
represented in their current backup image.
105+
<p>You can see whether the Backup Manager is operational at all with the <code>bmgr
106+
enabled</code> command:
115107

116-
<p>A full-system restore operation can be initiated with this shell command:
108+
<pre class="no-pretty-print">adb shell bmgr enabled</pre>
117109

118-
<pre>adb shell bmgr restore TOKEN</pre>
110+
<p>This might be useful if your application's backup agent is never being invoked for backup, to
111+
verify whether the operating system thinks it should be performing such operations at all.</p>
119112

120-
<p>where <code>TOKEN</code> is the desired restore set's token as printed out by the <code>bmgr
121-
list sets</code> command. <strong>Warning!</strong> This operation will <em>replace</em> the
122-
data of all backup-enabled applications with the contents of the given restore set. Be careful,
123-
and be aware of the potential consequences.
113+
<p>You can also directly disable or enable the Backup Manager with this command:
124114

125-
<p>A single-application restore operation does not reference a restore set token; it always uses
126-
the data from the currently active data set. You can induce such an operation from the command
127-
line like this:
115+
<pre class="no-pretty-print">adb shell bmgr enable <em>&lt;boolean&gt;</em></pre>
128116

129-
<pre>adb shell bmgr restore PACKAGE</pre>
117+
<p><code><em>&lt;boolean&gt;</em></code> is either <code>true</code> or <code>false</code>.
118+
This is equivalent to disabling or enabling backup in the device's main Settings UI.</p>
130119

131-
<p><code>PACKAGE</code> is the formal package name of an application that is participating in the
132-
backup/restore mechanism. The backup manager will immediately instantiate the application's
133-
agent and invoke it for restore.
120+
<p class="warning"><strong>Warning!</strong> When backup is disabled, the current backup transport
121+
will explicitly wipe
122+
the entire active data set from its backend storage. This is so that when a user says
123+
they do <em>not</em> want their data backed up, the Backup Manager respects that wish. No further
124+
data will be saved from the device, and no restore operations will be possible, unless the Backup
125+
Manager is re-enabled (either through Settings or through the above <code>bmgr</code> command).
134126

135-
<a name="other"></a>
136-
<h2>Other commands</h2>
137127

138-
<p>The data for a single application can be erased from the active data set on demand. This is
139-
very useful during development of backup agents, in case bugs lead you to write corrupt data
140-
or saved state information. The shell command for wiping an application's data is this:
141128

142-
<pre>adb shell bmgr wipe PACKAGE</pre>
143129

144-
<p><code>PACKAGE</code> is the formal package name of the application whose data you wish to
145-
erase. The next backup operation that the application's agent processes will look as
146-
though the application had never backed anything up before.
130+
<!-- The following is not useful to applications, but may be some useful information some day...
131+
132+
133+
<h2 id="transports">Applying a Backup Transport</h2>
134+
135+
<p>A "backup transport" is the code module responsible for moving backup and restore data
136+
to and from some storage location. A device can have multipe transports installed, though only
137+
one is active at any given time. Transports are identified by name. You can see what
138+
transports are available on your device or emulator by running the
139+
<code>bmgr list transports</code> command:
140+
141+
<pre class="no-pretty-print">adb shell bmgr list transports</pre>
142+
143+
<p>The output of this command is a list of the transports available on the device. The currently
144+
active transport is flagged with a <code>*</code> character. Transport names may look like
145+
component names (for example, <code>android/com.android.internal.backup.LocalTransport</code>),
146+
but they need not be, and the strings are never used as direct class references. The use of
147+
a component-like naming scheme is simply for purposes of preventing name collisions.
148+
149+
<p>You can change which transport is currently active from the command line as well:
150+
151+
<pre class="no-pretty-print">adb shell bmgr transport <em>&lt;name&gt;</em></pre>
152+
153+
<p><code><em>&lt;name&gt;</em></code> is one of the names as printed by the <code>bmgr list
154+
transports</code>
155+
command. From this point forward, backup and restore operations will be directed through the
156+
newly-selected transport. Backup state tracking is managed separately for each transport, so
157+
switching back and forth between them will not corrupt the saved state.
158+
159+
160+
147161

148-
<p>You can see whether the backup manager is operational at all by running this command:
162+
<h2 id="restoresets">Viewing Restore Sets</h2>
149163

150-
<pre>adb shell bmgr enabled</pre>
164+
<p>All of the application data that a device has written to its backup transport is tracked
165+
as a group that is collectively called a "restore set," because each data set is
166+
most often manipulated during a restore operation. When a device is provisioned for the first
167+
time, a new restore set is established. You can get a listing of all the restore sets available to
168+
the current transport by running the <code>bmgr list sets</code> command:
151169

152-
<p>This might be useful if your application's agent is never being invoked for backup, to verify
153-
whether the operating system thinks it should be performing such operations at all. You can also
154-
directly disable or enable the backup manager with this command:
170+
<pre class="no-pretty-print">adb shell bmgr list sets</pre>
155171

156-
<pre>adb shell bmgr enable BOOLEAN</pre>
172+
<p>The output is a listing of available restore sets, one per line. The first item on each line is
173+
a token (a hexadecimal value that identifies the restore set to the transport). Following
174+
the token is a string that briefly identifies the restore set.
175+
Only the token is used within the backup and restore mechanism.
157176

158-
<p>where <code>BOOLEAN</code> is either <code>true</code> or <code>false</code>. This is
159-
equivalent to disabling or enabling backup in the device's main Settings UI.
160-
<strong>Warning!</strong> When backup is disabled, the current transport will explicitly wipe
161-
the entire active data set from its backend storage. This is so that when a user says that no,
162-
they do not want their data backed up, the backup manager respects that wish. No further data
163-
will be saved from the device, and no restore operations will be possible, unless the backup
164-
manager is re-enabled (either through Settings or through the above <code>bmgr</code> command).
165177

178+
-->

‎docs/html/guide/guide_toc.cs‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -282,7 +282,8 @@ localized titles are added in the language order specified below.
282282
<!--<li><a href="<?cs var:toroot ?>guide/developing/tools/adt.html">ADT Plugin</a></li>-->
283283
<li><a href="<?cs var:toroot ?>guide/developing/tools/aidl.html">aidl</a></li>
284284
<li><a href="<?cs var:toroot ?>guide/developing/tools/avd.html">AVDs</a></li>
285-
<li><a href="<?cs var:toroot ?>guide/developing/tools/bmgr.html">bmgr</a></li>
285+
<li><a href="<?cs var:toroot ?>guide/developing/tools/bmgr.html">bmgr</a>
286+
<span class="new">new!</span></li>
286287
<li><a href="<?cs var:toroot ?>guide/developing/tools/ddms.html">ddms</a></li>
287288
<li><a href="<?cs var:toroot ?>guide/developing/tools/othertools.html#dx">dx</a></li>
288289
<li><a href="<?cs var:toroot ?>guide/developing/tools/draw9patch.html">Draw 9-Patch</a></li>

0 commit comments

Comments
 (0)