Byte Input Streams

The byte input stream class hierarchy is shown in Figure 25.1. The InputStream class is the abstract superclass of all byte input stream classes. It defines methods to read one or more bytes of data, to flush the contents of an input buffer, to close an input stream, and to determine how much data is available from an input stream. These methods are often overridden by InputStream subclasses.

Figure 25.1. Byte input class hierarchy

The InputStream class has a number of subclasses that provide additional functionality or are used for specialized purposes. The FileInputStream class allows you to read data from a file. The ObjectInputStream class lets you restore an object that was previously saved using an ObjectOutputStream . The ByteArrayInputStream class reads data from a byte array.

The FilterInputStream class is the direct superclass of two classes that wrap other InputStream objects to provide additional functionality. The BufferedInputStream class provides a memory buffer that results in more efficient reading of data. The DataInputStream class defines methods that can read a primitive value directly from the stream or to fill a byte array with data from the stream.

The byte input stream classes should be primarily used for data that would normally be stored as bytes such as image, audio, or binary data files. For reading text files, or other character data, you are probably better off using a character input stream.

InputStream Class

The InputStream class is an abstract class that is the superclass of all byte input stream classes and defines methods common to all byte input streams. Among the important methods defined in the InputStream class are the available() , close() , and read() methods.

[View full width]

 
 [View full width] 
 public int available() throws IOException public void close() throws IOException public abstract int read() throws IOException public int read(byte[] buf) throws IOException public int read(byte[] buf, int offset, int length) throws  IOException 

The available() method returns the number of bytes that can be read from the input stream. This method can be useful for sizing a byte array that will store input data. The close() method closes the input stream and releases any resources associated with it. It's always a good idea to close your I/O streams when you are finished with them.

The read() method reads one or more bytes from the input stream. The no-argument version reads a single byte from the stream and returns the byte as an integer value between 0 and 255. The return value is “1 when the end of the stream is reached. The second and third versions fill a byte array with data from the stream. The return value is the number of bytes actually read. An exception is thrown if the byte array argument is null.

BufferedInputStream Class

A BufferedInputStream is used to provide an underlying byte input stream with a memory buffer for more efficient data reading. Instead of reading data byte-by-byte, a large number of bytes are read into an internal buffer. Higher level system functions can read data from the memory buffer. Using a memory buffer improves performance by reducing the number of times the disk must be accessed. A BufferedInputStream object is always wrapped around an underlying InputStream .

The BufferedInputStream class defines two public constructors.

 public BufferedInputStream(InputStream stream) public BufferedInputStream(InputStream stream, int bufferSize) 

You can specify the buffer size in the constructor if you wish. In addition to the constructors, the BufferedInputStream class overrides some of the InputStream methods, including the read() methods, but does not define any new methods for reading byte data.

ByteArrayInputStream Class

The ByteArrayInputStream class is a subclass of the InputStream class that is used to read one or more bytes from a byte array passed to the ByteArrayInputStream constructor. The class defines two constructors.

 public ByteArrayInputStream(byte[] buf) public ByteArrayInputStream(byte[] buf, int offset, int length) 

With the first constructor the entire byte array is available for reading. The second constructor specifies that a maximum of length bytes will be read from the byte array starting at position offset . The ByteArrayInputStream class overrides many of the methods from the InputStream class including the read() methods.

DataInputStream Class

A DataInputStream object allows primitive type values to be read directly from an underlying byte input stream. This can be convenient , for instance, when reading data from a file. The DataInputStream class defines one constructor.

 public DataInputStream(InputStream stream) 

A DataInputStream object is always wrapped around an underlying InputStream . In addition to the read() methods it inherits from the InputStream class, the DataInputStream class defines the following methods to read data.

 public final boolean readBoolean() throws IOException public final byte readByte() throws IOException public final char readChar() throws IOException public final double readDouble() throws IOException public final float readFloat() throws IOException public final int readInt() throws IOException public final long readLong() throws IOException public final short readShort() throws IOException public final int readUnsignedByte() throws IOException public final int readUnsignedShort() throws IOException 

The DataInputStream class methods are all used to read one or more bytes from the underlying stream and return the data read as a primitive type value. The DataInputStream also defines a method that can be used to fill a byte array with data from the stream.

[View full width]

 
 [View full width] 
 public final void readFully(byte[] buf) throws IOException public final void readFully(byte[] buf, int offset, int length)  throws IOException 

The readFully() method will fill the specified byte array with data from the input stream. Either the entire byte array will be filled or a specified number of bytes, starting at the specified offset. If you want to read all of the available bytes in the stream, the available() method can be used to size the byte array before calling this method.

FileInputStream Class

A FileInputStream object associates an input stream with an input file, allowing you to read data from the file. The FileInputStream class defines three constructors.

 public FileInputStream(FileDescriptor fd) public FileInputStream(File file) throws FileNotFoundException public FileInputStream(String path) throws FileNotFoundException 

There are three ways to specify the file. The most direct way is to specify the path to the file. The FileInputStream class provides overridden versions of the three read() methods from the InputStream class. If you want to read primitive data from the file, you can wrap a DataInputStream around the FileInputStream . If you want to read an object that was stored to disk, you can wrap an ObjectInputStream around a FileInputStream .

For an example of using the FileInputStream class, look at the "Saving and Restoring Objects" section later in this chapter.

FilterInputStream Class

FilterInputStream is the superclass for byte input streams that are wrapped around other streams to provide additional functionality to the underlying stream. Subclasses of FilterInputStream include the DataInputStream and BufferedInputStream classes. The FilterInputStream class overrides the InputStream methods to pass all requests to the underlying stream, but does not define any new methods.

ObjectInputStream Class

The ObjectInputStream class is used to restore primitive data and objects that have been serialized using an ObjectOutputStream . When used in conjunction with a FileInputStream , an ObjectInputStream object can be used to read objects that have been saved to disk. Although the ObjectInputStream class is wrapped around another input stream, it is not a subclass of FilterInputStream . The ObjectInputStream class defines one public constructor.

 public ObjectInputStream(InputStream stream) 

In addition to overriding the methods defined in the InputStream class, the ObjectInputStream class defines the following methods to read a primitive value that was previously saved using an ObjectOutputStream .

 public boolean readBoolean() throws IOException public byte readByte() throws IOException public char readChar() throws IOException public double readDouble() throws IOException public float readFloat() throws IOException public int readInt() throws IOException public long readLong() throws IOException public short readShort() throws IOException public int readUnsignedByte() throws IOException public int readUnsignedShort() throws IOException 

The ObjectInputStream class defines two versions of the readFully() method that fill a byte array with data read from the input stream.

[View full width]

 
 [View full width] 
 public void readFully(byte[] buf) throws IOException public void readFully(byte[] buf, int offset, int length) throws  IOException 

The readFully() method will fill the specified byte array with data from the input stream. Either the entire byte array will be filled or a specified number of bytes, starting at the specified offset. If you want to read all of the available bytes in the stream, the available() method can be used to size the byte array before calling this method.

One of the more useful features of the ObjectInputStream class is that it defines a method that can restore a previously serialized object.

[View full width]

 
 [View full width] 
 public final Object readObject() throws IOException,  ClassNotFoundException 

The readObject() method is used to restore an instance of a class that was previously stored using an ObjectOutputStream . Typically, the object will have been written to a file. The default implementation restores the value of all nonstatic and nontransient data members to the return Object . The return value of the method can be cast into another data type if desired. An ObjectInputStream can only restore instances of classes that implement the Serializable interface. The Serializable interface is defined in the java.io package. It declares no methods or constants but is used as a marker to indicate a class that can be serialized (persistently stored).

The "Saving and Restoring Objects" section later in this chapter contains an example of saving and restoring an object to disk.

Other InputStream Subclasses

There are other subclasses of InputStream that you probably won't use much in your technical programming, including the StringBufferInputStream , AudioInputStream , PipedInputStream , and SequenceInputStream classes. We won't discuss details of these classes in this book. If you want more information on any of them, consult the Sun Java doc pages.