diff options
| -rw-r--r-- | core/java/android/app/backup/BackupAgent.java | 7 | ||||
| -rw-r--r-- | core/java/android/app/backup/package.html | 27 | ||||
| -rw-r--r-- | docs/html/guide/developing/eclipse-adt.jd | 391 | ||||
| -rw-r--r-- | docs/html/guide/developing/other-ide.jd | 422 | ||||
| -rw-r--r-- | docs/html/guide/guide_toc.cs | 12 | ||||
| -rw-r--r-- | docs/html/guide/practices/screens_support.jd | 18 | ||||
| -rw-r--r-- | docs/html/guide/topics/data/backup.jd | 761 | ||||
| -rw-r--r-- | docs/html/images/developing/adt-props-isLib.png | bin | 0 -> 102350 bytes | |||
| -rw-r--r-- | docs/html/images/developing/adt-props-libRef.png | bin | 0 -> 113604 bytes |
9 files changed, 1602 insertions, 36 deletions
diff --git a/core/java/android/app/backup/BackupAgent.java b/core/java/android/app/backup/BackupAgent.java index 5245da5..cb4e0e7 100644 --- a/core/java/android/app/backup/BackupAgent.java +++ b/core/java/android/app/backup/BackupAgent.java @@ -162,9 +162,10 @@ public abstract class BackupAgent extends ContextWrapper { * file descriptor pointing to a full snapshot of the * application's data. The application should consume every * entity represented in this data stream. - * @param appVersionCode The - * {@link android.R.styleable#AndroidManifest_versionCode android:versionCode} - * value of the application that backed up this particular data set. This + * @param appVersionCode The value of the <a + * href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code + * android:versionCode}</a> manifest attribute, + * from the application that backed up this particular data set. This * makes it possible for an application's agent to distinguish among any * possible older data versions when asked to perform the restore * operation. diff --git a/core/java/android/app/backup/package.html b/core/java/android/app/backup/package.html index e2518ec..ae29994 100644 --- a/core/java/android/app/backup/package.html +++ b/core/java/android/app/backup/package.html @@ -2,23 +2,28 @@ <BODY> <p>Contains the backup and restore functionality available to applications. If a user wipes the data on their device or upgrades to a new Android-powered -device, all applications that have enabled backup will restore the user's previous data and/or -preferences. {@more} All backup management is controlled through -{@link android.app.backup.BackupManager}. Individual backup functionality is -implemented through a subclass {@link android.app.backup.BackupAgent} and a -simple and easy-to-use implementation is provided in -{@link android.app.backup.BackupAgentHelper}.</p> +device, all applications that have enabled backup will restore the user's previous data.</p> +{@more} -<p>STOPSHIP: add more documentation and remove Dev Guide link if not written!</p> +<p>All backup and restore operations are controlled by the {@link +android.app.backup.BackupManager}. Each application that would +like to enable backup and preserve its data on remote strage must implement a +backup agent. A backup agent can be built by extending either {@link android.app.backup.BackupAgent} +or {@link android.app.backup.BackupAgentHelper}. The {@link +android.app.backup.BackupAgentHelper} class provides a wrapper around {@link +android.app.backup.BackupAgent} that simplifies the procedures to implement a backup agent by +employing backup helpers such as {@link android.app.backup.SharedPreferencesBackupHelper} and +{@link android.app.backup.FileBackupHelper}.</p> <p>The backup APIs let applications:</p> <ul> - <li>Perform backup of arbitrary data</li> - <li>Easily perform backup of Preferences and files</li> - <li>Handle restore of data</li> + <li>Perform backup of arbitrary data to remote storage</li> + <li>Easily perform backup of {@link android.content.SharedPreferences} and files</li> + <li>Restore the data saved to remote storage</li> </ul> <p>For a detailed guide to using the backup APIs, see the <a -href="{@docRoot}guide/topics/backup.html">Backup Dev Guide topic</a>.</p> +href="{@docRoot}guide/topics/data/backup.html">Data Backup</a> developer guide.</p> + </BODY> </HTML> diff --git a/docs/html/guide/developing/eclipse-adt.jd b/docs/html/guide/developing/eclipse-adt.jd index 549e093..cf2a457 100644 --- a/docs/html/guide/developing/eclipse-adt.jd +++ b/docs/html/guide/developing/eclipse-adt.jd @@ -15,6 +15,14 @@ page.title=Developing In Eclipse, with ADT </li> <li><a href="#RunConfig">Creating a Custom Run Configuration</a></li> <li><a href="#Signing">Setting Up Application Signing</a></li> + <li><a href="#libraryProject">Working with Library Projects</a> + <ol> + <li><a href="#libraryReqts">Development requirements</a></li> + <li><a href="#librarySetup">Setting up a library project</a></li> + <li><a href="#libraryReference">Referencing a library project</a></li> + <li><a href="#considerations">Development considerations</a></li> + </ol> + </li> <li><a href="#Tips">Eclipse Tips</a></li> </div> </div> @@ -118,12 +126,11 @@ folders and files in your new project:</p> <dd>This contains the Java files generated by ADT, such as your <code>R.java</code> file and interfaces created from AIDL files.</dd> <dt><code>assets/</code></dt> - <dd>This is empty. You can use it to store raw asset files. See - <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</dd> + <dd>This is empty. You can use it to store raw asset files. </dd> <dt><code>res/</code></dt> <dd>A folder for your application resources, such as drawable files, layout files, string values, etc. See - <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</dd> + <a href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>.</dd> <dt><code>AndroidManifest.xml</code></dt> <dd>The Android Manifest for your project. See <a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml @@ -303,8 +310,7 @@ document.</p> <h3 id="AutoAndManualTargetModes">Automatic and manual target modes</h3> <p>By default, a run configuration uses the <strong>automatic</strong> target mode in order to -select -an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p> +select an AVD. In this mode, ADT will select an AVD for the application in the following manner:</p> <ol> <li>If there's a device or emulator already running and its AVD configuration @@ -349,6 +355,381 @@ and what it means to you as an Android application developer. The document also a guide to exporting and signing your application with the ADT's Export Wizard.</p> +<h2 id="libraryProject">Working with Library Projects</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Library project example code</h2> + +<p>The SDK includes an example application called TicTacToeMain that shows how a +dependent application can use code and resources from an Android Library +project. The TicTacToeMain application uses code and resources from an example +library project called TicTacToeLib. + +<p style="margin-top:1em;">To download the sample applications and run them as +projects in your environment, use the <em>Android SDK and AVD Manager</em> to +download the "Samples for SDK API 8" component into your SDK. </p> + +<p style="margin-top:1em;">For more information and to browse the code of the +samples, see the <a +href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain +application</a>.</p> +</div> +</div> + +<p>An Android <em>library project</em> is a development project that holds +shared Android source code and resources. Other Android application projects can +reference the library project and, at build time, include its compiled sources +in their <code>.apk</code> files. Multiple application projects can reference +the same library project and any single application project can reference +multiple library projects. </p> + +<p>If you have source code and resources that are common to multiple application +projects, you can move them to a library project so that it is easier to +maintain across applications and versions. Here are some common scenarios in +which you could make use of library projects: </p> + +<ul> +<li>If you are developing multiple related applications that use some of the +same components, you move the redundant components out of their respective +application projects and create a single, reuseable set of the same components +in a library project. </li> +<li>If you are creating an application that exists in both free and paid +versions. You move the part of the application that is common to both versions +into a library project. The two dependent projects, with their different package +names, will reference the library project and provide only the difference +between the two application versions.</li> +</ul> + +<p>Structurally, a library project is similar to a standard Android application +project. For example, it includes a manifest file at the project root, as well +as <code>src/</code>, <code>res/</code> and similar directories. The project can +contain the same types of source code and resources as a standard +Android project, stored in the same way. For example, source code in the library +project can access its own resources through its <code>R</code> class. </p> + +<p>However, a library project differs from an standard Android application +project in that you cannot compile it directly to its own <code>.apk</code> or +run it on the Android platform. Similarly, you cannot export the library project +to a self-contained JAR file, as you would do for a true library. Instead, you +must compile the library indirectly, by referencing the library from a dependent +application's build path, then building that application. </p> + +<p>When you build an application that depends on a library project, the SDK +tools compile the library and merge its sources with those in the main project, +then use the result to generate the <code>.apk</code>. In cases where a resource +ID is defined in both the application and the library, the tools ensure that the +resource declared in the application gets priority and that the resource in the +library project is not compiled into the application <code>.apk</code>. This +gives your application the flexibility to either use or redefine any resource +behaviors or values that are defined in any library.</p> + +<p>To organize your code further, your application can add references to +multiple library projects, then specify the relative priority of the resources +in each library. This lets you build up the resources actually used in your +application in a cumulative manner. When two libraries referenced from an +application define the same resource ID, the tools select the resource from the +library with higher priority and discard the other. </p> + +<p>ADT lets you add references to library projects and set their relative +priority from the application project's Properties. As shown in Figure 2, +below, once you've added a reference to a library project, you can use the +<strong>Up</strong> and <strong>Down</strong> controls to change the ordering, +with the library listed at the top getting the higher priority. At build time, +the libraries are merged with the application one at a time, starting from the +lowest priority to the highest. </p> + +<p>Note that a library project cannot itself reference another library project +and that, at build time, library projects are <em>not</em> merged with each +other before being merged with the application. However, note that a library can +import an external library (JAR) in the normal way.</p> + +<p>The sections below describe how to use ADT to set up and manage library your +projects. Once you've set up your library projects and moved code into them, you +can import library classes and resources to your application in the normal way. +</p> + + +<h3 id="libraryReqts">Development requirements</h3> + +<p>Android library projects are a build-time construct, so you can use them to +build a final application <code>.apk</code> that targets any API level and is +compiled against any version of the Android library. </p> + +<p>However, to use library projects, you need to update your development +environment to use the latest tools and platforms, since older releases of the +tools and platforms do not support building with library projects. Specifically, +you need to download and install the versions listed below:</p> + +<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools +and plaforms on which you can develop library projects.</p> + +<table> +<tr> +<th>Component</th> +<th>Minimum Version</th> +</tr> +<tr> +<td>SDK Tools</td> +<td>r6 (or higher)</td> +</tr> +<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr> +<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr> +<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr> +<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr> +<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr> +<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr> +<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr> +</table> + +<p>You can download the tools and platforms using the <em>Android SDK and AVD +Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK +Components</a>. To install or update ADT, use the Eclipse Updater as described +in <a href="{@docRoot}sdk/eclipse-adt.html">ADT Plugin for Eclipse</a>.</p> + + +<h3 id="librarySetup">Setting up a library project</h3> + +<p>A library project is a standard Android project, so you can create a new one in the +same way as you would a new application project. Specifically, you can use +the New Project Wizard, as described in <a href="#CreatingAProject">Creating an +Android Project</a>, above. </p> + +<p>When you are creating the library project, you can select any application +name, package, and set other fields as needed, as shown in the diagram below. +Click Finish to create the project in the workspace.</p> + +<p>Next, set the project's Properties to indicate that it is a library project:</p> + +<ol> +<li>In the <strong>Package Explorer</strong>, right-click the library project +and select <strong>Properties</strong>.</li> +<li>In the <strong>Properties</strong> window, select the "Android" properties +group at left and locate the <strong>Library</strong> properties at right. </li> +<li>Select the "is Library" checkbox and click <strong>Apply</strong>.</li> +<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li> +</ol> + +<p>The new project is now marked as a library project. You can begin moving +source code and resources into it, as described in the sections below. </p> + +<p>You can also convert an existing application project into a library. To do +so, simply open the Properties for the project and select the "is Library" +checkbox. Other application projects can now reference the existing project as a +library project.</p> + +<img src="{@docRoot}images/developing/adt-props-isLib.png" style="margin:0;padding:0;" /> +<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 1.</strong> +Marking a project as an Android library project. </p> + +<h4>Creating the manifest file</h4> + +<p>A library project's manifest file must declare all of the shared components +that it includes, just as would a standard Android application. For more +information, see the documentation for <a +href="{@docRoot}guide/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> + +<p>For example, the <a +href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> +example library project declares the Activity <code>GameActivity</code>: </p> + +<pre><manifest> + ... + <application> + ... + <activity android:name="GameActivity" /> + ... + </application> + ... +</manifest></pre> + + +<h3 id="libraryReference">Referencing a library project from an application</h3> + +<p>If you are developing an application and want to include the shared code or +resources from a library project, you can do so easily by adding a reference to +the library project in the application project's Properties.</p> + +<p>To add a reference to a library project, follow these steps: </p> + +<ol> +<li>In the <strong>Package Explorer</strong>, right-click the dependent project +and select <strong>Properties</strong>.</li> +<li>In the <strong>Properties</strong> window, select the "Android" properties group +at left and locate the <strong>Library</strong> properties at right.</li> +<li>Click <strong>Add</strong> to open the <strong>Project Selection</strong> +dialog. </li> +<li>From the list of available library projects, select a project and click +<strong>OK</strong>.</li> +<li>When the dialog closes, click <strong>Apply</strong> in the +<strong>Properties</strong> window.</li> +<li>Click <strong>OK</strong> to close the <strong>Properties</strong> window.</li> +</ol> + +<p>As soon as the Properties dialog closes, Eclipse rebuilds the project, +including the contents of the library project. </p> + +<p>The figure below shows the Properties dialog that lets you add library +references and move them up and down in priority. </p> + +<img src="{@docRoot}images/developing/adt-props-libRef.png" style="margin:0;padding:0;" /> +<p class="img-caption" style="margin-left:3em;margin-bottom:2em;"><strong>Figure 2.</strong> +Adding a reference to a library project in the properties of an application project. </p> + +<p>If you are adding references to multiple libraries, note that you can set +their relative priority (and merge order) by selecting a library and using the +<strong>Up</strong> and <strong>Down</strong> controls. The tools merge the +referenced libraries with your application starting from lowest priority (bottom +of the list) to highest (top of the list). If more than one library defines the +same resource ID, the tools select the resource from the library with higher +priority. The application itself has highest priority and its resources are +always used in preference to identical resource IDs defined in libraries.</p> + +<h4>Declaring library components in the the manifest file</h4> + +<p>In the manifest file of the application project, you must add declarations +of all components that the application will use that are imported from a library +project. For example, you must declare any <code><activity></code>, +<code><service></code>, <code><receiver></code>, +<code><provider></code>, and so on, as well as +<code><permission></code>, <code><uses-library></code>, and similar +elements.</p> + +<p>Declarations should reference the library components by their fully-qualified +package names, where appropriate. </p> + +<p>For example, the <a +href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> +example application declares the library Activity <code>GameActivity</code> +like this: </p> + +<pre><manifest> + ... + <application> + ... + <activity android:name="com.example.android.tictactoe.library.GameActivity" /> + ... + </application> + ... +</manifest></pre> + +<p>For more information about the manifest file, see the documentation for <a href="{@docRoot}guide/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> + + +<h3 id="considerations">Development considerations</h3> + +<p>As you develop your library project and dependent applications, keep the +points listed below in mind.</p> + +<p><strong>Resource conflicts</strong></p> + +<p>Since the tools merge the resources of a library project with those of a +dependent application project, a given resource ID might be defined in both +projects. In this case, the tools select the resource from the application, or +the library with highest priority, and discard the other resource. As you +develop your applications, be aware that common resource IDs are likely to be +defined in more than one project and will be merged, with the resource from the +application or highest-priority library taking precedence.</p> + +<p><strong>Using prefixes to avoid resource conflicts</strong></p> + +<p>To avoid resource conflicts for common resource IDs, consider using a prefix +or other consistent naming scheme that is unique to the project (or is unique +across all projects). </p> + +<p><strong>No export of library project to JAR</strong></p> + +<p>A library cannot be distributed as a binary file (such as a jar file). This +is because the library project is compiled by the main project to use the +correct resource IDs.</p> + +<p><strong>One library project cannot reference another</strong></p> + +<p>A library cannot depend on another library.</p> + +<p><strong>A library project can include a JAR library</strong></p> + +<p>You can develop a library project that itself includes a JAR library, however +you need to manually edit the dependent application project's build path and add +a path to the JAR file. </p> + +<p><strong>A library project can depend on an external JAR library</strong></p> + +<p>You can develop a library project that depends on an external library (for +example, the Maps external library). In this case, the dependent application +must build against a target that includes the external library (for example, the +Google APIs Add-On). Note also that both the library project and the dependent +application must declare the external library their manifest files, in a <a +href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a> +element. </p> + +<p><strong>Library project can not include AIDL files</strong></p> + +<p>The tools do not support the use of <a +href="{@docRoot}guide/developing/tools/aidl.html">AIDL</a> files in a library project. +Any AIDL files used by an application must be stored in the application project +itself.</p> + +<p><strong>Library project can not include raw assets</strong></p> + +<p>The tools do not support the use of raw asset files in a library project. +Any asset resources used by an application must be stored in the +<code>assets/</code> directory of the application project +itself.</p> + +<p><strong>Targeting different Android platform versions in library project and +application project</strong></p> + +<p>A library is compiled as part of the dependent application project, so the +API used in the library project must be compatible with the version of the +Android library used to compile the application project. In general, the library +project should use an <a href="{@docRoot}guide/appendix/api-levels.html">API level</a> +that is the same as — or lower than — that used by the application. +If the library project uses an API level that is higher than that of the +application, the application project will fail to compile. It is perfectly +acceptable to have a library that uses the Android 1.5 API (API level 3) and +that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7) +project, for instance.</p> + +<p><strong>No restriction on library package name</strong></p> + +<p>There is no requirement for the package name of a library to be the same as +that of applications that use it.</p> + +<p><strong>Multiple R classes in gen/ folder of application project</strong></p> + +<p>When you build the dependent application project, the code of any libraries +is compiled and merged to the application project. Each library has its own +<code>R</code> class, named according to the library's package name. The +<code>R</code> class generated from the resources of the main project and of the +library is created in all the packages that are needed including the main +project’s package and the libraries’ packages.</p> + +<p><strong>Testing a library project</strong></p> + +<p>There are two recommended ways of setting up testing on code and resources in +a library project: </p> + +<ul> +<li>You can set up a <a +href="{@docRoot}guide/developing/testing/testing_otheride.html">test project</a> +that instruments an application project that depends on the library project. You +can then add tests to the project for library-specific features.</li> +<li>You can set up a set up a standard application project that depends on the +library and put the instrumentation in that project. This lets you create a +self-contained project that contains both the tests/instrumentations and the +code to test.</li> +</ul> + +<p><strong>Library project storage location</strong></p> + +<p>There are no specific requirements on where you should store a library +project, relative to a dependent application project, as long as the application +project can reference the library project by a relative link. You can place the +library project What is important is that the main project can reference the +library project through a relative link.</p> + + <h2 id="Tips">Eclipse Tips </h2> <h3 id="arbitraryexpressions">Executing arbitrary Java expressions in Eclipse</h3> diff --git a/docs/html/guide/developing/other-ide.jd b/docs/html/guide/developing/other-ide.jd index 76b2d9f..e8a6fb6 100644 --- a/docs/html/guide/developing/other-ide.jd +++ b/docs/html/guide/developing/other-ide.jd @@ -20,6 +20,15 @@ page.title=Developing In Other IDEs <li><a href="#RunningOnDevice">Running on a device</a></li> </ol> </li> + <li><a href="#libraryProject">Working with Library Projects</a> + <ol> + <li><a href="#libraryReqts">Development requirements</a></li> + <li><a href="#librarySetup">Setting up a library project</a></li> + <li><a href="#libraryReference">Referencing a library project</a></li> + <li><a href="#depAppBuild">Building a dependent application project</a></li> + <li><a href="#considerations">Development considerations</a></li> + </ol> + </li> <li><a href="#AttachingADebugger">Attaching a Debugger to Your Application</a></li> </ol> @@ -93,7 +102,7 @@ navigate to the <code>tools/</code> directory of your SDK and run:</p> android create project \ --target <em><target_ID></em> \ --name <em><your_project_name></em> \ ---path <em>/path/to/your/project</em> \ +--path <em>path/to/your/project</em> \ --activity <em><your_activity_name></em> \ --package <em><your_package_namespace></em> </pre> @@ -350,7 +359,7 @@ root of the project directory) and add entries for {@code key.store} and {@code For example:</p> <pre> -key.store=/path/to/my.keystore +key.store=path/to/my.keystore key.alias=mykeystore </pre> @@ -458,7 +467,7 @@ emulator: directory after you <a href="#Building">build your application</a>.</p> <p>If there is more than one emulator running, you must specify the emulator upon which to install the application, by its serial number, with the <code>-s</code> option. For example:</p> - <pre>adb -s emulator-5554 install <em>/path/to/your/app</em>.apk</pre> + <pre>adb -s emulator-5554 install <em>path/to/your/app</em>.apk</pre> <p>To see a list of available device serial numbers, execute {@code adb devices}.</p> </li> </ol> @@ -499,12 +508,10 @@ Development</a> for more information.</p> <p>Once your device is set up and connected via USB, navigate to your SDK's <code>tools/</code> directory and install the <code>.apk</code> on the device: - <pre>adb -d install <em>/path/to/your/app</em>.apk</pre> + <pre>adb -d install <em>path/to/your/app</em>.apk</pre> <p>The {@code -d} flag specifies that you want to use the attached device (in case you also have an emulator running).</p> - - <p>For more information on the tools used above, please see the following documents:</p> <ul> <li><a href="{@docRoot}guide/developing/tools/othertools.html#android">android Tool</a></li> @@ -512,6 +519,409 @@ have an emulator running).</p> <li><a href="{@docRoot}guide/developing/tools/adb.html">Android Debug Bridge</a> (ADB)</li> </ul> +<h2 id="libraryProject">Working with Library Projects</h2> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<h2>Library project example code</h2> + +<p>The SDK includes an example application called TicTacToeMain that shows how a +dependent application can use code and resources from an Android Library +project. The TicTacToeMain application uses code and resources from an example +library project called TicTacToeLib. + +<p style="margin-top:1em;">To download the sample applications and run them as +projects in your environment, use the <em>Android SDK and AVD Manager</em> to +download the "Samples for SDK API 8" component into your SDK. </p> + +<p style="margin-top:1em;">For more information and to browse the code of the +samples, see the <a +href="{@docRoot}resources/samples/TicTacToeMain/index.html">TicTacToeMain +application</a>.</p> +</div> +</div> + +<p>An Android <em>library project</em> is a development project that holds +shared Android source code and resources. Other Android application projects can +reference the library project and, at build time, include its compiled sources +in their <code>.apk</code> files. Multiple application projects can reference +the same library project and any single application project can reference +multiple library projects. </p> + +<p>If you have source code and resources that are common to multiple application +projects, you can move them to a library project so that it is easier to +maintain across applications and versions. Here are some common scenarios in +which you could make use of library projects: </p> + +<ul> +<li>If you are developing multiple related applications that use some of the +same components, you move the redundant components out of their respective +application projects and create a single, reuseable set of the same components +in a library project. </li> +<li>If you are creating an application that exists in both free and paid +versions. You move the part of the application that is common to both versions +into a library project. The two dependent projects, with their different package +names, will reference the library project and provide only the difference +between the two application versions.</li> +</ul> + +<p>Structurally, a library project is similar to a standard Android application +project. For example, it includes a manifest file at the project root, as well +as <code>src/</code>, <code>res/</code> and similar directories. The project can +contain the same types of source code and resources as a standard +Android project, stored in the same way. For example, source code in the library +project can access its own resources through its <code>R</code> class. </p> + +<p>However, a library project differs from an standard Android application +project in that you cannot compile it directly to its own <code>.apk</code> or +run it on the Android platform. Similarly, you cannot export the library project +to a self-contained JAR file, as you would do for a true library. Instead, you +must compile the library indirectly, by referencing the library from a dependent +application's build path, then building that application. </p> + +<p>When you build an application that depends on a library project, the SDK +tools compile the library and merge its sources with those in the main project, +then use the result to generate the <code>.apk</code>. In cases where a resource +ID is defined in both the application and the library, the tools ensure that the +resource declared in the application gets priority and that the resource in the +library project is not compiled into the application <code>.apk</code>. This +gives your application the flexibility to either use or redefine any resource +behaviors or values that are defined in any library.</p> + +<p>To organize your code further, your application can add references to +multiple library projects, then specify the relative priority of the resources +in each library. This lets you build up the resources actually used in your +application in a cumulative manner. When two libraries referenced from an +application define the same resource ID, the tools select the resource from the +library with higher priority and discard the other. + +<p>Once you've have added references, the tools let you set their relative +priority by editing the application project's build properties. At build time, +the tools merge the libraries with the application one at a time, starting from +the lowest priority to the highest. </p> + +<p>Note that a library project cannot itself reference another library project +and that, at build time, library projects are <em>not</em> merged with each +other before being merged with the application. However, note that a library can +import an external library (JAR) in the normal way.</p> + +<p>The sections below describe how to use ADT to set up and manage library your +projects. Once you've set up your library projects and moved code into them, you +can import library classes and resources to your application in the normal way. +</p> + + +<h3 id="libraryReqts">Development requirements</h3> + +<p>Android library projects are a build-time construct, so you can use them to +build a final application <code>.apk</code> that targets any API level and is +compiled against any version of the Android library. </p> + +<p>However, to use library projects, you need to update your development +environment to use the latest tools and platforms, since older releases of the +tools and platforms do not support building with library projects. Specifically, +you need to download and install the versions listed below:</p> + +<p class="table-caption"><strong>Table 1.</strong> Minimum versions of SDK tools +and plaforms on which you can develop library projects.</p> + +<table> +<tr> +<th>Component</th> +<th>Minimum Version</th> +</tr> +<tr> +<td>SDK Tools</td> +<td>r6 (or higher)</td> +</tr> +<tr><td>Android 2.2 platform</td><td>r1 (or higher)</td></tr> +<tr><td>Android 2.1 platform</td><td>r2 (or higher)</td></tr> +<tr><td style="color:gray">Android 2.0.1 platform</td><td style="color:gray"><em>not supported</em></td></tr> +<tr><td style="color:gray">Android 2.0 platform</td><td style="color:gray"><em>not supported</em></td></tr> +<tr><td>Android 1.6 platform</td><td>r3 (or higher)</td></tr> +<tr><td>Android 1.5 platform</td><td>r4 (or higher)</td></tr> +<tr><td>ADT Plugin</td><td>0.9.7 (or higher)</td></tr> +</table> + +<p>You can download the tools and platforms using the <em>Android SDK and AVD +Manager</em>, as described in <a href="{@docRoot}sdk/adding-components.html">Adding SDK +Components</a>.</p> + + +<h3 id="librarySetup">Setting up a new library project</h3> + +<p>A library project is a standard Android project, so you can create a new one in the +same way as you would a new application project. Specifically, you can use +the <code>android</code> tool to generate a new library project with all of the +necessary files and folders. </p> + +<h4>Creating a library project</h4> + +<p>To create a new library project, navigate to the <code><sdk>/tools/</code> directory +and use this command:</p> + +<pre class="no-pretty-print" style="color:black"> +android create lib-project --name <em><your_project_name></em> \ +--target <em><target_ID></em> \ +--path <em>path/to/your/project</em> \ +--package <em><your_library_package_namespace></em> +</pre> + +<p>The <code>create lib-project</code> command creates a standard project +structure that includes preset property that indicates to the build system that +the project is a library. It does this by adding this line to the project's +<code>default.properties</code> file: </p> + +<pre class="no-pretty-print" style="color:black">android.library=true</pre> + +<p>Once the command completes, the library project is created and you can begin moving +source code and resources into it, as described in the sections below.</p> + +<p>If you want to convert an existing application project to a library project, +so that other applications can use it, you can do so by adding a the +<code>android.library=true</code> property to the application's +<code>default.properties</code> file. </p> + +<h4>Creating the manifest file</h4> + +<p>A library project's manifest file must declare all of the shared components +that it includes, just as would a standard Android application. For more +information, see the documentation for <a +href="{@docRoot}guide/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> + +<p>For example, the <a +href="{@docRoot}resources/samples/TicTacToeLib/AndroidManifest.html">TicTacToeLib</a> +example library project declares the Activity <code>GameActivity</code>: </p> + +<pre><manifest> + ... + <application> + ... + <activity android:name="GameActivity" /> + ... + </application> + ... +</manifest></pre> + +<h4>Updating a library project</h4> + +<p>If you want to update the build properties (build target, location) of the +library project, use this command: </p> + +<pre> +android update lib-project \ +--target <em><target_ID></em> \ +--path <em>path/to/your/project</em> +</pre> + + +<h3 id="libraryReference">Referencing a library project from an application</h3> + +<p>If you are developing an application and want to include the shared code or +resources from a library project, you can do so easily by adding a reference to +the library project in the application project's build properties.</p> + +<p>To add a reference to a library project, navigate to the <code><sdk>/tools/</code> directory +and use this command:</p> + +<pre> +android update lib-project \ +--target <em><target_ID></em> \ +--path <em>path/to/your/project</em> +--library <em>path/to/library_projectA</em> +</pre> + +<p>This command updates the application project's build properties to include a +reference to the library project. Specifically, it adds an +<code>android.library.reference.<em>n</em></code> property to the project's +<code>default.properties</code> file. For example: </p> + +<pre class="no-pretty-print" style="color:black"> +android.library.reference.1=path/to/library_projectA +</pre> + +<p>If you are adding references to multiple libraries, note that you can set +their relative priority (and merge order) by manually editing the +<code>default.properties</code> file and adjusting the each reference's +<code>.<em>n</em></code> index as appropriate. For example, assume these +references: </p> + +<pre class="no-pretty-print" style="color:black"> +android.library.reference.1=path/to/library_projectA +android.library.reference.2=path/to/library_projectB +android.library.reference.3=path/to/library_projectC +</pre> + +<p>You can reorder the references to give highest priority to +<code>library_projectC</code> in this way:</p> + +<pre class="no-pretty-print" style="color:black"> +android.library.reference.2=path/to/library_projectA +android.library.reference.3=path/to/library_projectB +android.library.reference.1=path/to/library_projectC +</pre> + +<p>Note that the <code>.<em>n</em></code> index in the references +must begin at "1" and increase uniformly without "holes". References +appearing in the index after a hole are ignored. </p> + +<p>At build time, the libraries are merged with the application one at a time, +starting from the lowest priority to the highest. Note that a library cannot +itself reference another library and that, at build time, libraries are not +merged with each other before being merged with the application.</p> + + +<h4>Declaring library components in the the manifest file</h4> + +<p>In the manifest file of the application project, you must add declarations +of all components that the application will use that are imported from a library +project. For example, you must declare any <code><activity></code>, +<code><service></code>, <code><receiver></code>, +<code><provider></code>, and so on, as well as +<code><permission></code>, <code><uses-library></code>, and similar +elements.</p> + +<p>Declarations should reference the library components by their fully-qualified +package names, where appropriate. </p> + +<p>For example, the +<a href="{@docRoot}resources/samples/TicTacToeMain/AndroidManifest.html">TicTacToeMain</a> +example application declares the library Activity <code>GameActivity</code> +like this: </p> + +<pre><manifest> + ... + <application> + ... + <activity android:name="com.example.android.tictactoe.library.GameActivity" /> + ... + </application> + ... +</manifest></pre> + +<p>For more information about the manifest file, see the documentation for <a href="{@docRoot}guide/manifest/manifest-intro.html">AndroidManifest.xml</a>.</p> + +<h3 id="depAppBuild">Building a dependent application</h3> + +<p>To build an application project that depends on one or more library projects, +you can use the standard Ant build commands and compile modes, as described in +<a href=#Building">Building Your Application</a>, earlier in this document. The +tools compile and merge all libraries referenced by the application as part +of compiling the dependent application project. No additional commands or steps +are necessary. </p> + +<h3 id="considerations">Development considerations</h3> + +<p>As you develop your library project and dependent applications, keep the +points listed below in mind.</p> + +<p><strong>Resource conflicts</strong></p> + +<p>Since the tools merge the resources of a library project with those of a +dependent application project, a given resource ID might be defined in both +projects. In this case, the tools select the resource from the application, or +the library with highest priority, and discard the other resource. As you +develop your applications, be aware that common resource IDs are likely to be +defined in more than one project and will be merged, with the resource from the +application or highest-priority library taking precedence.</p> + +<p><strong>Using prefixes to avoid resource conflicts</strong></p> + +<p>To avoid resource conflicts for common resource IDs, consider using a prefix +or other consistent naming scheme that is unique to the project (or is unique +across all projects). </p> + +<p><strong>No export of library project to JAR</strong></p> + +<p>A library cannot be distributed as a binary file (such as a jar file). This +is because the library project is compiled by the main project to use the +correct resource IDs.</p> + +<p><strong>One library project cannot reference another</strong></p> + +<p>A library cannot depend on another library.</p> + +<p><strong>A library project can include a JAR library</strong></p> + +<p>You can develop a library project that itself includes a JAR library. When +you build the dependent application project, the tools automatically locate and +include the library in the application <code>.apk</code>. </p> + +<p><strong>A library project can depend on an external JAR library</strong></p> + +<p>You can develop a library project that depends on an external library (for +example, the Maps external library). In this case, the dependent application +must build against a target that includes the external library (for example, the +Google APIs Add-On). Note also that both the library project and the dependent +application must declare the external library their manifest files, in a <a +href="{@docRoot}guide/topics/manifest/uses-library-element.html"><code><uses-library></code></a> +element. </p> + +<p><strong>Library project cannot include AIDL files</strong></p> + +<p>The tools do not support the use of <a +href="{@docRoot}guide/developing/tools/aidl.html">AIDL</a> files in a library project. +Any AIDL files used by an application must be stored in the application project +itself.</p> + +<p><strong>Library project cannot include raw assets</strong></p> + +<p>The tools do not support the use of raw asset files in a library project. +Any asset resources used by an application must be stored in the +<code>assets/</code> directory of the application project +itself.</p> + +<p><strong>Targeting different Android platform versions in library project and +application project</strong></p> + +<p>A library is compiled as part of the dependent application project, so the +API used in the library project must be compatible with the version of the +Android library used to compile the application project. In general, the library +project should use an <a href="{@docRoot}guide/appendix/api-levels.html">API level</a> +that is the same as — or lower than — that used by the application. +If the library project uses an API level that is higher than that of the +application, the application project will fail to compile. It is perfectly +acceptable to have a library that uses the Android 1.5 API (API level 3) and +that is used in an Android 1.6 (API level 4) or Android 2.1 (API level 7) +project, for instance.</p> + +<p><strong>No restriction on library package name</strong></p> + +<p>There is no requirement for the package name of a library to be the same as +that of applications that use it.</p> + +<p><strong>Multiple R classes in gen/ folder of application project</strong></p> + +<p>When you build the dependent application project, the code of any libraries +is compiled and merged to the application project. Each library has its own +<code>R</code> class, named according to the library's package name. The +<code>R</code> class generated from the resources of the main project and of the +library is created in all the packages that are needed including the main +project’s package and the libraries’ packages.</p> + +<p><strong>Testing a library project</strong></p> + +<p>There are two recommended ways of setting up testing on code and resources in +a library project: </p> + +<ul> +<li>You can set up a <a +href="{@docRoot}guide/developing/testing/testing_otheride.html">test project</a> +that instruments an application project that depends on the library project. You +can then add tests to the project for library-specific features.</li> +<li>You can set up a set up a standard application project that depends on the +library and put the instrumentation in that project. This lets you create a +self-contained project that contains both the tests/instrumentations and the +code to test.</li> +</ul> + +<p><strong>Library project storage location</strong></p> + +<p>There are no specific requirements on where you should store a library +project, relative to a dependent application project, as long as the application +project can reference the library project by a relative link. You can place the +library project What is important is that the main project can reference the +library project through a relative link.</p> <h2 id="AttachingADebugger">Attaching a Debugger to Your Application</h2> diff --git a/docs/html/guide/guide_toc.cs b/docs/html/guide/guide_toc.cs index 51ca3cc..19f0f1d 100644 --- a/docs/html/guide/guide_toc.cs +++ b/docs/html/guide/guide_toc.cs @@ -144,9 +144,17 @@ <li><a href="<?cs var:toroot ?>guide/topics/intents/intents-filters.html"> <span class="en">Intents and Intent Filters</span> </a></li> - <li><a href="<?cs var:toroot ?>guide/topics/data/data-storage.html"> + <li class="toggle-list"> + <div><a href="<?cs var:toroot ?>guide/topics/data/data-storage.html"> <span class="en">Data Storage</span> - </a></li> + </a> <span class="new">new!</span></div> + <ul> + <li><a href="<?cs var:toroot ?>guide/topics/data/backup.html"> + <span class="en">Data Backup</span> + </a> <span class="new">new!</span> + </li> + </ul> + </li> <li><a href="<?cs var:toroot ?>guide/topics/providers/content-providers.html"> <span class="en">Content Providers</span> </a></li> diff --git a/docs/html/guide/practices/screens_support.jd b/docs/html/guide/practices/screens_support.jd index 1e254f0..45e3e49 100644 --- a/docs/html/guide/practices/screens_support.jd +++ b/docs/html/guide/practices/screens_support.jd @@ -35,7 +35,7 @@ page.title=Supporting Multiple Screens <ol> <li><code><a href="{@docRoot}guide/topics/manifest/supports-screens-element.html"><supports-screens></a></code></li> <li><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code></li> - <li><a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources">Alternate Resources</a></li> + <li><a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources">Alternative Resources</a></li> <li><a href="{@docRoot}guide/developing/tools/avd.html">Android Virtual Devices</a></li> </ol> @@ -279,16 +279,16 @@ href="{@docRoot}guide/resources/dashboard/screen-densities.html">Screen Densitie <div class="sidebox-wrapper"> <div class="sidebox"> -<h2>Using the alternate resources framework</h2> +<h2>Using the alternative resources framework</h2> <p>The platform's support for loading screen size- and density-specific -resources at run time is based on the alternate resources framework. +resources at run time is based on the alternative resources framework. <p> If you want to use size- or density-specific layouts or drawables in your application and you are not familiar with resource qualifiers or how the platform uses them, please read -<a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> -Alternate Resources</a>. +<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> +Alternative Resources</a>. </div> </div> @@ -738,8 +738,8 @@ res/drawable-nodpi/composite.xml // density independent resource <p>For more information about how to use resource qualifiers or how the platform selects them, please read -<a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> -Alternate Resources</a>.</p> +<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> +Alternative Resources</a>.</p> <h2 id="screen-independence">Best practices for Screen Independence</h2> @@ -1023,8 +1023,8 @@ scaling.</li> <li>Creating any size- or density-specific resources you need and placing them in directories tagged with the <a href="#qualifiers">correct qualifiers</a>. Qualifiers must be arranged in a proscribed order. See -<a href="{@docRoot}guide/topics/resources/resources-i18n.html#AlternateResources"> -Alternate Resources</a> for more information. </li> +<a href="{@docRoot}guide/topics/resources/providing-resources.html#AlternativeResources"> +Alternative Resources</a> for more information. </li> <li>Note that if you add size- or density-specific resource directories tagged with any of the resource qualifiers listed in this document, you should make sure to also tag those directories with the <code>v<api-level></code> diff --git a/docs/html/guide/topics/data/backup.jd b/docs/html/guide/topics/data/backup.jd new file mode 100644 index 0000000..98f7a4f --- /dev/null +++ b/docs/html/guide/topics/data/backup.jd @@ -0,0 +1,761 @@ +page.title=Data Backup +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>Back up your data to the cloud in case the user looses it</li> + <li>Easily back up SharedPreferences and private files with BackupAgentHelper</li> + <li>Requires API Level 8</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#Basics">The Basics</a></li> + <li><a href="#BackupAgent">Extending BackupAgent</a> + <ol> + <li><a href="#RequiredMethods">Required Methods</a></li> + <li><a href="#PerformingBackup">Performing backup</a></li> + <li><a href="#PerformingRestore">Performing restore</a></li> + </ol> + </li> + <li><a href="#BackupAgentHelper">Extending BackupAgentHelper</a> + <ol> + <li><a href="#SharedPreferences">Backing up SharedPreferences</a></li> + <li><a href="#Files">Backing up Private Files</a></li> + </ol> + </li> + <li><a href="#RestoreVersion">Checking the Restore Data Version</a></li> + <li><a href="#RequestingBackup">Requesting Backup</a></li> + <li><a href="#RequestingRestore">Requesting Restore</a></li> + </ol> + + <h2>Key classes</h2> + <ol> + <li>{@link android.app.backup.BackupManager}</li> + <li>{@link android.app.backup.BackupAgent}</li> + <li>{@link android.app.backup.BackupAgentHelper}</li> + </ol> + +</div> +</div> + +<p>Android's {@link android.app.backup backup} service allows you to copy your persistent +application data to a remote "cloud" storage, in order to provide a restore point for the +application data and settings. If a user performs a factory reset or converts to a new +Android-powered device, the system automatically restores your backup data when the application +is re-installed. This way, your users are not required to reproduce their previous data or +application settings. This process is completely transparent to the user and does not affect the +functionality or user experience in your application.</p> + +<p>Android-powered devices that support the backup service provide a cloud storage area that +saves your backup data and a backup transport that delivers your data to +the storage area and back to the device. During a backup +operation, Android's Backup Manager requests backup data from your application, then delivers it to +the cloud storage using the backup transport. During a restore operation, the Backup Manager +retrieves the backup data from the backup transport and returns it to your application +so it can restore the data to the device. The backup service is <em>not</em> designed for data +synchronization (you do not have access the backup data, except during a restore operation on the +device).</p> + +<p>The cloud storage used for backup won't necessarily be the same on all Android-powered devices. +The cloud storage and backup transport may differ between devices and service providers. +Where the backup data is stored is transparent to your application, but you are assured that your +application data cannot be read by other applications.</p> + +<p class="caution"><strong>Caution:</strong> Because the cloud storage and transport service can +differ from device to device, Android makes no guarantees about the security of your data while +using backup. You should be cautious about using backup to store sensitive data, such as usernames +and passwords.</p> + + +<h2 id="Basics">The Basics</h2> + +<p>To backup your application data, you need to implement a backup agent. Your backup +agent is called by the Backup Manager to provide the data you want to back up. It is also called +to restore your backup data when the application is re-installed. The Backup Manager handles all +your data transactions with the cloud storage and your backup agent handles all your data +transactions on the device.</p> + +<p>To implement a backup agent, you must:</p> + +<ol> + <li>Declare your backup agent in your manifest file with the <a +href="{@docRoot}guide/topics/manifest/application-element.html#agent">{@code +android:backupAgent}</a> attribute.</li> + <li>Define a backup agent by either:</p> + <ol type="a"> + <li><a href="#backupAgent">Extending BackupAgent</a> + <p>The {@link android.app.backup.BackupAgent} class provides the central interface with +which your application communicates with the Backup Manager. If you extend this class +directly, you must override {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} and {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()} to handle the backup and restore operations for your data.</p> + <p><em>Or</em></p> + <li><a href="#backupAgentHelper">Extending BackupAgentHelper</a> + <p>The {@link android.app.backup.BackupAgentHelper} class provides a convenient +wrapper around the {@link android.app.backup.BackupAgent} class, which minimizes the amount of code +you need to write. In your {@link android.app.backup.BackupAgentHelper}, you must use one or more +"helper" objects, which automatically backup and restore certain types of data, so that you do not +need to implement {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} and {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()}.</p> + <p>Android currently provides backup helpers that will backup and restore complete files +from {@link android.content.SharedPreferences} and <a +href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>.</p> + </li> + </ol> + </li> +</ol> + + + + +<h2 id="BackupManifest">Declaring the Backup Agent in Your Manifest</h2> + +<p>This is the easiest step, so once you've decided on the class name for your backup agent, declare +it in your manifest with the <a +href="{@docRoot}guide/topics/manifest/application-element.html#agent">{@code +android:backupAgent}</a> attribute in the <a +href="{@docRoot}guide/topics/manifest/application-element.html">{@code +<application>}</a> tag.</p> + +<p>For example:</p> + +<pre> +<manifest ... > + <application android:label="MyApplication" + <b>android:backupAgent="MyBackupAgent"</b>> + <activity ... > + ... + </activity> + </application> +</manifest> +</pre> + +<p>Another attribute you might want to use is <a +href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code +android:restoreAnyVersion}</a>. This attribute takes a boolean value to indicate whether you +want to restore the application data regardless of the current application version compared to the +version that produced the backup data. (The default value is "{@code false}".) See <a +href="#RestoreVersion">Checking the Restore Data Version</a> for more information.</p> + +<p class="note"><strong>Note:</strong> The backup service and the APIs you must use are +available only on devices running API Level 8 (Android 2.2) or greater, so you should also +set your <a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code android:minSdkVersion}</a> +attribute to "8". However, if you implement proper <a +href="{@docRoot}resources/articles/backward-compatibility.html">backward compatibility</a> in +your application, you can support this feature for devices running API Level 8 or greater, while +remaining compatible with older devices.</p> + + + + + +<h2 id="BackupAgent">Extending BackupAgent</h2> + +<p>Most applications shouldn't need to extend the {@link android.app.backup.BackupAgent} class +directly, but should instead <a href="BackupAgentHelper">extend BackupAgentHelper</a> to take +advantage of the built-in helper classes that automatically backup and restore your files. However, +you might want to extend {@link android.app.backup.BackupAgent} directly if you need to:</p> +<ul> + <li>Version your data format. For instance, if you anticipate the need to revise the +format in which you write your application data, you can build a backup agent to cross-check your +application version during a restore operation and perform any necessary compatibility work if the +version on the device is different than that of the backup data. For more information, see <a +href="#RestoreVersion">Checking the Restore Data Version</a>.</li> + <li>Instead of backing up an entire file, you can specify the portions of data the should be +backed up and how each portion is then restored to the device. (This can also help you manage +different versions, because you read and write your data as unique entities, rather than +complete files.)</li> + <li>Back up data in a database. If you have an SQLite database that you want to restore when +the user re-installs your application, you need to build a custom {@link +android.app.backup.BackupAgent} that reads the appropriate data during a backup operation, then +create your table and insert the data during a restore operation.</li> +</ul> + +<p>If you don't need to perform any of the tasks above and want to back up complete files from +{@link android.content.SharedPreferences} or <a +href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>, you +should skip to <a href="BackupAgentHelper">Extending BackupAgentHelper</a>.</p> + + + +<h3 id="RequiredMethods">Required Methods</h3> + +<p>When you create a backup agent by extending {@link android.app.backup.BackupAgent}, you +must implement the following callback methods:</p> + +<dl> + <dt>{@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()}</dt> + <dd>The Backup Manager calls this method after you <a href="#RequestBackup">request a +backup</a>. In this method, you read your application data from the device and pass the data you +want to back up to the Backup Manager, as described below in <a href="#PerformingBackup">Performing +backup</a>.</dd> + + <dt>{@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()}</dt> + <dd>The Backup Manager calls this method during a restore operation (you can <a +href="#RequestRestore">request a restore</a>, but the system automatically performs restore when the +user re-installs your application). When it calls this method, the Backup Manager delivers your +backup data, which you then restore to the device, as described below in <a +href="#PerformingRestore">Performing restore</a>.</dd> +</dl> + + + +<h3 id="PerformingBackup">Performing backup</h3> + + +<p>When it's time to back up your application data, the Backup Manager calls your {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} method. This is where you must provide your application data to the Backup Manager so +it can be saved to cloud storage.</p> + +<p>Only the Backup Manager can call your backup agent's {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} method. Each time that your application data changes and you want to perform a backup, +you must request a backup operation by calling {@link +android.app.backup.BackupManager#dataChanged()} (see <a href="#RequestingBackup">Requesting +Backup</a> for more information). A backup request does not result in an immediate call to your +{@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} method. Instead, the Backup Manager waits for an appropriate time, then performs +backup for all applications that have requested a backup since the last backup was performed.</p> + +<p class="note"><strong>Tip:</strong> While developing your application, you can initiate an +immediate backup operation from the Backup Manager with the <a +href="{@docRoot}guide/developing/tools/bmgr.html">bmgr tool</a>.</p> + +<p>When the Backup Manager calls your {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} method, it passes three parameters:</p> + +<dl> + <dt>{@code oldState}</dt> + <dd>An open, read-only {@link android.os.ParcelFileDescriptor} pointing to the last backup +state provided by your application. This is not the backup data from cloud storage, but a +local representation of the data that was backed up the last time {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} was called (as defined by {@code newState}, below, or from {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()}—more about this in the next section). Because {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} does not allow you to read existing backup data in +the cloud storage, you can use this local representation to determine whether your data has changed +since the last backup.</dd> + <dt>{@code data}</dt> + <dd>A {@link android.app.backup.BackupDataOutput} object, which you use to deliver your backup +data to the Backup Manager.</dd> + <dt>{@code newState}</dt> + <dd>An open, read/write {@link android.os.ParcelFileDescriptor} pointing to a file in which +you must write a representation of the data that you delivered to {@code data} (a representation +can be as simple as the last-modified timestamp for your file). This object is +returned as {@code oldState} the next time the Backup Manager calls your {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} method. If you do not write your backup data to {@code newState}, then {@code oldState} +will point to an empty file next time Backup Manager calls {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()}.</dd> +</dl> + +<p>Using these parameters, you should implement your {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} method to do the following:</p> + +<ol> + <li>Check whether your data has changed since the last backup by comparing {@code oldState} to +your current data. How you read data in {@code oldState} depends on how you originally wrote it to +{@code newState} (see step 3). The easiest way to record the state of a file is with its +last-modified timestamp. For example, here's how you can read and compare a timestamp from {@code +oldState}: + <pre> +// Get the oldState input stream +FileInputStream instream = new FileInputStream(oldState.getFileDescriptor()); +DataInputStream in = new DataInputStream(instream); + +try { + // Get the last modified timestamp from the state file and data file + long stateModified = in.readLong(); + long fileModified = mDataFile.lastModified(); + + if (stateModified != fileModified) { + // The file has been modified, so do a backup + // Or the time on the device changed, so be safe and do a backup + } else { + // Don't back up because the file hasn't changed + return; + } +} catch (IOException e) { + // Unable to read state file... be safe and do a backup +} +</pre> + <p>If nothing has changed and you don't need to back up, skip to step 3.</p> + </li> + <li>If your data has changed, compared to {@code oldState}, write the current data to +{@code data} to back it up to the cloud storage. + <p>You must write each chunk of data as an "entity" in the {@link +android.app.backup.BackupDataOutput}. An entity is a flattened binary data +record that is identified by a unique key string. Thus, the data set that you back up is +conceptually a set of key-value pairs.</p> + <p>To add an entity to your backup data set, you must:</p> + <ol> + <li>Call {@link android.app.backup.BackupDataOutput#writeEntityHeader(String,int) +writeEntityheader()}, passing a unique string key for the data you're about to write and the data +size.</li> + <li>Call {@link android.app.backup.BackupDataOutput#writeEntityData(byte[],int) +writeEntityData()}, passing a byte buffer that contains your data and the number of bytes to write +from the buffer (which should match the size passed to {@link +android.app.backup.BackupDataOutput#writeEntityHeader(String,int) writeEntityHeader()}).</li> + </ol> + <p>For example, the following code flattens some data into a byte stream and writes it into a +single entity:</p> + <pre> +// Create buffer stream and data output stream for our data +ByteArrayOutputStream bufStream = new ByteArrayOutputStream(); +DataOutputStream outWriter = new DataOutputStream(bufStream); +// Write structured data +outWriter.writeString(playerName); +outWriter.writeInt(playerScore); +// Send the data to the Backup Manager via the BackupDataOutput +byte[] buffer = bufStream.toByteArray(); +int len = buffer.length; +data.writeEntityHeader(TOPSCORE_BACKUP_KEY, len); +data.writeEntityData(buffer, len); +</pre> + <p>Perform this for each piece of data that you want to back up. How you divide your data into +entities is up to you (and you might use just one entity).</p> + </li> + <li>Whether or not you perform a backup (in step 2), write a representation of the current data to +the {@code newState} {@link android.os.ParcelFileDescriptor}. The Backup Manager retains this object +locally as a representation of the data that is currently backed up. It passes this back to you as +{@code oldState} the next time it calls {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} so you can determine whether another backup is necessary (as handled in step 1). If you +do not write the current data state to this file, then +{@code oldState} will be empty during the next callback. + <p>Again, the following example saves a representation of the data using the file's +last-modified timestamp:</p> + <pre> +FileOutputStream outstream = new FileOutputStream(stateFile.getFileDescriptor()); +DataOutputStream out = new DataOutputStream(outstream); + +long modified = mDataFile.lastModified(); +out.writeLong(modified); +</pre> + </li> +</ol> + +<p class="caution"><strong>Caution:</strong> If your application data is saved to a file, make sure +that you use synchronized statements while accessing the file so that your backup agent does not +read the file while an Activity in your application is also writing the file.</p> + + + + +<h3 id="PerformingRestore">Performing restore</h3> + +<p>When it's time to restore your application data, the Backup Manager calls your backup +agent's {@link android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()} method. When it calls this method, the Backup Manager delivers your backup data so +you can restore it onto the device.</p> + +<p>Only the Backup Manager can call {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()}, which happens automatically when the system installs your application and +finds existing backup data. However, you can request a restore operation for +your application by calling {@link +android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()} (see <a +href="#RequestingRestore">Requesting restore</a> for more information).</p> + +<p class="note"><strong>Note:</strong> While developing your application, you can also request a +restore operation with the <a href="{@docRoot}guide/developing/tools/bmgr.html">bmgr +tool</a>.</p> + +<p>When the Backup Manager calls your {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()} method, it passes three parameters:</p> + +<dl> + <dt>{@code data}</dt> + <dd>A {@link android.app.backup.BackupDataInput}, which allows you to read your backup +data.</dd> + <dt>{@code appVersionCode}</dt> + <dd>An integer representing the value of your application's <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a> +manifest attribute, as it was when this data was backed up. You can use this to cross-check the +current application version and determine if the data format is compatible. For more +information about using this to handle different versions of restore data, see the section +below about <a href="#RestoreVersion">Checking the Restore Data Version</a>.</dd> + <dt>{@code newState}</dt> + <dd>An open, read/write {@link android.os.ParcelFileDescriptor} pointing to a file in which +you must write the final backup state that was provided with {@code data}. This object is +returned as {@code oldState} the next time {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} is called. Recall that you must also write the same {@code newState} object in the +{@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} callback—also doing it here ensures that the {@code oldState} object given to +{@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} is valid even the first time {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} is called after the device is restored.</dd> +</dl> + +<p>In your implementation of {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()}, you should call {@link android.app.backup.BackupDataInput#readNextHeader()} to iterate +through all entities in the data set. For each entity found, do the following:</p> + +<ol> + <li>Get the entity key with {@link android.app.backup.BackupDataInput#getKey()}.</li> + <li>Compare the entity key to a list of known key values that you should have declared as static +final strings inside your {@link android.app.backup.BackupAgent} class. When the key matches one of +your known key strings, enter into a statement to extract the entity data and save it to the device: + <ol> + <li>Get the entity data size with {@link +android.app.backup.BackupDataInput#getDataSize()} and create a byte array of that size.</li> + <li>Call {@link android.app.backup.BackupDataInput#readEntityData(byte[],int,int) +readEntityData()} and pass it the byte array, which is where the data will go, and specify the +start offset and the size to read.</li> + <li>Your byte array is now full and you can read the data and write it to the device +however you like.</li> + </ol> + </li> + <li>After you read and write your data back to the device, write the state of your data to the +{@code newState} parameter the same as you do during {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()}. +</ol> + +<div class="special"> +<p>For an example implementation of {@link android.app.backup.BackupAgent}, see the <a +href="{@docRoot}resources/samples/BackupRestore/src/com/example/android/backuprestore/ExampleAgent.html">{@code +ExampleAgent}</a> class in the <a +href="{@docRoot}}resources/samples/BackupRestore/index.html">Backup and Restore</a> sample +application.</p> +</div> + + + + + + +<h2 id="BackupAgentHelper">Extending BackupAgentHelper</h2> + +<p>You should build your backup agent using {@link android.app.backup.BackupAgentHelper} if you want +to back up complete files (from either {@link android.content.SharedPreferences} or <a +href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>). +Building your backup agent with {@link android.app.backup.BackupAgentHelper} requires far less +code than extending {@link android.app.backup.BackupAgent}, because you don't have to implement +{@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} and {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()}.</p> + +<p>Your implementation of {@link android.app.backup.BackupAgentHelper} must +use one or more backup helpers. A backup helper is a specialized +component that {@link android.app.backup.BackupAgentHelper} summons to perform backup and +restore operations for a particular type of data. The Android framework currently provides two +different helpers:</p> +<ul> + <li>{@link android.app.backup.SharedPreferencesBackupHelper} to backup {@link +android.content.SharedPreferences} files.</li> + <li>{@link android.app.backup.FileBackupHelper} to backup files from <a +href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>.</li> +</ul> + +<p>You can include multiple helpers in your {@link android.app.backup.BackupAgentHelper}, but only +one helper is needed for each data type. That is, if you have multiple {@link +android.content.SharedPreferences} files, then you need only one {@link +android.app.backup.SharedPreferencesBackupHelper}.</p> + +<p>For each helper you want to add to your {@link android.app.backup.BackupAgentHelper}, you must do +the following during your {@link android.app.backup.BackupAgent#onCreate()} method:</p> +<ol> + <li>Instantiate in instance of the desired helper class. In the class constructor, you must +specify the appropriate file(s) you want to backup.</li> + <li>Call {@link android.app.backup.BackupAgentHelper#addHelper(String,BackupHelper) addHelper()} +to add the helper to your {@link android.app.backup.BackupAgentHelper}.</li> +</ol> + +<p>The following sections describe how to create a backup agent using each of the available +helpers.</p> + + + +<h3 id="SharedPreferences">Backing up SharedPreferences</h3> + +<p>When you instantiate a {@link android.app.backup.SharedPreferencesBackupHelper}, you must the +name of one or more {@link android.content.SharedPreferences} files.</p> + +<p>For example, to back up a {@link android.content.SharedPreferences} file named +"user_preferences", a complete backup agent using {@link android.app.backup.BackupAgentHelper} looks +like this:</p> + +<pre> +public class MyPrefsBackupAgent extends BackupAgentHelper { + // The name of the SharedPreferences file + static final String PREFS = "user_preferences"; + + // A key to uniquely identify the set of backup data + static final String PREFS_BACKUP_KEY = "prefs"; + + // Allocate a helper and add it to the backup agent + void onCreate() { + SharedPreferencesBackupHelper helper = new SharedPreferencesBackupHelper(this, PREFS); + addHelper(PREFS_BACKUP_KEY, helper); + } +} +</pre> + +<p>That's it! That's your entire backup agent. The {@link +android.app.backup.SharedPreferencesBackupHelper} includes all the code +needed to backup and restore a {@link android.content.SharedPreferences} file.</p> + +<p>When the Backup Manager calls {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} and {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()}, {@link android.app.backup.BackupAgentHelper} calls your backup helpers to perform +backup and restore for your specified files.</p> + +<p class="note"><strong>Note:</strong> {@link android.content.SharedPreferences} are threadsafe, so +you can safely read and write the shared preferences file from your backup agent and +other activities.</p> + + + +<h3 id="Files">Backing up other files</h3> + +<p>When you instantiate a {@link android.app.backup.FileBackupHelper}, you must include the name of +one or more files that are saved to your application's <a +href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a> +(as specified by {@link android.content.ContextWrapper#getFilesDir()}, which is the same +location where {@link android.content.Context#openFileOutput(String,int) openFileOutput()} writes +files).</p> + +<p>For example, to backup two files named "scores" and "stats," a backup agent using {@link +android.app.backup.BackupAgentHelper} looks like this:</p> + +<pre> +public class MyFileBackupAgent extends BackupAgentHelper { + // The name of the SharedPreferences file + static final String TOP_SCORES = "scores"; + static final String PLAYER_STATS = "stats"; + + // A key to uniquely identify the set of backup data + static final String FILES_BACKUP_KEY = "myfiles"; + + // Allocate a helper and add it to the backup agent + void onCreate() { + FileBackupHelper helper = new FileBackupHelper(this, TOP_SCORES, PLAYER_STATS); + addHelper(FILES_BACKUP_KEY, helper); + } +} +</pre> + +<p>The {@link android.app.backup.FileBackupHelper} includes all the code necessary to backup and +restore files that are saved to your application's <a +href="{@docRoot}guide/topics/data/data-storage.html#filesInternal">internal storage</a>..</p> + +<p>However, reading and writing to files on internal storage is <strong>not threadsafe</strong>. To +ensure that your backup agent does not read or write your files at the same time as your activities, +you must use synchronized statements each time you perform a read or write. For example, +in any Activity where you read and write the file, you need an object to use as the intrinsic +lock for the synchronized statements:</p> + +<div class="sidebox-wrapper"> +<div class="sidebox"> +<p><strong>Interesting Fact:</strong></p> +<p>A zero-length array is lighter-weight than a normal Object, so it's great for an +intrinsic lock.</p> +</div> +</div> + +<pre> +// Object for intrinsic lock +static final Object[] sDataLock = new Object[0]; +</pre> + +<p>Then create a synchronized statement with this lock each time you read or write the files. For +example, here's a synchronized statement for writing the latest score in a game to a file:</p> + +<pre> +try { + synchronized (MyActivity.sDataLock) { + File dataFile = new File({@link android.content.Context#getFilesDir()}, TOP_SCORES); + RandomAccessFile raFile = new RandomAccessFile(dataFile, "rw"); + raFile.writeInt(score); + } +} catch (IOException e) { + Log.e(TAG, "Unable to write to file"); +} +</pre> + +<p>You should synchronize your read statements with the same lock.</p> + +<p>Then, in your {@link android.app.backup.BackupAgentHelper}, you must override {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} and {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()} to synchronize the backup and restore operations with the same +intrinsic lock. For example, the {@code MyFileBackupAgent} example from above needs the following +methods:</p> + +<pre> +@Override +public void onBackup(ParcelFileDescriptor oldState, BackupDataOutput data, + ParcelFileDescriptor newState) throws IOException { + // Hold the lock while the FileBackupHelper performs backup + synchronized (MyActivity.sDataLock) { + super.onBackup(oldState, data, newState); + } +} + +@Override +public void onRestore(BackupDataInput data, int appVersionCode, + ParcelFileDescriptor newState) throws IOException { + // Hold the lock while the FileBackupHelper restores the file + synchronized (MyActivity.sDataLock) { + super.onRestore(data, appVersionCode, newState); + } +} +</pre> + +<p>That's it. All you need to do is add your {@link android.app.backup.FileBackupHelper} in the +{@link android.app.backup.BackupAgent#onCreate()} method and override {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} and {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) +onRestore()} to synchronize read and write operations.</p> + +<div class="special"> +<p>For an example implementation of {@link +android.app.backup.BackupAgentHelper} with {@link android.app.backup.FileBackupHelper}, see the +{@code FileHelperExampleAgent} class in the <a +href="{@docRoot}resources/samples/BackupRestore/index.html">Backup and Restore</a> sample +application.</p> +</div> + + + + + + +<h2 id="RestoreVersion">Checking the Restore Data Version</h2> + +<p>When the Backup Manager saves your data to cloud storage, it automatically includes the version +of your application, as defined by your manifest file's <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a> +attribute. Before the Backup Manager calls your backup agent to restore your data, it +looks at the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code +android:versionCode}</a> of the installed application and compares it to the value +recorded in the restore data set. If the version recorded in the restore data set is +<em>newer</em> than the application version on the device, then the user has downgraded their +application. In this case, the Backup Manager will abort the restore operation for your application +and not call your {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()} +method, because the restore set is considered meaningless to an older version.</p> + +<p>You can override this behavior with the <a +href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code +android:restoreAnyVersion}</a> attribute. This attribute is either "{@code true}" or "{@code +false}" to indicate whether you want to restore the application regardless of the restore set +version. The default value is "{@code false}". If you define this to be "{@code true}" then the +Backup Manager will ignore the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#vcode">{@code android:versionCode}</a> +and call your {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()} +method in all cases. In doing so, you can manually check for the version difference in your {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()} +method and take any steps necessary to make the data compatible if the versions conflict.</p> + +<p>To help you handle different versions during a restore operation, the {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()} +method passes you the version code included with the restore data set as the {@code appVersionCode} +parameter. You can then query the current application's version code with the {@link +android.content.pm.PackageInfo#versionCode PackageInfo.versionCode} field. For example:</p> + +<pre> +PackageInfo info; +try { + String name = {@link android.content.ContextWrapper#getPackageName() getPackageName}(); + info = {@link android.content.ContextWrapper#getPackageManager +getPackageManager}().{@link android.content.pm.PackageManager#getPackageInfo(String,int) +getPackageInfo}(name,0); +} catch (NameNotFoundException nnfe) { + info = null; +} + +int version; +if (info != null) { + version = info.versionCode; +} +</pre> + +<p>Then simply compare the {@code version} acquired from {@link android.content.pm.PackageInfo} +to the {@code appVersionCode} passed into {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}. +</p> + +<p class="caution"><strong>Caution:</strong> Be certain you understand the consequences of setting +<a href="{@docRoot}guide/topics/manifest/application-element.html#restoreany">{@code +android:restoreAnyVersion}</a> to "{@code true}" for your application. If each version of your +application that supports backup does not properly account for variations in your data format during +{@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()}, +then the data on the device could be saved in a format incompatible with the version currently +installed on the device.</p> + + + +<h2 id="RequestingBackup">Requesting Backup</h2> + +<p>You can request a backup operation at any time by calling {@link +android.app.backup.BackupManager#dataChanged()}. This method notifies the Backup Manager that you'd +like to backup your data using your backup agent. The Backup Manager then calls your backup +agent's {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()} method at an opportune time in the future. Typically, you should +request a backup each time your data changes (such as when the user changes an application +preference that you'd like to back up). If you call {@link +android.app.backup.BackupManager#dataChanged()} several times consecutively, before the Backup +Manager requests a backup from your agent, your agent still receives just one call to {@link +android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) +onBackup()}.</p> + +<p class="note"><strong>Note:</strong> While developing your application, you can request a +backup and initiate an immediate backup operation with the <a +href="{@docRoot}guide/developing/tools/bmgr.html">bmgr +tool</a>.</p> + + +<h2 id="RequestingRestore">Requesting Restore</h2> + +<p>During the normal life of your application, you shouldn't need to request a restore operation. +They system automatically checks for backup data and performs a restore when your application is +installed. However, you can manually request a restore operation by calling {@link +android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore()}, if necessary. In +which case, the Backup Manager calls your {@link +android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescriptor) onRestore()} +implementation, passing the data from the current set of backup data.</p> + +<p class="note"><strong>Note:</strong> While developing your application, you can request a +restore operation with the <a href="{@docRoot}guide/developing/tools/bmgr.html">bmgr +tool</a>.</p> + diff --git a/docs/html/images/developing/adt-props-isLib.png b/docs/html/images/developing/adt-props-isLib.png Binary files differnew file mode 100644 index 0000000..18bdb33 --- /dev/null +++ b/docs/html/images/developing/adt-props-isLib.png diff --git a/docs/html/images/developing/adt-props-libRef.png b/docs/html/images/developing/adt-props-libRef.png Binary files differnew file mode 100644 index 0000000..e61df51 --- /dev/null +++ b/docs/html/images/developing/adt-props-libRef.png |
