The java.io Package (Java in a Nutshell)

The java.io package contains a relatively large number of classes, but, as you can see from Figure 11-1 and Figure 11-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 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, let's examine 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 renaming and deleting files. FilenameFilter is an interface that defines a method that accepts or rejects specified filenames. It is used by java.awt.FileDialog and File to specify what types of files should be included in directory listings. RandomAccessFile allows you to read from or write 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 you create a FilterInputStream, you specify an InputStream for it to filter. When you call the read() method of a FilterInputStream, it calls the read() method of its InputStream, processes the bytes it reads, and returns the filtered bytes. Similarly, when you create a FilterOutputStream, you specify an OutputStream to be filtered. 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.

Figure 11-1. The java.io package

Figure 11-2. The exception classes of the java.io package

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 and later, the byte streams I 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 a 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).

The ObjectInputStream and ObjectOutputStream classes are special. These byte-stream classes are new as of Java 1.1 and are part of the Object Serialization API.

BufferedInputStream

Java 1.0

java.io

PJ1.1

This class is a FilterInputStream that provides input data buffering; efficiency is increased by reading in a large amount of data and storing it in an internal buffer. When data is requested, it is usually available from the buffer. Thus, most calls to read data do not actually have to read data from a disk, network, or other slow source. Create a BufferedInputStream by specifying the InputStream that is to be buffered in the call to the constructor. See also BufferedReader.

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

Hierarchy: Object-->java.io.InputStream-->FilterInputStream-->BufferedInputStream

BufferedOutputStream

Java 1.0

java.io

PJ1.1

This class is a FilterOutputStream that provides output data buffering; output efficiency is increased by storing values to be written in a buffer and actually writing them out only when the buffer fills up or when the flush() method is called. Create a BufferedOutputStream by specifying the OutputStream that is to be buffered in the call to the constructor. See also BufferedWriter.

public class BufferedOutputStream extends FilterOutputStream {
//	Public Constructors
	public BufferedOutputStream (java.io.OutputStream out);
	public BufferedOutputStream (java.io.OutputStream out, int size);
//	Public Methods Overriding FilterOutputStream
	public void flush () throws IOException;	synchronized
	public void write (int b) throws IOException;	synchronized
	public void write (byte[ ] b, int off, int len) throws IOException;	synchronized
//	Protected Instance Fields
	protected byte[ ] buf ;
	protected int count ;
}

Hierarchy: Object-->java.io.OutputStream-->FilterOutputStream-->BufferedOutputStream

BufferedReader

Java 1.1

java.io

PJ1.1

This class applies buffering to a character input stream, thereby improving the efficiency of character input. You create a BufferedReader by specifying some other character input stream from which it is to buffer input. (You can also specify a buffer size at this time, although the default size is usually fine.) Typically, you use this sort of buffering with a FileReader or InputStreamReader. BufferedReader defines the standard set of Reader methods and provides a readLine() method that reads a line of text (not including the line terminator) and returns it as a String. BufferedReader is the character-stream analog of BufferedInputStream. It also provides a replacement for the deprecated readLine() method of DataInputStream, which did not properly convert bytes into characters.

public class BufferedReader extends Reader {
//	Public Constructors
	public BufferedReader (Reader in);
	public BufferedReader (Reader in, int sz);
//	Public Instance Methods
	public String readLine () throws IOException;
//	Public Methods Overriding Reader
	public void close () throws IOException;
	public void mark (int readAheadLimit) throws IOException;
	public boolean markSupported ();	constant
	public int read () throws IOException;
	public int read (char[ ] cbuf, int off, int len) throws IOException;
	public boolean ready () throws IOException;
	public void reset () throws IOException;
	public long skip (long n) throws IOException;
}

Hierarchy: Object-->Reader-->BufferedReader

Subclasses: LineNumberReader

Returned By: javax.servlet.ServletRequest.getReader()

BufferedWriter

Java 1.1

java.io

PJ1.1

This class applies buffering to a character output stream, improving output efficiency by coalescing many small write requests into a single larger request. You create a BufferedWriter by specifying some other character output stream to which it sends its buffered and coalesced output. (You can also specify a buffer size at this time, although the default size is usually satisfactory.) Typically, you use this sort of buffering with a FileWriter or OutputStreamWriter. BufferedWriter defines the standard write(), flush(), and close() methods all output streams define, but it adds a newLine() method that outputs the platform-dependent line separator (usually a newline character, a carriage-return character, or both) to the stream. BufferedWriter is the character-stream analog of BufferedOutputStream.

public class BufferedWriter extends Writer {
//	Public Constructors
	public BufferedWriter (Writer out);
	public BufferedWriter (Writer out, int sz);
//	Public Instance Methods
	public void newLine () throws IOException;
//	Public Methods Overriding Writer
	public void close () throws IOException;
	public void flush () throws IOException;
	public void write (int c) throws IOException;
	public void write (String s, int off, int len) throws IOException;
	public void write (char[ ] cbuf, int off, int len) throws IOException;
}

Hierarchy: Object-->Writer-->BufferedWriter

ByteArrayInputStream

Java 1.0

java.io

PJ1.1

This class is a subclass of InputStream in which input data comes from a specified array of byte values. This is useful when you want to read data in memory as if it were coming from a file, pipe, or socket. Note that the specified array of bytes is not copied when a ByteArrayInputStream is created. See also CharArrayReader.

public class ByteArrayInputStream extends java.io.InputStream {
//	Public Constructors
	public ByteArrayInputStream (byte[ ] buf);
	public ByteArrayInputStream (byte[ ] buf, int offset, int length);
//	Public Methods Overriding InputStream
	public int available ();	synchronized
1.2	public void close () throws IOException;	synchronized
1.1	public void mark (int readAheadLimit);
1.1	public boolean markSupported ();	constant
	public int read ();	synchronized
	public int read (byte[ ] b, int off, int len);	synchronized
	public void reset ();	synchronized
	public long skip (long n);	synchronized
//	Protected Instance Fields
	protected byte[ ] buf ;
	protected int count ;
1.1	protected int mark ;
	protected int pos ;
}

Hierarchy: Object-->java.io.InputStream-->ByteArrayInputStream

ByteArrayOutputStream

Java 1.0

java.io

PJ1.1

This class is a subclass of OutputStream in which output data is stored in an internal byte array. The internal array grows as necessary and can be retrieved with toByteArray() or toString(). The reset() method discards any data currently stored in the internal array and stores data from the beginning again. See also CharArrayWriter.

public class ByteArrayOutputStream extends java.io.OutputStream {
//	Public Constructors
	public ByteArrayOutputStream ();
	public ByteArrayOutputStream (int size);
//	Public Instance Methods
	public void reset ();	synchronized
	public int size ();
	public byte[ ] toByteArray ();	synchronized
1.1	public String toString (String enc) throws UnsupportedEncodingException;
	public void writeTo (java.io.OutputStream out) throws IOException;	synchronized
//	Public Methods Overriding OutputStream
1.2	public void close () throws IOException;	synchronized
	public void write (int b);	synchronized
	public void write (byte[ ] b, int off, int len);	synchronized
//	Public Methods Overriding Object
	public String toString ();
//	Protected Instance Fields
	protected byte[ ] buf ;
	protected int count ;
//	Deprecated Public Methods
#	public String toString (int hibyte);
}

Hierarchy: Object-->java.io.OutputStream-->ByteArrayOutputStream

CharArrayReader

Java 1.1

java.io

PJ1.1

This class is a character input stream that uses a character array as the source of the characters it returns. You create a CharArrayReader by specifying the character array (or portion of an array) it is to read from. CharArrayReader defines the usual Reader methods and supports the mark() and reset() methods. Note that the character array you pass to the CharArrayReader() constructor is not copied. This means that changes you make to the elements of the array after you create the input stream affect the values read from the array. CharArrayReader is the character-array analog of ByteArrayInputStream and is similar to StringReader.

public class CharArrayReader extends Reader {
//	Public Constructors
	public CharArrayReader (char[ ] buf);
	public CharArrayReader (char[ ] buf, int offset, int length);
//	Public Methods Overriding Reader
	public void close ();
	public void mark (int readAheadLimit) throws IOException;
	public boolean markSupported ();	constant
	public int read () throws IOException;
	public int read (char[ ] b, int off, int len) throws IOException;
	public boolean ready () throws IOException;
	public void reset () throws IOException;
	public long skip (long n) throws IOException;
//	Protected Instance Fields
	protected char[ ] buf ;
	protected int count ;
	protected int markedPos ;
	protected int pos ;
}

Hierarchy: Object-->Reader-->CharArrayReader

CharArrayWriter

Java 1.1

java.io

PJ1.1

This class is a character output stream that uses an internal character array as the destination of characters written to it. When you create a CharArrayWriter, you may optionally specify an initial size for the character array, but you do not specify the character array itself; this array is managed internally by the CharArrayWriter and grows as necessary to accommodate all the characters written to it. The toString() and toCharArray() methods return a copy of all characters written to the stream, as a string and an array of characters, respectively. CharArrayWriter defines the standard write(), flush(), and close() methods all Writer subclasses define. It also defines a few other useful methods. size() returns the number of characters that have been written to the stream. reset() resets the stream to its initial state, with an empty character array; this is more efficient than creating a new CharArrayWriter. Finally, writeTo() writes the contents of the internal character array to some other specified character stream. CharArrayWriter is the character-stream analog of ByteArrayOutputStream and is quite similar to StringWriter.

public class CharArrayWriter extends Writer {
//	Public Constructors
	public CharArrayWriter ();
	public CharArrayWriter (int initialSize);
//	Public Instance Methods
	public void reset ();
	public int size ();
	public char[ ] toCharArray ();
	public void writeTo (Writer out) throws IOException;
//	Public Methods Overriding Writer
	public void close ();	empty
	public void flush ();	empty
	public void write (int c);
	public void write (char[ ] c, int off, int len);
	public void write (String str, int off, int len);
//	Public Methods Overriding Object
	public String toString ();
//	Protected Instance Fields
	protected char[ ] buf ;
	protected int count ;
}

Hierarchy: Object-->Writer-->CharArrayWriter

CharConversionException

Java 1.1

java.io

serializable checked PJ1.1

Signals an error when converting bytes to characters or vice versa.

public class CharConversionException extends IOException {
//	Public Constructors
	public CharConversionException ();
	public CharConversionException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->CharConversionException

DataInput

Java 1.0

java.io

PJ1.1

This interface defines the methods required for streams that can read Java primitive data types in a machine-independent binary format. It is implemented by DataInputStream and RandomAccessFile. See DataInputStream for more information on the methods.

public interface DataInput {
//	Public Instance Methods
	public abstract boolean readBoolean () throws IOException;
	public abstract byte readByte () throws IOException;
	public abstract char readChar () throws IOException;
	public abstract double readDouble () throws IOException;
	public abstract float readFloat () throws IOException;
	public abstract void readFully (byte[ ] b) throws IOException;
	public abstract void readFully (byte[ ] b, int off, int len) throws IOException;
	public abstract int readInt () throws IOException;
	public abstract String readLine () throws IOException;
	public abstract long readLong () throws IOException;
	public abstract short readShort () throws IOException;
	public abstract int readUnsignedByte () throws IOException;
	public abstract int readUnsignedShort () throws IOException;
	public abstract String readUTF () throws IOException;
	public abstract int skipBytes (int n) throws IOException;
}

Implementations: java.io.DataInputStream, ObjectInput, RandomAccessFile

Passed To: java.io.DataInputStream.readUTF(), java.rmi.server.UID.read()

DataInputStream

Java 1.0

java.io

PJ1.1

This class is a type of FilterInputStream that allows you to read binary representations of Java primitive data types in a portable way. Create a DataInputStream by specifying the InputStream that is to be filtered in the call to the constructor. DataInputStream reads only primitive Java types; use ObjectInputStream to read object values.

Many of the methods read and return a single Java primitive type, in binary format, from the stream. readUnsignedByte() and readUnsignedShort() read unsigned values and return them as int values, since unsigned byte and short types are not supported in Java. read() reads data into an array of bytes, blocking until at least some data is available. By contrast, readFully() reads data into an array of bytes, but blocks until all requested data becomes available. skipBytes() blocks until the specified number of bytes have been read and discarded. readLine() reads characters from the stream until it encounters a newline, a carriage return, or a newline/carriage return pair. The returned string is not terminated with a newline or carriage return. This method is deprecated as of Java 1.1; see BufferedReader for an alternative. readUTF() reads a string of Unicode text encoded in a slightly modified version of the UTF-8 transformation format. UTF-8 is an ASCII-compatible encoding of Unicode characters that is often used for the transmission and storage of Unicode text. This class uses a modified UTF-8 encoding that never contains embedded null characters.

public class DataInputStream extends FilterInputStream implements DataInput {
//	Public Constructors
	public DataInputStream (java.io.InputStream in);
//	Public Class Methods
	public static final String readUTF (DataInput in) throws IOException;
//	Methods Implementing DataInput
	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 void readFully (byte[ ] b) throws IOException;
	public final void readFully (byte[ ] b, int off, int len) 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;
	public final String readUTF () throws IOException;
	public final int skipBytes (int n) throws IOException;
//	Public Methods Overriding FilterInputStream
	public final int read (byte[ ] b) throws IOException;
	public final int read (byte[ ] b, int off, int len) throws IOException;
//	Deprecated Public Methods
#	public final String readLine () throws IOException;	Implements:DataInput
}

Hierarchy: Object-->java.io.InputStream-->FilterInputStream-->java.io.DataInputStream(DataInput)

Passed To: javax.swing.text.html.parser.DTD.read()

DataOutput

Java 1.0

java.io

PJ1.1

This interface defines the methods required for streams that can write Java primitive data types in a machine-independent binary format. It is implemented by DataOutputStream and RandomAccessFile. See DataOutputStream for more information on the methods.

public interface DataOutput {
//	Public Instance Methods
	public abstract void write (byte[ ] b) throws IOException;
	public abstract void write (int b) throws IOException;
	public abstract void write (byte[ ] b, int off, int len) throws IOException;
	public abstract void writeBoolean (boolean v) throws IOException;
	public abstract void writeByte (int v) throws IOException;
	public abstract void writeBytes (String s) throws IOException;
	public abstract void writeChar (int v) throws IOException;
	public abstract void writeChars (String s) throws IOException;
	public abstract void writeDouble (double v) throws IOException;
	public abstract void writeFloat (float v) throws IOException;
	public abstract void writeInt (int v) throws IOException;
	public abstract void writeLong (long v) throws IOException;
	public abstract void writeShort (int v) throws IOException;
	public abstract void writeUTF (String str) throws IOException;
}

Implementations: java.io.DataOutputStream, ObjectOutput, RandomAccessFile

Passed To: java.rmi.server.UID.write()

DataOutputStream

Java 1.0

java.io

PJ1.1

This class is a subclass of FilterOutputStream that allows you to write Java primitive data types in a portable binary format. Create a DataOutputStream by specifying the OutputStream that is to be filtered in the call to the constructor. DataOutputStream has methods that output only primitive types; use ObjectOutputStream to output object values.

Many of this class's methods write a single Java primitive type, in binary format, to the output stream. write() writes a single byte, an array, or a subarray of bytes. flush() forces any buffered data to be output. size() returns the number of bytes written so far. writeUTF() outputs a Java string of Unicode characters using a slightly modified version of the UTF-8 transformation format. UTF-8 is an ASCII-compatible encoding of Unicode characters that is often used for the transmission and storage of Unicode text. Except for the writeUTF() method, this class is used for binary output of data. Textual output should be done with PrintWriter (or PrintStream in Java 1.0).

public class DataOutputStream extends FilterOutputStream implements DataOutput {
//	Public Constructors
	public DataOutputStream (java.io.OutputStream out);
//	Public Instance Methods
	public final int size ();
//	Methods Implementing DataOutput
	public void write (int b) throws IOException;	synchronized
	public void write (byte[ ] b, int off, int len) throws IOException;	synchronized
	public final void writeBoolean (boolean v) throws IOException;
	public final void writeByte (int v) throws IOException;
	public final void writeBytes (String s) throws IOException;
	public final void writeChar (int v) throws IOException;
	public final void writeChars (String s) throws IOException;
	public final void writeDouble (double v) throws IOException;
	public final void writeFloat (float v) throws IOException;
	public final void writeInt (int v) throws IOException;
	public final void writeLong (long v) throws IOException;
	public final void writeShort (int v) throws IOException;
	public final void writeUTF (String str) throws IOException;
//	Public Methods Overriding FilterOutputStream
	public void flush () throws IOException;
//	Protected Instance Fields
	protected int written ;
}

Hierarchy: Object-->java.io.OutputStream-->FilterOutputStream-->java.io.DataOutputStream(DataOutput)

EOFException

Java 1.0

java.io

serializable checked PJ1.1

An IOException that signals the end-of-file.

public class EOFException extends IOException {
//	Public Constructors
	public EOFException ();
	public EOFException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->EOFException

Externalizable

Java 1.1

java.io

serializable PJ1.1

This interface defines the methods that must be implemented by an object that wants complete control over the way it is serialized. The writeExternal() and readExternal() methods should be implemented to write and read object data in some arbitrary format, using the methods of the DataOutput and DataInput interfaces. Externalizable objects must serialize their own fields and are also responsible for serializing the fields of their superclasses. Most objects do not need to define a custom output format and can use the Serializable interface instead of Externalizable for serialization.

public interface Externalizable extends Serializable {
//	Public Instance Methods
	public abstract void readExternal (ObjectInput in) throws IOExceptionClassNotFoundException;
	public abstract void writeExternal (ObjectOutput out) throws IOException;
}

Hierarchy: (Externalizable(Serializable))

Implementations: java.awt.datatransfer.DataFlavor, java.rmi.server.RemoteRef

File

Java 1.0

java.io

serializable comparable PJ1.1(opt)

This class supports a platform-independent definition of file and directory names. It also provides methods to list the files in a directory; check the existence, readability, writeability, type, size, and modification time of files and directories; make new directories; rename files and directories; delete files and directories; and create and delete temporary and lock files. The constants defined by this class are the platform-dependent directory and path-separator characters, available as a String and a char.

getName() returns the name of the File with any directory names omitted. getPath() returns the full name of the file, including the directory name. getParent() and getParentFile() return the directory that contains the File; the only difference between the two methods is that one returns a String, while the other returns a File. isAbsolute() tests whether the File is an absolute specification. If not, getAbsolutePath() returns an absolute filename created by appending the relative filename to the current working directory. getAbsoluteFile() returns the equivalent absolute File object. getCanonicalPath() and getCanonicalFile() are similar methods: they return an absolute filename or File object that has been converted to its system-dependent canonical form. This can be useful when comparing two File objects to see if they refer to the same file or directory.

exists(), canWrite(), canRead(), isFile(), isDirectory(), and isHidden() perform the obvious tests on the specified File. length() returns the length of the file. lastModified() returns the modification time of the file (which should be used for comparison with other file times only and not interpreted as any particular time format). setLastModified() allows the modification time to be set; setReadOnly() makes a file or directory read-only.

list() returns the names of all entries in a directory that are not rejected by an optional FilenameFilter. listFiles() returns an array of File objects that represent all entries in a directory not rejected by an optional FilenameFilter or FileFilter. listRoots() returns an array of File objects representing all root directories on the system. On Unix systems, for example, there is typically only one root, /. On Windows systems, however, there is a different root for each drive letter: c:\, d:\, and e:\, for example.

mkdir() creates a directory, and mkdirs() creates all the directories in a File specification. renameTo() renames a file or directory; delete() deletes a file or directory. Prior to Java 1.2, the File class doesn't provide any way to create a file; that task is accomplished typically with FileOutputStream. As of Java 1.2, however, two special-purpose file creation methods have been added. The static createTempFile() method returns a File object that refers to a newly created empty file with a unique name that begins with the specified prefix (which must be at least three characters long) and ends with the specified suffix. One version of this method creates the file in a specified directory, and the other creates it in the system temporary directory. Applications can use temporary files for any purpose without worrying about overwriting files belonging to other applications. The other file-creation method of Java 1.2 is createNewFile(). This instance method attempts to create a new, empty file with the name specified by the File object. If it succeeds, it returns true. However, if the file already exists, it returns false. createNewFile() works atomically, and is therefore useful for file locking and other mutual-exclusion schemes. When working with createTempFile() or createNewFile(), consider using deleteOnExit() to request that the files be deleted when the Java VM exits normally.

public class File implements ComparableSerializable {
//	Public Constructors
	public File (String pathname);
	public File (String parent, String child);
	public File (File parent, String child);
//	Public Constants
	public static final String pathSeparator ;
	public static final char pathSeparatorChar ;
	public static final String separator ;
	public static final char separatorChar ;
//	Public Class Methods
1.2	public static File createTempFile (String prefix, String suffix) throws IOException;
1.2	public static File createTempFile (String prefix, String suffix, File directory) throws IOException;
1.2	public static File[ ] listRoots ();
//	Property Accessor Methods (by property name)
	public boolean isAbsolute ();
1.2	public File getAbsoluteFile ();
	public String getAbsolutePath ();
1.2	public File getCanonicalFile () throws IOException;
1.1	public String getCanonicalPath () throws IOException;
	public boolean isDirectory ();
	public boolean isFile ();
1.2	public boolean isHidden ();
	public String getName ();
	public String getParent ();
1.2	public File getParentFile ();
	public String getPath ();
//	Public Instance Methods
	public boolean canRead ();
	public boolean canWrite ();
1.2	public int compareTo (File pathname);
1.2	public boolean createNewFile () throws IOException;
	public boolean delete ();
1.2	public void deleteOnExit ();
	public boolean exists ();
	public long lastModified ();
	public long length ();
	public String[ ] list ();
	public String[ ] list (FilenameFilter filter);
1.2	public File[ ] listFiles ();
1.2	public File[ ] listFiles (java.io.FileFilter filter);
1.2	public File[ ] listFiles (FilenameFilter filter);
	public boolean mkdir ();
	public boolean mkdirs ();
	public boolean renameTo (File dest);
1.2	public boolean setLastModified (long time);
1.2	public boolean setReadOnly ();
1.2	public java.net.URL toURL () throws java.net.MalformedURLException;
//	Methods Implementing Comparable
1.2	public int compareTo (Object o);
//	Public Methods Overriding Object
	public boolean equals (Object obj);
	public int hashCode ();
	public String toString ();
}

Hierarchy: Object-->File(Comparable,Serializable)

Passed To: Too many methods to list.

Returned By: Too many methods to list.

FileDescriptor

Java 1.0

java.io

PJ1.1

This class is a platform-independent representation of a low-level handle to an open file or socket. The static in, out, and err variables are FileDescriptor objects that represent the standard input, output, and error streams, respectively. There is no public constructor method to create a FileDescriptor object. You can obtain one with the getFD() method of FileInputStream, FileOutputStream, or RandomAccessFile.

public final class FileDescriptor {
//	Public Constructors
	public FileDescriptor ();
//	Public Constants
	public static final FileDescriptor err ;
	public static final FileDescriptor in ;
	public static final FileDescriptor out ;
//	Public Instance Methods
1.1	public void sync () throws SyncFailedException;	native
	public boolean valid ();
}

Passed To: FileInputStream.FileInputStream(), FileOutputStream.FileOutputStream(), FileReader.FileReader(), FileWriter.FileWriter(), SecurityManager.{checkRead(), checkWrite()}

Returned By: FileInputStream.getFD(), FileOutputStream.getFD(), RandomAccessFile.getFD(), java.net.DatagramSocketImpl.getFileDescriptor(), java.net.SocketImpl.getFileDescriptor()

Type Of: FileDescriptor.{err, in, out}, java.net.DatagramSocketImpl.fd, java.net.SocketImpl.fd

FileFilter

Java 1.2

java.io

This interface defines an accept() method that filters a list of files. You can list the contents of a directory by calling the listFiles() method of the File object that represents the desired directory. If you want a filtered listing, such as a listing of files but not subdirectories or a listing of files whose names end in .class, you can pass a FileFilter object to listFiles(). For each entry in the directory, a File object is passed to the accept() method. If accept() returns true, that File is included in the return value of listFiles(). If accept() returns false, that entry is not included in the listing. FileFilter is new in Java 1.2. Use FilenameFilter if compatibility with previous releases of Java is required or if you prefer to filter filenames (i.e., String objects) rather than File objects.

public interface FileFilter {
//	Public Instance Methods
	public abstract boolean accept (File pathname);
}

Passed To: File.listFiles()

FileInputStream

Java 1.0

java.io

PJ1.1(opt)

This class is a subclass of InputStream that reads bytes from a file specified by name or by a File or FileDescriptor object. read() reads a byte or array of bytes from the file. It returns -1 when the end-of-file has been reached. To read binary data, you typically use this class in conjunction with a BufferedInputStream and DataInputStream. To read text, you typically use it with an InputStreamReader and BufferedReader. Call close() to close the file when input is no longer needed.

public class FileInputStream extends java.io.InputStream {
//	Public Constructors
	public FileInputStream (String name) throws FileNotFoundException;
	public FileInputStream (FileDescriptor fdObj);
	public FileInputStream (File file) throws FileNotFoundException;
//	Public Instance Methods
	public final FileDescriptor getFD () throws IOException;
//	Public Methods Overriding InputStream
	public int available () throws IOException;	native
	public void close () throws IOException;	native
	public int read () throws IOException;	native
	public int read (byte[ ] b) throws IOException;
	public int read (byte[ ] b, int off, int len) throws IOException;
	public long skip (long n) throws IOException;	native
//	Protected Methods Overriding Object
	protected void finalize () throws IOException;
}

Hierarchy: Object-->java.io.InputStream-->FileInputStream

FilenameFilter

Java 1.0

java.io

PJ1.1(opt)

This interface defines the accept() method that must be implemented by any object that filters filenames (i.e., selects a subset of filenames from a list of filenames). There are no standard FilenameFilter classes implemented by Java, but objects that implement this interface are used by the java.awt.FileDialog object and the File.list() method. A typical FilenameFilter object might check that the specified File represents a file (not a directory), is readable (and possibly writable as well), and that its name ends with some desired extension.

public interface FilenameFilter {
//	Public Instance Methods
	public abstract boolean accept (File dir, String name);
}

Passed To: java.awt.FileDialog.setFilenameFilter(), java.awt.peer.FileDialogPeer.setFilenameFilter(), File.{list(), listFiles()}

Returned By: java.awt.FileDialog.getFilenameFilter()

FileNotFoundException

Java 1.0

java.io

serializable checked PJ1.1(opt)

An IOException that signals that a specified file cannot be found.

public class FileNotFoundException extends IOException {
//	Public Constructors
	public FileNotFoundException ();
	public FileNotFoundException (String s);
}

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->FileNotFoundException

Thrown By: FileInputStream.FileInputStream(), FileOutputStream.FileOutputStream(), FileReader.FileReader(), RandomAccessFile.RandomAccessFile()

FileOutputStream

Java 1.0

java.io

PJ1.1(opt)

This class is a subclass of OutputStream that writes data to a file specified by name or by a File or FileDescriptor object. write() writes a byte or array of bytes to the file. To write binary data, you typically use this class in conjunction with a BufferedOutputStream and a DataOutputStream. To write text, you typically use it with a PrintWriter, BufferedWriter and an OutputStreamWriter. Use close() to close a FileOutputStream when no further output will be written to it.

public class FileOutputStream extends java.io.OutputStream {
//	Public Constructors
	public FileOutputStream (FileDescriptor fdObj);
	public FileOutputStream (String name) throws FileNotFoundException;
	public FileOutputStream (File file) throws FileNotFoundException;
1.1	public FileOutputStream (String name, boolean append) throws FileNotFoundException;
//	Public Instance Methods
	public final FileDescriptor getFD () throws IOException;
//	Public Methods Overriding OutputStream
	public void close () throws IOException;	native
	public void write (int b) throws IOException;	native
	public void write (byte[ ] b) throws IOException;
	public void write (byte[ ] b, int off, int len) throws IOException;
//	Protected Methods Overriding Object
	protected void finalize () throws IOException;
}

Hierarchy: Object-->java.io.OutputStream-->FileOutputStream

FilePermission

Java 1.2

java.io

serializable permission

This class is a java.security.Permission that governs access to the local filesystem. A FilePermission has a name, or target, which specifies what file or files it pertains to, and a comma-separated list of actions that may be performed on the file or files. The supported actions are "read", "write", "delete", and "execute". Read and write permission are required by any methods that read or write a file. Delete permission is required by File.delete(), and execute permission is required by Runtime.exec().

The name of a FilePermission may be as simple as a file or directory name. FilePermission also supports the use of certain wildcards, however, to specify a permission that applies to more than one file. If the name of the FilePermission is a directory name followed by "/*" ("\*" on Windows platforms), it specifies all files in the named directory. If the name is a directory name followed by "/-" ("\-" on Windows), it specifies all files in the directory, and, recursively, all files in all subdirectories. A "*" alone specifies all files in the current directory, and a "-" alone specifies all files in or beneath the current directory. Finally, the special name "<<ALL FILES>>" matches all files anywhere in the filesystem.

Applications do not need to use this class directly. Programmers writing system-level code and system administrators configuring security policies may need to use it, however. Be very careful when granting any types of FilePermission. Restricting access (especially write access) to files is one of the cornerstones of the Java security model with regard to untrusted code.

public final class FilePermission extends java.security.Permission implements Serializable {
//	Public Constructors
	public FilePermission (String path, String actions);
//	Public Methods Overriding Permission
	public boolean equals (Object obj);
	public String getActions ();
	public int hashCode ();
	public boolean implies (java.security.Permission p);
	public java.security.PermissionCollection newPermissionCollection ();
}

Hierarchy: Object-->java.security.Permission(java.security.Guard,Serializable)-->FilePermission(Serializable)

FileReader

Java 1.1

java.io

PJ1.1(opt)

FileReader is a convenience subclass of InputStreamReader that is useful when you want to read text (as opposed to binary data) from a file. You create a FileReader by specifying the file to be read in any of three possible forms. The FileReader constructor internally creates a FileInputStream to read bytes from the specified file and uses the functionality of its superclass, InputStreamReader, to convert those bytes from characters in the local encoding to the Unicode characters used by Java. Because FileReader is a trivial subclass of InputStreamReader, it does not define any read() methods or other methods of its own. Instead, it inherits all its methods from its superclass. If you want to read Unicode characters from a file that uses some encoding other than the default encoding for the locale, you must explicitly create your own InputStreamReader to perform the byte-to-character conversion.

public class FileReader extends InputStreamReader {
//	Public Constructors
	public FileReader (FileDescriptor fd);
	public FileReader (File file) throws FileNotFoundException;
	public FileReader (String fileName) throws FileNotFoundException;
}

Hierarchy: Object-->Reader-->InputStreamReader-->FileReader

FileWriter

Java 1.1

java.io

PJ1.1(opt)

FileWriter is a convenience subclass of OutputStreamWriter that is useful when you want to write text (as opposed to binary data) to a file. You create a FileWriter by specifying the file to be written to and, optionally, whether the data should be appended to the end of an existing file instead of overwriting that file. The FileWriter class creates an internal FileOutputStream to write bytes to the specified file and uses the functionality of its superclass, OutputStreamWriter, to convert the Unicode characters written to the stream into bytes using the default encoding of the default locale. (If you want to use an encoding other than the default, you cannot use FileWriter; in that case you must create your own OutputStreamWriter and FileOutputStream.) Because FileWriter is a trivial subclass of OutputStreamWriter, it does not define any methods of its own, but simply inherits them from its superclass.

public class FileWriter extends OutputStreamWriter {
//	Public Constructors
	public FileWriter (File file) throws IOException;
	public FileWriter (FileDescriptor fd);
	public FileWriter (String fileName) throws IOException;
	public FileWriter (String fileName, boolean append) throws IOException;
}

Hierarchy: Object-->Writer-->OutputStreamWriter-->FileWriter

FilterInputStream

Java 1.0

java.io

PJ1.1

This class provides method definitions required to filter data obtained from the InputStream specified when the FilterInputStream is created. It must be subclassed to perform some sort of filtering operation and cannot be instantiated directly. See the subclasses BufferedInputStream, DataInputStream, and PushbackInputStream.

public class FilterInputStream extends java.io.InputStream {
//	Protected Constructors
	protected FilterInputStream (java.io.InputStream in);
//	Public Methods Overriding InputStream
	public int available () throws IOException;
	public void close () throws IOException;
	public void mark (int readlimit);	synchronized
	public boolean markSupported ();
	public int read () throws IOException;
	public int read (byte[ ] b) throws IOException;
	public int read (byte[ ] b, int off, int len) throws IOException;
	public void reset () throws IOException;	synchronized
	public long skip (long n) throws IOException;
//	Protected Instance Fields
	protected java.io.InputStream in ;
}

Hierarchy: Object-->java.io.InputStream-->FilterInputStream

Subclasses: BufferedInputStream, java.io.DataInputStream, LineNumberInputStream, PushbackInputStream, java.security.DigestInputStream, java.util.zip.CheckedInputStream, java.util.zip.InflaterInputStream, javax.crypto.CipherInputStream, javax.swing.ProgressMonitorInputStream

public class FilterOutputStream extends java.io.OutputStream {
//	Public Constructors
	public FilterOutputStream (java.io.OutputStream out);
//	Public Methods Overriding OutputStream
	public void close () throws IOException;
	public void flush () throws IOException;
	public void write (int b) throws IOException;
	public void write (byte[ ] b) throws IOException;
	public void write (byte[ ] b, int off, int len) throws IOException;
//	Protected Instance Fields
	protected java.io.OutputStream out ;
}

Chapter 11. The java.io Package

Figure 11-1. The java.io package

Figure 11-2. The exception classes of the java.io package