In this document

See also

Android provides several options for you to save persistent application data. The solution you
choose depends on your specific needs, such as whether the data should be private to your
application or accessible to other applications (and the user) and how much space your data
requires.

Android provides a way for you to expose even your private data to other applications
— with a content
provider. A content provider is an optional component that exposes read/write access to
your application data, subject to whatever restrictions you want to impose. For more information
about using content providers, see the
Content Providers
documentation.

Using Shared Preferences

The SharedPreferences class provides a general framework that allows you
to save and retrieve persistent key-value pairs of primitive data types. You can use SharedPreferences to save any primitive data: booleans, floats, ints, longs, and
strings. This data will persist across user sessions (even if your application is killed).

User Preferences

Shared preferences are not strictly for saving "user preferences," such as what ringtone a
user has chosen. If you're interested in creating user preferences for your application, see PreferenceActivity, which provides an Activity framework for you to create
user preferences, which will be automatically persisted (using shared preferences).

Using the Internal Storage

You can save files directly on the device's internal storage. By default, files saved
to the internal storage are private to your application and other applications cannot access
them (nor can the user). When the user uninstalls your application, these files are removed.

Tip: If you want to save a static file in your application at
compile time, save the file in your project res/raw/ directory. You can open it with
openRawResource(), passing the
R.raw.<filename> resource ID. This method returns an InputStream
that you can use to read the file (but you cannot write to the original file).

Saving cache files

If you'd like to cache some data, rather than store it persistently, you should use getCacheDir() to open a File that represents the internal directory where your application should save
temporary cache files.

When the device is
low on internal storage space, Android may delete these cache files to recover space. However, you
should not rely on the system to clean up these files for you. You should always maintain the cache
files yourself and stay within a reasonable limit of space consumed, such as 1MB. When the user
uninstalls your application, these files are removed.

Using the External Storage

Every Android-compatible device supports a shared "external storage" that you can use to
save files. This can be a removable storage media (such as an SD card) or an internal
(non-removable) storage. Files saved to the external storage are world-readable and can
be modified by the user when they enable USB mass storage to transfer files on a computer.

Caution: External storage can become unavailable if the user mounts the
external storage on a computer or removes the media, and there's no security enforced upon files you
save to the external storage. All applications can read and write files placed on the external
storage and the user can remove them.

Using Scoped Directory Access

On Android 7.0 or later, if you need access to a specific directory on
external storage, use scoped directory access. Scoped directory access
simplifies how your application accesses standard external storage directories,
such as the Pictures directory, and provides a simple
permissions UI that clearly details what directory the application is
requesting access to. For more details on scoped directory access, see
Using
Scoped Directory Access.

If you need to both read and write files, then you need to request only the
WRITE_EXTERNAL_STORAGE permission, because it
implicitly requires read access as well.

Note: Beginning with Android 4.4, these permissions are not
required if you're reading or writing only files that are private to your app. For more
information, see the section below about
saving files that are app-private.

Checking media availability

Before you do any work with the external storage, you should always call getExternalStorageState() to check whether the media is available. The
media might be mounted to a computer, missing, read-only, or in some other state. For example,
here are a couple methods you can use to check the availability:

The getExternalStorageState() method returns other states that you
might want to check, such as whether the media is being shared (connected to a computer), is missing
entirely, has been removed badly, etc. You can use these to notify the user with more information
when your application needs to access the media.

Saving files that can be shared with other apps

Hiding your files from the Media Scanner

Include an empty file named .nomedia in your external files directory (note the dot
prefix in the filename). This prevents media scanner from reading your media
files and providing them to other apps through the MediaStore
content provider. However, if your files are truly private to your app, you should
save them in an app-private directory.

Generally, new files that the user may acquire through your app should be saved to a "public"
location on the device where other apps can access them and the user can easily copy them from the
device. When doing so, you should use to one of the shared public directories, such as Music/, Pictures/, and Ringtones/.

Saving files that are app-private

If you are handling files that are not intended for other apps to use
(such as graphic textures or sound effects used by only your app), you should use
a private storage directory on the external storage by calling getExternalFilesDir().
This method also takes a type argument to specify the type of subdirectory
(such as DIRECTORY_MOVIES). If you don't need a specific
media directory, pass null to receive
the root directory of your app's private directory.

Beginning with Android 4.4, reading or writing files in your app's private
directories does not require the READ_EXTERNAL_STORAGE
or WRITE_EXTERNAL_STORAGE
permissions. So you can declare the permission should be requested only on the lower versions
of Android by adding the maxSdkVersion
attribute:

Note:
When the user uninstalls your application, this directory and all its contents are deleted.
Also, the system media scanner does not read files in these directories, so they are not accessible
from the MediaStore content provider. As such, you should not
use these directories for media that ultimately belongs to the user, such as photos
captured or edited with your app, or music the user has purchased with your app—those
files should be saved in the public directories.

Sometimes, a device that has allocated a partition of the
internal memory for use as the external storage may also offer an SD card slot.
When such a device is running Android 4.3 and lower, the getExternalFilesDir() method provides
access to only the internal partition and your app cannot read or write to the SD card.
Beginning with Android 4.4, however, you can access both locations by calling
getExternalFilesDirs(),
which returns a File array with entries each location. The first entry in the array is considered
the primary external storage and you should use that location unless it's full or
unavailable. If you'd like to access both possible locations while also supporting Android
4.3 and lower, use the support library's
static method, ContextCompat.getExternalFilesDirs(). This also returns a File array, but always includes only one entry on Android 4.3 and lower.

Saving cache files

To open a File that represents the
external storage directory where you should save cache files, call getExternalCacheDir(). If the user uninstalls your
application, these files will be automatically deleted.

Tip:
To preserve file space and maintain your app's performance,
it's important that you carefully manage your cache files and remove those that aren't
needed anymore throughout your app's lifecycle.

Using Databases

Android provides full support for SQLite databases.
Any databases you create will be accessible by name to any
class in the application, but not outside the application.

The recommended method to create a new SQLite database is to create a subclass of SQLiteOpenHelper and override the onCreate() method, in which you
can execute a SQLite command to create tables in the database. For example:

Android does not impose any limitations beyond the standard SQLite concepts. We do recommend
including an autoincrement value key field that can be used as a unique ID to
quickly find a record. This is not required for private data, but if you
implement a content provider,
you must include a unique ID using the BaseColumns._ID
constant.

You can execute SQLite queries using the SQLiteDatabasequery() methods, which accept various query parameters, such as the table to query,
the projection, selection, columns, grouping, and others. For complex queries, such as
those that require column aliases, you should use
SQLiteQueryBuilder, which provides
several convienent methods for building queries.

Every SQLite query will return a Cursor that points to all the rows
found by the query. The Cursor is always the mechanism with which
you can navigate results from a database query and read rows and columns.

Database debugging

The Android SDK includes a sqlite3 database tool that allows you to browse
table contents, run SQL commands, and perform other useful functions on SQLite
databases. See Examining sqlite3
databases from a remote shell to learn how to run this tool.

Using a Network Connection

You can use the network (when it's available) to store and retrieve data on your own web-based
services. To do network operations, use classes in the following packages: