The read( ) Method

The read() Method

The fundamental method of the InputStream class is read( ). This method reads a single unsigned byte of data and returns the integer value of the unsigned byte. This is a number between 0 and 255:

public abstract int read( ) throws IOException

read( ) is declared abstract; therefore, InputStream is abstract. Hence, you can never instantiate an InputStream directly; you always work with one of its concrete subclasses.

The following code reads 10 bytes from the System.in input stream and stores them in the int array data:

int[] data = new int[10]; for (int i = 0; i < data.length; i++) { data[i] = System.in.read( ); }

Notice that although read( ) is reading a byte, it returns an int. If you want to store the raw bytes instead, you can cast the int to a byte. For example:

byte[] b = new byte[10]; for (int i = 0; i < b.length; i++) { b[i] = (byte) System.in.read( ); }

Of course, this produces a signed byte instead of the unsigned byte returned by the read( ) method (that is, a byte in the range -128 to 127 instead of 0 to 255). As long as you're clear in your mind and in your code about whether you're working with signed or unsigned data, you won't have any trouble. Signed bytes can be converted back to ints in the range of 0 to 255 like this:

int i = (b >= 0) ? b : 256 + b;

When you call read( ), you also have to catch the IOException that it might throw, or declare that your methods throw it. However, there's no IOException if read( ) encounters the end of the input stream; in this case, it returns -1. You use this as a flag to watch for the end of stream. The following code fragment shows how to catch the IOException and test for the end of the stream:

try { InputStream in = new FileInputStream("file.txt"); int[] data = new int[10]; for (int i = 0; i < data.length; i++) { int datum = in.read( ); if (datum == -1) break; data[i] = datum; } } catch (IOException ex) { System.err.println(ex.getMessage( )); }

The read( ) method normally waits as long as it needs to in order to get a byte of data. Most input streams do not time out. (A few network streams are exceptions.) Input can be slow, so if your program is doing anything else of importance, try to put I/O in its own thread.

Example 3-1 is a program that reads data from System.in and prints the numeric value of each byte read on the console using System.out.println( ).

Example 3-1. The StreamPrinter class