Construction. The File Class

[comp1110-95]
  • Fabian Muehlboeck

Java's File class specifies objects that represent abstract file paths, and through them, the directories and files in your file system. To create an instance, you need to use the new operator, and give a path as an argument.

File f = new File(pathToFile);

With the above f, you can now call a number of methods:

  • f.exists()

    Returns a boolean that is true if the file or directory exists, false if it does not

  • f.delete()

    Deletes the file or directory. A directory has to be empty for this to work.

  • f.getName()

    Returns the name of the file or directory - useful if you are just given a File object without having created it.

  • f.getParent()

    Returns a different File object representing the parent directory of the file or directory, if that exists (the root directort "/" has no parent, so this would return null)

  • f.isDirectory()

    Returns true if the path represents a directory

  • f.isFile()

    Returns true if the path represents a file

  • f.listfiles()

    If f represents a directory, returns an array containing File objects representing all the files contained in the directory

  • f.mkdir()

    Creates a directory at the path represented by f

You can further use it as an argument to create FileReaders and FileWriters.

Context

    Files and File I/O

    [comp1110-94]
    • Fabian Muehlboeck

    So far, we have navigated the file system and created directories using a terminal emulator, and we have created and edited files using an editor like nano. We can do the same things programmatically in Java, which lets our programs store data for the long term and exchange data with other programs more easily.

    Construction. The File Class

    [comp1110-95]
    • Fabian Muehlboeck

    Java's File class specifies objects that represent abstract file paths, and through them, the directories and files in your file system. To create an instance, you need to use the new operator, and give a path as an argument.

    File f = new File(pathToFile);

    With the above f, you can now call a number of methods:

    • f.exists()

      Returns a boolean that is true if the file or directory exists, false if it does not

    • f.delete()

      Deletes the file or directory. A directory has to be empty for this to work.

    • f.getName()

      Returns the name of the file or directory - useful if you are just given a File object without having created it.

    • f.getParent()

      Returns a different File object representing the parent directory of the file or directory, if that exists (the root directort "/" has no parent, so this would return null)

    • f.isDirectory()

      Returns true if the path represents a directory

    • f.isFile()

      Returns true if the path represents a file

    • f.listfiles()

      If f represents a directory, returns an array containing File objects representing all the files contained in the directory

    • f.mkdir()

      Creates a directory at the path represented by f

    You can further use it as an argument to create FileReaders and FileWriters.

    Character Encodings

    [comp1110-7A]
    • Fabian Muehlboeck

    Files are essentially arrays of bytes stored on your computer. Sometimes that is fine and the bytes are all we care about - this is the case for Java's .class files, which are not really human-readable. For our purposes, however, we are mostly concerned with text files, which should consist of human-readable characters.

    On modern computers, bytes consist of 8 bits (0-or-1 values), which means a byte can have 256 possible values, as can Java's char data type. That is enough to store the latin alphabet, arabic numerals, and a number of standard punctuation characters, as in ASCII, but it is not enough to store various other ways of writing and the much larger set of special symbols people use, including emojis.

    These days, most text files (especially on the web) are encoded using UTF-8, which has the advantage of being compatible with the important parts of ASCII, in that the first 128 symbols are encoded identically, so any two files that only use characters in that range look the same in UTF-8 and ASCII. Other symbols may use more than one byte, which makes things a bit more complicated.

    On the other hand, Java internally encodes its Strings using UTF-16. Luckily, this is mostly something that you do not need to worry about. Java will by default assume that files are encoded in UTF-8 and do the necessary translation.

    We mentions this only because of two things: if you exchange data with some other system and start seeing strange symbols, it might be an encoding issue, at which point you should follow up on this more. More importantly for us, though, is that the fact that different encodings exist explains the way that reading and writing files works in Java.

    Construction. Reading Files

    [comp1110-96]
    • Fabian Muehlboeck

    Interacting with files is risky business, much more so than all the other things we have done in the course so far. This is because they are shared with other programs and users that might work with them at the same time we do. Files might exist one moment and then not anymore, without our program having done anything, just because some other program deleted it. They might exist but cannot be opened, because the user running our program does not have permission to read it, or because there is some deeper problem with the file system.

    For that reason, Java specifies a number of checked exceptions that you need to deal with when opening files and reading, usually under the umbrella of IOException. In principle, when opening a file, you can have access to the raw bytes in the file. However, for now, we use the FileReader class, which implicitly assumes that the file is encoded using UTF-8 (though you can specify a different encoding when creating the FileReader; that won't be necessary in this course). The FileReader's role is to interpret the files in the appropriate encoding, and so it's core functionality is to read UTF-16 (Java's internal encoding) code points one by one. It has a utility method that gives you all lines in a file at once, but that is often undesirable, especially for large files.

    To be able to easily read a file line-by-line, we have to use a BufferedReader. A BufferedReader requires some underlying reader, like a FileReader, to provide the actual data. The main thing it does is provide a readLine() method, which reads the next line in the file since the last time you called it.

    This is a way in which objects have behavior that changes their state. A FileReader starts at the beginning of a file and moves forward in it with every byte that it reads. As the BufferedReader asks it to keep reading data until it reaches a line ending, each call of readLine() moves the internal state ahead by as many bytes as are needed to represent the line.

    File f = new File(pathToFile); try { BufferedReader reader = new BufferedReader(new FileReader(f)); // use reader.readLine() to read the next line from the file // when the reader reaches the end of the file, reader.readLine() // will return null } catch(IOException e) { // handle error }

    Construction. try-with-resources

    [comp1110-97]
    • Fabian Muehlboeck

    Opening a file reserves resources on your computer. Conflicts over such resources may arise when multiple programs try to access the resources at the same time. Additionally, not every operation on such resources will necessarily happen immediately. For example, reading from and writing to files is somewhat expensive, so we use something like BufferedReader and (coming up) BufferedWriter, which try to combine several smaller operations into bigger ones, meaning that a number of smaller writes will not immediately take effect until there are enough of them. If your program crashes in the meantime, it is likely that such data will be lost. Closing an open file forces any remaining data to be written and any required resources to be returned to the operating system.

    Therefore, it is a good idea to keep things clean and tidy, and close an open file as soon as you do not need it anymore (at least for the time being - you can always reopen it later). All readers and writers have a close() method to do just that. However, given that lots of exceptions can happen when interacting with files, guaranteeing that the file will be closed regardless of what happens can be tricky. By default, this is what the finally block of the try-catch-finally construct is for:

    try { FileReader fr = new FileReader(theFile); try { BufferedReader reader = new BufferedReader(fr); // use the reader } finally { if(reader != null) { reader.close(); } } } catch(IOException e) { // handle IOException } finally { if(fr != null) { fr.close(); } }

    Since this is a very standard pattern, a variant of try-catch-finally, called "try-with-resources", makes this more concise:

    try(FileReader fr = new FileReader(theFile); BufferedReader reader = new BufferedReader(fr)) { // use the reader } catch(IOException e) { // handle IOException }

    In this case, the BufferedReader and the FileReader will automatically be close in that order (reversed order of declaration) whenever program execution leaves the try-with-resources block. The two code blocks here are not perfectly equivalent because the ordering of closing the reader and handling the IOException is different, but that typically does not really matter.

    Construction. Writing Files

    [comp1110-98]
    • Fabian Muehlboeck

    Writing files shares many considerations with reading files. As such, the pattern is rather similar, but instead of a FileReader, we use a FileWriter, and instead of a BufferedReader, we use a BufferedWriter.

    try(FileWriter fw = new FileWriter(theFile); BufferedWriter writer = new BufferedWriter(fw)) { // use the writer } catch(IOException e) { // handle IOException }

    The BufferedWriter does not have a writeLine or printLine method. Instead, you have to use the write method and add a newline character yourself:

    writer.write(someString + "\n");

    Here, "\n" is a string consisting of a single newline character '\n'. Backslashes \ start what is called an escape sequence, expressing characters that are not easily printable. To include a backslash itself, you have to write "\\". The newline character '\n' (also called "line feed" or "LF") is the standard way of expressing line breaks on Linux and modern MacOS. (Very) old Macs used a different character, '\r' (called "carriage return" or "CR", representing the idea of resetting the position of your typewriter to the start of a line).

    Not to be outdone, Windows programs represent line breaks using a combination of the two, as "\r\n" (also described as "CRLF"). However, most Windows programs also recognize '\n' on its own as a line break (and BufferedReader considers any of the three to be terminating a line).

    For this reason, it is usually fine to stick with just using '\n' as line break if you do not need to keep compatibility with specific Windows programs. Alternatively, you can use BufferedReader's newLine method, which will write a system-specific line break (i.e. usually either '\n' or "\r\n") to your file at the current position:

    writer.write(someString); writer.newLine();

    Finally, BufferedReader does not necessarily write everything to your file right away. If you want to make sure that everything you have written so far makes it to your file even if your program crashes at some later point, use the method flush().

    writer.write(someString); writer.newLine(); writer.flush(); // everything written so far will // definitely be written to the file now

    In any case, flush will automatically be part of closing the file, say at the end of a try-with-resources.

    Example. Reading and Writing from a File

    [comp1110-99]
    • Fabian Muehlboeck

    In the lecture, we wrote a program that asks the user for some input, and if it has been run before, will display the input it got the last time we ran the program. We picked the name ".storage" for a file that would store the last input in between program runs. The "." at the start of the filename means this file should normally be hidden, as it is meant as internal data for programs, not for users to interact with outside of it. You can still find it and edit it manually if you wish.

    void main() { File store = new File(".storage"); if(store.exists()) { try(FileReader fr = new FileReader(store); BufferedReader reader = new BufferedReader(fr)) { String lastSentence = reader.readLine(); IO.println("Last time, you said: "+lastSentence); } catch(IOException e) { IO.println("ERROR: "+e.getMessage()); } } else { IO.println("Hello for the first time!"); } String input = IO.readln("Tell us something new! "); try(FileWriter fw = new FileWriter(store); BufferedWriter writer = new BufferedWriter(fw)) { writer.write(input); //no need to print a newline anyway // short program, no explicit flush needed } catch(IOException e) { IO.println("ERROR: "+e.getMessage()); } }

    Related

      Construction. Reading Files

      [comp1110-96]
      • Fabian Muehlboeck

      Interacting with files is risky business, much more so than all the other things we have done in the course so far. This is because they are shared with other programs and users that might work with them at the same time we do. Files might exist one moment and then not anymore, without our program having done anything, just because some other program deleted it. They might exist but cannot be opened, because the user running our program does not have permission to read it, or because there is some deeper problem with the file system.

      For that reason, Java specifies a number of checked exceptions that you need to deal with when opening files and reading, usually under the umbrella of IOException. In principle, when opening a file, you can have access to the raw bytes in the file. However, for now, we use the FileReader class, which implicitly assumes that the file is encoded using UTF-8 (though you can specify a different encoding when creating the FileReader; that won't be necessary in this course). The FileReader's role is to interpret the files in the appropriate encoding, and so it's core functionality is to read UTF-16 (Java's internal encoding) code points one by one. It has a utility method that gives you all lines in a file at once, but that is often undesirable, especially for large files.

      To be able to easily read a file line-by-line, we have to use a BufferedReader. A BufferedReader requires some underlying reader, like a FileReader, to provide the actual data. The main thing it does is provide a readLine() method, which reads the next line in the file since the last time you called it.

      This is a way in which objects have behavior that changes their state. A FileReader starts at the beginning of a file and moves forward in it with every byte that it reads. As the BufferedReader asks it to keep reading data until it reaches a line ending, each call of readLine() moves the internal state ahead by as many bytes as are needed to represent the line.

      File f = new File(pathToFile); try { BufferedReader reader = new BufferedReader(new FileReader(f)); // use reader.readLine() to read the next line from the file // when the reader reaches the end of the file, reader.readLine() // will return null } catch(IOException e) { // handle error }

      Construction. Writing Files

      [comp1110-98]
      • Fabian Muehlboeck

      Writing files shares many considerations with reading files. As such, the pattern is rather similar, but instead of a FileReader, we use a FileWriter, and instead of a BufferedReader, we use a BufferedWriter.

      try(FileWriter fw = new FileWriter(theFile); BufferedWriter writer = new BufferedWriter(fw)) { // use the writer } catch(IOException e) { // handle IOException }

      The BufferedWriter does not have a writeLine or printLine method. Instead, you have to use the write method and add a newline character yourself:

      writer.write(someString + "\n");

      Here, "\n" is a string consisting of a single newline character '\n'. Backslashes \ start what is called an escape sequence, expressing characters that are not easily printable. To include a backslash itself, you have to write "\\". The newline character '\n' (also called "line feed" or "LF") is the standard way of expressing line breaks on Linux and modern MacOS. (Very) old Macs used a different character, '\r' (called "carriage return" or "CR", representing the idea of resetting the position of your typewriter to the start of a line).

      Not to be outdone, Windows programs represent line breaks using a combination of the two, as "\r\n" (also described as "CRLF"). However, most Windows programs also recognize '\n' on its own as a line break (and BufferedReader considers any of the three to be terminating a line).

      For this reason, it is usually fine to stick with just using '\n' as line break if you do not need to keep compatibility with specific Windows programs. Alternatively, you can use BufferedReader's newLine method, which will write a system-specific line break (i.e. usually either '\n' or "\r\n") to your file at the current position:

      writer.write(someString); writer.newLine();

      Finally, BufferedReader does not necessarily write everything to your file right away. If you want to make sure that everything you have written so far makes it to your file even if your program crashes at some later point, use the method flush().

      writer.write(someString); writer.newLine(); writer.flush(); // everything written so far will // definitely be written to the file now

      In any case, flush will automatically be part of closing the file, say at the end of a try-with-resources.

      bars magnifying-glass caret-down plus minus arrow-right xmark