The Java Development Kit^TM (JDK^TM) provides APIs for reading and writing streams of data. These APIs have been part of the core JDK since version 1.0, but are often overshadowed by the more well-known APIs, such as JavaBeans^TM, JFC, RMI, JDBC^TM, and so on. However, input and output streams are the backbone of the JDK APIs, and understanding them is not only crucial, but can also make programming with them a lot of fun.

This article covers the fundamentals of Java streams by reviewing the differences between byte and character streams, peruses the various stream classes available in the java.io package, and looks at the concept of stream chaining.

Overview

To bring data into a program, a Java program opens a stream to a data source, such as a file or remote socket, and reads the information serially. On the flip side, a program can open a stream to a data source and write to it in a serial fashion. Whether you are reading from a file or from a socket, the concept of serially reading from, and writing to different data sources is the same. For that very reason, once you understand the top level classes (java.io.Reader, java.io.Writer), the remaining classes are straightforward to work with.

Character Streams versus Byte Streams

Most of the functionality available for byte streams is also provided for character streams. The methods for character streams generally accept parameters of data type char parameters, while byte streams, you guessed it, work with byte data types. The names of the methods in both sets of classes are almost identical except for the suffix, that is, character-stream classes end with the suffix Reader or Writer and byte-stream classes end with the suffix InputStream and OutputStream. For example, to read files using character streams, you would use the java.io.FileReader class; for reading it using byte streams you would use java.io.FileInputStream.

Unless you are working with binary data, such as image and sound files, you should use readers and writers (character streams) to read and write information for the following reasons:

• They can handle any character in the Unicode character set (while the byte streams are limited to ISO-Latin-1 8-bit bytes).
• They are easier to internationalize because they are not dependent upon a specific character encoding.
• They use buffering techniques internally and are therefore potentially much more efficient than byte streams.

Bridging the Gap Between Byte and Character Streams

 
     BufferedReader in = new BufferedReader(new 
    InputStreamReader(System.in));
  

For JDK 1.0 Versions

Various Stream Classes

Top Level Classes: java.io.Reader and java.io.Writer

• int read()
• int read(char cbuf[])
• int read(char cbuf[], int offset, int length)
• int write(int c)
• int write(char cbuf[])
• int write(char cbuf[], int offset, int length)

Consider the following simple example program that demonstrates how the read and write methods can be used (this program is similar to the MS-DOS type and Unix cat commands, that is, it displays the contents of a file):

 
import java.io.*;


   // Displays contents of a file 
   //(e.g. java Type app.ini) 
   public class Type
     {
     public static void main(
       String args[]) throws Exception
     {
      // Open input/output and setup variables
      FileReader fr = new FileReader(args[0]);
      PrintWriter pw = new PrintWriter(
        System.out, true);
      char c[] = new char[4096];
      int read = 0;

      // Read (and print) till end of file
      while ((read = fr.read(c)) != -1)
         pw.write(c, 0, read);

      // Close shop
      fr.close();
      pw.close();
     }
   }
   

The following code fragment from the above program, opens the input and output streams:

 
   FileReader  fr = new FileReader(args[0]);
   PrintWriter pw = new PrintWriter(System.out, true);
  

The program reads the input file and displays its contents until it reaches an end-of-file condition (-1), as shown here:

  
    while ((read = fr.read(c)) != -1)
     pw.write(c, 0, read);
     

Notice the "(char cbuf[])" version of the read method. This is used here because in most cases reading a single character at a time can be approximately five times slower than reading chunks of data (array) at a time.

Other Notable Methods

skip() as the name implies, allows you to skip over characters.

mark() and reset() provide a book-marking feature that allows you to read ahead in a stream to inspect the upcoming data but not necessarily process it. Not all streams support "marking." To determine if a stream supports marking, use the markSupported() method.

InputStream.available() tells you how many bytes are available to be read before the next read() will block. Reader.ready() is similar to the available() method, except it does not indicate how many characters are available.

The flush() method simply writes out any buffered characters (or bytes) to the destination (for example, file, or socket).

Specialized Descendent Stream Classes

The following class hierarchy shows a few of the specialized classes found in the java.io package: Reader

• BufferedReader
  • LineNumberReader
• FilterReader
  • PushbackReader
• InputStreamReader
  • FileReader
• StringReader

The above hierarchy simply demonstrates how stream classes extend their parent classes (for example, LineNumberReader) to add more specialized functionality.

The following three tables provide a more comprehensive list of the various descendent classes found in the java.io and other packages, along with a brief description for each class. These descendent classes are divided into two categories: those that read from, or write to data sinks, and those that perform some sort of processing on the data—this distinction is merely to group the classes into two logical sections, you do not have to know one way or the other when using them.

Note: to give you a general idea of the various types of descendant classes provided in the JDK, these tables only show a subset of the classes found in the java.io package. The byte counterparts to the char-based classes and a few others have been intentionally skipped. Please refer to the Java Platform 1.2 API Specification (java.io) for a complete list.

Stream Chaining

One of the most convenient features of the I/O stream classes is that they are designed to work together via stream chaining.

Stream chaining is a way of connecting several stream classes together to get the data in the form required. Each class performs a specific task on the data and forwards it to the next class in the chain. Stream chaining can be very handy. For example, Divya Incorporated's 100% Pure Java backup software, BackOnline, chains several stream classes to compress, encrypt, transmit, receive, and finally store the data in a remote file.

The following figure portrays chaining three classes to convert raw data into compressed and encrypted data that is stored in a local file. This is how it works: the data is written to GZIPOutputStream, which compresses the input data and sends it to CryptOutputStream. CryptOutputStream encrypts the data prior to forwarding it to FileOutputStream, which writes it out to a file. The result is a file that contains encrypted and compressed data.

The source code for the stream chaining shown in the above figure would look something like this:

  
  FileOutputStream  fos = 
    new FileOutputStream("myfile.out");
   CryptOutputStream cos = new CryptOutputStream(fos);
   GZIPOutputStream  gos = new GZIPOutputStream(cos);
 

or simply:

    GZIPOutputStream gos = new 
    GZIPOutputStream(new CryptOutputStream(new 
    FileOutputStream("myfile.out")));

To write to chained streams, you simply call the write() method on the outermost class as follows:

    gos.write('a');

Similarly, when closing chained streams, you only need to close the outermost stream class because the close() call is automatically trickled through all the chained classes; in the example above, you would simply call the close() method on the GZIPOutputStream class.

Summary

Anil Hemrajani is a senior consultant at Divya Incorporated, a consulting firm specializing in Java/Internet software solutions. Anil Hemrajani provides Java/Internet-based architecture, design and development solutions to Fortune 500 companies, and occasionally writes articles and speaks at conferences. He can be reached at anil@divya.com

Reader Feedback