How to use files in android

Saving Files

This lesson teaches you to

You should also read

Android uses a file system that’s similar to disk-based file systems on other platforms. This lesson describes how to work with the Android file system to read and write files with the File APIs.

A File object is suited to reading or writing large amounts of data in start-to-finish order without skipping around. For example, it’s good for image files or anything exchanged over a network.

This lesson shows how to perform basic file-related tasks in your app. The lesson assumes that you are familiar with the basics of the Linux file system and the standard file input/output APIs in java.io .

Choose Internal or External Storage

All Android devices have two file storage areas: «internal» and «external» storage. These names come from the early days of Android, when most devices offered built-in non-volatile memory (internal storage), plus a removable storage medium such as a micro SD card (external storage). Some devices divide the permanent storage space into «internal» and «external» partitions, so even without a removable storage medium, there are always two storage spaces and the API behavior is the same whether the external storage is removable or not. The following lists summarize the facts about each storage space.

• It’s always available.
• Files saved here are accessible by only your app by default.
• When the user uninstalls your app, the system removes all your app’s files from internal storage.

Internal storage is best when you want to be sure that neither the user nor other apps can access your files.

• It’s not always available, because the user can mount the external storage as USB storage and in some cases remove it from the device.
• It’s world-readable, so files saved here may be read outside of your control.
• When the user uninstalls your app, the system removes your app’s files from here only if you save them in the directory from getExternalFilesDir() .

External storage is the best place for files that don’t require access restrictions and for files that you want to share with other apps or allow the user to access with a computer.

Tip: Although apps are installed onto the internal storage by default, you can specify the android:installLocation attribute in your manifest so your app may be installed on external storage. Users appreciate this option when the APK size is very large and they have an external storage space that’s larger than the internal storage. For more information, see App Install Location.

Obtain Permissions for External Storage

To write to the external storage, you must request the WRITE_EXTERNAL_STORAGE permission in your manifest file:

Caution: Currently, all apps have the ability to read the external storage without a special permission. However, this will change in a future release. If your app needs to read the external storage (but not write to it), then you will need to declare the READ_EXTERNAL_STORAGE permission. To ensure that your app continues to work as expected, you should declare this permission now, before the change takes effect.

However, if your app uses the WRITE_EXTERNAL_STORAGE permission, then it implicitly has permission to read the external storage as well.

You don’t need any permissions to save files on the internal storage. Your application always has permission to read and write files in its internal storage directory.

Save a File on Internal Storage

When saving a file to internal storage, you can acquire the appropriate directory as a File by calling one of two methods:

getFilesDir() Returns a File representing an internal directory for your app. getCacheDir() Returns a File representing an internal directory for your app’s temporary cache files. Be sure to delete each file once it is no longer needed and implement a reasonable size limit for the amount of memory you use at any given time, such as 1MB. If the system begins running low on storage, it may delete your cache files without warning.

To create a new file in one of these directories, you can use the File() constructor, passing the File provided by one of the above methods that specifies your internal storage directory. For example:

Alternatively, you can call openFileOutput() to get a FileOutputStream that writes to a file in your internal directory. For example, here’s how to write some text to a file:

Or, if you need to cache some files, you should instead use createTempFile() . For example, the following method extracts the file name from a URL and creates a file with that name in your app’s internal cache directory:

Note: Your app’s internal storage directory is specified by your app’s package name in a special location of the Android file system. Technically, another app can read your internal files if you set the file mode to be readable. However, the other app would also need to know your app package name and file names. Other apps cannot browse your internal directories and do not have read or write access unless you explicitly set the files to be readable or writable. So as long as you use MODE_PRIVATE for your files on the internal storage, they are never accessible to other apps.

Save a File on External Storage

Because the external storage may be unavailable—such as when the user has mounted the storage to a PC or has removed the SD card that provides the external storage—you should always verify that the volume is available before accessing it. You can query the external storage state by calling getExternalStorageState() . If the returned state is equal to MEDIA_MOUNTED , then you can read and write your files. For example, the following methods are useful to determine the storage availability:

Although the external storage is modifiable by the user and other apps, there are two categories of files you might save here:

Public files Files that should be freely available to other apps and to the user. When the user uninstalls your app, these files should remain available to the user.

For example, photos captured by your app or other downloaded files.

Private files Files that rightfully belong to your app and should be deleted when the user uninstalls your app. Although these files are technically accessible by the user and other apps because they are on the external storage, they are files that realistically don’t provide value to the user outside your app. When the user uninstalls your app, the system deletes all files in your app’s external private directory.

For example, additional resources downloaded by your app or temporary media files.

If you want to save public files on the external storage, use the getExternalStoragePublicDirectory() method to get a File representing the appropriate directory on the external storage. The method takes an argument specifying the type of file you want to save so that they can be logically organized with other public files, such as DIRECTORY_MUSIC or DIRECTORY_PICTURES . For example:

If you want to save files that are private to your app, you can acquire the appropriate directory by calling getExternalFilesDir() and passing it a name indicating the type of directory you’d like. Each directory created this way is added to a parent directory that encapsulates all your app’s external storage files, which the system deletes when the user uninstalls your app.

For example, here’s a method you can use to create a directory for an individual photo album:

If none of the pre-defined sub-directory names suit your files, you can instead call getExternalFilesDir() and pass null . This returns the root directory for your app’s private directory on the external storage.

Remember that getExternalFilesDir() creates a directory inside a directory that is deleted when the user uninstalls your app. If the files you’re saving should remain available after the user uninstalls your app—such as when your app is a camera and the user will want to keep the photos—you should instead use getExternalStoragePublicDirectory() .

Regardless of whether you use getExternalStoragePublicDirectory() for files that are shared or getExternalFilesDir() for files that are private to your app, it’s important that you use directory names provided by API constants like DIRECTORY_PICTURES . These directory names ensure that the files are treated properly by the system. For instance, files saved in DIRECTORY_RINGTONES are categorized by the system media scanner as ringtones instead of music.

Query Free Space

If you know ahead of time how much data you’re saving, you can find out whether sufficient space is available without causing an IOException by calling getFreeSpace() or getTotalSpace() . These methods provide the current available space and the total space in the storage volume, respectively. This information is also useful to avoid filling the storage volume above a certain threshold.

However, the system does not guarantee that you can write as many bytes as are indicated by getFreeSpace() . If the number returned is a few MB more than the size of the data you want to save, or if the file system is less than 90% full, then it’s probably safe to proceed. Otherwise, you probably shouldn’t write to storage.

Note: You aren’t required to check the amount of available space before you save your file. You can instead try writing the file right away, then catch an IOException if one occurs. You may need to do this if you don’t know exactly how much space you need. For example, if you change the file’s encoding before you save it by converting a PNG image to JPEG, you won’t know the file’s size beforehand.

Delete a File

You should always delete files that you no longer need. The most straightforward way to delete a file is to have the opened file reference call delete() on itself.

If the file is saved on internal storage, you can also ask the Context to locate and delete a file by calling deleteFile() :

Note: When the user uninstalls your app, the Android system deletes the following:

• All files you saved on internal storage
• All files you saved on external storage using getExternalFilesDir() .

However, you should manually delete all cached files created with getCacheDir() on a regular basis and also regularly delete other files you no longer need.

Источник

How to Correctly Store App-Specific Files in Android

Christophe Versieux (Waza_be) posted a rant about android developers’ bad habit to store files directly on the root of the sd card. I completely agree with the post. It’s bad usage to create app-specific folders directly at the root. If you install a lot of apps, the sd card’s root gets cluttered fast.

One comment also mentioned that most tutorials do not cover the app-specific folders, so let me correct that with a short tutorial on how to do it correctly.

App-specific files vs. app-independent files

If you need to store files there are generally two usage types:

• App independent data
• App specific data

I will cover both types in more detail in the following sections. But in short I would characterize those types as follows: App-specific files are those that only are useful for as long as the app is installed (e.g. ebooks in a proprietary format). App-independent files on the other hand are those that the user cares about regardless of the specific app that created them (e.g. photos).

App-independent files

This type of data is stuff your user very likely cares about, even if your app is no longer installed on the device. Examples are photos shot, images processed or sketched, code-files edited, audio files bought and so on.

For most of these types, Android provides special directories. A full list of directories that Android provides out of the box can be seen in the documentation of the Environment class. Those fields all start with «DIRECTORY». E.g. DIRECTORY_MUSIC or DIRECTORY_PICTURES.

Those files always have to be stored on the sd card (or the equivalent partition for devices that have no sd card slot like the Google Nexus line). The reason is, that those files tend to be quite large, that they need to be world-readable and that they must not be stored in a directory that get’s cleaned up when your app gets uninstalled. I will cover external storage in more detail in the following sections.

You can get access to the root of the sd card by calling the getExternalStorageDirectory() method on the Environment class.

And you can use getExternalStoragePublicDirectory(String type) to directly get a File object for any of the supported types:

It’s the usual Java IO API from here on.

App-specific files

This type of files is for any kind of data that only this specific app can or should make use of. This could be proprietary files like ebooks, media files that should not be available through the normal media players (e.g. thumbnails for CD covers), downloaded magazines, database files, preferences and so on.

App-specific files can be stored internally or externally (on the sd card) and the Android API helps you to find the appropriate directories.

What’s nice for app-specific folders that follow a certain naming convention is Android’s cleanup mechanism. Android takes care to delete these folder when users uninstall your app. This way Android gets rid of unnecessary files and users do not have to clean up manually after any deinstallation.

Internal storage versus external storage

You should know that there are two app-specific folders for any app. The internal one which you can use for private files and the external one. External storage refers to the sd card of Android devices or the equivalent partition that devices with no sd card option offer (e.g. the Nexus line).

Internal storage space can be limited

Especially for larger files you should prefer the external storage option. You should do so because internal storage space can be very limited depending on the device of your user. A probably extreme example is my old LG Optimus One that has only about 300 MB of internal storage. But with a 16 GB sd card I have plenty of external storage. Even if this device is one of the worst examples regarding internal storage, there are plenty of devices out there that also come with little internal storage. Not everyone uses high-end phones.

Permissions for writing to external storage

Whenever you want to access files on the external storage you need permissions to do so. Add this permissions to your manifest file:

The need to declare this permissions is a slight drawback compared to internal storage. Some users may be wary — especially if this adds to an already long list of permissions. But if you explain this in your app description you should be fine.

Note: For reading files of the sd card no permissions were needed prior to Jelly Bean. So you can leave this one out if your build target is lower than API level 16.

External storage might be unavailable

The biggest problem with external storage is, that it might be unmounted when you need it. That’s obviously the case when the sd card is ejected but also when your device is mounted for file access to your computer. Because of this, you always have to check, if the external storage is currently available:

Sometimes the external storage might be mounted read-only. If you only need to read data the following check is better suited for you:

This works since the value of the final field Environment.MEDIA_MOUNTED_READ_ONLY is «mounted_ro» . I actually do not like code, that uses knowledge of final fields’ value. In my opinion it would have been better, had Google chosen to use an integer so that we could use final fields as bitmasks to test for the state.

Internal app-specific directories

Android creates a directory private to your app for you. Your shared preferences go in here, as well as your SQLite databases, native libraries or cached files.

All app-specific files are within a folder named

Within this folder some common sub-folders might exist — depending on what your app needs:

• databases — for SQLite databases
• shared_prefs — for your preferences
• cache — for cache files and data
• lib — for native libraries
• files — for files that do not fit into other categories

The Context class provides some methods you can use to create new directories, open InputStreams and so on. The following table lists these methods:

Methods to help you with internal storage

Method	When to use
deleteFile(String name)	Deletes the file with the given name
fileList()	Returns a list of files
getDir(String name, int mode)	Returns a file object to this directory. If the directory doesn’t exist yet, it gets created.
getFilesDir()	Returns a File object pointing to the files directory
openFileInput(String name)	Opens an InputStream object to the file with the given name
openFileOutput(String name, int mode)	Opens an OutputStream object to the file with the given name. The file gets created if it does not exists

Some methods use a mode parameter. This can be any of the following constants of the Context class:

• MODE_APPEND
• MODE_PRIVATE
• MODE_WORLD_READABLE
• MODE_WORLD_WRITEABLE

These are int values and you can use the or operator («|») to combine them — e.g. to append to a world readable file:

External app-specific directories

This is where Waza_be’s rant comes into play — because too many apps ignore the correct handling of app-specific directories on external storage.

All external app-specific files should be stored within a folder named

Note that I use a relative path. This path is relative to the root of the sdcard. The convention of where sdcards are mounted, changed between Android releases.

It’s always good practice to use API calls instead of hard-coded values, but the fact that the mount-point has changed in the past should make you even more cautious.

Now for external files there exists only one method you can use:

If you pass in a null value the File object will point to the files directory. If you add any of the directory constants of the Environment class, you will get a File object pointing to a sub-directory within your files directory. If the directory doesn’t exits yet, Android creates it for you. If the external media is not mounted, the method returns null.

Note: This method has only been introduced with API Level 8 (that is Froyo or Android 2.2). In the next section I briefly touch on the issues you face when dealing with older devices.

Older devices

There are still devices out there on older versions, which you might want to support. In this case using the naming convention shown above is still a good idea.

Alas, neither the method getExternalFilesDir(String type) exists, nor does Android clean up after an app uninstall. But using the same naming convention still avoids too many irritating folders on the root of your sd card.

Cache

Many times you need to cache data you downloaded from the net or created within your app. Android allows you to use internal as well as external storage space to use the cache. But using the external storage can be risky, since your cache might be unavailable when you need it.

The Context object has two methods to get a File object for either the internal or the external cache directory:

You have to take care of the cache size yourself. Android deletes all files in both directories on an uninstallation of your app, but otherwise it’s up to you to clean up any cache files no longer needed.

If Android is running low on internal storage it cleans up cache files first but the API states explicitly that you should not rely on Android to clean up for you!

With the external cache storage Android doesn’t care at all. Even if the external storage is full, no cache files will be deleted.

Naming of the folder

The official naming convention for the folder contains your package name. Christophe Versieux (Waza_be) himself mentioned that he used to use the app name instead, since users are more familiar with the package name of the app.

Even though familiarity is something to consider, I do not agree with this statement. First of all the API call uses the package name, so why not use it. Only with this method you can rely to be on the safe side. Secondly Android only cleans up a folder using the package name. And finally you could get screwed since app names do not have to be unique. In this case you might end up doing stuff in your folder that clashes with the intentions of the other app.

Be aware of the «.nomedia»-switch

Android’s MediaScanner regularly scans the sd card for any media files and adds these to the public list of media files. Thus images will show up in the Gallery app or music files in audio players.

But that’s not always what you want. Sometimes those files really should be presented by your app only. That’s where «.nomedia» comes into play. If a folder contains a file named «.nomedia» it will be skipped by the MediaScanner and any media files will thus not show up in the public media list.

That’s another reason to use the standard app-specific folder. It contains the file «.nomedia» within the data directory so that any media files you add to your app-specific directory will not show up.

Lessons learned

In this tutorial you have heard about the difference between app-specific and app-independent files and how to apply this knowledge to Android.

Also you have seen how to use app-specific files on Android, and how to leverage the internal storage as well as the external storage.

In a follow up post I will cover how to add app-independent media files to the corresponding content providers, so that they show up immediately in the list of public media files. Stay tuned.

Edited:
Minor changes due to comments by +Alexandre Roman and +Cyril Mottier to my G+ announcement of this post.

Wolfram Rittmeyer lives in Germany and has been developing with Java for many years.

He has been interested in Android for quite a while and has been blogging about all kind of topics around Android.

Источник