STUDENT OUTLINE

Lesson 14 - Text File I/O

INTRODUCTION:

In this lesson you will learn about text file input and output using the Java Scanner and PrintWriter classes. The source programs you have been writing are all stored as text files. After this lesson you will have a greater understanding of how files are saved and retrieved.

Sending output to disk and reading text files from disk are a bit harder because we need to watch for errors or "exceptions". Reading from a text file also requires us to watch out for the EOF (end-of-file) sentinel value. After this lesson, many of the programming exercises will work with data stored in text files.


The key topics for this lesson:

A. Standard ASCII Text Files
B. Exception Handling
C. Saving Text Files to Disk using the PrintWriter Class
D. Reading Text Files from Disk using the Scanner Class

VOCABULARY:

TEXT FILE
EXCEPTION
TRY-CATCH BLOCK

THROW
EOF
EXTERNAL FILE

DISCUSSION:

A. Standard ASCII Text Files

1.A text file is a sequential access file that stores characters. A sequential file is one which must be read from the beginning of the file, and then element by element. You must read the file from the beginning. You cannot jump to any location in the file.

2. A random access file is one where the program can access any element in the file, given its location in the file. Random access files are available in Java, but they will not be covered in this curriculum guide.

3. An ASCII text file is stored using the ASCII codes for each keystroke. An 'a' is ASCII code 97, which is eventually stored in binary format (using ones and zeroes) on disk.


4. A text file is organized by lines, just as a printed page would be. Each line ends with a special character (or characters), called the eoln (end-of-line) marker. Different operating systems (Windows, MacOS, Unix) separate lines of text in different ways. In Java environments, the eoln marker corresponds to the return key and has an ASCII value of 10 ('\n'), 13 ('\r') or a combination of both.

5. The eof (end of file) marks the termination of a text file. There is no standard character for eof. Instead, each operating system has its own way to handle eof. Various standard Java stream processing tools are available to create and detect the eof.

6. A text file has as many eoln's as there are lines in the file, but only one eof marker.

7. A text file can store numeric data, but integer and float types are converted into text format. For example, the character '4' is stored as ASCII code 52.

8. When a text file is stored on disk, it can be thought of as one long stream of ASCII codes. The following text example on screen would be stored as one long list of ASCII codes on disk.

Apple
IBM

Disk text file (for Windows):

65  112  112  108  101  13  10  73  66  77  "eof"
A    P    P    L    E    eoln   I   B   M

B. Exception Handling

1. Exception handling is a mechanism in Java designed to handle errors that disrupt the flow of execution during runtime. Raising an exception is a useful way to signal that a routine could not execute normally. Exceptions are especially useful when Java is trying to read from or write to a device, like a hard drive, a DVD, a USB port, a network port, etc.

2. Reading from or writing to a file on the hard drive can cause an exception to occur. Java requires that you specify how these exceptions are handled. Java provides a try-catch block to handle them. Program 14-1 is an example.

Program 14-1

    try 
    {
    	<open the file>...
    } 
    catch (<exceptionName> id) 
    {
    	<do this if file is not found>...
    }

In this example, the try block contains a command which opens a file and can throw (detect) an exception. If the file is not found, an exception is thrown and Java proceeds to the catch block which contains the error handling commands you specify.

4. If you try to open a file without using a try-catch block, the compiler will produce the following error:

		unreported exception; <exceptionName>
		must be caught or declared to be thrown

C. Saving Text Files to Disk using the PrintWriter Class

1. The PrintWriter class is used to write text to files. An output stream is an object used to transfer data from memory to a file. A PrintWriter object must be declared to allow a program to write to a text file. The PrintWriter object must also be embedded in a try-catch block in case an exception occurs. For example, the effect of the following program is to create a file named "output.txt" which will receive the output shown below. Notice that numbers are saved as text in the file.

Program 14-2
import java.io.File;
import java.io.IOException;
import java.io.PrintWriter;

public class SaveTextFile 
{
	 PrintWriter outFile;
	  
 
	public static void main (String[] args)   
	{
		SaveTextFile stf = new SaveTextFile();
		stf.Run();
		 
	}
	 
	public void Run()   
	{
		     File ioFile = new File("output.txt");
		try      
		{
			    outFile = new PrintWriter( ioFile );
		}
		      catch (IOException e)      
		{
			    e.printStackTrace();
			    System.exit(1);
		}
		for (int i = 4; i < 10; i++)outFile.printf("i = %d\n", i);
		outFile.close();
		 
	}
}
      
	Run output to "output.txt":
        i = 4
        i = 5
        i = 6
        i = 7
        i = 8
        i = 9

2. In Program 14-2, the try block declares and initializes outFile. 

	PrintWriter outFile = new PrintWriter( new File("output.txt") );

This declaration wipes out the contents of the file "output.txt", if it exists, and starts with a blank file.

3. If the file "output.txt" cannot be created, then PrintWriter throws IOException which is handled by the catch block. 

	catch (IOException e)
        {
	    e.printStackTrace();
	    System.exit(1);
	}

In this case, the catch block prints the execution stack trace to the screen, then exits the program.

4. If the file "output.txt" is successfully created, then Java ignores the catch block and continues with the rest of the program.

5. PrintWriter provides print(), println(), and printf() methods, the same as in System.out, to write data to a file. For example: 

		int i = 4;
		outFile.print("i = " + i + "\n");
		outFile.println("i = " + i);
		outFile.printf("i = %d\n", i);

Each of these print statements output "i = 4" to the file.

6. A close() method is provided to finalize file processing and to mark the eof in the file. The close() method should always be used when a program is finished writing to a file. If a file is not closed, the program might end before the operating system has finished writing data to the file. The last data in the file might be lost!

 

D. Reading Text Files from Disk using the Scanner Class

1.The Scanner class is used to read text from files. An input stream is an object used to transfer data from a file to memory. The syntax of declaring and initializing (opening) an Scanner object is identical to that of PrintWriter objects. Once initialized, we can use all of the methods associated with the Scanner class to retrieve data from a text file.

2. Reading a text file assumes that the file already exists at some external location. If the file does not exist or cannot be opened, then Scanner will throw a FileNotFoundException that forces Java to execute the catch block. If the file is successfully opened, then Java will ignore the catch block and continue with the rest of the program.

3. The following example Program 14-3 will read a text file of integer data and echo its contents to the terminal. The contents of "data.txt" are shown to the right of program 14-3.

Program 14-3

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


public class ReadData 
{
	 private Scanner inFile;
	 private int number;
	 
	public static void main(String[] args)   
	{
		  ReadData rd = new ReadData();
		  rd.Run2();
		  
	}
	   
	public void Run2()   
	{
		String fileName = "data.txt";
		     File inputFile = new File(fileName);
		try      
		{
			inFile = new Scanner( inputFile );
		}
		      catch (FileNotFoundException e)      
		{
			System.err.printf("ERROR: Cannot open %s\n", fileName);
			System.exit(1);
		}
		while (inFile.hasNext())      
		{
			number = inFile.nextInt();
			System.out.print(number + "   ");
		}
		inFile.close();
		 
	}
}

data.txt


-2
-1
0
1
2
" eof" 

	Run output:

		-2   -1   0   1   2

4. A text file always has a special sentinel, or eof (end of file) marker. The Scanner's hasNext() method detects this sentinel marker. It returns true if the input file has another piece of information or false if it has reached the end of file.

5. In Program 14-3, the while loop reads the 5 integers from the file and echoes them to the screen. When it detects the eof, it closes the file.

SUMMARY/ REVIEW:

Text files can be used to store, manipulate, and move information from one location to another. Such files can be used to transfer information from one environment (Macintosh to Windows) and even from one application to another (word processor to spreadsheet). While there are many ways to get the job done, this lesson has attempted to show the cleanest methods to manipulate text files.