Accessing the File System

Android devices are computers, with file systems that can be accessed using many of the same methods as for standard computers (see Transferring Files). In this project we give two examples of using the Android file system.

1. Writing to files on the SD card or other external media.


2. Reading data at runtime from static (read-only) files that are packaged with an application.

In later projects we shall use these methods and others to give additional examples of storing and retrieving information.

Creating the Project in Android Studio

Following the general procedure in Creating a New Project, either choose Start a new Android Studio project from the Android Studio homepage, or from the Android Studio interface choose File > New > New Project. Fill out the fields in the resulting screens as follows,

where you should substitute your namespace for <YourNamespace> (com.lightcone in my case) and <ProjectPath> is the path to the directory where you will store this Android Studio Project (/home/guidry/StudioProjects/ in my case). If you have chosen to use version control for your projects, go ahead and commit this project to version control.

Filling out the Code

We first insert all the Java and XML that we shall need and then we shall explain its functionality.

The XML Files

Edit the res/values/strings.xml file to read

<resources>
<string name="app_name">WriteSDCard</string>
<string name="action_settings">Settings</string>
<string name="hello">FILE SYSTEM I/O</string>
</resources>

and edit the res/layout/activity_main.xml file so that it reads:

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:tools="http://schemas.android.com/tools"
   android:layout_width="match_parent"
   android:layout_height="match_parent"
   android:paddingBottom="@dimen/activity_vertical_margin"
   android:paddingLeft="@dimen/activity_horizontal_margin"
   android:paddingRight="@dimen/activity_horizontal_margin"
   android:paddingTop="@dimen/activity_vertical_margin"
   tools:context=".MainActivity" >

   <TextView
      android:id="@+id/TextView01"
      android:layout_width="fill_parent"
      android:layout_height="wrap_content"
      android:textSize="15sp"
      android:textColor="@color/colorPrimary"
      android:text="@string/hello" />

</RelativeLayout>

The Manifest File

Next, we must modify the manifest file because we are going to need explicit permission to write to external files. Open AndroidManifest.xml and edit it to read

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="<YourNamespace>.writesdcard">

  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"
     android:maxSdkVersion="18" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">
        <activity android:name=".MainActivity">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />

                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>

</manifest>

where the added permission WRITE_EXTERNAL_STORAGE is highlighted in red.

The Java Class Files

Next, open the file java/<YourNamespace>.writesdcard/MainActivity.java and edit it to read

package <YourNamespace>.writesdcard;
   
import android.os.Bundle;
import android.support.v7.app.AppCompatActivity;

import java.io.BufferedReader;
import java.io.File;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.PrintWriter;

import android.os.Environment;
import android.util.Log;
import android.widget.TextView;

public class MainActivity extends AppCompatActivity {

    private static final String TAG = "MEDIA";
    private TextView tv;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        tv = (TextView) findViewById(R.id.TextView01);
        checkExternalMedia();
        writeToSDFile();
        readRaw();
    }

    /**
     * Method to check whether external media available and writable. This is adapted from
     * http://developer.android.com/guide/topics/data/data-storage.html#filesExternal
     */

    private void checkExternalMedia() {
        boolean mExternalStorageAvailable = false;
        boolean mExternalStorageWriteable = false;
        String state = Environment.getExternalStorageState();

        if (Environment.MEDIA_MOUNTED.equals(state)) {
            // Can read and write the media
            mExternalStorageAvailable = mExternalStorageWriteable = true;
        } else if (Environment.MEDIA_MOUNTED_READ_ONLY.equals(state)) {
            // Can only read the media
            mExternalStorageAvailable = true;
            mExternalStorageWriteable = false;
        } else {
            // Can't read or write
            mExternalStorageAvailable = mExternalStorageWriteable = false;
        }
            tv.append("\n\nEXTERNAL MEDIA: readable="
                + mExternalStorageAvailable + " writable=" + mExternalStorageWriteable);
    }

    /**
     * Method to write ascii text characters to file on SD card. In earlier versions of Android a
     * WRITE_EXTERNAL_STORAGE permission must be added to the manifest file or this method will throw
     * a FileNotFound Exception because you won't have write permission. But not true after
     * API 18 for files in storage area of app (then no write permission required).
     */

    private void writeToSDFile() {

        // Root of the external file system

        File root0 = android.os.Environment.getExternalStorageDirectory();

        /* Now find the root of the external storage for this app (where the app can place
        * persistent files that it owns internal to the application and not typically visible
        * to the user as media).  See
        *
        *    http://developer.android.com/guide/topics/data/data-storage.html#filesExternal
        *
        * The method getExternalFilesDir (string) returns the user storage associated with the
        * app, which doesn't require write permissions after API 18.  The string argument specifies various
        * regions of this storage.  For example,
        *
        * - null specifies the root of the storage for this app
        * - Environment.DIRECTORY_NOTIFICATIONS specifies the Notifications directory of app storage
        * - Environvment.DIRECTORY_DOWNLOADS specifies standard directory for files downloaded by user
        * - Environment.DIRECTORY_PICTURES specifies standard directory for pictures available to the user
        * - Environment.DIRECTORY_DOCUMENTS specifies standard directory for documents produced by user
        * etc.
        *
        * See the fields of the Environment class at
        *    https://developer.android.com/reference/android/os/Environment.html
        * for other possibilities.  For example, on my phone (running Android 6.0.1) the root of
        * the user storage for this specific app is found at
        *
        *    /storage/emulated/0/Android/data/com.lightcone.writesdcard/files
        * */

        // Root of the data directories Documents subdirectory specific to this app, for which no write
        // permission is required for Android 4.4 and later.

        File root = this.getExternalFilesDir(Environment.DIRECTORY_DOCUMENTS);

        tv.append("\n\nEXTERNAL FILE SYSTEM ROOT DIRECTORY:\n" + root0);

        tv.append("\n\nEXTERNAL APP DATA ROOT DIRECTORY:\n" + root);

        // Create a Documents/download subdirectory in the data area for this app
        // See http://stackoverflow.com/questions/3551821/android-write-to-sd-card-folder

        File dir = new File(root.getAbsolutePath() + "/download");
        dir.mkdirs();
        File file = new File(dir, "myData.txt");

        // Must catch FileNotFoundException and IOException
        try {
            FileOutputStream f = new FileOutputStream(file);
            PrintWriter pw = new PrintWriter(f);
            pw.println("Howdy do to you,");
            pw.println("and the horse you rode in on.");
            pw.flush();
            pw.close();
            f.close();
        } catch (FileNotFoundException e) {
            e.printStackTrace();
            Log.i(TAG, "File not found");
        } catch (IOException e) {
            e.printStackTrace();
            Log.i(TAG, "I/O exception");
        }
        tv.append("\n\nFILE WRITTEN TO:\n" + file);
    }

    /**
     * Method to read in a text file placed in the res/raw directory of the application. The
     * method reads in all lines of the file sequentially.
     */

    private void readRaw() {
        tv.append("\n\nDATA READ FROM res/raw/textfile.txt:\n");
        InputStream is = this.getResources().openRawResource(R.raw.textfile);
        InputStreamReader isr = new InputStreamReader(is);
        BufferedReader br = new BufferedReader(isr, 8192);    // 2nd arg is buffer size

        // More efficient (less readable) implementation of above is the composite expression
        //    BufferedReader br = new BufferedReader(new InputStreamReader(
        //             this.getResources().openRawResource(R.raw.textfile)), 8192);

        try {
            String test;
            while (true) {
                test = br.readLine();
                // readLine() returns null if no more lines in the file
                if (test == null) break;
                tv.append("\n" + "    " + test);
            }
            isr.close();
            is.close();
            br.close();
        } catch (IOException e) {
            e.printStackTrace();
        }
        tv.append("\n\nTHAT IS ALL");
    }
}

Adding Resources

Finally, to test part of our application we need to create the res/raw directory and place a file containing some lines of text in it.

1. If res/raw does not exist in the project, right click on the res directory in the left panel of Android Studio and select New > Directory. In the resulting window, give the folder the name raw and click OK.


2. Then, right-click on the new res/raw folder and select New > File. In the resulting window give the new file the name textfile.txt (with the .txt extension) and click OK.


3. Double click on the new res/raw/textfile.txt to open it in the editor and add several lines of text to it for testing purposes. For this example, I inserted into res/raw/textfile.txt

       Now is the time
       for all good men
       to come to the aid
       of their country.
   

   but you can put whatever you wish.

That completes our application. Now let's test it and explain what it does.

Trying it Out

Execution of the application on a phone or emulator should produce a display like the following figure

indicating that several tasks have been carried out:

1. The external file system (generically the SD card) has been checked for whether it is mounted and readable/writable.


2. The root directory of the external file system has been identified.


3. The root directory of the data directory for this app in the external file system has been identified.


4. A data file was written to
   
   /storage/emulated/0/Android/data/com.lightcone.writesdcard/files/Documents/download/myData.txt
   
   on the external file system.


5. Data were read in and displayed from a file res/raw/textfile.txt.

Let us now explain how the code in our XML and Java files carries this out.

Overview of Basic Functionality

First, we set up the ability to output results to our main display:

1. In a manner that should by now be familiar, a TextView object tv is defined by using FindViewByID().


2. Then, at various places, the append(CharSequence text) method of TextView is used to append additional information to that already displayed on the screen.

Besides the onCreate() method, there are three methods in MainActivity.java. Each implements a basic functionality:

1. The method checkExternalMedia() checks whether the device has external media installed and whether it is readable and writable.


2. The method writeToSDFile() writes some output to a file on the external SD card.


3. The method readRaw() reads input from a file installed with the application in the res/raw directory.

Let us now explain in turn how each of these methods works.

Checking External Media

To check the status of external storage media in the method checkExternalMedia(), we first invoke the getExternalStorageState() method of Environment to return a string that is stored in the variable state. This string is then compared, using the equals() method of the String class, with various String constants of the Environment class to determine the state of the external media.

• If state is equal to Environment.MEDIA_MOUNTED, the storage medium is present and mounted at its mount point, with read/write access.


• If state is equal to Environment.MEDIA_MOUNTED_READ_ONLY, the storage medium is present and mounted at its mount point, with read but not write access.


• If state has any other value, the storage medium is neither readable nor writable.

If the check is successful, we display the line on the screen

   EXTERNAL MEDIA: readable=true writable=true

Assuming this to be the case, in the next section we shall write to a file on the external storage medium.

Writing to a File on the SD Card

Assuming that we have a writable external medium, the method writeSDCard() illustrates how to output a file to that storage.

Finding the Root of External Storage

First, we use the getExternalStorageDirectory() method of Environment to return the root of the file system for the external medium, assigning the returned string to the Java File object root.

For example, when executed on a Nexus 6P phone running Android 6.0.1, the line

   EXTERNAL FILE SYSTEM ROOT DIRECTORY: /storage/emulated/0

was written to the screen, indicating that the external medium was mounted and writable, with the root of the filesystem at /storage/emulated/0.

But what is more relevant to the present application is the location of the user-writable storage allocated for this app (where the app can place persistent files that it owns internal to the application and not typically visible to the user as media). This is obtained using the getExternalFilesDir(String string) method of Context to return the root directory for writing app-specific data to the external medium, assigning the returned string to the Java File object root.

   /storage/emulated/0/Android/data/com.lightcone.writesdcard/files ,

The following screenshot shows part of the file structure on my phone in the directory /storage/emulated/0/Android/data.

We see that /storage/emulated/0/Android/data contains a whole set of directories associated with different package names. For example, there are six directories associated with the com.lightcone package name that I use for my apps, each distinguished by a different app name (including com.lightcone.writesdcard, which corresponds to the present app). Generally, for Android 4.4 and later external storage read/write permission is not required within the same package space but paths belonging to other packages require read/write external media permissions (see the documentation associated with getExternalFilesDir).

Setting Up the Path to the File

Now suppose that we wish create and write to a file called myData.txt in a subdirectory download of the root directory on the SD card for our app. The statements in MainActivity.java that set up the path up for that output are

File dir = new File (root.getAbsolutePath() + "/download");
dir.mkdirs();
File file = new File(dir, "myData.txt");

• The first line above creates a new instance of File using the constructor File(String path), where path is the path to the "file" (which in this case is actually going to be a directory).


• To construct this path we first use the getAbsolutePath() method that root inherits from File to return the absolute path corresponding to root (the root of the external-storage file system for the app), and then we concatenate that with the string "/download". The net effect in this case will be to pass to the File constructor the path

   /storage/emulated/0/Android/data/com.lightcone.writesdcard/files/Documents/download
  

• Then in the second line above we use the mkdirs() method of File, which creates the corresponding directory.


• Finally, in the third line above we define another instance of File called file (in this case it actually is a file and not a directory), creating it using a different version of the constructor File(File directory, String filename), where directory is the directory where the file is to be stored and filename is the name of the file.

Thus file now specifies the absolute path

 /storage/emulated/0/Android/data/com.lightcone.writesdcard/files/Documents/download/myData.txt

to the file into which we wish to write.

Writing Using Output Streams and Writers

To write to the file standard Java i/o stream capability is used, implemented in terms of the classes

1. FileOutputStream, which subclasses the abstract class OutputStream (the superclass of all classes representing an output stream of bytes) and generates a byte output stream.


2. PrintWriter, which is used to wrap the FileOutputStream and provide friendly user i/o (capability to deal with lines of ascii text rather than a byte stream).

The relevant code excerpted from the method writeToSDFile() is

try {
   FileOutputStream f = new FileOutputStream(file);
   PrintWriter pw = new PrintWriter(f);
   pw.println("Howdy do to you.");
   pw.println("Here is a second line.");
   pw.flush();
   pw.close();
   f.close();
} catch (FileNotFoundException e) {
   e.printStackTrace();
   Log.i(TAG, "File not found");
} catch (IOException e) {
   e.printStackTrace();
   Log.i(TAG, "I/O exception");
}

which creates a FileOutputStream, wraps it in a PrintWriter, and then appends lines to a file through this stream.

Handling Exceptions in the I/O

Note that all of the functional code above for the FileOuputStream is enclosed in a try-catch block. This is standard exception handling in Java.

1. The constructor FileOutputStream(File file) for FileOutputStream throws FileNotFoundException if the File in its argument cannot be found.


2. The method close() of FileOutputStream throws IOException if an error occurs in trying to close the stream.

Java requires that these exceptions be handled . The standard way to do that is in a try-catch block, which has the general form

try {
   // Code in which an exception might be thrown
   .
   .  
} catch (ExceptionType name1) {
   // Code to process exception type name1
   .
   .
} catch (ExceptionType name2) {
   // Code to process exception type name2
   .
   .
}

where one or more appended catch blocks process the named exceptions thrown in the try block. For a more extensive discussion of try-catch blocks, start with the Java Tutorials. In the present code the two catch blocks deal respectively with any FileNotFoundException or IOException that might be thrown in the try block.

For the catch block corresponding to FileNotFoundException we first invoke the printStackTrace() method that FileNotFoundException inherits from Throwable, which sends a human-readable form of the Throwable's stack trace to the System.err stream.

Within the try-catch block we then instantiate a FileOutputStream f using the constructor with the File file as argument, and create a PrintWriter pw using the just-created FileOutputStream f as argument. Now we can write to the file using the print methods of PrintWriter. In this case we use println(String s) to output lines of text to the file. When we are through writing, the flush() method of PrintWriter is called to ensure that all pending data have been sent to the file, and then the PrintWriter pw and FileOutputStream f are closed.

BufferedOutputStream b = new BufferedOutputStream(new FileOutputStream("file"));

Outputting a File

If this application is executed on a real device or emulator, the screen output shown above should result and you should find that the file

 /storage/emulated/0/Android/data/com.lightcone.writesdcard/files/Documents/download/myData.txt

has been written to the SD card (or equivalent external storage). You can check the content of the file by copying it to your computer using ADB or Android Studio, as described in Transferring Files, or by using a file-management app like WiFi File Explorer. For example, on my Linux Fedora 23 system connected to an Android phone I used ADB to give

   [guidry@m33 ~]$ adb -d pull /storage/emulated/0/Android/data/com.lightcone.writesdcard/files/Documents/download/myData.txt
   0 KB/s (40 bytes in 0.081s)
   [guidry@m33 ~]$ cat myData.txt
   Howdy do to you,
   and the horse you rode in on.
   [guidry@m33 ~]$

indicating that our application has indeed written the requested output to the file on the phone's external storage, and that this file is publicly accessible. (The adb -d pull command copies the file from the device to the computer and the Unix cat command displays the content of the file on the computer.)

Appending Rather Than Overwriting

The default behavior of the output stream that we created above is to overwrite the file if it already exists. We can instead append to the file if it already exists by substituting for the constructor FileOutputStream (File file) the constructor FileOutputStream(File file, boolean append), where the file will be overwritten if append is false and appended to if append is true.

Reading from a Static Resource File

The method readRaw() illustrates one way to set up an input stream to read in an external file. In this example we assume the external file to be ascii text in the res/raw directory of the application, and read it in line by line until no lines remain.

Input Streams and Readers

We begin by defining a buffered reader using the following code sequence.

InputStream is = this.getResources().openRawResource(R.raw.textfile);
InputStreamReader isr = new InputStreamReader(is);
BufferedReader br = new BufferedReader(isr, 8192);    // 2nd arg is buffer size

• The method getResources() is inherited by Activity from ContextWrapper. It returns a Resources instance (Resources is the class that sits above the asset manager for the application and gives access to an application's resources).


• The Resources openRawResource(int resourceID) method returns an InputStream named is, where resourceID is of the form res.raw.myfile.txt, if the file to be input is called myfile.txt and resides in the res/raw directory of the application.

• An InputStreamReader instance isr is then created using the constructor with the InputStream is as argument. An InputStreamReader reads a buffer of bytes from the source stream and converts these into characters as needed.


• Finally, we create a BufferedReader from isr using the constructor BufferedReader(Reader reader, int buffsize), where reader is an instance of the class Reader and buffsize is the size of the read-in buffer in bytes. (Reader is the superclass of all readers, which are means of reading data character-wise from a source; for example, InputStreamReader is a subclass of Reader.)

InputStream is = this.getResources().openRawResource(R.raw.textfile);
InputStreamReader isr = new InputStreamReader(is);
BufferedReader br = new BufferedReader(isr, 8192);

BufferedReader br = new BufferedReader(new InputStreamReader(
this.getResources().openRawResource(R.raw.textfile)), 8192);

• With our buffered input now set up we execute a while-loop, reading data in from the file a line at a time using the readLine() method of BufferedReader.


• Since readline() returns null when there are no more lines in the file, we check for null and break from the while-loop when it is found. We then use the close() methods of the readers and streams to close them all.


• Because readLine() and the close() methods throw the checked exception IOException, we enclose all of this in a try-catch block to process any i/o exceptions.

Testing Read-In from a File

If you execute the application, you should find the lines that you put in the file res/raw/textfile.txt displayed on the screen because of the tv.append() statement in the while-loop. As seen in the figure above, for my example I obtained

    Now is the time
    for all good men
    to come to the aid
    of their country.

which corresponds exactly to the four lines that I inserted in the file res/raw/textfile.txt when it was created.

Last modified: July 8, 2016