1 page.title=bmgr 2 parent.title=Tools 3 parent.link=index.html 4 @jd:body 5 6 <!-- quickview box content here --> 7 8 <div id="qv-wrapper"> 9 <div id="qv"> 10 <h2>bmgr quickview</h2> 11 <p><code>bmgr</code> lets you control the backup/restore system on an Android device. 12 13 <h2>In this document</h2> 14 <ol> 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> 18 </ol> 19 20 <h2>See also</h2> 21 <ol> 22 <li><a href="{@docRoot}guide/topics/data/backup.html">Data Backup</a></li> 23 </ol> 24 25 </div> 26 </div> 27 28 <!-- normal page content here --> 29 30 <p><code>bmgr</code> is a shell tool you can use to interact with the Backup Manager 31 on Android devices supporting API Level 8 or greater. It provides commands to induce backup 32 and restore operations so that you don't need to repeatedly wipe data or take similar 33 intrusive steps in order to test your application's backup agent. These commands are 34 accessed via the <a href="{@docRoot}tools/help/adb.html">adb</a> shell. 35 36 <p>For information about adding support for backup in your application, read <a 37 href="{@docRoot}guide/topics/data/backup.html">Data Backup</a>, which includes a guide to testing 38 your application using {@code bmgr}.</p> 39 40 41 <h2 id="backup">Forcing a Backup Operation</h2> 42 43 <p>Normally, your application must notify the Backup Manager when its data has changed, via {@link 44 android.app.backup.BackupManager#dataChanged()}. The Backup Manager will then invoke your 45 backup agent's {@link 46 android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) 47 onBackup()} implementation at some time in the future. However, instead of calling {@link 48 android.app.backup.BackupManager#dataChanged()}, you can invoke a backup request from the command 49 line by running the <code>bmgr backup</code> command: 50 51 <pre class="no-pretty-print">adb shell bmgr backup <em><package></em></pre> 52 53 <p><code><em><package></em></code> is the formal package name of the application you wish to 54 schedule for 55 backup. When you execute this backup command, your application's backup agent will be invoked to 56 perform a backup operation at some time in the future (via your {@link 57 android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) 58 onBackup()} method), though there is no guarantee when it will occur. However, you can force all 59 pending backup operations to run immediately by using the <code>bmgr run</code> command: 60 61 <pre class="no-pretty-print">adb shell bmgr run</pre> 62 63 <p>This causes a backup pass to execute immediately, invoking the backup agents of all applications 64 that had previously called {@link android.app.backup.BackupManager#dataChanged()} since the 65 last backup operation, plus any applications which had been manually scheduled for 66 backup via <code>bmgr backup</code>. 67 68 69 70 <h2 id="restore">Forcing a Restore Operation</h2> 71 72 <p>Unlike backup operations, which are batched together and run on an occasional basis, restore 73 operations execute immediately. The Backup Manager currently provides two kinds of restore 74 operations. The first kind restores an entire device with the data that has been backed up. This 75 is typically performed only when a device is first provisioned (to replicate settings and other 76 saved state from the user's previous device) and is an operation that only the system can 77 perform. The second kind of restore operation restores 78 a single application to its "active" data set; that is, the application will abandon its current 79 data and revert to the last-known-good data that is held in the current backup image. You can 80 invoke this second restore operation with the {@link 81 android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method. The 82 Backup Manager will then invoke your backup agent's {@link 83 android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) 84 onRestore()} implementation. 85 86 <p>While testing your application, you can immediately invoke the restore operation (bypassing the 87 {@link android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} method) 88 for your application by using the <code>bmgr restore</code> command: 89 90 <pre class="no-pretty-print">adb shell bmgr restore <em><package></em></pre> 91 92 <p><code><em><package></em></code> is the formal Java-style package name of the application 93 participating in the backup/restore mechanism, which you would like to restore. The Backup 94 Manager will immediately instantiate the application's backup agent and invoke it for restore. This 95 will happen even if your application is not currently running. 96 97 98 99 100 101 <h2 id="other">Other Commands</h2> 102 103 <h3>Wiping data</h3> 104 105 <p>The data for a single application can be erased from the active data set on demand. This is 106 very useful while you're developing a backup agent, in case bugs lead you to write corrupt data 107 or saved state information. You can wipe an application's data with the <code>bmgr wipe</code> 108 command: 109 110 <pre class="no-pretty-print">adb shell bmgr wipe <em><package></em></pre> 111 112 <p><code><em><package></em></code> is the formal package name of the application whose data 113 you wish to 114 erase. The next backup operation that the application's agent processes will look as 115 though the application had never backed anything up before. 116 117 118 <h3>Enabling and disabling backup</h3> 119 120 <p>You can see whether the Backup Manager is operational at all with the <code>bmgr 121 enabled</code> command: 122 123 <pre class="no-pretty-print">adb shell bmgr enabled</pre> 124 125 <p>This might be useful if your application's backup agent is never being invoked for backup, to 126 verify whether the operating system thinks it should be performing such operations at all.</p> 127 128 <p>You can also directly disable or enable the Backup Manager with this command: 129 130 <pre class="no-pretty-print">adb shell bmgr enable <em><boolean></em></pre> 131 132 <p><code><em><boolean></em></code> is either <code>true</code> or <code>false</code>. 133 This is equivalent to disabling or enabling backup in the device's main Settings UI.</p> 134 135 <p class="warning"><strong>Warning!</strong> When backup is disabled, the current backup transport 136 will explicitly wipe 137 the entire active data set from its backend storage. This is so that when a user says 138 they do <em>not</em> want their data backed up, the Backup Manager respects that wish. No further 139 data will be saved from the device, and no restore operations will be possible, unless the Backup 140 Manager is re-enabled (either through Settings or through the above <code>bmgr</code> command). 141 142 143 144 145 <!-- The following is not useful to applications, but may be some useful information some day... 146 147 148 <h2 id="transports">Applying a Backup Transport</h2> 149 150 <p>A "backup transport" is the code module responsible for moving backup and restore data 151 to and from some storage location. A device can have multipe transports installed, though only 152 one is active at any given time. Transports are identified by name. You can see what 153 transports are available on your device or emulator by running the 154 <code>bmgr list transports</code> command: 155 156 <pre class="no-pretty-print">adb shell bmgr list transports</pre> 157 158 <p>The output of this command is a list of the transports available on the device. The currently 159 active transport is flagged with a <code>*</code> character. Transport names may look like 160 component names (for example, <code>android/com.android.internal.backup.LocalTransport</code>), 161 but they need not be, and the strings are never used as direct class references. The use of 162 a component-like naming scheme is simply for purposes of preventing name collisions. 163 164 <p>You can change which transport is currently active from the command line as well: 165 166 <pre class="no-pretty-print">adb shell bmgr transport <em><name></em></pre> 167 168 <p><code><em><name></em></code> is one of the names as printed by the <code>bmgr list 169 transports</code> 170 command. From this point forward, backup and restore operations will be directed through the 171 newly-selected transport. Backup state tracking is managed separately for each transport, so 172 switching back and forth between them will not corrupt the saved state. 173 174 175 176 177 <h2 id="restoresets">Viewing Restore Sets</h2> 178 179 <p>All of the application data that a device has written to its backup transport is tracked 180 as a group that is collectively called a "restore set," because each data set is 181 most often manipulated during a restore operation. When a device is provisioned for the first 182 time, a new restore set is established. You can get a listing of all the restore sets available to 183 the current transport by running the <code>bmgr list sets</code> command: 184 185 <pre class="no-pretty-print">adb shell bmgr list sets</pre> 186 187 <p>The output is a listing of available restore sets, one per line. The first item on each line is 188 a token (a hexadecimal value that identifies the restore set to the transport). Following 189 the token is a string that briefly identifies the restore set. 190 Only the token is used within the backup and restore mechanism. 191 192 193 --> 194
