diff options
Diffstat (limited to 'docs/html/guide/topics/data')
| -rw-r--r-- | docs/html/guide/topics/data/backup.jd | 12 | ||||
| -rw-r--r-- | docs/html/guide/topics/data/data-storage.jd | 23 | ||||
| -rw-r--r-- | docs/html/guide/topics/data/index.html | 9 | ||||
| -rw-r--r-- | docs/html/guide/topics/data/index.jd | 23 | ||||
| -rw-r--r-- | docs/html/guide/topics/data/install-location.jd | 206 |
5 files changed, 240 insertions, 33 deletions
diff --git a/docs/html/guide/topics/data/backup.jd b/docs/html/guide/topics/data/backup.jd index d91e422..602b6e8 100644 --- a/docs/html/guide/topics/data/backup.jd +++ b/docs/html/guide/topics/data/backup.jd @@ -47,7 +47,7 @@ data onto the new device</li> <h2>See also</h2> <ol> - <li><a href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr} tool</a></li> + <li><a href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a></li> </ol> </div> @@ -316,7 +316,7 @@ backup for all applications that have requested a backup since the last backup w <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">{@code bmgr} tool</a>.</p> +href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p> <p>When the Backup Manager calls your {@link android.app.backup.BackupAgent#onBackup(ParcelFileDescriptor,BackupDataOutput,ParcelFileDescriptor) @@ -460,7 +460,7 @@ android.app.backup.BackupManager#requestRestore(RestoreObserver) requestRestore( 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">{@code bmgr} +restore operation with the <a href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p> <p>When the Backup Manager calls your {@link @@ -863,7 +863,7 @@ 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">{@code bmgr} +href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p> @@ -878,7 +878,7 @@ android.app.backup.BackupAgent#onRestore(BackupDataInput,int,ParcelFileDescripto 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">{@code bmgr} +restore operation with the <a href="{@docRoot}tools/help/bmgr.html">{@code bmgr} tool</a>.</p> @@ -886,7 +886,7 @@ tool</a>.</p> <p>Once you've implemented your backup agent, you can test the backup and restore functionality with the following procedure, using <a -href="{@docRoot}guide/developing/tools/bmgr.html">{@code bmgr}</a>.</p> +href="{@docRoot}tools/help/bmgr.html">{@code bmgr}</a>.</p> <ol> <li>Install your application on a suitable Android system image diff --git a/docs/html/guide/topics/data/data-storage.jd b/docs/html/guide/topics/data/data-storage.jd index d31afa5..e9d2d25 100644 --- a/docs/html/guide/topics/data/data-storage.jd +++ b/docs/html/guide/topics/data/data-storage.jd @@ -1,4 +1,4 @@ -page.title=Data Storage +page.title=Storage Options @jd:body @@ -16,22 +16,9 @@ page.title=Data Storage <h2>In this document</h2> <ol> <li><a href="#pref">Using Shared Preferences</a></li> - <li><a href="#filesInternal">Using the Internal Storage</a> - <ol> - <li><a href="#InternalCache">Saving cache files</a></li> - <li><a href="#InternalMethods">Other useful methods</a></li> - </ol></li> - <li><a href="#filesExternal">Using the External Storage</a> - <ol> - <li><a href="#MediaAvail">Checking media availability</a></li> - <li><a href="#AccessingExtFiles">Accessing files on external storage</a></li> - <li><a href="#SavingSharedFiles">Saving files that should be shared</a></li> - <li><a href="#ExternalCache">Saving cache files</a></li> - </ol></li> - <li><a href="#db">Using Databases</a> - <ol> - <li><a href="#dbDebugging">Database debugging</a></li> - </ol></li> + <li><a href="#filesInternal">Using the Internal Storage</a></li> + <li><a href="#filesExternal">Using the External Storage</a></li> + <li><a href="#db">Using Databases</a></li> <li><a href="#netw">Using a Network Connection</a></li> </ol> @@ -449,7 +436,7 @@ applications.</p> <p>The Android SDK includes a {@code sqlite3} database tool that allows you to browse table contents, run SQL commands, and perform other useful functions on SQLite -databases. See <a href="{@docRoot}guide/developing/tools/adb.html#sqlite">Examining sqlite3 +databases. See <a href="{@docRoot}tools/help/adb.html#sqlite">Examining sqlite3 databases from a remote shell</a> to learn how to run this tool. </p> diff --git a/docs/html/guide/topics/data/index.html b/docs/html/guide/topics/data/index.html deleted file mode 100644 index a94f8c0..0000000 --- a/docs/html/guide/topics/data/index.html +++ /dev/null @@ -1,9 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=data-storage.html"> -<title>Redirecting...</title> -</head> -<body> -<a href="data-storage.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/data/index.jd b/docs/html/guide/topics/data/index.jd new file mode 100644 index 0000000..1e082b3 --- /dev/null +++ b/docs/html/guide/topics/data/index.jd @@ -0,0 +1,23 @@ +page.title=Data Storage +page.landing=true +page.landing.intro=Store application data in databases, files, or preferences, in internal or removeable storage. You can also add a data backup service to let users store and recover application and system data. +page.landing.image= + +@jd:body + +<div class="landing-docs"> + + + <div class="col-12"> + <h3>Training</h3> + + <a href="http://developer.android.com/training/cloudsync/index.html"> + <h4>Syncing to the Cloud</h4> + <p>This class covers different strategies for cloud enabled applications. It covers syncing +data with the cloud using your own back-end web application, and backing up data using the cloud so +that users can restore their data when installing your application on a new device.</p> + </a> + + </div> + +</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/data/install-location.jd b/docs/html/guide/topics/data/install-location.jd new file mode 100644 index 0000000..19c4b39 --- /dev/null +++ b/docs/html/guide/topics/data/install-location.jd @@ -0,0 +1,206 @@ +page.title=App Install Location +@jd:body + + +<div id="qv-wrapper"> +<div id="qv"> + + <h2>Quickview</h2> + <ul> + <li>You can allow your application to install on the device's external storage.</li> + <li>Some types of applications should <strong>not</strong> allow installation on the external +storage.</li> + <li>Installing on the external storage is ideal for large applications that are not tightly +integrated with the system (most commonly, games).</li> + </ul> + + <h2>In this document</h2> + <ol> + <li><a href="#Compatiblity">Backward Compatibility</a></li> + <li><a href="#ShouldNot">Applications That Should NOT Install on External Storage</a></li> + <li><a href="#Should">Applications That Should Install on External Storage</a></li> + </ol> + + <h2>See also</h2> + <ol> + <li><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"> +<manifest></a></code></li> + </ol> + +</div> +</div> + +<p>Beginning with API Level 8, you can allow your application to be installed on the +external storage (for example, the device's SD card). This is an optional feature you can declare +for your application with the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code +android:installLocation}</a> manifest attribute. If you do +<em>not</em> declare this attribute, your application will be installed on the internal storage +only and it cannot be moved to the external storage.</p> + +<p>To allow the system to install your application on the external storage, modify your +manifest file to include the <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code +android:installLocation}</a> attribute in the <code><a +href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element, +with a value of either "{@code preferExternal}" or "{@code auto}". For example:</p> + +<pre> +<manifest xmlns:android="http://schemas.android.com/apk/res/android" + android:installLocation="preferExternal" + ... > +</pre> + +<p>If you declare "{@code preferExternal}", you request that your application be installed on the +external storage, but the system does not guarantee that your application will be installed on +the external storage. If the external storage is full, the system will install it on the internal +storage. The user can also move your application between the two locations.</p> + +<p>If you declare "{@code auto}", you indicate that your application may be installed on the +external storage, but you don't have a preference of install location. The system will +decide where to install your application based on several factors. The user can also move your +application between the two locations.</p> + +<p>When your application is installed on the external storage:</p> +<ul> + <li>There is no effect on the application performance so long +as the external storage is mounted on the device.</li> + <li>The {@code .apk} file is saved on the external storage, but all private user data, +databases, optimized {@code .dex} files, and extracted native code are saved on the +internal device memory.</li> + <li>The unique container in which your application is stored is encrypted with a randomly +generated key that can be decrypted only by the device that originally installed it. Thus, an +application installed on an SD card works for only one device.</li> + <li>The user can move your application to the internal storage through the system settings.</li> +</ul> + +<p class="warning"><strong>Warning:</strong> When the user enables USB mass storage to share files +with a computer or unmounts the SD card via the system settings, the external storage is unmounted +from the device and all applications running on the external storage are immediately killed.</p> + + + +<h2 id="Compatiblity">Backward Compatibility</h2> + +<p>The ability for your application to install on the external storage is a feature available only +on devices running API Level 8 (Android 2.2) or greater. Existing applications that were built prior +to API Level 8 will always install on the internal storage and cannot be moved to the external +storage (even on devices with API Level 8). However, if your application is designed to support an +API Level <em>lower than</em> 8, you can choose to support this feature for devices with API Level 8 +or greater and still be compatible with devices using an API Level lower than 8.</p> + +<p>To allow installation on external storage and remain compatible with versions lower than API +Level 8:</p> +<ol> + <li>Include the {@code android:installLocation} attribute with a value of "{@code auto}" or +"{@code preferExternal}" in the <code><a +href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><manifest></a></code> +element.</li> + <li>Leave your {@code android:minSdkVersion} attribute as is (something <em>less +than</em> "8") and be certain that your application code uses only APIs compatible with that +level.</li> + <li>In order to compile your application, change your build target to API Level 8. This is +necessary because older Android libraries don't understand the {@code android:installLocation} +attribute and will not compile your application when it's present.</li> +</ol> + +<p>When your application is installed on a device with an API Level lower than 8, the {@code +android:installLocation} attribute is ignored and the application is installed on the internal +storage.</p> + +<p class="caution"><strong>Caution:</strong> Although XML markup such as this will be ignored by +older platforms, you must be careful not to use programming APIs introduced in API Level 8 +while your {@code minSdkVersion} is less than "8", unless you perform the work necessary to +provide backward compatibility in your code. For information about building +backward compatibility in your application code, see the <a +href="{@docRoot}resources/articles/backward-compatibility.html">Backward Compatibility</a> +article.</p> + + + +<h2 id="ShouldNot">Applications That Should NOT Install on External Storage</h2> + +<p>When the user enables USB mass storage to share files with their computer (or otherwise +unmounts or removes the external storage), any application +installed on the external storage and currently running is killed. The system effectively becomes +unaware of the application until mass storage is disabled and the external storage is +remounted on the device. Besides killing the application and making it unavailable to the user, +this can break some types of applications in a more serious way. In order for your application to +consistently behave as expected, you <strong>should not</strong> allow your application to be +installed on the external storage if it uses any of the following features, due to the cited +consequences when the external storage is unmounted:</p> + +<dl> + <dt>Services</dt> + <dd>Your running {@link android.app.Service} will be killed and will not be restarted when +external storage is remounted. You can, however, register for the {@link +android.content.Intent#ACTION_EXTERNAL_APPLICATIONS_AVAILABLE} broadcast Intent, which will notify +your application when applications installed on external storage have become available to the +system again. At which time, you can restart your Service.</dd> + <dt>Alarm Services</dt> + <dd>Your alarms registered with {@link android.app.AlarmManager} will be cancelled. You must +manually re-register any alarms when external storage is remounted.</dd> + <dt>Input Method Engines</dt> + <dd>Your <a href="{@docRoot}resources/articles/on-screen-inputs.html">IME</a> will be +replaced by the default IME. When external storage is remounted, the user can open system settings +to enable your IME again.</dd> + <dt>Live Wallpapers</dt> + <dd>Your running <a href="{@docRoot}resources/articles/live-wallpapers.html">Live Wallpaper</a> +will be replaced by the default Live Wallpaper. When external storage is remounted, the user can +select your Live Wallpaper again.</dd> + <dt>Live Folders</dt> + <dd>Your <a href="{@docRoot}resources/articles/live-folders.html">Live Folder</a> will be +removed from the home screen. When external storage is remounted, the user can add your Live Folder +to the home screen again.</dd> + <dt>App Widgets</dt> + <dd>Your <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widget</a> will be removed +from the home screen. When external storage is remounted, your App Widget will <em>not</em> be +available for the user to select until the system resets the home application (usually not until a +system reboot).</dd> + <dt>Account Managers</dt> + <dd>Your accounts created with {@link android.accounts.AccountManager} will disappear until +external storage is remounted.</dd> + <dt>Sync Adapters</dt> + <dd>Your {@link android.content.AbstractThreadedSyncAdapter} and all its sync functionality will +not work until external storage is remounted.</dd> + <dt>Device Administrators</dt> + <dd>Your {@link android.app.admin.DeviceAdminReceiver} and all its admin capabilities will +be disabled, which can have unforeseeable consequences for the device functionality, which may +persist after external storage is remounted.</dd> + <dt>Broadcast Receivers listening for "boot completed"</dt> + <dd>The system delivers the {@link android.content.Intent#ACTION_BOOT_COMPLETED} broadcast +before the external storage is mounted to the device. If your application is installed on the +external storage, it can never receive this broadcast.</dd> + <dt>Copy Protection</dt> + <dd>Your application cannot be installed to a device's SD card if it uses Google Play's + Copy Protection feature. However, if you use Google Play's + <a href="{@docRoot}guide/google/play/licensing.html">Application Licensing</a> instead, your + application <em>can</em> be installed to internal or external storage, including SD cards.</dd> +</dl> + +<p>If your application uses any of the features listed above, you <strong>should not</strong> allow +your application to install on external storage. By default, the system <em>will not</em> allow your +application to install on the external storage, so you don't need to worry about your existing +applications. However, if you're certain that your application should never be installed on the +external storage, then you should make this clear by declaring <a +href="{@docRoot}guide/topics/manifest/manifest-element.html#install">{@code +android:installLocation}</a> with a value of "{@code internalOnly}". Though this does not +change the default behavior, it explicitly states that your application should only be installed +on the internal storage and serves as a reminder to you and other developers that this decision has +been made.</p> + + +<h2 id="Should">Applications That Should Install on External Storage</h2> + +<p>In simple terms, anything that does not use the features listed in the previous section +are safe when installed on external storage. Large games are more commonly the types of +applications that should allow installation on external storage, because games don't typically +provide additional services when inactive. When external storage becomes unavailable and a game +process is killed, there should be no visible effect when the storage becomes available again and +the user restarts the game (assuming that the game properly saved its state during the normal +<a href="{@docRoot}guide/components/activities.html#Lifecycle">Activity lifecycle</a>).</p> + +<p>If your application requires several megabytes for the APK file, you should +carefully consider whether to enable the application to install on the external storage so that +users can preserve space on their internal storage.</p> + |