CPS251 Android Development by Scott Shaper

File Management

Imagine you're building a note-taking app or a file manager. You need to save user data, load files, and manage documents. Just like a filing cabinet where you store and organize papers, file management in Android apps lets you save data to files, read files, and organize information. Whether you're saving user preferences, storing downloaded content, or managing app data, understanding file management is essential for building apps that need to persist information.

In this lesson, we'll learn how to work with files in Android, including reading and writing text files, managing app storage, and handling file permissions. We'll create a simple note-taking app that can save and load notes from files.

When to Use File Management

  • When saving user data or preferences
  • When storing downloaded content or media files
  • When creating note-taking or document apps
  • When implementing data export or import features
  • When caching data for offline use
  • When storing app logs or debugging information
  • When managing user-generated content
  • When implementing file sharing between apps

Key File Management Concepts

Concept What It Does When to Use It
Context.filesDir Gets the app's private internal storage directory When you need to store files only your app can access
Context.getExternalFilesDir() Gets the app's external storage directory When you need more storage space or user-accessible files
File Represents a file or directory path When you need to work with files and directories
FileInputStream / FileOutputStream Reads from or writes to files When you need to read or write file data
BufferedReader / BufferedWriter Efficiently reads or writes text files When working with text files
use Automatically closes resources when done When you want to ensure files are properly closed
exists() Checks if a file or directory exists Before reading files to avoid errors

Project Setup: Note Taking App

Let's start by setting up our NoteTaking project. This will be a simple app that demonstrates how to save and load notes from files.

Step 1: Understanding Storage Locations

Android provides different storage locations for files:

  • Internal Storage - Private to your app, cleared when app is uninstalled
  • External Storage - Can be accessed by other apps, may persist after uninstall
  • Cache Storage - Temporary files that can be cleared by the system

Step 2: Understanding the App Structure

Our NoteTaking app will have a simple structure with:

  • Note List - Shows all saved notes
  • Note Editor - Create or edit notes
  • File Operations - Save and load notes from files
  • Note Management - Delete and organize notes

Step 3: Creating the Data Model

First, let's create our data model. Create a new file called Note.kt:

package com.example.notetaking

import java.util.Date

// Data class representing a note
data class Note(
    val id: String,
    val title: String,
    val content: String,
    val createdAt: Long = System.currentTimeMillis(),
    val updatedAt: Long = System.currentTimeMillis()
)

What this does:

  • id - Unique identifier for each note
  • title - The title of the note
  • content - The main content of the note
  • createdAt - When the note was created
  • updatedAt - When the note was last updated

Step 4: Creating a File Manager

Now let's create a class to handle file operations. Create FileManager.kt:

package com.example.notetaking

import android.content.Context
import kotlinx.serialization.Serializable
import kotlinx.serialization.encodeToString
import kotlinx.serialization.json.Json
import java.io.File
import java.io.FileInputStream
import java.io.FileOutputStream

@Serializable
data class NoteData(
    val id: String,
    val title: String,
    val content: String,
    val createdAt: Long,
    val updatedAt: Long
)

class FileManager(private val context: Context) {
    private val notesFileName = "notes.json"
    
    // Get the file where we'll store notes
    private fun getNotesFile(): File {
        // Use internal storage - private to this app
        val filesDir = context.filesDir
        return File(filesDir, notesFileName)
    }
    
    // Save notes to a file
    fun saveNotes(notes: List): Boolean {
        return try {
            val file = getNotesFile()
            val notesData = notes.map { note ->
                NoteData(
                    id = note.id,
                    title = note.title,
                    content = note.content,
                    createdAt = note.createdAt,
                    updatedAt = note.updatedAt
                )
            }
            
            val json = Json { prettyPrint = true }
            val jsonString = json.encodeToString(notesData)
            
            // Write to file
            FileOutputStream(file).use { outputStream ->
                outputStream.write(jsonString.toByteArray())
            }
            true
        } catch (e: Exception) {
            e.printStackTrace()
            false
        }
    }
    
    // Load notes from a file
    fun loadNotes(): List {
        return try {
            val file = getNotesFile()
            
            // Check if file exists
            if (!file.exists()) {
                return emptyList()
            }
            
            // Read from file
            val jsonString = FileInputStream(file).use { inputStream ->
                inputStream.bufferedReader().use { reader ->
                    reader.readText()
                }
            }
            
            // Parse JSON
            val json = Json { ignoreUnknownKeys = true }
            val notesData = json.decodeFromString>(jsonString)
            
            // Convert to Note objects
            notesData.map { data ->
                Note(
                    id = data.id,
                    title = data.title,
                    content = data.content,
                    createdAt = data.createdAt,
                    updatedAt = data.updatedAt
                )
            }
        } catch (e: Exception) {
            e.printStackTrace()
            emptyList()
        }
    }
    
    // Save a single note as a text file (simpler example)
    fun saveNoteAsText(note: Note): Boolean {
        return try {
            val filesDir = context.filesDir
            val file = File(filesDir, "${note.id}.txt")
            
            FileOutputStream(file).use { outputStream ->
                outputStream.bufferedWriter().use { writer ->
                    writer.write("Title: ${note.title}\n\n")
                    writer.write(note.content)
                }
            }
            true
        } catch (e: Exception) {
            e.printStackTrace()
            false
        }
    }
    
    // Load a note from a text file
    fun loadNoteFromText(noteId: String): String? {
        return try {
            val filesDir = context.filesDir
            val file = File(filesDir, "$noteId.txt")
            
            if (!file.exists()) {
                return null
            }
            
            FileInputStream(file).use { inputStream ->
                inputStream.bufferedReader().use { reader ->
                    reader.readText()
                }
            }
        } catch (e: Exception) {
            e.printStackTrace()
            null
        }
    }
}

Key features:

  • context.filesDir - Gets the app's private internal storage
  • File - Represents a file path
  • FileOutputStream - Writes data to files
  • FileInputStream - Reads data from files
  • use - Automatically closes files when done
  • exists() - Checks if a file exists before reading

Step 5: Creating a Simple Text File Example

Let's create a simpler example that works with plain text files. Create SimpleFileManager.kt:

package com.example.notetaking

import android.content.Context
import java.io.File
import java.io.FileInputStream
import java.io.FileOutputStream

class SimpleFileManager(private val context: Context) {
    private val notesDirName = "notes"
    
    // Get or create the notes directory
    private fun getNotesDirectory(): File {
        val filesDir = context.filesDir
        val notesDir = File(filesDir, notesDirName)
        if (!notesDir.exists()) {
            notesDir.mkdirs() // Create directory if it doesn't exist
        }
        return notesDir
    }
    
    // Save a note to a text file
    fun saveNote(note: Note): Boolean {
        return try {
            val notesDir = getNotesDirectory()
            val file = File(notesDir, "${note.id}.txt")
            
            FileOutputStream(file).use { outputStream ->
                outputStream.bufferedWriter().use { writer ->
                    writer.write("${note.title}\n")
                    writer.write("---\n")
                    writer.write("${note.content}\n")
                    writer.write("---\n")
                    writer.write("Created: ${note.createdAt}\n")
                    writer.write("Updated: ${note.updatedAt}\n")
                }
            }
            true
        } catch (e: Exception) {
            e.printStackTrace()
            false
        }
    }
    
    // Load a note from a text file
    fun loadNote(noteId: String): Note? {
        return try {
            val notesDir = getNotesDirectory()
            val file = File(notesDir, "$noteId.txt")
            
            if (!file.exists()) {
                return null
            }
            
            val lines = FileInputStream(file).use { inputStream ->
                inputStream.bufferedReader().use { reader ->
                    reader.readLines()
                }
            }
            
            if (lines.size < 5) {
                return null
            }
            
            val title = lines[0]
            val content = lines[2] // Skip the "---" separator
            val createdAt = lines[4].substringAfter("Created: ").toLongOrNull() ?: 0L
            val updatedAt = lines[5].substringAfter("Updated: ").toLongOrNull() ?: 0L
            
            Note(
                id = noteId,
                title = title,
                content = content,
                createdAt = createdAt,
                updatedAt = updatedAt
            )
        } catch (e: Exception) {
            e.printStackTrace()
            null
        }
    }
    
    // Get all note IDs from the directory
    fun getAllNoteIds(): List {
        return try {
            val notesDir = getNotesDirectory()
            notesDir.listFiles()?.map { file ->
                file.nameWithoutExtension
            } ?: emptyList()
        } catch (e: Exception) {
            e.printStackTrace()
            emptyList()
        }
    }
    
    // Delete a note file
    fun deleteNote(noteId: String): Boolean {
        return try {
            val notesDir = getNotesDirectory()
            val file = File(notesDir, "$noteId.txt")
            if (file.exists()) {
                file.delete()
            } else {
                false
            }
        } catch (e: Exception) {
            e.printStackTrace()
            false
        }
    }
}

Step 6: Creating the Note List Screen

Now let's create a screen that displays all notes. Create NoteListScreen.kt:

package com.example.notetaking

import androidx.compose.foundation.layout.*
import androidx.compose.foundation.lazy.LazyColumn
import androidx.compose.foundation.lazy.items
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.Add
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp
import java.text.SimpleDateFormat
import java.util.*

@Composable
fun NoteListScreen(
    notes: List,
    onNoteClick: (Note) -> Unit,
    onAddNoteClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    Scaffold(
        floatingActionButton = {
            FloatingActionButton(onClick = onAddNoteClick) {
                Icon(
                    imageVector = Icons.Default.Add,
                    contentDescription = "Add Note"
                )
            }
        }
    ) { paddingValues ->
        if (notes.isEmpty()) {
            Box(
                modifier = modifier
                    .fillMaxSize()
                    .padding(paddingValues)
                    .padding(top = 50.dp),
                contentAlignment = androidx.compose.ui.Alignment.Center
            ) {
                Column(
                    horizontalAlignment = androidx.compose.ui.Alignment.CenterHorizontally
                ) {
                    Text(
                        text = "No notes yet",
                        style = MaterialTheme.typography.titleLarge
                    )
                    Spacer(modifier = Modifier.height(8.dp))
                    Text(
                        text = "Tap the + button to create your first note",
                        style = MaterialTheme.typography.bodyMedium
                    )
                }
            }
        } else {
            LazyColumn(
                modifier = modifier
                    .fillMaxSize()
                    .padding(paddingValues)
                    .padding(top = 50.dp),
                contentPadding = PaddingValues(16.dp),
                verticalArrangement = Arrangement.spacedBy(8.dp)
            ) {
                items(notes) { note ->
                    NoteListItem(
                        note = note,
                        onClick = { onNoteClick(note) }
                    )
                }
            }
        }
    }
}

@Composable
fun NoteListItem(
    note: Note,
    onClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    val dateFormat = SimpleDateFormat("MMM dd, yyyy", Locale.getDefault())
    val formattedDate = dateFormat.format(Date(note.updatedAt))
    
    Card(
        modifier = modifier
            .fillMaxWidth()
            .clickable(onClick = onClick)
    ) {
        Column(
            modifier = Modifier.padding(16.dp)
        ) {
            Text(
                text = note.title,
                style = MaterialTheme.typography.titleMedium
            )
            Spacer(modifier = Modifier.height(4.dp))
            Text(
                text = note.content.take(100) + if (note.content.length > 100) "..." else "",
                style = MaterialTheme.typography.bodyMedium,
                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.7f),
                maxLines = 2
            )
            Spacer(modifier = Modifier.height(8.dp))
            Text(
                text = formattedDate,
                style = MaterialTheme.typography.bodySmall,
                color = MaterialTheme.colorScheme.onSurface.copy(alpha = 0.6f)
            )
        }
    }
}

Step 7: Creating the Note Editor Screen

Let's create a screen for creating and editing notes. Create NoteEditorScreen.kt:

package com.example.notetaking

import androidx.compose.foundation.layout.*
import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.filled.ArrowBack
import androidx.compose.material.icons.filled.Save
import androidx.compose.material3.*
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.unit.dp

@Composable
fun NoteEditorScreen(
    note: Note?,
    onSave: (Note) -> Unit,
    onBackClick: () -> Unit,
    modifier: Modifier = Modifier
) {
    var title by remember { mutableStateOf(note?.title ?: "") }
    var content by remember { mutableStateOf(note?.content ?: "") }
    
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text(if (note == null) "New Note" else "Edit Note") },
                navigationIcon = {
                    IconButton(onClick = onBackClick) {
                        Icon(
                            imageVector = Icons.Default.ArrowBack,
                            contentDescription = "Back"
                        )
                    }
                },
                actions = {
                    IconButton(
                        onClick = {
                            val noteToSave = Note(
                                id = note?.id ?: System.currentTimeMillis().toString(),
                                title = title,
                                content = content,
                                createdAt = note?.createdAt ?: System.currentTimeMillis(),
                                updatedAt = System.currentTimeMillis()
                            )
                            onSave(noteToSave)
                            onBackClick()
                        },
                        enabled = title.isNotBlank() || content.isNotBlank()
                    ) {
                        Icon(
                            imageVector = Icons.Default.Save,
                            contentDescription = "Save"
                        )
                    }
                }
            )
        }
    ) { paddingValues ->
        Column(
            modifier = modifier
                .fillMaxSize()
                .padding(paddingValues)
                .padding(16.dp),
            verticalArrangement = Arrangement.spacedBy(16.dp)
        ) {
            OutlinedTextField(
                value = title,
                onValueChange = { title = it },
                label = { Text("Title") },
                modifier = Modifier.fillMaxWidth(),
                singleLine = true
            )
            
            OutlinedTextField(
                value = content,
                onValueChange = { content = it },
                label = { Text("Content") },
                modifier = Modifier
                    .fillMaxWidth()
                    .weight(1f),
                minLines = 10
            )
        }
    }
}

Step 8: Updating MainActivity

Finally, let's update MainActivity.kt to use our file management:

package com.example.notetaking

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.activity.enableEdgeToEdge
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.Scaffold
import androidx.compose.runtime.*
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalContext
import com.example.notetaking.ui.theme.NoteTakingTheme
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        setContent {
            NoteTakingTheme {
                Scaffold(modifier = Modifier.fillMaxSize()) { innerPadding ->
                    NoteTakingApp(modifier = Modifier.padding(innerPadding))
                }
            }
        }
    }
}

@Composable
fun NoteTakingApp(modifier: Modifier = Modifier) {
    val context = LocalContext.current
    val fileManager = remember { SimpleFileManager(context) }
    val scope = rememberCoroutineScope()
    
    var notes by remember { mutableStateOf>(emptyList()) }
    var selectedNote by remember { mutableStateOf(null) }
    var isEditing by remember { mutableStateOf(false) }
    
    // Load notes when app starts
    LaunchedEffect(Unit) {
        withContext(Dispatchers.IO) {
            val noteIds = fileManager.getAllNoteIds()
            notes = noteIds.mapNotNull { id ->
                fileManager.loadNote(id)
            }
        }
    }
    
    if (isEditing) {
        NoteEditorScreen(
            note = selectedNote,
            onSave = { note ->
                scope.launch(Dispatchers.IO) {
                    fileManager.saveNote(note)
                    // Reload notes
                    val noteIds = fileManager.getAllNoteIds()
                    notes = noteIds.mapNotNull { id ->
                        fileManager.loadNote(id)
                    }
                }
            },
            onBackClick = {
                isEditing = false
                selectedNote = null
            }
        )
    } else {
        NoteListScreen(
            notes = notes,
            onNoteClick = { note ->
                selectedNote = note
                isEditing = true
            },
            onAddNoteClick = {
                selectedNote = null
                isEditing = true
            }
        )
    }
}

Understanding Each Part of the Implementation

File Operations:

  • context.filesDir - Gets the app's private storage directory
  • File - Represents a file path
  • FileOutputStream - Writes data to files
  • FileInputStream - Reads data from files
  • use - Automatically closes files

Directory Management:

  • mkdirs() - Creates directories if they don't exist
  • exists() - Checks if files or directories exist
  • listFiles() - Gets all files in a directory

Error Handling:

  • Try-catch blocks - Handle file operation errors
  • Check if files exist - Avoid errors when reading
  • Return null or empty lists - Handle missing files gracefully

What This App Demonstrates

This NoteTaking app demonstrates several important concepts:

Basic File Operations
  • Saving Files - How to write data to files
  • Loading Files - How to read data from files
  • File Organization - Organizing files in directories
Storage Management
  • Internal Storage - Using app-private storage
  • File Naming - Creating meaningful file names
  • Directory Creation - Organizing files in folders

Running the App

To run the NoteTaking app:

  1. Open the project in Android Studio
  2. Build and run the app on a device or emulator
  3. Test the following features:
    • Create a new note
    • Save the note (it will be saved to a file)
    • Close and reopen the app (notes should persist)
    • Edit an existing note
    • View the note list

Why This Implementation is Important

This example demonstrates how to:

  • Save data to files for persistence across app sessions
  • Load data from files when the app starts
  • Organize files in directories for better management
  • Handle file errors gracefully
  • Use internal storage for app-private data

By understanding file management, you can create apps that save user data, cache content, and persist information between app sessions. This is essential for any app that needs to store data locally, whether it's a note-taking app, a game with saved progress, or any app that needs to remember user preferences.

Tips for Success

  • Always use use when working with files to ensure they're closed
  • Check if files exist before reading to avoid errors
  • Use context.filesDir for app-private storage
  • Create directories with mkdirs() before saving files
  • Handle file operations in background threads (Dispatchers.IO)
  • Use meaningful file names that help identify content
  • Organize files in directories for better management
  • Always handle exceptions when working with files
  • Test file operations with different scenarios (missing files, etc.)
  • Consider file size when saving large amounts of data

Common Mistakes to Avoid

  • Forgetting to close files, causing resource leaks
  • Not checking if files exist before reading
  • Not handling exceptions when file operations fail
  • Performing file operations on the main thread
  • Not creating directories before saving files
  • Using unclear file names that are hard to identify
  • Not organizing files in directories
  • Forgetting to handle cases where files don't exist
  • Not testing file persistence across app restarts
  • Ignoring file size limits and storage constraints

Best Practices

  • Always use use to ensure files are properly closed
  • Check file existence before reading to avoid crashes
  • Handle all file operations in try-catch blocks
  • Perform file I/O on background threads (Dispatchers.IO)
  • Use meaningful file and directory names
  • Organize files logically in directories
  • Test file operations thoroughly, including error cases
  • Consider using JSON or other structured formats for complex data
  • Monitor file sizes to avoid storage issues
  • Provide user feedback when file operations succeed or fail