Java IO: Streams

Java IO streams are flows of data you can either read from, or write to. As mentioned in the Java IO Overview, streams are typically connected to a data source, or data destination, like a file or network connection.

A stream has no concept of an index of the read or written data, like an array does. Nor can you typically move forth and back in a stream, like you can in an array, or in a file using RandomAccessFile. A stream is just a continuous flow of data.

Some stream implementations like the PushbackInputStream allows you to push data back into the stream, to be re-read again later. But you can only push back a limited amount of data, and you cannot traverse the data at will, like you can with an array. Data can only be accessed sequentially.

Java IO streams are typically either byte based or character based. The streams that are byte based are typically called something with "stream", like InputStream or OutputStream. These streams read and write a raw byte at a time, with the exception of the DataInputStream and DataOutputStream which can also read and write int, long, float and double values.

The streams that are character based are typically called something with "Reader" or "Writer". The character based streams can read / write characters (like Latin1 or UNICODE characters). See the text Java Readers and Writers for more information about character based input and output.

InputStream

The class java.io.InputStream is the base class for all Java IO input streams. If you are writing a component that needs to read input from a stream, try to make our component depend on an InputStream, rather than any of it's subclasses (e.g. FileInputStream). Doing so makes your code able to work with all types of input streams, instead of only the concrete subclass.

Depending on InputStream only isn't always possible, though. If you need to be able to push back data into the stream, you will have to depend on a PushbackInputStream - meaning your stream variable will be of this type. Otherwise your code will not be able to call the unread() method on the PushbackInputStream.

You typically read data from an InputStream by calling the read() method. The read() method returns a int containing the byte value of the byte read. If there is no more data to be read, the read() method typically returns -1;

Here is a simple example:

InputStream input = new FileInputStream("c:\\data\\input-file.txt");

int data = input.read();

while(data != -1){
  data = input.read();
}

OutputStream

The class java.io.OutputStream is the base class of all Java IO output streams. If you are writing a component that needs to write output to a stream, try to make sure that component depends on an OutputStream and not one of its subclasses.

Here is a simple example pushing some data out to a file:

OutputStream output = new FileOutputStream("c:\\data\\output-file.txt");
output.write("Hello World".getBytes());
output.close();

Combining Streams

You can combine streams into chains to achieve more advanced input and output operations. For instance, reading every byte one at a time from a file is slow. It is faster to read a larger block of data from the disk and then iterate through that block byte for byte afterwards. To achieve buffering you can wrap your InputStream in an BufferedInputStream. Here is an example:

InputStream input = new BufferedInputStream(
                        new FileInputStream("c:\\data\\input-file.txt"));

...

Buffering can also be applied to OutputStream's thereby batching the writes to disk (or the underlying stream) up in larger chunks. That provides faster output too. This is done with a BufferedOutputStream.

Buffering is just one of the effects you can achieve by combining streams. You can also wrap your InputStream in a PushbackStream. That way you can push data back into the stream to be re-read later. This is sometimes handy during parsing. Or, you can combine two InputStreams into one using the SequenceInputStream

There are several other effects that can be achieved by combining input and output streams into chains. You can even write your own stream classes to wrap the standard stream classes that comes with Java. That way you can create your own effects or filters.