J2SE1.4  Overview   Package   Class  Text Changes  Statistics  Help 
Generated by
JDiff
PREV PACKAGE    NEXT PACKAGE          FRAMES    NO FRAMES  

java.io Documentation Differences

This file contains all the changes in documentation in the package java.io as colored differences. Deletions are shown like this, and additions are shown like this.
If no deletions or additions are shown in an entry, the HTML tags will be what has changed. The new HTML tags are shown in the differences. If no documentation existed, and then some was added in a later version, this change is noted in the appropriate class pages of differences, but the change is not shown on this page. Only changes in existing text are shown here. Similarly, documentation which was inherited from another class or interface is not shown here.
Note that an HTML error in the new documentation may cause the display of other documentation changes to be presented incorrectly. For instance, failure to close a <code> tag will cause all subsequent paragraphs to be displayed differently.
Class BufferedInputStream

A BufferedInputStream adds functionality to another input stream-namely the ability to buffer the input and to support the mark and reset methods. When the BufferedInputStream is created an internal buffer array is created. As bytes from the stream are read or skipped the internal buffer is refilled as necessary from the contained input stream many bytes at a time. The mark operation remembers a point in the input stream and the reset operation causes all the bytes read since the most recent mark operation to be reread before new bytes are taken from the contained input stream. @author Arthur van Hoff @version 1.41 0242 12/0203/0001 @since JDK1.0
Class BufferedOutputStream

The class implements a buffered output stream. By setting up such an output stream an application can write bytes to the underlying output stream without necessarily causing a call to the underlying system for each byte written. The data is written into an internal buffer and then written to the underlying stream if the buffer reaches its capacity the buffer output stream is closed or the buffer output stream is explicitly flushed. @author Arthur van Hoff @version 1.27 0229 12/0203/0001 @since JDK1.0
Class BufferedOutputStream, constructor BufferedOutputStream(OutputStream, int)

Creates a new buffered output stream to write data to the specified underlying output stream with the specified buffer size. @param out the underlying output stream. @param size the buffer size. @exception IllegalArgumentException if size <= 0.
Class BufferedReader

Read text from a character-input stream buffering characters so as to provide for the efficient reading of characters arrays and lines.

The buffer size may be specified or the default size may be used. The default is large enough for most purposes.

In general each read request made of a Reader causes a corresponding read request to be made of the underlying character or byte stream. It is therefore advisable to wrap a BufferedReader around any Reader whose read() operations may be costly such as FileReaders and InputStreamReaders. For example 

 BufferedReader in = new BufferedReader(new FileReader("foo.in"));
will buffer the input from the specified file. Without buffering each invocation of read() or readLine() could cause bytes to be read from the file converted into characters and then returned which can be very inefficient.

Programs that use DataInputStreams for textual input can be localized by replacing each DataInputStream with an appropriate BufferedReader. @see FileReader @see InputStreamReader @version 1.2728 01/0212/0903 @author Mark Reinhold @since JDK1.1

Class BufferedReader, int read()

Read a single character. @return The character read as an integer in the range 0 to 65535 (0x00-0xffff) or -1 if the end of the stream has been reached @exception IOException If an I/O error occurs
Class BufferedWriter

Write text to a character-output stream buffering characters so as to provide for the efficient writing of single characters arrays and strings.

The buffer size may be specified or the default size may be accepted. The default is large enough for most purposes.

A newLine() method is provided which uses the platform's own notion of line separator as defined by the system property line.separator. Not all platforms use the newline character ('\n') to terminate lines. Calling this method to terminate each output line is therefore preferred to writing a newline character directly.

In general a Writer sends its output immediately to the underlying character or byte stream. Unless prompt output is required it is advisable to wrap a BufferedWriter around any Writer whose write() operations may be costly such as FileWriters and OutputStreamWriters. For example 

 PrintWriter out = new PrintWriter(new BufferedWriter(new FileWriter("foo.out")));
will buffer the PrintWriter's output to the file. Without buffering each invocation of a print() method would cause characters to be converted into bytes that would then be written immediately to the file which can be very inefficient. @see PrintWriter @see FileWriter @see OutputStreamWriter @version 1.22 0023 01/0212/0203 @author Mark Reinhold @since JDK1.1
Class ByteArrayInputStream

A ByteArrayInputStream contains an internal buffer that contains bytes that may be read from the stream. An internal counter keeps track of the next byte to be supplied by the read method.

Closing a ByteArrayInputStream has no effect. The methods in this class can be called after the stream has been closed without generating an IOException. @author Arthur van Hoff @version 1.35 0239 12/0203/0001 @see java.io.StringBufferInputStream @since JDK1.0

Class ByteArrayInputStream, constructor ByteArrayInputStream(byte[], int, int)

Creates ByteArrayInputStream that uses buf as its buffer array. The initial value of pos is offset and the initial value of count is offset+len. The buffer array is not copied. Note that if bytes are simply read from the resulting input stream elements buf[pos] through buf[pos+len-1] will be read; however if aThe resetbuffer's operationmark is performed then bytes buf[0] through buf[pos-1] willset then becometo available for inputthe specified offset. @param buf the input buffer. @param offset the offset in the buffer of the first byte to read. @param length the maximum number of bytes to read from the buffer.
Class ByteArrayInputStream, void close()

Closes thisClosing a inputByteArrayInputStream streamhas no effect. The andmethods releasesin this any system resources associated withclass can be called after the stream has been closed without generating an IOException.

Class ByteArrayInputStream, void mark(int)

Set the current marked position in the stream. ByteArrayInputStream objects are marked at position zero by default when constructed. They may be marked at another position within the buffer by this method.

If no mark has been set then the value of the mark is the offset passed to the constructor (or 0 if the offset was not supplied). @since JDK1.1

Class ByteArrayInputStream, void reset()

Resets the buffer to the marked position. The marked position is the beginning0 unless another position was marked. The value ofor an offset poswas is set to 0specified in the constructor.
Class ByteArrayInputStream, int mark

The currently marked position in the stream. ByteArrayInputStream objects are marked at position zero by default when constructed. They may be marked at another position within the buffer by the mark() method. The current buffer position is set to this point by the reset() method.

If no mark has been set then the value of mark is the offset passed to the constructor (or 0 if the offset was not supplied). @since JDK1.1

Class ByteArrayOutputStream

This class implements an output stream in which the data is written into a byte array. The buffer automatically grows as data is written to it. The data can be retrieved using toByteArray() and toString().

Closing a ByteArrayOutputStream has no effect. The methods in this class can be called after the stream has been closed without generating an IOException. @author Arthur van Hoff @version 1.43 0245 12/0203/0001 @since JDK1.0

Class ByteArrayOutputStream, void close()

Closes thisClosing a outputByteArrayOutputStream stream andhas no releaseseffect. any system resources associated with thisThe methods in this class can stream.be A closed stream cannot perform output operations and cannot becalled after the stream has been closed without generating an reopenedIOException.

Class CharArrayReader

This class implements a character buffer that can be used as a character-input stream. @author Herb Jellinek @version 1.15 0217 12/0203/0001 @since JDK1.1
Class CharArrayReader, int count

The numberindex of validthe characters in theend of this buffer. There is not valid data at or beyond this index.
Class CharArrayWriter

This class implements a character buffer that can be used as an Writer. The buffer automatically grows when data is written to the stream. The data can be retrieved using toCharArray() and toString(). @author Herb Jellinek @version 1.15 0216 12/0203/0001 @since JDK1.1
Class CharConversionException

Base class for character conversion exceptions. @author Asmus Freytag @version 1.12 0213 12/0203/0001 @since JDK1.1
Class DataInput

The DataInput interface provides for reading bytes from a binary stream and reconstructing from them data in any of the Java primitive types. There is also a facility for reconstructing a String from data in Java modified UTF-8 format.

It is generally true of all the reading routines in this interface that if end of file is reached before the desired number of bytes has been read an EOFException (which is a kind of IOException) is thrown. If any byte cannot be read for any reason other than end of file an IOException other than EOFException is thrown. In particular an IOException may be thrown if the input stream has been closed. @author Frank Yellin @version 1.16 0219 12/0203/0001 @see java.io.DataInputStream @see java.io.DataOutput @since JDK1.0

Class DataInput, String readLine()

Reads the next line of text from the input stream. It reads successive bytes converting each byte separately into a character until it encounters a line terminator or end of file; the characters read are then returned as a String. Note that because this method processes bytes it does not support input of the full Unicode character set.

If end of file is encountered before even one byte can be read then null is returned. Otherwise each byte that is read is converted to type char by zero-extension. If the character '\n' is encountered it is discarded and reading ceases. If the character '\r' is encountered it is discarded and if the following byte converts to the character '\n' then that is discarded also; reading then ceases. If end of file is encountered before either of the characters '\n' and '\r' is encountered reading ceases. Once reading has ceased a String is returned that contains all the characters read and not discarded taken in order. Note that every character in this string will have a value less than \u0100 that is (char)256. @return ifthe thisnext line of text from the input stream reachesor null if the end of file is encountered before reading all thea byte can bytesbe read. @exception IOException if an I/O error occurs.

Class DataInput, int skipBytes(int)

Makes an attempt to skip over n bytes of data from the input stream discarding the skipped bytes. However it may skip over some smaller number of bytes possibly zero. This may result from any of a number of conditions; reaching end of file before n bytes have been skipped is only one possibility. This method never throws an EOFException. The actual number of bytes skipped is returned. @param n the number of bytes to be skipped. @return the number of bytes skipped which is always n. @exception EOFException ifactually this stream reaches the end before skipping all the bytesskipped. @exception IOException if an I/O error occurs.
Class DataInputStream

A data input stream lets an application read primitive Java data types from an underlying input stream in a machine-independent way. An application uses a data output stream to write data that can later be read by a data input stream.

Data input streams and data output streams represent Unicode strings in a format that is a slight modification of UTF-8. (For more information see X/Open Company Ltd. "File System Safe UCS Transformation Format (FSS_UTF)" X/Open Preliminary Specification Document Number: P316. This information also appears in ISO/IEC 10646 Annex P.) Note that in the following tables the most significant bit appears in the far left-hand column.

All characters in the range '\u0001' to '\u007F' are represented by a single byte:

0 bits 06-70

The null character '\u0000' and characters in the range '\u0080' to '\u07FF' are represented by a pair of bytes:

1 1 0 bits 6-10-6
1 0 bits 0-5-0

Characters in the range '\u0800' to '\uFFFF' are represented by three bytes:
1 1 1 0 bits 12-15-12
1 0 bits 6-11-6
1 0 bits 0-5-0

The two differences between this format and the "standard" UTF-8 format are the following:

@author Arthur van Hoff @version 1.51 0256 12/2803/0001 @see java.io.DataOutputStream @since JDK1.0
Class DataInputStream, int read(byte[])

SeeReads some number of bytes from the contained input stream and stores them into the generalbuffer array b. The number of bytes actually read is returned as an integer. This method blocks until input data is available contractend of file is detected or an exception is thrown.

If b is null a NullPointerException is thrown. If the length of b is zero then no bytes are read and 0 methodis returned; otherwise there is an attempt to read at least one byte. If no byte is available because the stream is at end of file the value -1 is returned; otherwise at least one byte is read and stored into DataInputb.

The Bytesfirst forbyte read this operationis stored areinto element b[0] the next one into b[1] and so on. The number of bytes read fromis at most equal to the containedlength of b. Let k be the number of bytes actually read; these bytes will be stored in elements b[0] through b[k-1] leaving elements b[k] through b[b.length-1] unaffected.

If the first byte cannot be read for any reason other than end of file then an IOException is thrown. In particular an IOException is thrown if the input stream has been closed.

The read(b) method has the same effect as: 

 read(b 0 b.length)
@param b the buffer into which the data is read. @return the total number of bytes read into the buffer or -1 if there is no more data because the end of the stream has been reached. @exception IOException if an I/O error occurs. @see java.io.FilterInputStream#in @see java.io.InputStream#read(byte[] int int)
Class DataInputStream, int read(byte[], int, int)

SeeReads theup to generallen contractbytes of data from the contained input stream into an array of bytes. An attempt is made to read as many as len bytes but a smaller number may be read possibly zero. The number of bytes actually read is returned as an integer.

This method blocks until input data is available end of file is detected or an exception is thrown.

If b is null a DataInputNullPointerException is thrown.

BytesIf foroff thisis negative or len is negative or off+len is greater than the length of the array operationb then an IndexOutOfBoundsException is thrown.

If len is zero then no bytes are read fromand 0 is returned; otherwise there is an attempt to read at least one byte. If no byte is available because the containedstream is at end of file the value -1 is returned; otherwise at least one byte is read and stored into b.

The first byte read is stored into element b[off] the next one into b[off+1] and so on. The number of bytes read is at most equal to len. Let k be the number of bytes actually read; these bytes will be stored in elements b[off] through b[off+k-1] leaving elements b[off+k] through b[off+len-1] unaffected.

In every case elements b[0] through b[off] and elements b[off+len] through b[b.length-1] are unaffected.

If the first byte cannot be read for any reason other than end of file then an IOException is thrown. In particular an IOException is thrown if the input stream has been closed. @param b the buffer into which the data is read. @param off the start offset of the data. @param len the maximum number of bytes read. @return the total number of bytes read into the buffer or -1 if there is no more data because the end of the stream has been reached. @exception IOException if an I/O error occurs. @see java.io.FilterInputStream#in @see java.io.InputStream#read(byte[] int int)

Class DataOutput

The DataOutput interface provides for converting data from any of the Java primitive types to a series of bytes and writing these bytes to a binary stream. There is also a facility for converting a String into Java modified UTF-8 format and writing the resulting series of bytes.

For all the methods in this interface that write bytes it is generally true that if a byte cannot be written for any reason an IOException is thrown. @author Frank Yellin @version 1.13 0216 12/0203/0001 @see java.io.DataInput @see java.io.DataOutputStream @since JDK1.0

Class DataOutput, void writeLong(long)

Writes ana long value which is comprised of foureight bytes to the output stream. The byte values to be written in the order shown are: 

 (byte)(0xff & (v >> 56)) (byte)(0xff & (v >> 48)) (byte)(0xff & (v >> 40)) (byte)(0xff & (v >> 32)) (byte)(0xff & (v >> 24)) (byte)(0xff & (v >> 16)) (byte)(0xff & (v >> 8)) (byte)(0xff & v)

The bytes written by this method may be read by the readLong method of interface DataInput which will then return a long equal to v. @param v the long value to be written. @exception IOException if an I/O error occurs.

Class DataOutputStream

A data inputoutput stream lets an application write primitive Java data types to an output stream in a portable way. An application can then use a data input stream to read the data back in. @author unascribed @version 1.3234 0212/0203/0001 @see java.io.DataInputStream @since JDK1.0
Class EOFException

Signals that an end of file or end of stream has been reached unexpectedly during input.

This exception is mainly used by data input streams which generally expect a binary file in a specific format and for whichto ansignal end of stream is an. unusualNote condition.that Mostmany other input streamsoperations return a special value on end of stream. Note that some input operations react to end-of-file by returning a distinguished value (such as -1) rather than by throwing an exception.

@author Frank Yellin @version 1.9 0211 12/0203/0001 @see java.io.DataInputStream @see java.io.IOException @since JDK1.0

Class Externalizable

Only the identity of the class of an Externalizable instance is written in the serialization stream and it is the responsibility of the class to save and restore the contents of its instances. The writeExternal and readExternal methods of the Externalizable interface are implemented by a class to give the class complete control over the format and contents of the stream for an object and its supertypes. These methods must explicitly coordinate with the supertype to save its state. These methods supercede customized implementations of writeObject and readObject methods.
Object Serialization uses the Serializable and Externalizable interfaces. Object persistence mechanisms can use them as well. Each object to be stored is tested for the Externalizable interface. If the object supports Externalizable the writeExternal method is called. If the object does not support Externalizable and does implement Serializable the object is saved using ObjectOutputStream.
When an Externalizable object is reconstructed an instance is created using the public no-arg constructor then the readExternal method called. Serializable objects are restored by reading them from an ObjectInputStream.
An Externalizable instance can designate a substitution object via the writeReplace and readResolve methods documented in the Serializable interface.
@author unascribed @version 1.15 0216 12/0203/0001 @see java.io.ObjectOutputStream @see java.io.ObjectInputStream @see java.io.ObjectOutput @see java.io.ObjectInput @see java.io.Serializable @since JDK1.1
Class File

An abstract representation of file and directory pathnames.

User interfaces and operating systems use system-dependent pathname strings to name files and directories. This class presents an abstract system-independent view of hierarchical pathnames. An abstract pathname has two components:

  1. An optional system-dependent prefix string such as a disk-drive specifier "/"  for the UNIX root directory or "\\"  for a Win32 UNC pathname and
  2. A sequence of zero or more string names.
Each name in an abstract pathname except for the last denotes a directory; the last name may denote either a directory or a file. The empty abstract pathname has no prefix and an empty name sequence.

The conversion of a pathname string to or from an abstract pathname is inherently system-dependent. When an abstract pathname is converted into a pathname string each name is separated from the next by a single copy of the default separator character. The default name-separator character is defined by the system property file.separator and is made available in the public static fields {@link #separator} and {@link #separatorChar} of this class. When a pathname string is converted into an abstract pathname the names within it may be separated by the default name-separator character or by any other name-separator character that is supported by the underlying system.

A pathname whether abstract or in string form may be either absolute or relative. An absolute pathname is complete in that no other information is required in order to locate the file that it denotes. A relative pathname in contrast must be interpreted in terms of information taken from some other pathname. By default the classes in the java.io package always resolve relative pathnames against the current user directory. This directory is named by the system property user.dir and is typically the directory in which the Java virtual machine was invoked.

The prefix concept is used to handle root directories on UNIX platforms and drive specifiers root directories and UNC pathnames on Win32 platforms as follows:

Instances of the File class are immutable; that is once created the abstract pathname represented by a File object will never change. @version 1.98 03102 12/2203/01 @author unascribed @since JDK1.0

Class File, boolean canRead()

Tests whether the application can read the file denoted by this abstract pathname. @return true if and only if the file specified by this abstract pathname exists and can be read by the application; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the file
Class File, boolean canWrite()

Tests whether the application can modify to the file denoted by this abstract pathname. @return true if and only if the file system actually contains a file denoted by this abstract pathname and the application is allowed to write to the file; false otherwise. @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method denies write access to the file
Class File, boolean createNewFile()

Atomically creates a new empty file named by this abstract pathname if and only if a file with this name does not yet exist. The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file. This method in combination with the {@link #deleteOnExit} method can therefore serve as the basis for a simple but reliable cooperative file-locking protocol. @return true if the named file does not exist and was successfully created; false if the named file already exists @throws IOException If an I/O error occurred @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method denies write access to the file @since 1.2
Class File, File createTempFile(String, String)

Creates an empty file in the default temporary-file directory using the given prefix and suffix to generate its name. Invoking this method is equivalent to invoking {@link #createTempFile(java.lang.String java.lang.String java.io.File) createTempFile(prefix  suffix  null)}. @param prefix The prefix string to be used in generating the file's name; must be at least three characters long @param suffix The suffix string to be used in generating the file's name; may be null in which case the suffix ".tmp" will be used @return An abstract pathname denoting a newly-created empty file @throws IllegalArgumentException If the prefix argument contains fewer than three characters @throws IOException If a file could not be created @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method does not allow a file to be created @since 1.2
Class File, File createTempFile(String, String, File)

Creates a new empty file in the specified directory using the given prefix and suffix strings to generate its name. If this method returns successfully then it is guaranteed that:

  1. The file denoted by the returned abstract pathname did not exist before this method was invoked and
  2. Neither this method nor any of its variants will return the same abstract pathname again in the current invocation of the virtual machine.
This method provides only part of a temporary-file facility. To arrange for a file created by this method to be deleted automatically use the {@link #deleteOnExit} method.

The prefix argument must be at least three characters long. It is recommended that the prefix be a short meaningful string such as "hjb" or "mail". The suffix argument may be null in which case the suffix ".tmp" will be used.

To create the new file the prefix and the suffix may first be adjusted to fit the limitations of the underlying platform. If the prefix is too long then it will be truncated but its first three characters will always be preserved. If the suffix is too long then it too will be truncated but if it begins with a period character ('.') then the period and the first three characters following it will always be preserved. Once these adjustments have been made the name of the new file will be generated by concatenating the prefix five or more internally-generated characters and the suffix.

If the directory argument is null then the system-dependent default temporary-file directory will be used. The default temporary-file directory is specified by the system property java.io.tmpdir. On UNIX systems the default value of this property is typically "/tmp" or "/var/tmp"; on Win32 systems it is typically "c:\\temp". A different value may be given to this system property when the Java virtual machine is invoked but programmatic changes to this property are not guaranteed to have any effect upon the the temporary directory used by this method. @param prefix The prefix string to be used in generating the file's name; must be at least three characters long @param suffix The suffix string to be used in generating the file's name; may be null in which case the suffix ".tmp" will be used @param directory The directory in which the file is to be created or null if the default temporary-file directory is to be used @return An abstract pathname denoting a newly-created empty file @throws IllegalArgumentException If the prefix argument contains fewer than three characters @throws IOException If a file could not be created @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method does not allow a file to be created @since 1.2

Class File, boolean exists()

Tests whether the file denoted by this abstract pathname exists. @return true if and only if the file denoted by this abstract pathname exists; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the file
Class File, File getAbsoluteFile()

Returns the absolute form of this abstract pathname. Equivalent to new File(this.{@link #getAbsolutePath}()). @return The absolute abstract pathname denoting the same file or directory as this abstract pathname @throws SecurityException If a required system property value cannot be accessed. @since 1.2
Class File, String getAbsolutePath()

Returns the absolute pathname string of this abstract pathname.

If this abstract pathname is already absolute then the pathname string is simply returned as if by the {@link #getPath} method. If this abstract pathname is the empty abstract pathname then the pathname string of the current user directory which is named by the system property user.dir is returned. Otherwise this pathname is resolved in a system-dependent way. On UNIX systems a relative pathname is made absolute by resolving it against the current user directory. On Win32 systems a relative pathname is made absolute by resolving it against the current directory of the drive named by the pathname if any; if not it is resolved against the current user directory. @return The absolute pathname string denoting the same file or directory as this abstract pathname @throws SecurityException If a required system property value cannot be accessed. @see java.io.File#isAbsolute()

Class File, File getCanonicalFile()

Returns the canonical form of this abstract pathname. Equivalent to new File(this.{@link #getCanonicalPath}()). @return The canonical pathname string denoting the same file or directory as this abstract pathname @throws IOException If an I/O error occurs which is possible because the construction of the canonical pathname may require filesystem queries @throws SecurityException If a required system property value cannot be accessed. @since 1.2
Class File, String getCanonicalPath()

Returns the canonical pathname string of this abstract pathname.

A canonical pathname is both absolute and unique. The precise definition of canonical form is system-dependent. This method first converts this pathname to absolute form if necessary as if by invoking the #getAbsolutePath method and then maps it to its unique form in a system-dependent way. This typically involves removing redundant names such as "." and ".." from the pathname resolving symbolic links (on UNIX platforms) and converting drive letters to a standard case (on Win32 platforms).

Every pathname that denotes an existing file or directory has a unique canonical form. Every pathname that denotes a nonexistent file or directory also has a unique canonical form. The canonical form of the pathname of a nonexistent file or directory may be different from the canonical form of the same pathname after the file or directory is created. Similarly the canonical form of the pathname of an existing file or directory may be different from the canonical form of the same pathname after the file or directory is deleted. @return The canonical pathname string denoting the same file or directory as this abstract pathname @throws IOException If an I/O error occurs which is possible because the construction of the canonical pathname may require filesystem queries @throws SecurityException If a required system property value cannot be accessed. @since JDK1.1

Class File, boolean isDirectory()

Tests whether the file denoted by this abstract pathname is a directory. @return true if and only if the file denoted by this abstract pathname exists and is a directory; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the file
Class File, boolean isFile()

Tests whether the file denoted by this abstract pathname is a normal file. A file is normal if it is not a directory and in addition satisfies other system-dependent criteria. Any non-directory file created by a Java application is guaranteed to be a normal file. @return true if and only if the file denoted by this abstract pathname exists and is a normal file; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the file
Class File, boolean isHidden()

Tests whether the file named by this abstract pathname is a hidden file. The exact definition of hidden is system-dependent. On UNIX systems a file is considered to be hidden if its name begins with a period character ('.'). On Win32 systems a file is considered to be hidden if it has been marked as such in the filesystem. @return true if and only if the file denoted by this abstract pathname is hidden according to the conventions of the underlying platform @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the file @since 1.2
Class File, long lastModified()

Returns the time that the file denoted by this abstract pathname was last modified. @return A long value representing the time the file was last modified measured in milliseconds since the epoch (00:00:00 GMT January 1 1970) or 0L if the file does not exist or if an I/O error occurs @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the file
Class File, long length()

Returns the length of the file denoted by this abstract pathname. The return value is unspecified if this pathname denotes a directory. @return The length in bytes of the file denoted by this abstract pathname or 0L if the file does not exist @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the file
Class File, String[] list()

Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname.

If this abstract pathname does not denote a directory then this method returns null. Otherwise an array of strings is returned one for each file or directory in the directory. Names denoting the directory itself and the directory's parent directory are not included in the result. Each string is a file name rather than a complete path.

There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not in particular guaranteed to appear in alphabetical order. @return An array of strings naming the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory or if an I/O error occurs. @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the directory

Class File, String[] list(FilenameFilter)

Returns an array of strings naming the files and directories in the directory denoted by this abstract pathname that satisfy the specified filter. The behavior of this method is the same as that of the {@link #list()} method except that the strings in the returned array must satisfy the filter. If the given filter is null then all names are accepted. Otherwise a name satisfies the filter if and only if the value true results when the {@link FilenameFilter#accept} method of the filter is invoked on this abstract pathname and the name of a file or directory in the directory that it denotes. @param filter A filename filter @return An array of strings naming the files and directories in the directory denoted by this abstract pathname that were accepted by the given filter. The array will be empty if the directory is empty or if no names were accepted by the filter. Returns null if this abstract pathname does not denote a directory or if an I/O error occurs. @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the directory
Class File, File[] listFiles()

Returns an array of abstract pathnames denoting the files in the directory denoted by this abstract pathname.

If this abstract pathname does not denote a directory then this method returns null. Otherwise an array of File objects is returned one for each file or directory in the directory. Pathnames denoting the directory itself and the directory's parent directory are not included in the result. Each resulting abstract pathname is constructed from this abstract pathname using the {@link #File(java.io.File java.lang.String) File(File  String)} constructor. Therefore if this pathname is absolute then each resulting pathname is absolute; if this pathname is relative then each resulting pathname will be relative to the same directory.

There is no guarantee that the name strings in the resulting array will appear in any specific order; they are not in particular guaranteed to appear in alphabetical order. @return An array of abstract pathnames denoting the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory or if an I/O error occurs. @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the directory @since 1.2

Class File, File[] listFiles(FileFilter)

Returns an array of abstract pathnames denoting the files and directories in the directory denoted by this abstract pathname that satisfy the specified filter. The behavior of this method is the same as that of the {@link #listFiles()} method except that the pathnames in the returned array must satisfy the filter. If the given filter is null then all pathnames are accepted. Otherwise a pathname satisfies the filter if and only if the value true results when the {@link FilenameFilterFileFilter#accept(java.io.File)} method of the filter is invoked on the pathname. @param filter A filenamefile filter @return An array of abstract pathnames denoting the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory or if an I/O error occurs. @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the directory @since 1.2
Class File, File[] listFiles(FilenameFilter)

Returns an array of abstract pathnames denoting the files and directories in the directory denoted by this abstract pathname that satisfy the specified filter. The behavior of this method is the same as that of the {@link #listFiles()} method except that the pathnames in the returned array must satisfy the filter. If the given filter is null then all pathnames are accepted. Otherwise a pathname satisfies the filter if and only if the value true results when the {@link FilenameFilter#accept} method of the filter is invoked on this abstract pathname and the name of a file or directory in the directory that it denotes. @param filter A filename filter @return An array of abstract pathnames denoting the files and directories in the directory denoted by this abstract pathname. The array will be empty if the directory is empty. Returns null if this abstract pathname does not denote a directory or if an I/O error occurs. @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to the directory @since 1.2
Class File, File[] listRoots()

List the available filesystem roots.

A particular Java platform may support zero or more hierarchically-organized file systems. Each file system has a root directory from which all other files in that file system can be reached. Windows platforms for example have a root directory for each active drive; UNIX platforms have a single root directory namely "/". The set of available filesystem roots is affected by various system-level operations such the insertion or ejection of removable media and the disconnecting or unmounting of physical or virtual disk drives.

This method returns an array of File objects that denote the root directories of the available filesystem roots. It is guaranteed that the canonical pathname of any file physically present on the local machine will begin with one of the roots returned by this method.

The canonical pathname of a file that resides on some other machine and is accessed via a remote-filesystem protocol such as SMB or NFS may or may not begin with one of the roots returned by this method. If the pathname of a remote file is syntactically indistinguishable from the pathname of a local file then it will begin with one of the roots returned by this method. Thus for example File objects denoting the root directories of the mapped network drives of a Windows platform will be returned by this method while File objects containing UNC pathnames will not be returned by this method.

Unlike most methods in this class this method does not throw security exceptions. If a security manager exists and its {@link java.lang.SecurityManager#checkRead(java.lang.String)} method denies read access to a particular root directory then that directory will not appear in the result. @return An array of File objects denoting the available filesystem roots or null if the set of roots could not be determined. The array will be empty if there are no filesystem roots. @since 1.2

Class File, boolean mkdir()

Creates the directory named by this abstract pathname. @return true if and only if the directory was created; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method does not permit the named directory to be created
Class File, boolean mkdirs()

Creates the directory named by this abstract pathname including any necessary but nonexistent parent directories. Note that if this operation fails it may have succeeded in creating some of the necessary parent directories. @return true if and only if the directory was created along with all necessary parent directories; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method does not permit the named directory and all necessary parent directories and to be created
Class File, boolean renameTo(File)

Renames the file denoted by this abstract pathname. @param dest The new abstract pathname for the named file @return true if and only if the renaming succeeded; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method denies write access to either the old or new pathnames @throws NullPointerException If parameter dest is null
Class File, boolean setLastModified(long)

Sets the last-modified time of the file or directory named by this abstract pathname.

All platforms support file-modification times to the nearest second but some provide more precision. The argument will be truncated to fit the supported precision. If the operation succeeds and no intervening operations on the file take place then the next invocation of the {@link #lastModified} method will return the (possibly truncated) time argument that was passed to this method. @param time The new last-modified time measured in milliseconds since the epoch (00:00:00 GMT January 1 1970) @return true if and only if the operation succeeded; false otherwise @throws IllegalArgumentException If the argument is negative @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method denies write access to the named file @since 1.2

Class File, boolean setReadOnly()

Marks the file or directory named by this abstract pathname so that only read operations are allowed. After invoking this method the file or directory is guaranteed not to change until it is either deleted or marked to allow write access. Whether or not a read-only file or directory may be deleted depends upon the underlying system. @return true if and only if the operation succeeded; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method denies write access to the named file @since 1.2
Class File, URL toURL()

Converts this abstract pathname into a file: URL. The exact form of the URL is system-dependent. If it can be determined that the file denoted by this abstract pathname is a directory then the resulting URL will end with a slash.

Usage note: This method does not automatically escape characters that are illegal in URLs. It is recommended that new code convert an abstract pathname into a URL by first converting it into a URI via the toURI method and then converting the URI into a URL via the URI.toURL method. @return aA URL object representing the equivalent file URL. @throws MalformedURLException ifIf the path cannot be parsed as a URL @see #toURI() @see java.net.URI @see java.net.URI#toURL() @see java.net.URL @since 1.2

Class FileDescriptor

Instances of the file descriptor class serve as an opaque handle to the underlying machine-specific structure representing an open file an open socket or another source or sink of bytes. The main practical use for a file descriptor is to create a FileInputStream or FileOutputStream to contain it.

Applications should not create their own file descriptors. @author Pavani Diwanji @version 1.18 0219 12/0203/0001 @see java.io.FileInputStream @see java.io.FileOutputStream @since JDK1.0

Class FileInputStream

A FileInputStream obtains input bytes from a file in a file system. What files are available depends on the host environment.

FileInputStream is meant for reading streams of raw bytes such as image data. For reading streams of characters consider using FileReader. @author Arthur van Hoff @version 1.45 0257 12/0203/0001 @see java.io.File @see java.io.FileDescriptor @see java.io.FileOutputStream @since JDK1.0

Class FileInputStream, void close()

Closes this file input stream and releases any system resources associated with the stream.

If this stream has an associated channel then the channel is closed as well. @exception IOException if an I/O error occurs. @revised 1.4 @spec JSR-51

Class FileNotFoundException

Signals that an attempt to open the file denoted by a specified pathname has failed.

This exception will be thrown by the FileInputStream FileOutputStream and RandomAccessFile constructors when a file with the specified pathname does not exist. It will also be thrown by these constructors if the file does exist but for some reason is inaccessible for example when an attempt is made to open a read-only file for writing. @author unascribed @version 1.20 0221 12/0203/0001 @since JDK1.0

Class FileOutputStream

A file output stream is an output stream for writing data to a File or to a FileDescriptor. Whether or not a file is available or may be created depends upon the underlying platform. Some platforms in particular allow a file to be opened for writing by only one FileOutputStream (or other file-writing object) at a time. In such situations the constructors in this class will fail if the file involved is already open.

FileOutputStream is meant for writing streams of raw bytes such as image data. For writing streams of characters consider using FileWriter. @author Arthur van Hoff @version 1.39 0253 12/0203/0001 @see java.io.File @see java.io.FileDescriptor @see java.io.FileInputStream @since JDK1.0

Class FileOutputStream, constructor FileOutputStream(FileDescriptor)

Creates an output file stream to write to the specified file descriptor which represents an existing connection to an actual file in the file system.

First if there is a security manager its checkWrite method is called with the file descriptor fdObj argument as its argument. @param fdObj the file descriptor to be opened for writing. @exception SecurityException if a security manager exists and its checkWrite method denies write access to the file descriptor. @see java.lang.SecurityManager#checkWrite(java.io.FileDescriptor)

Class FileOutputStream, void close()

Closes this file output stream and releases any system resources associated with this stream. This file output stream may no longer be used for writing bytes.

If this stream has an associated channel then the channel is closed as well. @exception IOException if an I/O error occurs. @revised 1.4 @spec JSR-51

Class FilePermission

This class represents access to a file or directory. A FilePermission consists of a pathname and a set of actions valid for that pathname.

Pathname is the pathname of the file or directory granted the specified actions. A pathname that ends in "/*" (where "/" is the file separator character File.separatorChar) indicates all the files and directories contained in that directory. A pathname that ends with "/-" indicates (recursively) all files and subdirectories contained in that directory. A pathname consisting of the special token "<<ALL FILES>>" matches any file.

Note: A pathname consisting of a single "*" indicates all the files in the current directory while a pathname consisting of a single "-" indicates all the files in the current directory and (recursively) all files and subdirectories contained in the current directory.

The actions to be granted are passed to the constructor in a string containing a list of one or more comma-separated keywords. The possible keywords are "read" "write" "execute" and "delete". Their meaning is defined as follows:

read
read permission
write
write permission
execute
execute permission. Allows Runtime.exec to be called. Corresponds to SecurityManager.checkExec.
delete
delete permission. Allows File.delete to be called. Corresponds to SecurityManager.checkDelete.

The actions string is converted to lowercase before processing.

Be careful when granting FilePermissions. Think about the implications of granting read and especially write access to various files and directories. The "<<ALL FILES>>" permission with write action is especially dangerous. This grants permission to write to the entire file system. One thing this effectively allows is replacement of the system binary including the JVM runtime environment.

Please note: Code can always read a file from the same directory it's in (or a subdirectory of that directory); it does not need explicit permission to do so. @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @version 1.67 0069 01/0212/0203 @author Marianne Mueller @author Roland Schemers @since 1.2 @serial exclude

Class FileReader

Convenience class for reading character files. The constructors of this class assume that the default character encoding and the default byte-buffer size are appropriate. To specify these values yourself construct an InputStreamReader on a FileInputStream.

FileReader is meant for reading streams of characters. For reading streams of raw bytes consider using a FileInputStream. @see InputStreamReader @see FileInputStream @version 1.10 0012 01/0212/0203 @author Mark Reinhold @since JDK1.1

Class FileWriter

Convenience class for writing character files. The constructors of this class assume that the default character encoding and the default byte-buffer size are acceptable. To specify these values yourself construct an OutputStreamWriter on a FileOutputStream.

Whether or not a file is available or may be created depends upon the underlying platform. Some platforms in particular allow a file to be opened for writing by only one FileWriter (or other file-writing object) at a time. In such situations the constructors in this class will fail if the file involved is already open.

FileWriter is meant for writing streams of characters. For writing streams of raw bytes consider using a FileOutputStream. @see OutputStreamWriter @see FileOutputStream @version 1.11 0015 01/0212/0203 @author Mark Reinhold @since JDK1.1

Class FilenameFilter

Instances of classes that implement this interface are used to filter filenames. These instances are used to filter directory listings in the list method of class File and by the Abstract Window Toolkit's file dialog component. @author Arthur van Hoff @author Jonathan Payne @version 1.20 0221 12/0203/0001 @see java.awt.FileDialog#setFilenameFilter(java.io.FilenameFilter) @see java.io.File @see java.io.File#list(java.io.FilenameFilter) @since JDK1.0
Class FilterInputStream

A FilterInputStream contains some other input stream which it uses as its basic source of data possibly transforming the data along the way or providing additional functionality. The class FilterInputStream itself simply overrides all methods of InputStream with versions that pass all requests to the contained input stream. Subclasses of FilterInputStream may further override some of these methods and may also provide additional methods and fields. @author Jonathan Payne @version 1.23 0224 12/0203/0001 @since JDK1.0
Class FilterOutputStream

This class is the superclass of all classes that filter output streams. These streams sit on top of an already existing output stream (the underlying output stream) which it uses as its basic sink of data but possibly transforming the data along the way or providing additional functionality.

The class FilterOutputStream itself simply overrides all methods of OutputStream with versions that pass all requests to the underlying output stream. Subclasses of FilterOutputStream may further override some of these methods as well as provide additional methods and fields. @author Jonathan Payne @version 1.28 0229 12/0203/0001 @since JDK1.0

Class FilterReader

Abstract class for reading filtered character streams. The abstract class FilterReader itself provides default methods that pass all requests to the contained stream. Subclasses of FilterReader should override some of these methods and may also provide additional methods and fields. @version 1.11 0013 01/0212/0203 @author Mark Reinhold @since JDK1.1
Class FilterWriter

Abstract class for writing filtered character streams. The abstract class FilterWriter itself provides default methods that pass all requests to the contained stream. Subclasses of FilterWriter should override some of these methods and may also provide additional methods and fields. @version 1.11 0013 01/0212/0203 @author Mark Reinhold @since JDK1.1
Class IOException

Signals that an I/O exception of some sort has occurred. This class is the general class of exceptions produced by failed or interrupted I/O operations. @author unascribed @version 1.19 0220 12/0203/0001 @see java.io.InputStream @see java.io.OutputStream @since JDK1.0
Class InputStream

This abstract class is the superclass of all classes representing an input stream of bytes.

Applications that need to define a subclass of InputStream must always provide a method that returns the next byte of input. @author Arthur van Hoff @version 1.36 0238 12/0203/0001 @see java.io.BufferedInputStream @see java.io.ByteArrayInputStream @see java.io.DataInputStream @see java.io.FilterInputStream @see java.io.InputStream#read() @see java.io.OutputStream @see java.io.PushbackInputStream @since JDK1.0

Class InputStream, boolean markSupported()

Tests if this input stream supports the mark and reset methods. Whether or not mark and reset are supported is an invariant property of a particular input stream instance. The markSupported method of InputStream returns false. @return true if this true typestream instance supports the mark and reset methodmethods; false otherwise. @see java.io.InputStream#mark(int) @see java.io.InputStream#reset()
Class InputStreamReader

An InputStreamReader is a bridge from byte streams to character streams: It reads bytes and translatesdecodes them into characters accordingusing to a specified character encoding.charset The encodingcharset that it uses may be specified by name or may be given explicitly or the platform's default encodingcharset may be accepted.

Each invocation of one of an InputStreamReader's read() methods may cause one or more bytes to be read from the underlying byte-input stream. To enable the efficient conversion of bytes to characters more bytes may be read ahead from the underlying stream than are necessary to satisfy the current read operation.

For top efficiency consider wrapping an InputStreamReader within a BufferedReader. For example: 

 BufferedReader in = new BufferedReader(new InputStreamReader(System.in));
@see BufferedReader @see InputStream @see Character encodingsjava.nio.charset.Charset @version 1.25 0042 01/0212/0203 @author Mark Reinhold @since JDK1.1
Class InputStreamReader, constructor InputStreamReader(InputStream)

Create an InputStreamReader that uses the default character encodingcharset. @param in An InputStream
Class InputStreamReader, constructor InputStreamReader(InputStream, String)

Create an InputStreamReader that uses the named character encodingcharset. @param in An InputStream @param enccharsetName The name of a supported character encodingcharset @exception UnsupportedEncodingException If the named encodingcharset is not supported
Class InputStreamReader, String getEncoding()

ReturnsReturn the canonical name of the character encoding being used by this stream.

If the encoding has an historical name then that name is returned; otherwise the encoding's canonical name is returned.

If this InputStreamReaderinstance was created with the String) constructor then the returned encoding name being canonicalunique for the encoding may differ from the encoding name passed to the constructor. MayThis method may return null if the stream has been closed.

@return a String representing the encoding nameThe historical name of this encoding or possibly null if the stream has been closed @see Characterjava.nio.charset.Charset @revised 1.4 @spec encodingsJSR-51
Class InputStreamReader, int read(char[], int, int)

Read characters into a portion of an array. @param cbuf Destination buffer @param offoffset Offset at which to start storing characters @param lenlength Maximum number of characters to read @return The number of characters read or -1 if the end of the stream has been reached @exception IOException If an I/O error occurs
Class InterruptedIOException

Signals that an I/O operation has been interrupted. An InterruptedIOException is thrown to indicate that an input or output transfer has been terminated because the thread performing it was terminatedinterrupted. The field #bytesTransferred indicates how many bytes were successfully transferred before the interruption occurred. @author unascribed @version 1.1517 0212/0203/0001 @see java.io.InputStream @see java.io.OutputStream @see java.lang.Thread#interrupt() @since JDK1.0
Class InvalidClassException

Thrown when the Serialization runtime detects one of the following problems with a Class. @author unascribed @version 1.17 0218 12/0203/0001 @since JDK1.1
Class InvalidObjectException

Indicates that one or more deserialized objects failed validation tests. The argument should provide the reason for the failure. @see ObjectInputValidation @since JDK1.1 @author unascribed @version 1.12 0213 12/0203/0001 @since JDK1.1
Class LineNumberInputStream

This class is an input stream filter that provides the added functionality of keeping track of the current line number.

A line is a sequence of bytes ending with a carriage return character ('\r') a newline character ('\n') or a carriage return character followed immediately by a linefeed character. In all three cases the line terminating character(s) are returned as a single newline character.

The line number begins at 0 and is incremented by 1 when a read returns a newline character. @author Arthur van Hoff @version 1.22 0223 12/0203/0001 @see java.io.LineNumberReader @since JDK1.0 @deprecated This class incorrectly assumes that bytes adequately represent characters. As of JDK 1.1 the preferred way to operate on character streams is via the new character-stream classes which include a class for counting line numbers.

Class LineNumberReader

A buffered character-input stream that keeps track of line numbers. This class defines methods void setLineNumber(int) and int getLineNumber() for setting and getting the current line number respectively.

By default line numbering begins at 0. This number increments as data is read and can be changed with a call to setLineNumber(int). Note however that setLineNumber(int) does not actually change the current position in the stream; it only changes the value that will be returned by getLineNumber().

A line is considered to be terminated by any one of a line feed ('\n') a carriage return ('\r') or a carriage return followed immediately by a linefeed. @version 1.13 0015 01/0212/0203 @author Mark Reinhold @since JDK1.1

Class NotActiveException

Thrown when serialization or deserialization is not active. @author unascribed @version 1.12 0213 12/0203/0001 @since JDK1.1
Class NotSerializableException

Thrown when an instance is required to have a Serializable interface. The serialization runtime or the class of the instance can throw this exception. The argument should be the name of the class. @author unascribed @version 1.11 0212 12/0203/0001 @since JDK1.1
Class ObjectInput

ObjectInput extends the DataInput interface to include the reading of objects. DataInput includes methods for the input of primitive types ObjectInput extends that interface to include objects arrays and Strings. @author unascribed @version 1.16 0217 12/0203/0001 @see java.io.InputStream @see java.io.ObjectOutputStream @see java.io.ObjectInputStream @since JDK1.1
Class ObjectInputStream

An ObjectInputStream deserializes primitive data and objects previously written using an ObjectOutputStream.

ObjectOutputStream and ObjectInputStream can provide an application with persistent storage for graphs of objects when used with a FileOutputStream and FileInputStream respectively. ObjectInputStream is used to recover those objects previously serialized. Other uses include passing objects between hosts using a socket stream or for marshaling and unmarshaling arguments and parameters in a remote communication system.

ObjectInputStream ensures that the types of all objects in the graph created from the stream match the classes present in the Java Virtual Machine. Classes are loaded as required using the standard mechanisms.

Only objects that support the java.io.Serializable or java.io.Externalizable interface can be read from streams.

The method readObject is used to read an object from the stream. Java's safe casting should be used to get the desired type. In Java strings and arrays are objects and are treated as objects during serialization. When read they need to be cast to the expected type.

Primitive data types can be read from the stream using the appropriate method on DataInput.

The default deserialization mechanism for objects restores the contents of each field to the value and type it had when it was written. Fields declared as transient or static are ignored by the deserialization process. References to other objects cause those objects to be read from the stream as necessary. Graphs of objects are restored correctly using a reference sharing mechanism. New objects are always allocated when deserializing which prevents existing objects from being overwritten.

Reading an object is analogous to running the constructors of a new object. Memory is allocated for the object and initialized to zero (NULL). No-arg constructors are invoked for the non-serializable classes and then the fields of the serializable classes are restored from the stream starting with the serializable class closest to java.lang.object and finishing with the object's most specifiecspecific class.

For example to read from a stream as written by the example in ObjectOutputStream: 

 FileInputStream istream = new FileInputStream("t.tmp"); ObjectInputStream p = new ObjectInputStream(istream); int i = p.readInt(); String today = (String)p.readObject(); Date date = (Date)p.readObject(); istream.close();

Classes control how they are serialized by implementing either the java.io.Serializable or java.io.Externalizable interfaces.

Implementing the Serializable interface allows object serialization to save and restore the entire state of the object and it allows classes to evolve between the time the stream is written and the time it is read. It automatically traverses references between objects saving and restoring entire graphs.

Serializable classes that require special handling during the serialization and deserialization process should implement both ofthe thesefollowing methods:

 private void writeObject(java.io.ObjectOutputStream stream) throws IOException; private void readObject(java.io.ObjectInputStream stream) throws IOException ClassNotFoundException; private void readObjectNoData() throws ObjectStreamException;

The readObject method is responsible for reading and restoring the state of the object for its particular class using data written to the stream by the corresponding writeObject method. The method does not need to concern itself with the state belonging to its superclasses or subclasses. State is restored by reading data from the ObjectInputStream for the individual fields and making assignments to the appropriate fields of the object. Reading primitive data types is supported by DataInput.

Any attempt to read object data which exceeds the boundaries of the custom data written by the corresponding writeObject method will cause an OptionalDataException to be thrown with an eof field value of true. Non-object reads which exceed the end of the allotted data will reflect the end of data in the same way that they would indicate the end of the stream: bytewise reads will return -1 as the byte read or number of bytes read and primitive reads will throw EOFExceptions. If there is no corresponding writeObject method then the end of default serialized data marks the end of the allotted data.

Primitive and object read calls issued from within a readExternal method behave in the same manner--if the stream is already positioned at the end of data written by the corresponding writeExternal method object reads will throw OptionalDataExceptions with eof set to true bytewise reads will return -1 and primitive reads will throw EOFExceptions. Note that this behavior does not hold for streams written with the old ObjectStreamConstants.PROTOCOL_VERSION_1 protocol in which the end of data written by writeExternal methods is not demarcated and hence cannot be detected.

The readObjectNoData method is responsible for initializing the state of the object for its particular class in the event that the serialization stream does not list the given class as a superclass of the object being deserialized. This may occur in cases where the receiving party uses a different version of the deserialized instance's class than the sending party and the receiver's version extends classes that are not extended by the sender's version. This may also occur if the serialization stream has been tampered; hence readObjectNoData is useful for initializing deserialized objects properly despite a "hostile" or incomplete source stream.

Serialization does not read or assign values to the fields of any object that does not implement the java.io.Serializable interface. Subclasses of Objects that are not serializable can be serializable. In this case the non-serializable class must have a no-arg constructor to allow its fields to be initialized. In this case it is the responsibility of the subclass to save and restore the state of the non-serializable class. It is frequently the case that the fields of that class are accessible (public package or protected) or that there are get and set methods that can be used to restore the state.

Any exception that occurs while deserializing an object will be caught by the ObjectInputStream and abort the reading process.

Implementing the Externalizable interface allows the object to assume complete control over the contents and format of the object's serialized form. The methods of the Externalizable interface writeExternal and readExternal are called to save and restore the objects state. When implemented by a class they can write and read their own state using all of the methods of ObjectOutput and ObjectInput. It is the responsibility of the objects to handle any versioning that occurs. @author Mike Warres @author Roger Riggs @version 1.107 02136 01/0912/0103 @see java.io.DataInput @see java.io.ObjectOutputStream @see java.io.Serializable @see Object Serialization Specification Section 3 Object Input Classes @since JDK1.1

Class ObjectInputStream.GetField, Object get(String, Object)

Get the value of the named Object field from the persistent field. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named Object field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream.GetField, boolean get(String, boolean)

Get the value of the named boolean field from the persistent field. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named boolean field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream.GetField, byte get(String, byte)

Get the value of the named byte field from the persistent fieldsfield. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named byte field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream.GetField, char get(String, char)

Get the value of the named char field from the persistent fieldsfield. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named char field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream.GetField, double get(String, double)

Get the value of the named double field from the persistent field. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named double field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream.GetField, float get(String, float)

Get the value of the named float field from the persistent fieldsfield. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named float field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream.GetField, int get(String, int)

Get the value of the named int field from the persistent fieldsfield. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named int field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream.GetField, long get(String, long)

Get the value of the named long field from the persistent fieldsfield. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named long field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream.GetField, short get(String, short)

Get the value of the named short field from the persistent fieldsfield. @param name the name of the field @param defvalueval the default value to use if name does not have a value @return the value of the named short field @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if type of name is not serializable or if the field type is incorrect
Class ObjectInputStream, constructor ObjectInputStream()

Provide a way for subclasses that are completely reimplementing ObjectInputStream to not have to allocate private data just used by this implementation of ObjectInputStream.

If there is a security manager installed this method first calls the security manager's checkPermission method with the SerializablePermission("enableSubclassImplementation") permission to ensure it's ok to enable subclassing. @exception IOException Thrown if not called by a subclass. @throws SecurityException if a security manager exists and its checkPermission method denies enabling subclassing. @see SecurityManager#checkPermission @see java.io.SerializablePermission

Class ObjectInputStream, constructor ObjectInputStream(InputStream)

CreateCreates an ObjectInputStream that reads from the specified InputStream. TheA serialization stream header containing the magic number and version number areis read from the stream and verified. This methodconstructor will block until the corresponding ObjectOutputStream has written and flushed the header. @param

If ina security manager is installed this constructor will check for the underlying"enableSubclassImplementation" InputStreamSerializablePermission fromwhen invoked directly or indirectly by the constructor of a subclass which overrides the ObjectInputStream.readFields or ObjectInputStream.readUnshared methods. @param in input stream to read from @exceptionthrows StreamCorruptedException The versionif or magic number arethe stream header is incorrect. @exceptionthrows IOException Anif an exceptionI/O occurred in the underlyingerror occurs while reading stream. header @throws SecurityException if untrusted subclass illegally overrides security-sensitive methods @see ObjectInputStream#ObjectInputStream() @see ObjectInputStream#readFields() @see ObjectOutputStream#ObjectOutputStream(OutputStream)

Class ObjectInputStream, void close()

Closes the input stream. Must be called to release any resources associated with the stream. @exceptionthrows IOException If an I/O error has occurred.
Class ObjectInputStream, void defaultReadObject()

Read the non-static and non-transient fields of the current class from this stream. This may only be called from the readObject method of the class being deserialized. It will throw the NotActiveException if it is called otherwise. @exceptionthrows java.lang.ClassNotFoundException if the class of a serialized object could not be found. @exceptionthrows IOException if an I/O error occurs. @exceptionthrows NotActiveException if the stream is not currently reading objects.
Class ObjectInputStream,