Chapter 24

 

---

24. The java.io Package

The java.io package contains a relatively large number of classes, but, as you can see from Figure 24.1 and Figure 24.2, the classes form a fairly structured hierarchy. Most of the package consists of byte streams--subclasses of InputStream or OutputStream--and (in Java 1.1) character streams--subclasses of Reader or Writer. Each of these stream types has a very specific purpose, and despite its size, java.io is a straightforward package to understand and to use.

Before we consider the stream classes in the package, we'll consider the important non-stream classes. File represents a file or directory name in a system independent way, and provides methods for listing directories, querying file attributes, and for renaming and deleting files. FilenameFilter is an interface that defines a method that accepts or rejects specified filenames. It is used by the java.awt.FileDialog dialog box and by the File class to specify what types of files should be included in directory listings. RandomAccessFile allows you to read or write from or to arbitrary locations of a file. Often, though, you'll prefer sequential access to a file and should use one of the stream classes.

InputStream and OutputStream are abstract classes that define methods for reading and writing bytes. Their subclasses allow bytes to be read from and written to a variety of sources and sinks. FileInputStream and FileOutputStream read from and write to files. ByteArrayInputStream and ByteArrayOutputStream read from and write to an array of bytes in memory. PipedInputStream reads bytes from a PipedOutputStream, and PipedOutputStream writes bytes to a PipedInputStream. These classes work together to implement a "pipe" for communication between threads.

FilterInputStream and FilterOutputStream are special--they filter input and output bytes. When a FilterInputStream is created, an InputStream is specified for it to filter. When you call the read() method of a FilterInputStream, it calls the read() method of its specified stream, processes the bytes it reads somehow, and then returns the filtered bytes. Similarly, you specify an OutputStream to be filtered when you create a FilterOutputStream. Calling the write() method of a FilterOutputStream causes it to process your bytes in some way and then pass those filtered bytes to the write() method of its OutputStream.

FilterInputStream and FilterOutputStream do not perform any filtering themselves; this is done by their subclasses. BufferedInputStream and BufferedOutputStream provide input and output buffering and can increase I/O efficiency. DataInputStream reads raw bytes from a stream and interprets them in various binary formats. It has various methods to read primitive Java data types in their standard binary formats. DataOutputStream allows you to write Java primitive data types in binary format.

In Java 1.1, the byte streams just described are complemented by an analogous set of character input and output streams. Reader is the superclass of all character input streams, and Writer is the superclass of all character output streams. These character streams supersede the byte streams for all textual I/O. They are more efficient than the byte streams, and they correctly handle the conversion between local encodings and Unicode text, making them invaluable for internationalized programs. Most of the Reader and Writer streams have obvious byte stream analogs. BufferedReader is a commonly used stream. It provides buffering for efficiency, and also has a readLine() method to read one line of text at a time. PrintWriter is another very common stream--its methods allow output of a textual representation of any primitive Java type or of any object (via the object's toString() method). See Chapter 11, Internationalization for a discussion of the use of character streams in internationalized programs.

The ObjectInputStream and ObjectOutputStream classes are special. These byte stream classes are new in Java 1.1 and are part of the Object Serialization API. See Chapter 9, Object Serialization for further details.

public class BufferedInputStream extends FilterInputStream {
    // Public Constructors
            public BufferedInputStream(InputStream in);
            public BufferedInputStream(InputStream in, int size);
    // Protected Instance Variables
            protected byte[] buf;
            protected int count;
            protected int marklimit;
            protected int markpos;
            protected int pos;
    // Public Instance Methods
            public synchronized int available() throws IOException;  // Overrides FilterInputStream
            public synchronized void mark(int readlimit);  // Overrides FilterInputStream
            public boolean markSupported();  // Overrides FilterInputStream
            public synchronized int read() throws IOException;  // Overrides FilterInputStream
            public synchronized int read(byte[] b, int off, int len) throws IOException;  // Overrides FilterInputStream
            public synchronized void reset() throws IOException;  // Overrides FilterInputStream
            public synchronized long skip(long n) throws IOException;  // Overrides FilterInputStream
}

---

java.beans.Visibility (JDK 1.1)		java.io.BufferedOutputStream (JDK 1.0)

---