Start Concurrent: A Gentle Introduction to Concurrent Programming

You might be wondering how to read the command-line arguments such as -c test.bmp or -d test.bmp.compress. These arguments can’t be read using Scanner as we read most text. Instead, they’re passed directly into your program. By this point, you’ve written so many main() methods that you might have stopped paying attention to their syntax. Remember that main() methods always take a single parameter of type String[]. We’ve always called this parameter args in this book, but you’re free to call it whatever you like.

This array of String values is how command-line arguments are passed into your program. A Java program invoked by typing java BitmapCompression -c test.bmp will have an array of length 2 passed in. The first String stored in this array (args[0]) will be "-c". The second String stored in this array (args[1]) will be "test.bmp". The operating system passes in these command-line arguments to the JVM which passes them along to your program as String values.

Command-line programs often take these arguments to specify which options the program will be run with. Although they’re useful, we didn’t focus on these arguments in early chapters partly because they involve arrays and partly because all arguments, even those that look like numbers, will be passed in as String values. Furthermore, it’s cumbersome to specify command-line arguments when using IDEs like Eclipse or IntelliJ.

A computer program is like a living thing, always moving and restless. The variables in a program are stored in RAM, which is volatile storage. The data in volatile memory will only persist as long as there’s electricity powering it. But most programs don’t run constantly, and neither do most computers. We need a place to store data between runs of a particular program. Likewise, we need a place to store data when our computer isn’t turned on. Both scenarios share a common solution: secondary storage such as hard drives, flash drives, and optical media like DVD and Blu-ray discs.

Files are not always stored in non-volatile memory. It’s possible to load entire files into RAM and keep them there for long periods of time. Likewise, all input and output on Unix and Linux systems are viewed as file operations. Nevertheless, the characteristics of non-volatile memory are often associated with file I/O: slow access times and the possibility of errors in the event of inaccessible files or hardware problems.

While discussing RLE encoding, we described a file as a stream of bytes, and that’s a good definition for a file, especially in Java. Since Java is platform independent, and different operating systems and hardware will deal with the nitty gritty details of storing files in different ways, we want to think about files as abstractly as possible. Reading from and writing to a stream of bytes is not so different from the other input and output you’ve done so far. For the most part, file I/O will be similar to command-line I/O and, in fact, can use some of the same classes.

Although reading and writing from the files can be like reading from the keyboard and writing to the screen, there are a few additional complications. For one thing, you must open a file before you can read or write. Sometimes opening the file will fail: You could try to open a file for reading which doesn’t exist or try to open a file for writing which you don’t have permissions for. When reading data, you might try to read past the end of the file or try to read an int when the next item is a String. Unlike reading from the keyboard, you cannot ask the user to try again if there’s a mistake in input. To deal with these possible errors, exception handling will accompany many different file I/O operations in Java.

When talking about files, many people divide files into two categories: text files and binary files. A text file can be read by humans. That is, when you open a text file with a simple file reader, it won’t be filled with gibberish and nonsense characters. A Java source file is an excellent example of a text file.

In contrast, a binary file is a file meant only to be read by a computer. Instead of printing out characters meant to be read by a human, the raw bytes of memory for specific pieces of data are written to binary files. To clarify, if we wanted to write the number 2,127,480,645 in a text file, the file would contain the following.

However, if we wanted to write the same number in a binary file, the file would contain the following.

If you recall, an int in Java uses four bytes of storage. There’s a system of encoding called the ASCII table which maps each of the 256 (0–255) numerical bytes to a character. The four characters given above are the extended ASCII representation of the four bytes of the number 2,127,480,645.

In some sense, the idea of a text file is artificial. All files are binary in the sense that they’re readable by a computer. You’ll take different steps and create different objects depending on whether you want to do file I/O in the text or binary paradigms, but the overall process will be similar in either case.

A basic class for interacting with files in Java is the File class. A File object allows you to interact with a file at the operating system level. You can create a new file, test to see if a file is a directory, find out the size of a file, and so on. A number of file I/O classes require a File object as a parameter. To use the File class, import java.io.File or java.io.*.

To create a File object, you can call the File constructor with a String specifying the name of the file.

Doing so will create a virtual file object associated with the name file.txt (which might not exist yet) in the working directory of the Java program. In this case, the extension txt doesn’t have any real meaning. On many systems, the extension (like pdf or html) is used by the operating system to guess which application should open the file. To Java, however, the extension is just part of the file name. A file name passed to the constructor of a File object can have any number of periods in it (or none).

A file name without a directory is all well and good, but file systems are useful in part because of their hierarchical structure. If we want to create a file in a particular location, we specify the path in the String before the name of the file.

In this case, the prefix /homes/owilde/documents/ is the path and file.txt is still the file name. Each slash ('/') separates a parent directory from the files or directories inside of it. This path specifies that we start at the root, go into the homes directory, then the owilde directory, and then the documents directory. Note that we can also use a single period (.) in a path to refer to the current working directory and two periods (..) to refer to a parent directory.

This is one of those sticky places where Java’s trying to be platform independent, but the platforms each have different needs. The example we gave above is for a macOS or Linux system. In Windows, the way to specify the path is slightly different. Creating a similar File object on Windows system might be done as follows.

Then, the path specifies that we start in the C drive, go into the Users directory, the owilde directory, and then the Documents directory. Windows systems use a backslash (\) to separate a parent directory from its children. But in Java a backslash isn’t allowed to be by itself in a string literal, and so each backslash must be escaped with another backslash. To simplify things somewhat, Java allows Windows paths to be separated with regular slashes as well, so we’ll use this style for the rest of the book.

A further complication is that file and directory names are case sensitive in Linux, aren’t case sensitive in Windows, and could be either in macOS depending on file system settings.

Returning to File objects, there are a number of things we can do directly. A File object has methods that can test if a file with the associated name and path exists, if it’s readable, if it’s writable, and many other things. Because there are so many classes associated with file I/O and each class has so many methods, now’s a good time to remind you of the usefulness of the Java API. If you visit the Java API documentation site, you can get detailed documentation for the entire standard library, including file I/O classes.

Once you have a File object, most of its usefulness comes from combining it with other classes. You’re already familiar with the Scanner class. The Scanner constructor can take a File object (instead of System.in), creating a Scanner that reads from a text file instead of the keyboard.

Assuming that file is linked to a file which the program has read access to, this block of code will extract int values from the file and pass them to the process() method. If the file doesn’t exist or isn’t readable to the program, a FileNotFoundException will be thrown and an error message printed. Creating a Scanner from a File object instead of System.in can throw a checked exception, so the try and catch are needed before the program will compile. Note that you’ll need to import java.util.Scanner or java.util.* just like any other time you use the Scanner class.

And that’s all there is to it. After opening the file, using the Scanner class will be almost the same as before. One difference is that you should close the Scanner object (and by extension the file) when you’re done reading from it, as we do in the example. Closing files is key to writing robust code.

You’ll notice that we put in.close() in a finally block. Using finally is a good habit for file I/O. File operations could fail for any number of reasons, but you will still need to close the file afterward. We put in the null check in case the file didn’t exist and the reference in never pointed to a valid object. (We also begin by setting in to null. Otherwise, Java complains that it might not have been initialized.)

Writing information to a file is similar to using System.out. First, you need to create a PrintWriter object. Like Scanner, you can create a PrintWriter object directly from a File object. If we want to write a list of random numbers to the file we were reading from earlier, we could do it as follows.

Again, once you have a PrintWriter object, the methods for outputting data are just like using System.out. Be sure to import java.io.* in order to have access to the PrintWriter class.

We covered text files first because their input and output is similar to command-line I/O. When reading and writing text files, you can visually verify that file reading and writing operations were successful. Although it’s harder to check the contents of binary files, they have other advantages. Data can often be stored more compactly in binary files, as in the example with the integer 2,127,480,645. Even better, Java provides facilities for easily dumping (and later retrieving) primitive data types, objects, and even complex data structures to binary files.

The simplest object for reading input from a binary file is a FileInputStream object. As with a File object, you can create a FileInputStream object from a String specifying the file path and name.

Unfortunately, you can’t do much with a FileInputStream object. Its methods allow you to read single bytes, either one at a time or into an array as a group. The basic read() method returns the next byte in the file or a -1 if the end of the file has been reached. Working only at the level of bytes, we can still write useful code like the following method that prints the size of a file.

Note the extra try-catch block inside of the finally. Like the other binary file I/O objects we’ll discuss in this section, FileInputStream can throw an IOException when closing. Usually, you won’t need to deal with this exception, but you still must catch it. Since we’re catching any Exception, we’re saving a little bit of code by eliminating the null check. If in is null in this example, a NullPointerException will be thrown and immediately caught, causing no damage. Catching Exception breaks our rule of never catching exceptions that are broader than we need, but we only have a single line of code in our try block with nothing else to do if it fails.

To output a sequence of bytes, you can create a FileOutputStream object. Its write() methods are the mirror images of the read() methods in FileInputStream. It would be convenient if there was a way to read and write any primitive type instead of just byte values, and DataInputStream and DataOutputStream provide exactly that functionality.

For output, a DataOutputStream chops up primitive data types into their component bytes and sends those bytes to a FileOutputStream. For input, a DataInputStream reads a sequence of bytes from a FileInputStream and reassembles them into whatever kind of primitive data they’re supposed to be.

To create an DataInputStream, you supply a FileInputStream to its constructor, usually one that you’ve just created on the fly for this purpose.

Now, let’s assume that baseball.bin contains baseball statistics. The first thing in the file is an int indicating the number of records it contains. Then, for each record, it’ll list home runs, RBI, and batting average, as an int, an int, and a double, respectively. Assuming that we’ve opened the file correctly above, we can read these statistics into three arrays with the following code.

When opening the file in the FileInputStream constructor, a FileNotFoundException will be thrown if the file doesn’t exist or is inaccessible. If the readInt() or readDouble() methods fail, they’ll throw an IOException. If the DataInputStream object tries to read past the end of a file, it’ll throw an EOFException exception. If you wanted to deal with these exceptions separately, you could, but since FileNotFoundException and EOFException are both children of IOException, a single catch clause for IOException handles all three.

As expected, the DataOutputStream methods for writing to a file match DataInputStream methods for reading from a file. If you substitute write for read, DataOutputStream methods are almost the same as DataInputStream methods. Below is a companion piece of code which assumes that homeRuns, RBI, and battingAverage are filled with data and writes them to a file.

Using DataInputStream and DataOutputStream in this way isn’t too difficult, but it seems cumbersome. The programmer has the responsibility to read and write every piece of primitive data separately. It would be convenient if there was a way to read an entire object at once, including any references to other objects that it contains. If a tool exists for reading an entire object, we’d also want a matching tool for writing an entire object at once.

Such tools can be found in the ObjectInputStream and ObjectOutputStream classes, respectively. These file I/O objects provide methods that elegantly allow you to read or write a whole object at a time. To use them with our baseball data example, we need to define a new class.

The new class BaseballPlayer encapsulates the three pieces of information we want. Note that it also implements the interface Serializable, but it doesn’t seem to implement any special methods to conform to the interface. We’ll discuss this interface more after we show how using this new class can simplify file I/O. Our input code will change to the following.

The corresponding output will become what follows.

This process of outputting an entire object at a time is called serialization. The BaseballPlayer class is very simple, but even complex objects can be serialized, and Java takes care of almost everything for you. The only magic needed is for the class that’s going to be serialized to implement Serializable. There are no methods in Serializable. It’s just a tag for a class that can be packed up and stored. The catch is that, if there are any references to other objects inside of the object being serialized, they must also be serializable. Otherwise, a NotSerializableException will be thrown when the JVM tries to perform the serialized output. Many classes are serializable, including the vast majority of the Java API.

However, objects that have some kind of special system-dependent state, like a Thread or a FileInputStream object, can’t be serialized. If you need to serialize a class with references to objects like these, add the transient keyword to the declaration of each unserializable reference. That said, these should be few and far between. For BaseballPlayer, adding implements Serializable was all we needed, and we can still get more mileage out of serialization! An array can be treated liked an Object and is also serializable. We can further simplify the input as shown below.

And the corresponding output code can be simplified as well.

When you go to write your code, which binary file I/O classes should you use? It depends on the situation. FileInputStream and FileOutputStream are very low level. You’ll use those classes to construct DataInputStream, DataOutputStream, ObjectInputStream, and ObjectOutputStream objects, but you probably won’t use them on their own unless your application is focused on byte-level input and output.

If you only want to read and write primitive types, you can use DataInputStream and DataOutputStream objects. These classes have methods to read and write all primitive types. Ultimately, all objects are made up of primitive types, though those primitive types might be buried inside of other objects. Most languages provide binary I/O tools like DataInputStream and DataOutputStream, so code using these objects will be similar to code in other languages that writes individual pieces of primitive data.

Finally, if you want to read and write whole objects (or even arrays of objects) at a time, ObjectInputStream and ObjectOutputStream are powerful tools. Using them leverages Java serialization, making the JVM do the work of dividing up your objects into primitive types and writing them (for output) or reading that primitive data and reassembling it into objects (for input). Even complex objects with many (potentially circular) references to other objects, like linked list classes, can be serialized. The Java implementation of serialization is smart enough to write each unique object only once and then refer to it later. This power feels like magic, but serialization has limitations. Only classes that implement the Serializable interface can be serialized. Also, serialization carries with it some overhead: the files must contain additional metadata describing the class being stored. Using DataInputStream and DataOutputStream can allow you to write only the necessary member data, resulting in a smaller file. You can also run into trouble if you make changes to a class. If one version of an object is serialized and then you try to read that object back after making the smallest change to the class, your code will fail. One last issue is that Java serializes objects according to its own rules, making files written in this way difficult (if not impossible) to use with code written in other languages. This consideration is not insignificant, since files are often written by one program and read by another.

The following table summarizes the three approaches to binary I/O we’ve discussed. Be sure to consult each class’s documentation for more information.

One of the more tedious aspects of working with files in command-line programs is typing the name of the file correctly. Although most OS terminals have time-saving autocomplete features to help users choose the right file name, typing the name of a file directly into a prompt so that it can be read by a Scanner object is error prone. Navigating long directory paths can also be a headache when using a command-line interface.

Indeed, most users are used to selecting files to open or to save via a GUI file chooser instead of typing file names explicitly. The Java Swing library provides such a file chooser called JFileChooser.

We discussed fully featured GUI programs in Chapter 15, but like the JOptionPane class covered in Chapter 7, JFileChooser can be used with or without a complex GUI.

Unlike the JOptionPane class whose functionality is accessed through static methods, you must create a JFileChooser object to use it.

Once you’ve created the JFileChooser object, you can call either the showOpenDialog() method to show a dialog to open existing files or the showSaveDialog() to save a potentially new file. The dialog looks similar in either case, with only minor differences such as title and buttons names.

Both methods take a Component object as an argument. If you’re creating a GUI program, you can pass in a JFrame or a JDialog for this argument to pop up a modal file chooser dialog that must be dealt with before returning control to the parent frame or dialog. If your program doesn’t otherwise use a GUI, you can pass in null.

Both methods also return an int value indicating the result of user input. A return value of JFileChooser.APPROVE_OPTION means that the user selected a file. The value JFileChooser.CANCEL_OPTION means that the user canceled instead of picking a file. Finally, JFileChooser.ERROR_OPTION means some error occurred.

Once the user has selected a file for opening or for saving, you can call the getSelectedFile() method to retrieve the File that the user selected.

If the user canceled or an error occurred, this File object could be null.

In many cases, a programmer will want to focus the user on files of a certain kind. For example, a program that plays audio files might display only files that have extensions associated with audio formats such as wav, mp3, and flac. To include this functionality, you can create a FileNameExtensionFilter object and set it as a file filter on your JFileChooser.

The first argument to the FileNameExtensionFilter constructor is a user-friendly description of the kinds of files displayed by the filter. After the description, the constructor takes a variable number of arguments, each of which gives one of the included file extensions. Extensions are case insensitive and should not include a dot (.) at the beginning. You should set the file filter before displaying a dialog with either showOpenDialog() or showSaveDialog().

FileNameExtensionFilter covers most of what people want from a file filter, but it’s possible to create your own class that extends FileFilter if you need to filter files based on more complex criteria.

Next, we’ll give a short example that uses a JFileChooser.

Note that the purpose of JFileChooser is to allow users to select a file. It doesn’t guarantee that the file exists or that the user has rights to read from the file or to write to it. Most commercial software asks the user if he or she wants to overwrite an existing file when saving. JFileChooser doesn’t have that functionality built in, requiring additional program logic to to prompt the user if an existing file is about to be overwritten.

Like most of the Swing library, JFileChooser has many options and features that we don’t have time to cover. Its display can be customized, and it can be configured to interact with the file system in a number of ways, such as displaying only normal files, displaying only directories, or both. There are even settings that allow the user to select multiple files at once.