Unit 4.6: Using Text Files

Files and Persistent Storage

A file provides storage for data that persists when the program is not running. Unlike variables and objects stored in RAM, data saved to a file remains even after the program has finished executing or the computer is shut down. The data in a file can be retrieved during program execution.

Connecting to a File

A file can be connected to a program using the File and Scanner classes. These two classes work together to bridge your Java code with the physical data stored on your hard drive or SSD.

The File Object Constructor

A file is opened by creating a File object, using the name of the file as the argument of the constructor.

• File(String str): This is the File constructor that accepts a String representing the pathname for the file. The pathname tells Java exactly where the file is located on the computer.

Creating a Physical File

It is important to remember that the constructor new File("name.txt") only creates a memory representation of the path. To actually create a new, empty file on your disk, you must use the createNewFile() method.

Task: Creating a new physical file on the disk.

// In the main method ...
public void makeNewFile() throws IOException 
{
    File file = new File("newfile.txt");
    
    // createNewFile() returns true if the file was created, 
    // and false if the file already exists.
    if (file.createNewFile()) 
    {
        System.out.println("File created: " + file.getName());
    } 
    else 
    {
        System.out.println("File already exists.");
    }
}

Accessing Files in Folders

In simple exercises, you might provide a basic file name like scores.txt. However, in a real-world Java application, you cannot simply retrieve a file from a random folder using a relative path. Instead, files must be organized into packages that are part of the Classpath.

What is the Classpath?

The Classpath is a collection of directories and ZIP/JAR files that the Java Virtual Machine (JVM) searches to find your compiled .class files and other required resources (like .txt files). It essentially defines the "world" of data that your program is allowed to see and interact with.

Organization into Packages

To ensure your program is portable and reliable, data files are typically placed within the project's folder structure inside specific packages. When the program executes, these packages are included in the classpath, allowing the code to locate the files consistently.

Task: Identifying file paths within a project structure.

// In the main method ...
// Accessing a file directly in the project root
File f1 = new File("scores.txt");

// Accessing a file inside a specific package structure (e.g., "assets/data")
File f2 = new File("src/assets/data/results.txt");

Handling IOException

When working with files, operations can fail (e.g., the file doesn't exist). This can cause an IOException. Java requires you to indicate what to do if the file with the provided name cannot be opened. The simplest way to handle this possibility is to add throws IOException to the header of the method where the file is being accessed.

Task: Using throws IOException in a method header.

import java.io.File;        // Represents the file pathname
import java.io.IOException; // Handles potential file errors
import java.util.Scanner;   // Provides methods to read the file

public class DataReader 
{
    // The "throws" keyword goes after the parentheses in the header
    public void printScores() throws IOException 
    {
        // This will fail because such a file does not exist
        File myFile = new File("no_such_file_exists.txt");
        Scanner sc = new Scanner(myFile); // This line throws IOException
        
        while (sc.hasNext()) 
        {
            System.out.println(sc.next());
        }
        sc.close();
    }
}

If the file name provided is invalid and the exception is not handled, the program will terminate.

Packages and Imports

The File and IOException classes are part of the java.io package. An import statement must be used to make these classes available for use in your program.

import java.io.File;        // Bridge to the file system
import java.io.IOException; // Error handling for file access
import java.util.Scanner;   // Tools for reading data (from java.util)

Using the Wildcard (*)

If you are using many classes from the same package, you can use the asterisk (*) wildcard to import every class in that package at once.

import java.io.*;   // Imports File, IOException, and everything else in java.io
import java.util.*; // Imports Scanner, ArrayList, and everything else in java.util

The Scanner Class for File Input

The following Scanner methods and constructor—including what they do and when they are used—are part of the Java Quick Reference.

• Scanner(File f): This is the required constructor for this unit. It takes an existing File object and connects the scanner to the contents of that file.

Assume a file contains: 10 20.5 true Java is fun

Task: Reading diverse tokens using Scanner.

// In the main method ...
Scanner sc = new Scanner(new File("data.txt"));
int val = sc.nextInt();
double dVal = sc.nextDouble();
String sVal = sc.next();

nextLine() and Whitespace Handling

Mixing nextLine() with other Scanner methods (like nextInt()) requires caution because numeric methods leave the newline character (\n) in the buffer.

Task: Demonstrating the nextLine() buffer pitfall.

// Logic Error Example:
int age = sc.nextInt();    // Reads 18, but leaves \n in buffer
String name = sc.nextLine(); // Reads the \n and results in an EMPTY string!

The split() Method

The split(String del) method is used to break a single String into an array of smaller strings. The parameter del stands for delimiter.

What is a Delimiter?

A delimiter is a character or sequence of characters that marks the boundary between separate pieces of data.

Examples of Different Delimiters

1. Splitting by Space (The most common "default") If you want to break a sentence into individual words, use a space " " as the delimiter.

// In the main method ...
String sentence = "Java is fun";
String[] words = sentence.split(" "); 
// result: {"Java", "is", "fun"}

2. Splitting by Comma (CSV Data) Comma-Separated Values (CSV) are common in data files.

String csvData = "Apples,10,0.99";
String[] items = csvData.split(","); 
// result: {"Apples", "10", "0.99"}

3. Splitting by Semicolon or Colon You can use any character that separates your data points.

String record = "ID101:John:Smith";
String[] parts = record.split(":"); 
// result: {"ID101", "John", "Smith"}

Handling Empty Strings

When using split(), consecutive delimiters or delimiters at the boundaries of a string can produce empty strings (""). Java treats these in two different ways:

1. Leading and Middle Empty Strings: These are preserved and included in the resulting array.
2. Trailing Empty Strings: By default, any empty strings at the end of the resulting array are discarded.

Task: Observing how split() handles empty resulting strings.

// In the main method ...
// 1. Leading and Middle: Both are preserved
String s1 = ",apple,,banana";
String[] res1 = s1.split(","); // {"", "apple", "", "banana"}

// 2. Trailing: These are discarded
String s2 = "apple,banana,,";
String[] res2 = s2.split(",");
// result: {"apple", "banana"} (length 2)
// The two empty strings at the end were thrown away!

• Scanner: Automatically splits data by any whitespace (spaces, tabs, newlines) unless you tell it otherwise.
• String.split(): Requires you to explicitly state the delimiter. It does not have an automatic default.

Example Comparison:

String data = "apple banana cherry";

// 1. Scanner handles spaces automatically
Scanner sc = new Scanner(data); 
String s1 = sc.next(); // Result: "apple"

// 2. String.split() requires you to pass " " 
String[] fruits = data.split(" "); // Result: {"apple", "banana", "cherry"}

Traversing a File

A while loop can be used to detect if the file still contains elements to read by using the hasNext method as the condition of the loop.

Task: Using a while loop to read all tokens in a file.

import java.io.File;
import java.io.IOException;
import java.util.Scanner;

public void printFile(File f) throws IOException
{
    Scanner sc = new Scanner(f);
    while (sc.hasNext())
    {
        System.out.println(sc.next());
    }
    sc.close();
}

Resource Management

A file should be closed when the program is finished using it. The close() method from the Scanner class is called to close the file and release the system resources.

Scanner Pitfalls and Exceptions

Working with the Scanner class requires careful management of its internal state.

1. Multiple next() calls in one loop

A common mistake is calling next() more than once inside a while (sc.hasNext()) loop. Each call to next() moves the cursor forward. If you call it twice, you might "skip" data or run out of tokens before the next check.

Task: Identifying dangerous multiple-call logic.

// DANGEROUS CODE:
while (sc.hasNext()) 
{
    String first = sc.next();
    String second = sc.next(); // Error if there is only one word left!
}

2. Common Runtime Exceptions

• NoSuchElementException: Thrown if you call next(), nextInt(), etc., but the scanner has already reached the end of the data. Always use hasNext() before reading!
• IllegalStateException: Thrown if you attempt to use any scanner method (like next() or hasNext()) after the close() method has been called.
• InputMismatchException: Thrown if the data being read doesn't match the expected type (e.g., calling nextInt() when the next word is "hello").

Excluded from AP CSA Exam

The following concepts and syntaxes are outside the scope of the AP Computer Science A course and exam.

// EXCLUDED: Interactive console input
Scanner sc = new Scanner(System.in); 

int age = sc.nextInt();
sc.nextLine(); // "Consume" the leftover newline manually
String name = sc.nextLine(); // NOW it waits for the actual name

// EXCLUDED: Splitting by a literal period
String filename = "data.txt";
String[] parts = filename.split("\\."); // The \\ tells Java "this is just a dot"