We’ll explore FileInputStream and FileOutputStream by examining an example program named CopyBytes,^[6] which uses byte streams to copy xanadu.txt:

import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;

public class CopyBytes {

  public static void main(String[] args) throws IOException {
    FileInputStream in = null;
    FileOutputStream out = null;
    try {
        in = new FileInputStream("xanadu.txt");
        out = new FileOutputStream("outagain.txt");
        int c;
        while ((c = in.read()) != -1) {
          out.write(c);
        }
    } finally {
        if (in != null) {
          in.close();
        }
        if (out != null) {
          out.close();
        }
    }
  }
}

CopyBytes spends most of its time in a simple loop that reads the input stream and writes the output stream, one byte at a time, as shown in Figure 10.3.

Figure 10.3. Simple byte stream input and output.

Notice that read() returns an int value. If the input is a stream of bytes, why doesn’t read() return a byte value? Using an int as a return type allows read() to use -1 to indicate that it has reached the end of the stream.

Closing a stream when it’s no longer needed is very important—so important that CopyBytes uses a finally block to guarantee that both streams will be closed even if an error occurs. This practice helps avoid resource leaks.

One possible error is that CopyBytes was unable to open one or both files. When that happens, the stream variable corresponding to the file never changes from its initial null value. That’s why CopyBytes makes sure that each stream variable contains an object reference before invoking close.

CopyBytes seems like a normal program, but it actually represents a kind of low-level I/O that you should avoid. Since xanadu.txt contains character data, the best approach is to use character streams, as discussed in the next section. There are also streams for more complicated data types. Byte streams should only be used for the most primitive I/O.

So why talk about byte streams? Because all other stream types are built on byte streams.

All character stream classes are descended from Reader^[8] and Writer.^[9] As with byte streams, there are character stream classes that specialize in file I/O: FileReader^[10] and FileWriter.^[11] The CopyCharacters^[12] example illustrates these classes:

import java.io.FileReader;
import java.io.FileWriter;
import java.io.IOException;

public class CopyCharacters {

  public static void main(String[] args) throws IOException {

    FileReader inputStream = null;
    FileWriter outputStream = null;

    try {
        inputStream = new FileReader("xanadu.txt");
        outputStream = new FileWriter("characteroutput.txt");

        int c;
        while ((c = inputStream.read()) != -1) {
          outputStream.write(c);
        }
    } finally {
        if (inputStream != null) {
          inputStream.close();
        }
        if (outputStream != null) {
          outputStream.close();
        }
    }
  }

}

CopyCharacters is very similar to CopyBytes. The most important difference is that CopyCharacters uses FileReader and FileWriter for input and output in place of FileInputStream and FileOutputStream. Notice that both CopyBytes and CopyCharacters use an int variable to read to and write from. However, in CopyCharacters, the int variable holds a character value in its last 16 bits; in CopyBytes, the int variable holds a byte value in its last 8 bits.

Character streams are often “wrappers” for byte streams. The character stream uses the byte stream to perform the physical I/O, while the character stream handles translation between characters and bytes. FileReader, for example, uses FileInputStream, while FileWriter uses FileOutputStream.

There are two general-purpose byte-to-character “bridge” streams: InputStream-Reader^[13] and OutputStreamWriter.^[14] Use them to create character streams when there are no prepackaged character stream classes that meet your needs. For an example that creates character streams from network byte streams, refer to the online sockets lesson.^[15]

Character I/O usually occurs in bigger units than single characters. One common unit is the line: a string of characters with a line terminator at the end. A line terminator can be a carriage-return/line-feed sequence (" "), a single carriage-return (" "), or a single line-feed (" "). Supporting all possible line terminators allows programs to read text files created on any of the widely used operating systems.

Let’s modify the CopyCharacters example to use line-oriented I/O. To do this, we have to use two classes we haven’t seen before, BufferedReader^[16] and PrintWriter.^[17] We’ll explore these classes in greater depth in the Buffered Streams (page 269) and the Formatting (page 272) sections. Right now, we’re just interested in their support for line-oriented I/O.

The CopyLines^[18] example invokes BufferedReader.readLine and PrintWriter.println to do input and output one line at a time:

import java.io.FileReader;
import java.io.FileWriter;
import java.io.BufferedReader;
import java.io.PrintWriter;
import java.io.IOException;

public class CopyLines {

  public static void main(String[] args) throws IOException {
    BufferedReader inputStream = null;
    PrintWriter outputStream = null;

    try {
        inputStream =
	  new BufferedReader(new FileReader("xanadu.txt"));
	outputStream =
	  new PrintWriter(new
			  FileWriter("characteroutput.txt"));
	String l;
	while ((l = inputStream.readLine()) != null) {
	  outputStream.println(l);
        }
    } finally {
        if (inputStream != null) {
          inputStream.close();
        }
        if (outputStream != null) {
          outputStream.close();
        }
    }
  }

}

Invoking readLine returns a line of text with the line terminator removed. CopyLines outputs each line using println, which appends the line terminator for the current operating system. This might not be the same line terminator that was used in the input file.

There are many ways to structure text input and output beyond characters and lines. For more information, see the Scanning and Formatting section (page 270).

It often makes sense to write out a buffer at critical points, without waiting for it to fill. This is known as flushing the buffer.

Some buffered output classes support autoflush, specified by an optional constructor argument. When autoflush is enabled, certain key events cause the buffer to be flushed. For example, an autoflush PrintWriter object flushes the buffer on every invocation of println or format. See the Formatting section (page 272) for more on these methods.

To flush a stream manually, invoke its flush method. The flush method is valid on any output stream, but has no effect unless the stream is buffered.

Objects of type Scanner^[22] are useful for breaking down formatted input into tokens and translating individual tokens according to their data types.

import java.io.*;
import java.util.Scanner;

public class ScanXan {

  public static void main(String[] args) throws IOException {
    Scanner s = null;

    try {
      s = new Scanner(new BufferedReader(new
                      FileReader("xanadu.txt")));

      while (s.hasNext()) {
        System.out.println(s.next());
      }
    } finally {
        if (s != null) {
          s.close();
        }
    }
  }
}

In
Xanadu
did
Kubla
Khan
A
stately
pleasure-dome
...

s.useDelimiter(",\s*");

import java.io.FileReader;
import java.io.BufferedReader;
import java.io.IOException;
import java.util.Scanner;
import java.util.Locale;

public class ScanSum {
  public static void main(String[] args) throws IOException {
    Scanner s = null;
    double sum = 0;
    try {
      s = new Scanner(new
            BufferedReader(new FileReader("usnumbers.txt")));
      s.useLocale(Locale.US);

      while (s.hasNext()) {
        if (s.hasNextDouble()) {
              sum += s.nextDouble();
          } else {
              s.next();
          }
      }
    } finally {
        s.close();
    }
    System.out.println(sum);
  }
}

8.5
32,767
3.14159
1,000,000.1

Stream objects that implement formatting are instances of either PrintWriter, a character stream class, or PrintStream,^[26] a byte stream class.

Like all byte and character stream objects, instances of PrintStream and PrintWriter implement a standard set of write methods for simple byte and character output. In addition, both PrintStream and PrintWriter implement the same set of methods for converting internal data into formatted output. Two levels of formatting are provided:

public class Root {
  public static void main(String[] args) {
    int i = 2;
    double r = Math.sqrt(i);

    System.out.print("The square root of ");
    System.out.print(i);
    System.out.print(" is ");
    System.out.print(r);
    System.out.println(".");

    i = 5;
    r = Math.sqrt(i);
    System.out.println("The square root of " +
                              i + " is " + r + ".");
  }
}

The square root of 2 is 1.4142135623730951.
The square root of 5 is 2.23606797749979.

The format Method

The format method formats multiple arguments based on a format string. The format string consists of static text embedded with format specifiers; except for the format specifiers, the format string is output unchanged.

Format strings support many features. In this tutorial, we’ll just cover some basics. For a complete description, see Format String Syntax in the API specification.^[29]

The Root2^[30] example formats two values with a single format invocation:

public class Root2 {
  public static void main(String[] args) {
    int i = 2;
    double r = Math.sqrt(i);

    System.out.format("The square root of %d is %f.%n", i, r);
  }
}

Here is the output:

The square root of 2 is 1.414214.

Like the three used in this example, all format specifiers begin with a % and end with a 1- or 2-character conversion that specifies the kind of formatted output being generated. The three conversions used here are:

• d formats an integer value as a decimal value.

• f formats a floating point value as a decimal value.

• n outputs a platform-specific line terminator.

Here are some other conversions:

• x formats an integer as a hexadecimal value.

• s formats any value as a string.

• tB formats an integer as a locale-specific month name.

There are many other conversions.

Note

Except for %% and %n, all format specifiers must match an argument. If they don’t, an exception is thrown.

In the Java programming language, the escape always generates the linefeed character (u000A). Don’t use unless you specifically want a linefeed character. To get the correct line separator for the local platform, use %n.

In addition to the conversion, a format specifier can contain several additional elements that further customize the formatted output. Here’s an example, Format,^[31] that uses every possible kind of element:

public class Format {
  public static void main(String[] args) {
    System.out.format("%f, %1$+020.10f %n", Math.PI);
  }
}

Here’s the output:

3.141593, +00000003.1415926536

The additional elements are all optional.

Figure 10.4 shows how the longer specifier breaks down into elements.

Figure 10.4. Elements of a format specifier.

The elements must appear in the order shown. Working from the right, the optional elements are:

• Precision. For floating point values, this is the mathematical precision of the formatted value. For s and other general conversions, this is the maximum width of the formatted value; the value is right-truncated if necessary.

• Width. The minimum width of the formatted value; the value is padded if necessary. By default the value is left-padded with blanks.

• Flags. Specify additional formatting options. In the Format example, the + flag specifies that the number should always be formatted with a sign, and the 0 flag specifies that 0 is the padding character. Other flags include - (pad on the right) and , (format number with locale-specific thousands separators). Note that some flags cannot be used with certain other flags or with certain conversions.

• Argument Index. Allows you to explicitly match a designated argument. You can also specify < to match the same argument as the previous specifier. Thus the example could have said:

  System.out.format("%f, %<+020.10f %n", Math.PI);
  

Standard Streams are a feature of many operating systems. By default, they read input from the keyboard and write output to the display. They also support I/O on files and between programs, but that feature is controlled by the command line interpreter, not the program.

The Java platform supports three Standard Streams: Standard Input, accessed through System.in; Standard Output, accessed through System.out; and Standard Error, accessed through System.err. These objects are defined automatically and do not need to be opened. Standard Output and Standard Error are both for output; having error output separately allows the user to divert regular output to a file and still be able to read error messages. For more information, refer to the documentation for your command-line interpreter.

You might expect the Standard Streams to be character streams, but, for historical reasons, they are byte streams. System.out and System.err are defined as PrintStream objects. Although it is technically a byte stream, PrintStream uses an internal character stream object to emulate many of the features of character streams.

By contrast, System.in is a byte stream with no character stream features. To use Standard Input as a character stream, wrap System.in in InputStreamReader:

InputStreamReader cin = new InputStreamReader(System.in);

A more advanced alternative to the Standard Streams is the Console. This is a single, predefined object of type Console^[32] that has most of the features provided by the Standard Streams, and others besides. The Console is particularly useful for secure password entry. The Console object also provides input and output streams that are true character streams, through its reader and writer methods.

Before a program can use the Console, it must attempt to retrieve the Console object by invoking System.console(). If the Console object is available, this method returns it. If System.console returns NULL, then Console operations are not permitted, either because the OS doesn’t support them or because the program was launched in a noninteractive environment.

import java.io.Console;
import java.util.Arrays;
import java.io.IOException;

public class Password {

  public static void main (String args[]) throws IOException {

    Console c = System.console();
    if (c == null) {
      System.err.println("No console.");
      System.exit(1);
    }

    String login = c.readLine("Enter your login: ");
    char [] oldPassword = c.readPassword("Enter your " +
                                             old password: ");

    if (verify(login, oldPassword)) {
      boolean noMatch;
      do {
        char [] newPassword1 =
            c.readPassword("Enter your new password: ");
        char [] newPassword2 =
            c.readPassword("Enter new password again: ");
        noMatch = ! Arrays.equals(newPassword1, newPassword2);
        if (noMatch) {
            c.format("Passwords don't match. Try again.%n");
        } else {
            change(login, newPassword1);
            c.format("Password for %s changed.%n", login);
        }
        Arrays.fill(newPassword1, ' '),
        Arrays.fill(newPassword2, ' '),
      } while (noMatch);
    }

    Arrays.fill(oldPassword, ' '),
  }

  // Dummy verify method.
  static boolean verify(String login, char[] password) {
    return true;
  }

  // Dummy change method.
  static void change(String login, char[] password) {}
}

The writeObject and readObject methods are simple to use, but they contain some very sophisticated object management logic. This isn’t important for a class like Calendar, which just encapsulates primitive values. But many objects contain references to other objects. If readObject is to reconstitute an object from a stream, it has to be able to reconstitute all of the objects the original object referred to. These additional objects might have their own references, and so on. In this situation, writeObject traverses the entire web of object references and writes all objects in that web onto the stream. Thus a single invocation of writeObject can cause a large number of objects to be written to the stream.

This is demonstrated in Figure 10.5, where writeObject is invoked to write a single object named a. This object contains references to objects b and c, while b contains references to d and e. Invoking writeObject(a) writes not just a, but all the objects necessary to reconstitute a, so the other four objects in this web are written as well. When a is read back by readObject, the other four objects are read back also, and all the original object references are preserved.

Figure 10.5. I/O of multiple referred-to objects.

You might wonder what happens if two objects on the same stream both contain references to a single object. Will they both refer to a single object when they’re read back? The answer is “yes.” A stream can only contain one copy of an object, though it can contain any number of references to it. Thus if you explicitly write an object to a stream twice, you’re really writing only the reference twice. For example, if the following code writes an object ob twice to a stream:

Object ob = new Object();
out.writeObject(ob);
out.writeObject(ob);

each writeObject has to be matched by a readObject, so the code that reads the stream back will look something like this:

Object ob1 = in.readObject();
Object ob2 = in.readObject();

This results in two variables, ob1 and ob2, that are references to a single object.

However, if a single object is written to two different streams, it is effectively duplicated—a single program reading both streams back will see two distinct objects.

A File object contains the file name string used to construct it. That string never changes throughout the lifetime of the object. A program can use the File object to obtain other versions of the file name, some of which may or may not be the same as the original file name string passed to the constructor.

Suppose a program creates a File object with the constructor invocation:

File a = new File("xanadu.txt");

The program invokes a number of methods to obtain different versions of the file name. The program is then run both on a Microsoft Windows system (in directory c:javaexamples) and a Solaris system (in directory /home/cafe/java/examples). Table 10.2 shows what the methods would return.

Then the same program constructs a File object from a more complicated file name, using File.separator to specify the file name in a platform-independent way:

File b = new File(".." + File.separator + "examples" +
                           File.separator + "xanadu.txt");

Although b refers to the same file as a, the methods return slightly different values, as shown in Table 10.3.

Running the same program on a Linux system would give results similar to those on the Solaris system.

It’s worth mentioning that File.compareTo() would not consider a and b to be the same. Even though they refer to the same file, the names used to construct them are different.

The FileStuff^[49] example creates File objects from names passed from the command line and exercises various information methods on them. You’ll find it instructive to run FileStuff on a variety of file names. Be sure to include directory names as well as the names of files that don’t actually exist. Try passing FileStuff a variety of relative and absolute path names:

import java.io.File;
import java.io.IOException;
import static java.lang.System.out;

public class FileStuff {

  public static void main(String args[]) throws IOException {

    out.print("File system roots: ");
    for (File root : File.listRoots()) {
      out.format("%s ", root);
    }
    out.println();

    for (String fileName : args) {
      out.format("%n------ %nnew File(%s)%n", fileName);
      File f = new File(fileName);
      out.format("toString(): %s%n", f);
      out.format("exists(): %b%n", f.exists());
      out.format("lastModified(): %tc%n", f.lastModified());
      out.format("isFile(): %b%n", f.isFile());
      out.format("isDirectory(): %b%n", f.isDirectory());
      out.format("isHidden(): %b%n", f.isHidden());
      out.format("canRead(): %b%n", f.canRead());
      out.format("canWrite(): %b%n", f.canWrite());
      out.format("canExecute(): %b%n", f.canExecute());
      out.format("isAbsolute(): %b%n", f.isAbsolute());
      out.format("length(): %d%n", f.length());
      out.format("getName(): %s%n", f.getName());
      out.format("getPath(): %s%n", f.getPath());
      out.format("getAbsolutePath(): %s%n",
                                f.getAbsolutePath());
      out.format("getCanonicalPath(): %s%n",
                               f.getCanonicalPath());
      out.format("getParent(): %s%n", f.getParent());
      out.format("toURI: %s%n", f.toURI());
    }
  }
}

If a File object names an actual file, a program can use it to perform a number of useful operations on the file. These include passing the object to the constructor for a stream to open the file for reading or writing.

The delete method deletes the file immediately, while the deleteOnExit method deletes the file when the virtual machine terminates.

The setLastModified sets the modification date/time for the file. For example, to set the modification time of xanadu.txt to the current time, a program could do:

new File("xanadu.txt").setLastModified(new Date().getTime());

The renameTo() method renames the file. Note that the file name string behind the File object remains unchanged, so the File object will not refer to the renamed file.

File has some useful methods for working with directories.

The mkdir method creates a directory. The mkdirs method does the same thing, after first creating any parent directories that don’t yet exist.

The list and listFiles methods list the contents of a directory. The list method returns an array of String file names, while listFiles returns an array of File objects.

File contains some useful static methods.

The createTempFile method creates a new file with an unique name and returns a File object referring to it.

The listRoots returns a list of file system root names. On Microsoft Windows, this will be the root directories of mounted drives, such as a: and c:. On UNIX and Linux systems, this will be the root directory, /.