Chapter 11. The java.io Package

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

FilterOutputStream	Java 1.0
java.io	PJ1.1

This class provides method definitions required to filter the data to be written to the OutputStream specified when the FilterOutputStream is created. It must be subclassed to perform some sort of filtering operation and may not be instantiated directly. See the subclasses BufferedOutputStream and DataOutputStream.

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

Subclasses: BufferedOutputStream, java.io.DataOutputStream, PrintStream, java.security.DigestOutputStream, java.util.zip.CheckedOutputStream, java.util.zip.DeflaterOutputStream, javax.crypto.CipherOutputStream

FilterReader	Java 1.1
java.io	PJ1.1

This abstract class is intended to act as a superclass for character input streams that read data from some other character input stream, filter it in some way, and then return the filtered data when a read() method is called. FilterReader is declared abstract so that it cannot be instantiated. But none of its methods are themselves abstract: they all simply call the requested operation on the input stream passed to the FilterReader() constructor. If you were allowed to instantiate a FilterReader, you'd find that it is a null filter (i.e., it simply reads characters from the specified input stream and returns them without any kind of filtering).

Because FilterReader implements a null filter, it is an ideal superclass for classes that want to implement simple filters but do not want to override all the methods of Reader. In order to create your own filtered character input stream, you should subclass FilterReader and override both its read() methods to perform the desired filtering operation. Note that you can implement one of the read() methods in terms of the other, and thus only implement the filtration once. Recall that the other read() methods defined by Reader are implemented in terms of these methods, so you do not need to override those. In some cases, you may need to override other methods of FilterReader and provide methods or constructors that are specific to your subclass. FilterReader is the character-stream analog to FilterInputStream.

Hierarchy: Object-->Reader-->FilterReader

Subclasses: PushbackReader

FilterWriter	Java 1.1
java.io	PJ1.1

This abstract class is intended to act as a superclass for character output streams that filter the data written to them before writing it to some other character output stream. FilterWriter is declared abstract so that it cannot be instantiated. But none of its methods are themselves abstract: they all simply invoke the corresponding method on the output stream that was passed to the FilterWriter constructor. If you were allowed to instantiate a FilterWriter object, you'd find that it acts as a null filter (i.e., it simply passes the characters written to it along, without any filtration).

Because FilterWriter implements a null filter, it is an ideal superclass for classes that want to implement simple filters without having to override all of the methods of Writer. In order to create your own filtered character output stream, you should subclass FilterWriter and override all its write() methods to perform the desired filtering operation. Note that you can implement two of the write() methods in terms of the third and thus implement your filtering algorithm only once. In some cases, you may want to override other Writer methods and add other methods or constructors that are specific to your subclass. FilterWriter is the character-stream analog of FilterOutputStream.

Hierarchy: Object-->Writer-->FilterWriter

InputStream	Java 1.0
java.io	PJ1.1

This abstract class is the superclass of all input streams. It defines the basic input methods all input stream classes provide.read() reads a single byte or an array (or subarray) of bytes. It returns the byte read, the number of bytes read, or -1 if the end-of-file has been reached. skip() skips a specified number of bytes of input. available() returns the number of bytes that can be read without blocking. close() closes the input stream and frees up any system resources associated with it. The stream should not be used after close() has been called.

If markSupported() returns true for a given InputStream, that stream supports mark() and reset() methods. mark() marks the current position in the input stream so that reset() can return to that position (as long as no more than the specified number of bytes have been read between the calls to mark() and reset()). See also Reader.

Subclasses: ByteArrayInputStream, FileInputStream, FilterInputStream, ObjectInputStream, PipedInputStream, SequenceInputStream, StringBufferInputStream, javax.servlet.ServletInputStream, org.omg.CORBA.portable.InputStream

Passed To: Too many methods to list.

Returned By: Too many methods to list.

Type Of: FilterInputStream.in, System.in

InputStreamReader	Java 1.1
java.io	PJ1.1

This class is a character input stream that uses a byte input stream as its data source. It reads bytes from a specified InputStream and translates them into Unicode characters according to a particular platform- and locale-dependent character encoding. This is an important internationalization feature in Java 1.1 and later. InputStreamReader supports the standard Reader methods. It also has a getEncoding() method that returns the name of the encoding being used to convert bytes to characters.

When you create an InputStreamReader, you specify an InputStream from which the InputStreamReader is to read bytes and, optionally, the name of the character encoding used by those bytes. If you do not specify an encoding name, the InputStreamReader uses the default encoding for the default locale, which is usually the correct thing to do.

Hierarchy: Object-->Reader-->InputStreamReader

Subclasses: FileReader

InterruptedIOException	Java 1.0
java.io	serializable checked PJ1.1

An IOException that signals that an input or output operation was interrupted. The bytesTransferred field contains the number of bytes read or written before the operation was interrupted.

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

InvalidClassException	Java 1.1
java.io	serializable checked PJ1.1

Signals that the serialization mechanism has encountered one of several possible problems with the class of an object that is being serialized or deserialized. The classname field should contain the name of the class in question, and the getMessage() method is overridden to return this class name with the message.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->ObjectStreamException-->InvalidClassException

InvalidObjectException	Java 1.1
java.io	serializable checked PJ1.1

This exception should be thrown by the validateObject() method of an object that implements the ObjectInputValidation interface when a deserialized object fails an input validation test for any reason.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->ObjectStreamException-->InvalidObjectException

Thrown By: java.awt.font.TextAttribute.readResolve(), ObjectInputStream.registerValidation(), ObjectInputValidation.validateObject(), java.text.AttributedCharacterIterator.Attribute.readResolve()

IOException	Java 1.0
java.io	serializable checked PJ1.1

Signals that an exceptional condition has occurred during input or output. This class has several more specific subclasses. See EOFException, FileNotFoundException, InterruptedIOException, and UTFDataFormatException.

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

Subclasses: CharConversionException, EOFException, FileNotFoundException, InterruptedIOException, ObjectStreamException, SyncFailedException, UnsupportedEncodingException, UTFDataFormatException, java.net.MalformedURLException, java.net.ProtocolException, java.net.SocketException, java.net.UnknownHostException, java.net.UnknownServiceException, java.rmi.RemoteException, java.util.zip.ZipException, javax.swing.text.ChangedCharSetException

Passed To: java.awt.print.PrinterIOException.PrinterIOException()

Returned By: java.awt.print.PrinterIOException.getIOException()

Thrown By: Too many methods to list.

LineNumberInputStream	Java 1.0; Deprecated in Java 1.1
java.io	PJ1.1

This class is a FilterInputStream that keeps track of the number of lines of data that have been read. getLineNumber() returns the current line number; setLineNumber() sets the line number of the current line. Subsequent lines are numbered starting from that number. This class is deprecated as of Java 1.1 because it does not properly convert bytes to characters. Use LineNumberReader instead.

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

LineNumberReader	Java 1.1
java.io	PJ1.1

This class is a character input stream that keeps track of the number of lines of text that have been read from it. It supports the usual Reader methods and also the readLine() method introduced by its superclass. In addition to these methods, you can call getLineNumber() to query the number of lines set so far. You can also call setLineNumber() to set the line number for the current line. Subsequent lines are numbered sequentially from this specified starting point. This class is a character-stream analog to LineNumberInputStream, which has been deprecated as of Java 1.1.

Hierarchy: Object-->Reader-->BufferedReader-->LineNumberReader

NotActiveException	Java 1.1
java.io	serializable checked PJ1.1

This exception is thrown in several circumstances. It indicates that the invoked method was not invoked at the right time or in the correct context. Typically, it means that an ObjectOutputStream or ObjectInputStream is not currently active and therefore the requested operation cannot be performed.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->ObjectStreamException-->NotActiveException

Thrown By: ObjectInputStream.{defaultReadObject(), readFields(), registerValidation()}

NotSerializableException	Java 1.1
java.io	serializable checked PJ1.1

Signals that an object cannot be serialized. It is thrown when serialization is attempted on an instance of a class that does not implement the Serializable interface. Note that it is also thrown when an attempt is made to serialize a Serializable object that refers to (or contains) an object that is not Serializable. A subclass of a class that is Serializable can prevent itself from being serialized by throwing this exception from its writeObject() and/or readObject() methods.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->ObjectStreamException-->NotSerializableException

ObjectInput	Java 1.1
java.io	PJ1.1

This interface extends the DataInput interface and adds methods for deserializing objects and reading bytes and arrays of bytes.

Hierarchy: (ObjectInput(DataInput))

Implementations: ObjectInputStream

Passed To: java.awt.datatransfer.DataFlavor.readExternal(), Externalizable.readExternal(), java.rmi.server.ObjID.read()

Returned By: java.rmi.server.RemoteCall.getInputStream()

ObjectInputStream	Java 1.1
java.io	PJ1.1

ObjectInputStream deserializes objects, arrays, and other values from a stream that was previously created with an ObjectOutputStream. The readObject() method deserializes objects and arrays (which should then be cast to the appropriate type); various other methods read primitive data values from the stream. Note that only objects that implement the Serializable or Externalizable interface can be serialized and deserialized.

A class may implement its own private readObject(ObjectInputStream) method to customize the way it is deserialized. If you define such a method, there are several ObjectInputStream methods you can use to help you deserialize the object. defaultReadObject() is the easiest. It reads the content of the object just as an ObjectInputStream would normally do. If you wrote additional data before or after the default object contents, you should read that data before or after calling defaultReadObject(). When working with multiple versions or implementations of a class, you may have to deserialize a set of fields that do not match the fields of your class. In this case, give your class a static field named serialPersistentFields whose value is an array of ObjectStreamField objects that describe the fields to be deserialized. If you do this, your readObject() method can call readFields() to read the specified fields from the stream and return them in a ObjectInputStream.GetField object. See ObjectStreamField and ObjectInputStream.GetField for more details. Finally, you can call registerValidation() from a custom readObject() method. This method registers an ObjectInputValidation object (typically the object being deserialized) to be notified when a complete tree of objects has been deserialized, and the original call to the readObject() method of the ObjectInputStream is about to return to its caller.

The remaining methods include miscellaneous stream-manipulation methods and several protected methods for use by subclasses that want to customize the deserialization behavior of ObjectInputStream.

Hierarchy: Object-->java.io.InputStream-->ObjectInputStream(ObjectInput(DataInput),ObjectStreamConstants)

Passed To: java.beans.beancontext.BeanContextServicesSupport.bcsPreDeserializationHook(), java.beans.beancontext.BeanContextSupport.{bcsPreDeserializationHook(), deserialize(), readChildren()}, javax.swing.text.StyleContext.{readAttributes(), readAttributeSet()}

ObjectInputStream.GetField	Java 1.2
java.io

This class holds the values of named fields read by an ObjectInputStream. It gives the programmer precise control over the deserialization process and is typically used when implementing an object with a set of fields that do not match the set of fields (and the serialization stream format) of the original implementation of the object. This class allows the implementation of a class to change without breaking serialization compatibility.

In order to use the GetField class, your class must implement a private readObject() method that is responsible for custom deserialization. Typically, when using the GetField class, you have also specified an array of ObjectStreamField objects as the value of a private static field named serialPersistentFields. This array specifies the names and types of all fields expected to be found when reading from a serialization stream. If there is no serialPersistantField field, the array of ObjectStreamField objects is created from the actual fields (excluding static and transient fields) of the class.

Within the readObject() method of your class, call the readFields() method of ObjectInputStream(). This method reads the values of all fields from the stream and stores them in an ObjectInputStream.GetField object that it returns. This GetField object is essentially a mapping from field names to field values, and you can extract the values of whatever fields you need in order to restore the proper state of the object being deserialized. The various get() methods return the values of named fields of specified types. Each method takes a default value as an argument, in case no value for the named field was present in the serialization stream. (This can happen when deserializing an object written by an earlier version of the class, for example.) Use the defaulted() method to determine whether the GetField object contains a value for the named field. If this method returns true, the named field had no value in the stream, so the get() method of the GetField object has to return the specified default value. The getObjectStreamClass() method of a GetField object returns the ObjectStreamClass object for the object being deserialized. This ObjectStreamClass can obtain the array of ObjectStreamField objects for the class.

See also ObjectOutputStream.PutField

Returned By: ObjectInputStream.readFields()

ObjectInputValidation	Java 1.1
java.io	PJ1.1

A class implements this interface and defines the validateObject() method in order to validate itself when it and all the objects it depends on have been completely deserialized from an ObjectInputStream. The validateObject() method is only invoked, however, if the object is passed to ObjectInputStream.registerValidation(); this must be done from the readObject() method of the object. Note that if an object is deserialized as part of a larger object graph, its validateObject() method is not invoked until the entire graph is read, and the original call to ObjectInputStream.readObject() is about to return. validateObject() should throw an InvalidObjectException if the object fails validation. This stops object serialization, and the original call to ObjectInputStream.readObject() terminates with the InvalidObjectException exception.

Passed To: ObjectInputStream.registerValidation()

ObjectOutput	Java 1.1
java.io	PJ1.1

This interface extends the DataOutput interface and adds methods for serializing objects and writing bytes and arrays of bytes.

Hierarchy: (ObjectOutput(DataOutput))

Implementations: ObjectOutputStream

Passed To: java.awt.datatransfer.DataFlavor.writeExternal(), Externalizable.writeExternal(), ObjectOutputStream.PutField.write(), java.rmi.server.ObjID.write(), java.rmi.server.RemoteRef.getRefClass()

Returned By: java.rmi.server.RemoteCall.{getOutputStream(), getResultStream()}

ObjectOutputStream	Java 1.1
java.io	PJ1.1

The ObjectOutputStream serializes objects, arrays, and other values to a stream. The writeObject() method serializes an object or array, and various other methods write primitive data values to the stream. Note that only objects that implement the Serializable or Externalizable interface can be serialized.

A class that wants to customize the way instances are serialized should declare a private writeObject(ObjectOutputStream) method. This method is invoked when an object is being serialized and can use several additional methods of ObjectOutputStream. defaultWriteObject() performs the same serialization that would happen if no writeObject() method existed. An object can call this method to serialize itself and then use other methods of ObjectOutputStream to write additional data to the serialization stream. The class must define a matching readObject() method to read that additional data, of course. When working with multiple versions or implementations of a class, you may have to serialize a set of fields that do not precisely match the fields of your class. In this case, give your class a static field named serialPersistentFields whose value is an array of ObjectStreamField objects that describe the fields to be serialized. In your writeObject() method, call putFields() to obtain an ObjectOutputStream.PutField object. Store field names and values into this object, and then call writeFields() to write them out to the serialization stream. See ObjectStreamField and ObjectOutputStream.PutField for further details.

The remaining methods of ObjectOutputStream are miscellaneous stream-manipulation methods and protected methods for use by subclasses that want to customize its serialization behavior.

Hierarchy: Object-->java.io.OutputStream-->ObjectOutputStream(ObjectOutput(DataOutput),ObjectStreamConstants)

Passed To: java.awt.AWTEventMulticaster.{save(), saveInternal()}, java.beans.beancontext.BeanContextServicesSupport.bcsPreSerializationHook(), java.beans.beancontext.BeanContextSupport.{bcsPreSerializationHook(), serialize(), writeChildren()}, javax.swing.text.StyleContext.{writeAttributes(), writeAttributeSet()}

ObjectOutputStream.PutField	Java 1.2
java.io

This class holds values of named fields and allows them to be written to an ObjectOutputStream during the process of object serialization. It gives the programmer precise control over the serialization process and is typically used when the set of fields defined by a class do not match the set of fields (and the serialization stream format) defined by the original implementation of the class. In other words, ObjectOutputStream.PutField allows the implementation of a class to change without breaking serialization compatibility.

In order to use the PutField class, you typically define a private static serialPersistentFields field that refers to an array of ObjectStreamField objects. This array defines the set of fields written to the ObjectOutputStream, and therefore defines the serialization format. If you do not declare a serialPersistentFields field, the set of fields is all fields of the class, excluding static and transient fields.

In addition to the serialPersistentFields field, your class must also define a private writeObject() method that is responsible for the custom serialization of your class. In this method, call the putFields() method of ObjectOutputStream to obtain an ObjectOutputStream.PutField object. Once you have this object, use its various put() methods to specify the names and values of the field to be written out. The set of named fields should match those specified by serialPersistentFields. You may specify the fields in any order; the PutField class is responsible for writing them out in the correct order. Once you have specified the values of all fields, call the write() method of your PutField object in order to write the field values out to the serialization stream.

To reverse this custom serialization process, see ObjectInputStream.GetField.

Returned By: ObjectOutputStream.putFields()

ObjectStreamClass	Java 1.1
java.io	serializable PJ1.1

This class represents a class that is being serialized. An ObjectStreamClass object contains the name of a class, its unique version identifier, and the name and type of the fields that constitute the serialization format for the class. getSerialVersionUID() returns a unique version identifier for the class. It returns either the value of the private serialVersionUID field of the class or a computed value that is based upon the public API of the class. In Java 1.2 and later, getFields() returns an array of ObjectStreamField objects that represent the names and types of the fields of the class to be serialized. getField() returns a single ObjectStreamField object that represents a single named field. By default, these methods use all the fields of a class except those that are static or transient. However, this default set of fields can be overridden by declaring a private serialPersistentFields field in the class. The value of this field should be the desired array of ObjectStreamField objects.

ObjectStreamClass class does not have a constructor; you should use the static lookup() method to obtain an ObjectStreamClass object for a given Class object. The forClass() instance method performs the opposite operation; it returns the Class object that corresponds to a given ObjectStreamClass. Most applications never need to use this class.

Hierarchy: Object-->ObjectStreamClass(Serializable)

Passed To: ObjectInputStream.resolveClass(), ObjectOutputStream.writeClassDescriptor()

Returned By: ObjectInputStream.readClassDescriptor(), ObjectInputStream.GetField.getObjectStreamClass(), ObjectStreamClass.lookup()

ObjectStreamConstants	Java 1.2
java.io

This interface defines various constants used by the Java object-serialization mechanism. Two important constants are PROTOCOL_VERSION_1 and PROTOCOL_VERSION_2, which specify the version of the serialization protocol to use. In Java 1.2, you can pass either of these values to the useProtocolVersion() method of an ObjectOutputStream. By default, Java 1.2 uses Version 2 of the protocol, and Java 1.1 uses Version 1 when serializing objects. Java 1.2 can deserialize objects written using either version of the protocol, as can Java 1.1.7 and later. If you want to serialize an object so that it can be read by versions of Java prior to Java 1.1.7, use PROTOCOL_VERSION_1.

The other constants defined by this interface are low-level values used by the serialization protocol. You do not need to use them unless you are reimplementing the serialization mechanism yourself.

Implementations: ObjectInputStream, ObjectOutputStream

ObjectStreamException	Java 1.1
java.io	serializable checked PJ1.1

This class is the superclass of a number of more specific exception types that may be raised in the process of serializing and deserializing objects with the ObjectOutputStream and ObjectInputStream classes.

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

Subclasses: InvalidClassException, InvalidObjectException, NotActiveException, NotSerializableException, OptionalDataException, StreamCorruptedException, WriteAbortedException

Thrown By: java.awt.color.ICC_Profile.readResolve(), java.security.cert.Certificate.writeReplace(), java.security.cert.Certificate.CertificateRep.readResolve()

ObjectStreamField	Java 1.2
java.io	comparable

This class represents a named field of a specified type (i.e., a specified Class). When a class serializes itself by writing a set of fields that are different from the fields it uses in its own implementation, it defines the set of fields to be written with an array of ObjectStreamField objects. This array should be the value of a private static field named serialPersistentFields. The methods of this class are used internally by the serialization mechanism and are not typically used elsewhere. See also ObjectOutputStream.PutField and ObjectInputStream.GetField.

Hierarchy: Object-->ObjectStreamField(Comparable)

Returned By: ObjectStreamClass.{getField(), getFields()}

Type Of: ObjectStreamClass.NO_FIELDS

OptionalDataException	Java 1.1
java.io	serializable checked PJ1.1

Thrown by the readObject() method of an ObjectInputStream when it encounters primitive type data where it expects object data. Despite the exception name, this data is not optional, and object deserialization is stopped.

Hierarchy: Object-->Throwable(Serializable)-->Exception-->IOException-->ObjectStreamException-->OptionalDataException

Thrown By: ObjectInputStream.{readObject(), readObjectOverride()}

OutputStream	Java 1.0
java.io	PJ1.1

This abstract class is the superclass of all output streams. It defines the basic output methods all output stream classes provide. write() writes a single byte or an array (or subarray) of bytes. flush() forces any buffered output to be written. close() closes the stream and frees up any system resources associated with it. The stream may not be used once close() has been called. See also Writer.

Subclasses: ByteArrayOutputStream, FileOutputStream, FilterOutputStream, ObjectOutputStream, PipedOutputStream, javax.servlet.ServletOutputStream, org.omg.CORBA.portable.OutputStream

Passed To: Too many methods to list.

Returned By: Process.getOutputStream(), Runtime.getLocalizedOutputStream(), java.net.Socket.getOutputStream(), java.net.SocketImpl.getOutputStream(), java.net.URLConnection.getOutputStream(), java.rmi.server.LogStream.getOutputStream()

Type Of: FilterOutputStream.out

OutputStreamWriter	Java 1.1
java.io	PJ1.1

This class is a character output stream that uses a byte output stream as the destination for its data. When characters are written to an OutputStreamWriter, it translates them into bytes according to a particular locale- and/or platform-specific character encoding and writes those bytes to the specified OutputStream. This is a very important internationalization feature in Java 1.1 and later. OutputStreamWriter supports the usual Writer methods. It also has a getEncoding() method that returns the name of the encoding being used to convert characters to bytes.

When you create an OutputStreamWriter, specify the OutputStream to which it writes bytes and, optionally, the name of the character encoding that should be used to convert characters to bytes. If you do not specify an encoding name, the OutputStreamWriter uses the default encoding of the default locale, which is usually the correct thing to do.

Hierarchy: Object-->Writer-->OutputStreamWriter

Subclasses: FileWriter

PipedInputStream	Java 1.0
java.io	PJ1.1

This class is an InputStream that implements one half of a pipe and is useful for communication between threads. A PipedInputStream must be connected to a PipedOutputStream object, which may be specified when the PipedInputStream is created or with the connect() method. Data read from a PipedInputStream object is received from the PipedOutputStream to which it is connected. See InputStream for information on the low-level methods for reading data from a PipedInputStream. A FilterInputStream can provide a higher-level interface for reading data from a PipedInputStream.

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

Passed To: PipedOutputStream.{connect(), PipedOutputStream()}

PipedOutputStream	Java 1.0
java.io	PJ1.1

This class is an OutputStream that implements one half of a pipe and is useful for communication between threads. A PipedOutputStream must be connected to a PipedInputStream, which may be specified when the PipedOutputStream is created or with the connect() method. Data written to the PipedOutputStream is available for reading on the PipedInputStream. See OutputStream for information on the low-level methods for writing data to a PipedOutputStream. A FilterOutputStream can provide a higher-level interface for writing data to a PipedOutputStream.

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

Passed To: PipedInputStream.{connect(), PipedInputStream()}

PipedReader	Java 1.1
java.io	PJ1.1

PipedReader is a character input stream that reads characters from a PipedWriter character output stream to which it is connected. PipedReader implements one half of a pipe and is useful for communication between two threads of an application. A PipedReader cannot be used until it is connected to a PipedWriter object, which may be passed to the PipedReader() constructor or to the connect() method. PipedReader inherits most of the methods of its superclass. See Reader for more information. PipedReader is the character-stream analog of PipedInputStream.

Hierarchy: Object-->Reader-->PipedReader

Passed To: PipedWriter.{connect(), PipedWriter()}

PipedWriter	Java 1.1
java.io	PJ1.1

PipedWriter is a character output stream that writes characters to the PipedReader character input stream to which it is connected. PipedWriter implements one half of a pipe and is useful for communication between two threads of an application. A PipedWriter cannot be used until it is connected to a PipedReader object, which may be passed to the PipedWriter() constructor, or to the connect() method. PipedWriter inherits most of the methods of its superclass. See Writer for more information. PipedWriter is the character-stream analog of PipedOutputStream.

Hierarchy: Object-->Writer-->PipedWriter

Passed To: PipedReader.{connect(), PipedReader()}