Reading and writing byte streams

Copying a file sounds like a single action, but inside a program it becomes a small repeated process. The program takes a piece of data from one place, puts it in another place, and keeps going until nothing is left to copy. Before reading the explanation in this article, try to picture what the copy loop does on each pass. Building that picture first makes the rest of the material much easier to follow.

The rest of this article follows the loop step by step. You will trace what happens to a single piece of data, see how the program decides when to stop, and learn why the whole copy has to be protected against failure.

The heart of the copy is a while loop. On each pass, the program calls source.read() to get one byte, and then calls copy.write(data) to store that byte in the output. Here source refers to the InputStream connected to the source file, and copy refers to the OutputStream connected to the destination file. Each pass through the loop therefore performs one read and, unless the read signalled the end of the data, one write.

The diagram shows the path for a single byte. The variable data is the link between the two streams. It is assigned the value returned by source.read(), and that same value is then passed to copy.write(data). The program does not hold the whole file in memory. Nothing is stored beyond this one value, so the file is copied as a stream of individual bytes. Once the byte has been written, the loop starts over and the next byte follows the same path.

This skeleton uses only the calls described in the source. The source describes the loop in these terms: a while loop that calls source.read() and copy.write(data), with a check for -1 that ends the loop through break. The loop is written with while(true), which never ends on its own, so the break is the only exit.

A copy program has to work for any file, not only for files that contain text a person could read. Images, compiled programs, and plain text notes all have to be copied correctly. The program therefore cannot assume that the contents are human-readable characters, and it cannot rely on tools that interpret data as text. Instead, it works with the raw data, using the byte streams InputStream and OutputStream.

This choice makes the copy program indifferent to content. The loop never looks at what the bytes represent. An image, a compiled program, and a plain text note all pass through the same loop unchanged. The only thing the loop needs to know is when the input has run out.

A loop needs a way to stop, and in this copy the stopping signal comes from the input itself. The function source.read() returns the value -1 once every byte in the input file has been read. Each time the loop reads, the program checks the result with if (data < 0). When that check succeeds, the program leaves the loop with break. A returned value of -1 is therefore never copied; it only tells the program that the input is finished.

Notice that the loop runs as long as each read returns a real byte. It writes that byte and then starts again. The first read that returns -1 sends control out of the loop, and at that point the copy is finished.

The loop shown so far is only the heart of the program. Reading from an input and writing to an output are both I/O operations, and either one may fail while the copy is in progress. Input and output operations can throw exceptions, so the source requires that this work be placed inside a try..catch statement. The loop is the code that performs the reads and writes, so it is the part that must be protected.

Because a failure can happen partway through the copy, the program must be ready for the case where some bytes have already been read or written when the problem occurs. The try block holds the loop, and the catch block is where the program responds to the failure. Placing the loop inside try..catch means the failure is handled in one defined place instead of stopping the program without warning.

The copy loop is short, so a few details carry most of the weight. The mistakes below are the ones most likely to break the copy or hide what it is doing.