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.

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.36 0841 02/1802/9800 @since JDK1.0

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.25 0427 02/3002/9800 @since JDK1.0

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.19 9825 00/0802/1802 @author Mark Reinhold @since JDK1.1

Skip characters. @param n The number of characters to skip @return The number of characters actually skipped @exception IllegalArgumentException If n is negative. @exception IOException If an I/O error occurs

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.20 9822 00/0802/0302 @author Mark Reinhold @since JDK1.1

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. @author Arthur van Hoff @version 1.32 0935 02/3002/9800 @see java.io.StringBufferInputStream @since JDK1.0

Resets the buffer to the marked position. The marked position is the beginning unless another position was marked. The value of pos is set to 0.

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(). @author Arthur van Hoff @version 1.27 1043 02/2002/9700 @since JDK1.0

Converts the buffer's contents into a string translating bytes into characters according to the platform's default character encoding. @return String translated from the buffer's contents. @since JDK1.1

Converts the buffer's contents into a string translating bytes into characters according to the specified character encoding. @param enc a character-encoding name. @return String translated from the buffer's contents. @throws UnsupportedEncodingException If the named encoding is not supported. @since JDK1.1

This class implements a character buffer that can be used as a character-input stream. @author Herb Jellinek @version 1.12 0615 02/0502/9800 @since JDK1.1

CharacterThe character buffer.

NumberThe number of valid characters in the buffer.

PositionThe position of mark in buffer.

CurrentThe current buffer position.

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.11 0615 02/2902/9800 @since JDK1.1

Creates a new CharArrayWriter with the specified initial size. @param initialSize an int specifying the initial buffer size. @exception IllegalArgumentException if initialSize is negative

Returns the current size of the buffer. @return an int representing the current size of the buffer.

Returns a copy of the input data. @return an array of chars copied from the input data.

Writes the contents of the buffer to another character stream. @param out the output stream to write to @throws IOException If an I/O error occurs.

baseBase class for character conversion exceptions. @author Asmus Freytag @version 1.8 0912 02/2102/9800 @since JDK1.1

This provides no detailed message.

This provides a detailed message. @param s the detailed message associated with the exception.

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.13 0616 02/2902/9800 @see java.io.DataInputStream @see java.io.DataOutput @since JDK1.0

Reads len bytes from an input stream.

This method blocks until one of the following conditions occurs:

• len bytes of input data are available in which case a normal return is made.
• End of file is detected in which case an EOFException is thrown.
• An I/O error occurs in which case an IOException other than EOFException is thrown.

If b is null a NullPointerException is thrown. If off is negative or len is negative or off+len is greater than the length of the array b then an IndexOutOfBoundsException is thrown. If len is zero then no bytes are read. Otherwise 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. @param b the buffer into which the data is read. @param off an int specifying the offset into the data. @param len an int specifying the number of bytes to read. @exception EOFException if this stream reaches the end before reading all the bytes. @exception IOException if an I/O error occurs.

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

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

0

bits 0-7

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
1	0	bits 0-5

Characters in the range '\u0800' to '\uFFFF' are represented by three bytes:

1	1	1	0	bits 12-15
1	0	bits 6-11
1	0	bits 0-5

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

• The null byte '\u0000' is encoded in 2-byte format rather than 1-byte so that the encoded strings never have embedded nulls.
• Only the 1-byte 2-byte and 3-byte formats are used.

@author Arthur van Hoff @version 1.46 0650 02/2902/9800 @see java.io.DataOutputStream @since JDK1.0

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.10 0613 02/2902/9800 @see java.io.DataInput @see java.io.DataOutputStream @since JDK1.0

Writes two bytes of length information to the output stream followed by the Java modified UTF representation of every character in the string s. If s is null a NullPointerException is thrown. Each character in the string s is converted to a group of one two or three bytes depending on the value of the character.

If a character c is in the range \u0001 through \u007f it is represented by one byte:

(byte)c 

If a character c is \u0000 or is in the range \u0080 through \u07ff then it is represented by two bytes to be written in the order shown:

 (byte)(0xc0 | (0x1f & (c >> 6))) (byte)(0x80 | (0x3f & c)) 

If a character c is in the range \u0800 through uffff then it is represented by three bytes to be written in the order shown:

 (byte)(0xc00xe0 | (0x0f & (c >> 12))) (byte)(0x80 | (0x3f & (c >> 6))) (byte)(0x80 | (0x3f & c)) 

First the total number of bytes needed to represent all the characters of s is calculated. If this number is larger than 65535 then a UTFDataFormatError is thrown. Otherwise this length is written to the output stream in exactly the manner of the writeShort method; after this the one- two- or three-byte representation of each character in the string s is written.

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

A data input 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.28 0432 02/3002/9800 @see java.io.DataInputStream @since JDK1.0

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 which an end of stream is an unusual condition. Most other input streams 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.7 069 02/2902/9800 @see java.io.DataInputStream @see java.io.IOException @since JDK1.0

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.12 0615 02/2902/9800 @see java.io.ObjectOutputStream @see java.io.ObjectInputStream @see java.io.ObjectOutput @see java.io.ObjectInput @see java.io.Serializable @since JDK1.1

The object implements the readExternal method to restore its contents by calling the methods of DataInput for primitive types and readObject for objects strings and arrays. The readExternal method must read the values in the same sequence and with the same types as were written by writeExternal. @param in the stream to read data from in order to restore the object @exception IOException if I/O errors occur @exception ClassNotFoundException If the class for an object being restored cannot be found.

The object implements the writeExternal method to save its contents by calling the methods of DataOutput for its primitive values or calling the writeObject method of ObjectOutput for objects strings and arrays. @serialData Overriding methods should use this tag to describe the data layout of this Externalizable object. List the sequence of element types and if possible relate the element to a public/protected field and/or method of this Externalizable class. @param out the stream to write the object to @exception IOException Includes any I/O exceptions that may occur

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:

• For UNIX platforms the prefix of an absolute pathname is always "/". Relative pathnames have no prefix. The abstract pathname denoting the root directory has the prefix "/" and an empty name sequence.
• For Win32 platforms the prefix of a pathname that contains a drive specifier consists of the drive letter followed by ":" and possibly followed by "\" if the pathname is absolute. The prefix of a UNC pathname is "\\"; the hostname and the share name are the first two names in the name sequence. A relative pathname that does not specify a drive has no prefix.

Instances of the File class are immutable; that is once created the abstract pathname represented by a File object will never change. @version 1.79 9892 02/0802/1800 @author unascribed @since JDK1.0

Compares two abstract pathnames lexicographically. The ordering defined by this method depends upon the underlying system. On UNIX systems alphabetic case is significant in comparing pathnames; on Win32 systems it is not. @param pathname The abstract pathname to be compared to this abstract pathname @return Zero if the argument is equal to this abstract pathname a value less than zero if this abstract pathname is lexicographically less than the argument or a value greater than zero if this abstract pathname is lexicographically greater than the argument @since JDK11.2

Compares this abstract pathname to another object. If the other object is an abstract pathname then this function behaves like {@link #compareTo(File)}. Otherwise it throws a ClassCastException since abstract pathnames can only be compared to abstract pathnames. @param o The Object to be compared to this abstract pathname @return If the argument is an abstract pathname returns zero if the argument is equal to this abstract pathname a value less than zero if this abstract pathname is lexicographically less than the argument or a value greater than zero if this abstract pathname is lexicographically greater than the argument @throws ClassCastException if the argument is not an abstract pathname @see java.lang.Comparable @since JDK11.2

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} method denies write access to the file @since JDK11.2

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} method does not allow a file to be created @since JDK11.2

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". @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} method does not allow a file to be created @since JDK11.2

Requests that the file or directory denoted by this abstract pathname be deleted when the virtual machine terminates. Deletion will be attempted only for normal termination of the virtual machine as defined by the Java Language Specification (12.9).

Once deletion has been requested it is not possible to cancel the request. This method should therefore be used with care. @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkDelete} method denies delete access to the file @see #delete @since JDK11.2

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 @since JDK11.2

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 @since JDK11.2

Returns the abstract pathname of this abstract pathname's parent or null if this pathname does not name a parent directory.

The parent of an abstract pathname consists of the pathname's prefix if any and each name in the pathname's name sequence except for the last. If the name sequence is empty then the pathname does not name a parent directory. @return The abstract pathname of the parent directory named by this abstract pathname or null if this pathname does not name a parent @since JDK11.2

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} method denies read access to the file @since JDK11.2

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} method denies read access to the directory @since JDK11.2

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 the pathname. @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} method denies read access to the directory @since JDK11.2

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} method denies read access to the directory @since JDK11.2

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} 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 JDK11.2

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} method denies write access to botheither the old andor new pathnames @throws NullPointerException If parameter dest is null

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) @returnsreturn 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} method denies write access to the named file @since JDK11.2

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. @returnsreturn true if and only if the operation succeeded; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite} method denies write access to the named file @since JDK11.2

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. @return a URL object representing the equivalent file URL. @throws MalformedURLException if the path cannot be parsed as a URL. @see java.net.URL @since JDK11.2

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.15 0618 02/2902/9800 @see java.io.FileInputStream @see java.io.FileOutputStream @see java.net.SocketInputStream @see java.net.SocketOutputStream @since JDK1.0

A filter for abstract pathnames.

Instances of this interface may be passed to the {@link File#listFiles(java.io.FileFilter); listFiles(FileFilter)} method of the {@link java.io.FileFilter} class. @since JDK11.2

A FileInputStream obtains input bytes from a file in a file system. What files are available depends on the host environment. @author Arthur van Hoff @version 1.42 0945 02/2402/9800 @see java.io.File @see java.io.FileDescriptor @see java.io.FileOutputStream @since JDK1.0

Creates a FileInputStream by using the file descriptor fdObj which represents an existing connection to an actual file in the file system.

FirstIf if there is a security manager its checkRead method is called with the file descriptor fdObj as its argument to see if it's ok to read the file descriptor. If read access is denied to the file descriptor a SecurityException is thrown.

If fdObj is null then a NullPointerException is thrown. @param fdObj the file descriptor to be opened for reading. @throws SecurityException if a security manager exists and its checkRead method denies read access to the file descriptor. @see SecurityManager#checkRead(java.io.FileDescriptor)

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.16 0920 02/02/9800 @since JDK1.0

A file output stream is an output stream for writing data to a File or to a FileDescriptor. WhatWhether filesor not a arefile is available or may be created depends onupon 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 hostfile involved is already environmentopen. @author Arthur van Hoff @version 1.3539 0902/2402/9800 @see java.io.File @see java.io.FileDescriptor @see java.io.FileInputStream @since JDK1.0

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.59 9967 00/0402/2202 @author Marianne Mueller @author Roland Schemers @since 1.2 @serial exclude

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. @see InputStreamReader @see FileInputStream @version 1.7 9810 00/0902/2102 @author Mark Reinhold @since JDK1.1

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. @see OutputStreamWriter @see FileOutputStream @version 1.7 9811 00/0902/2102 @author Mark Reinhold @since JDK1.1

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.18 0620 02/2902/9800 @see java.awt.FileDialog#setFilenameFilter(java.io.FilenameFilter) @see java.io.File @see java.io.File#list(java.io.FilenameFilter) @since JDK1.0

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.21 0623 02/2402/9800 @since JDK1.0

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.25 0828 02/2602/9800 @since JDK1.0

Abstract class for reading filtered character streams. @version 1.8 9811 00/0902/2102 @author Mark Reinhold @since JDK1.1

Create a new filtered reader. @param in a Reader object providing the underlying stream.

The underlying character-input stream or null if the stream has been closed.

Abstract class for writing filtered character streams. @version 1.8 9811 00/0902/2102 @author Mark Reinhold @since JDK1.1

Create a new filtered writer. @param out a Writer object to provide the underlying stream.

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.17 0619 02/2902/9800 @see java.io.InputStream @see java.io.OutputStream @since JDK1.0

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.34 0836 02/1602/9800 @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

An InputStreamReader is a bridge from byte streams to character streams: It reads bytes and translates them into characters according to a specified character encoding. The encoding that it uses may be specified by name or the platform's default encoding 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. For example:

 BufferedReader in = new BufferedReader(new InputStreamReader(System.in)); 

@see BufferedReader @see InputStream @see Character encodings @version 1.20 9825 00/0802/0602 @author Mark Reinhold @since JDK1.1

Create an InputStreamReader that uses the named character encoding. @param in An InputStream @param enc NameThe name of encoding toa supported becharacter usedencoding @exception UnsupportedEncodingException If the named encoding is not supported

Returns the canonical name of the character encoding being used by this stream. If this InputStreamReader was created with the String) constructor then the returned encoding name being canonical may differ from the encoding name passed to the constructor. May return null if the stream has been closed. @return a String representing the encoding name or possibly null if the stream has been closed @see Character encodings

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 terminated. The field #bytesTransferred indicates how many bytes were successfully transferred before the interruption occurred. @author unascribed @version 1.13 0615 02/2902/9800 @see java.io.InputStream @see java.io.OutputStream @see java.lang.Thread#interrupt() @since JDK1.0

Thrown when the Serialization runtime detects one of the following problems with a Class.

• The serial version of the class does not match that of the class descriptor read from the stream
• The class contains unknown datatypes
• The class does not have an accessible no-arg constructor

@author unascribed @version 1.13 0617 02/2902/9800 @since JDK1.1

Report a InvalidClassException for the reason specified. @param reason String describing the reason for the exception.

Name of the invalid class. @serial Name of the invalid class.

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.10 0612 02/2902/9800 @since JDK1.1

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.19 0322 02/2302/9800 @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.

Returns the current line number. @return the current line number. @see #setLineNumber

Sets the line number to the specified argument. @param lineNumber the new line number. @see #getLineNumber

A buffered character-input stream that keeps track of line numbers. 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.9 9813 00/0302/1802 @author Mark Reinhold @since JDK1.1

Create a new line-numbering reader using the default input-buffer size. @param in a Reader object to provide the underlying stream.

Create a new line-numbering reader reading characters into a buffer of the given size. @param in a Reader object to provide the underlying stream. @param sz an int specifying the size of the buffer.

Get the current line number. @return The current line number. @see #setLineNumber

Set the current line number. @param lineNumber an int specifying the line number. @see #getLineNumber

Thrown when serialization or deserialization is not active. @author unascribed @version 1.9 0612 02/2902/9800 @since JDK1.1

Constructor to create a new NotActiveException with the reason given. @param reason a String describing the reason for the exception.

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.8 0611 02/2902/9800 @since JDK1.1

Constructs a NotSerializableException object with message string. @param classname Class of the instance being serialized/deserialized.

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.13 0916 02/2102/9800 @see java.io.InputStream @see java.io.ObjectOutputStream @see java.io.ObjectInputStream @since JDK1.1

Returns the number of bytes that can be read without blocking. @return the number of available bytes. @exception IOException If an I/O error has occurred.

Read and return an object. The class that implements this interface defines where the object is "read" from. @return the object read from the stream @exception java.lang.ClassNotFoundException If the class of a serialized object cannot be found. @exception IOException If any of the usual Input/Output related exceptions occur.

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 specifiec 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 of these methods:

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

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.

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 Roger Riggs @version 1.78 09105 02/2402/9800 @see java.io.DataInput @see java.io.ObjectOutputStream @see java.io.Serializable @see Object Serialization Specification Section 3 Object Input Classes @since JDK1.1

Return true if the named field is defaulted and has no value in this stream. @param name the name of the field @return true if and only if the named field is defaulted @throws IOException if there are I/O errors while reading from the underlying InputStream @throws IllegalArgumentException if name does not correspond to a serializable field

Get the value of the named Object field from the persistent field. @param name the name of the field @param defvalue 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

Get the value of the named boolean field from the persistent field. @param name the name of the field @param defvalue 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

Get the value of the named byte field from the persistent fields. @param name the name of the field @param defvalue 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

Get the value of the named char field from the persistent fields. @param name the name of the field @param defvalue 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

Get the value of the named double field from the persistent field. @param name the name of the field @param defvalue 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

Get the value of the named float field from the persistent fields. @param name the name of the field @param defvalue 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

Get the value of the named int field from the persistent fields. @param name the name of the field @param defvalue 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

Get the value of the named long field from the persistent fields. @param name the name of the field @param defvalue 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

Get the value of the named short field from the persistent fields. @param name the name of the field @param defvalue 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

Get the ObjectStreamClass that describes the fields in the stream. @return the descriptor class that describes the serializable fields

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.securityio.SerializablePermission

Create an ObjectInputStream that reads from the specified InputStream. The stream header containing the magic number and version number are read from the stream and verified. This method will block until the corresponding ObjectOutputStream has written and flushed the header. @param in the underlying InputStream from which to read @exception StreamCorruptedException The version or magic number are incorrect. @exception IOException An exception occurred in the underlying stream.

Returns the number of bytes that can be read without blocking. @return the number of available bytes. @throws IOException if there are I/O errors while reading from the underlying InputStream

Enable the stream to allow objects read from the stream to be replaced. When enabled the resolveObject method is called for every object being deserialized. If enable is true and there is a security manager installed this method first calls the security manager's checkPermission method with the SerializablePermission("enableSubstitution") permission to ensure it's ok to enable the stream to allow objects read from the stream to be replaced. @param enable true for enabling use of resolveObject for every object being deserialized @return the previous setting before this method was invoked @throws SecurityException if a security manager exists and its checkPermission method denies enabling the stream to allow objects read from the stream to be replaced. @see SecurityManager#checkPermission @see java.securityio.SerializablePermission

Reads the persistent fields from the stream and makes them available by name. @return the GetField object representing the persistent fields of the object being deserialized @exception java.lang.ClassNotFoundException if the class of a serialized object could not be found. @exception IOException if an I/O error occurs. @exception NotActiveException if the stream is not currently reading objects. @since JDK 1.2

Reads bytes blocking until all bytes are read. @param bdata the buffer into which the data is read @exception EOFException If end of file is reached. @exception IOException If other I/O error has occurred.

Reads bytes blocking until all bytes are read. @param bdata the buffer into which the data is read @param offoffset the start offset of the data @param lensize the maximum number of bytes to read @exception EOFException If end of file is reached. @exception IOException If other I/O error has occurred.

Reads in a line that has been terminated by a \n \r \r\n or EOF. @return a String copy of the line. @throws IOException if there are I/O errors while reading from the underlying InputStream @deprecated This method does not properly convert bytes to characters. see DataInputStream for the details and alternatives.

This method is called by trusted subclasses of ObjectOutputStream that constructed ObjectOutputStream using the protected no-arg constructor. The subclass is expected to provide an override method with the modifier "final". @return the Object read from the stream. @exception java.lang.ClassNotFoundException Class definition of a serialized object cannot be found. @exception OptionalDataException Primitive data was found in the stream instead of objects. @exception IOException if I/O errors occurred while reading from the underlying stream @see #ObjectInputStream() @see #readObject() @since JDK 1.2

The readStreamHeader method is provided to allow subclasses to read and verify their own stream headers. It reads and verifies the magic number and version number. @throws IOException if there are I/O errors while reading from the underlying InputStream @throws StreamCorruptedException if control information in the stream is inconsistent

Reads a UTF format String. @return the String. @throws IOException if there are I/O errors while reading from the underlying InputStream

Load the local class equivalent of the specified stream class description. Subclasses may implement this method to allow classes to be fetched from an alternate source. The corresponding method in ObjectOutputStream is annotateClass. This method will be invoked only once for each unique class in the stream. This method can be implemented by subclasses to use an alternate loading mechanism but must return a Class object. Once returned the serialVersionUID of the class is compared to the serialVersionUID of the serialized class. If there is a mismatch the deserialization fails and an exception is raised.

By default the class name is resolved relative to the class that called readObject.

@param v an instance of class ObjectStreamClass @return a Class object corresponding to v @exception IOException Any of the usual Input/Output exceptions. @exception ClassNotFoundException If class of a serialized object cannot be found.

This method will allow trusted subclasses of ObjectInputStream to substitute one object for another during deserialization. Replacing objects is disabled until enableResolveObject is called. The enableResolveObject method checks that the stream requesting to resolve object can be trusted. Every reference to serializable objects is passed to resolveObject. To insure that the private state of objects is not unintentionally exposed only trusted streams may use resolveObject.

This method is called after an object has been read but before it is returned from readObject. The default resolveObject method just returns the newsame object.

When a subclass is replacing objects it must insure that the substituted object is compatible with every field where the reference will be stored. Objects whose type is not a subclass of the type of the field or array element abort the serialization by raising an exception and the object is not be stored.

This method is called only once when each object is first encountered. All subsequent references to the object will be redirected to the new object.

@param obj object to be substituted @return the substituted object @exception IOException Any of the usual Input/Output exceptions.

Skips bytes block until all bytes are skipped. @param nlen the number of bytes to be skipped @return the actual number of bytes skipped. @exception EOFException If end of file is reached. @exception IOException If other I/O error has occurred.

Callback interface to allow validation of objects within a graph. Allows an object to be called when a complete graph of objects has been deserialized. @author unascribed @version 1.12 0915 02/2102/9800 @see ObjectInputStream @see ObjectInputStream#registerValidation(java.io.ObjectInputValidation int) @since JDK1.1

Validates the object. @exception InvalidObjectException If the object cannot validate itself.

ObjectOutput extends the DataOutput interface to include writing of objects. DataOutput includes methods for output of primitive types ObjectOutput extends that interface to include objects arrays and Strings. @author unascribed @version 1.10 0913 02/2102/9800 @see java.io.InputStream @see java.io.ObjectOutputStream @see java.io.ObjectInputStream @since JDK1.1

Write an object to the underlying storage or stream. The class that implements this interface defines how the object is written. @param obj the object to be written @exception IOException Any of the usual Input/Output related exceptions.

An ObjectOutputStream writes primitive data types and graphs of Java objects to an OutputStream. The objects can be read (reconstituted) using an ObjectInputStream. Persistent storage of objects can be accomplished by using a file for the stream. If the stream is a network socket stream the objects can be reconsituted on another host or in another process.

Only objects that support the java.io.Serializable interface can be written to streams. The class of each serializable object is encoded including the class name and signature of the class the values of the object's fields and arrays and the closure of any other objects referenced from the initial objects.

The method writeObject is used to write an object to the stream. Any object including Strings and arrays is written with writeObject. Multiple objects or primitives can be written to the stream. The objects must be read back from the corresponding ObjectInputstream with the same types and in the same order as they were written.

Primitive data types can also be written to the stream using the appropriate methods from DataOutput. Strings can also be written using the writeUTF method.

The default serialization mechanism for an object writes the class of the object the class signature and the values of all non-transient and non-static fields. References to other objects (except in transient or static fields) cause those objects to be written also. Multiple references to a single object are encoded using a reference sharing mechanism so that graphs of objects can be restored to the same shape as when the original was written.

For example to write an object that can be read by the example in ObjectInputStream:

 FileOutputStream ostream = new FileOutputStream("t.tmp"); ObjectOutputStream p = new ObjectOutputStream(ostream); p.writeInt(12345); p.writeObject("Today"); p.writeObject(new Date()); p.flush(); ostream.close(); 

Classes that require special handling during the serialization and deserialization process must implement special methods with these exact signatures:

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

The writeObject method is responsible for writing the state of the object for its particular class so that the corresponding readObject method can restore it. The method does not need to concern itself with the state belonging to the object's superclasses or subclasses. State is saved by writing the individual fields to the ObjectOutputStream using the writeObject method or by using the methods for primitive data types supported by DataOutput.

Serialization does not write out 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.

Serialization of an object can be prevented by implementing writeObject and readObject methods that throw the NotSerializableException. The exception will be caught by the ObjectOutputStream and abort the serialization 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. Primitive data excluding serializable fields and externalizable data is written to the ObjectOutputStream in block-data records. A block data record is composed of a header and data. The block data header consists of a marker and the number of bytes to follow the header. Consecutive primitive data writes are merged into one block-data record. (*) The blocking factor used for a block-data record will be 1024 bytes. (*) Each block-data record will be filled up to 1024 bytes or be written whenever there is a termination of block-data mode. Calls to the ObjectOutputStream methods writeObject defaultWriteObject and writeFields initially terminate any existing block-data record. @author Roger Riggs @version 1.67103 03/02/9817/00 @see java.io.DataOutput @see java.io.ObjectInputStream @see java.io.Serializable @see java.io.Externalizable @see Object Serialization Specification Section 2 Object Output Classes @since JDK1.1

Provide programatic access to the persistent fields to be written to ObjectOutput. @since JDK 1.2

Put the value of the named Object field into the persistent field. @param name the name of the serializable field @param value the value to assign to the field

Put the value of the named boolean field into the persistent field. @param name the name of the serializable field @param value the value to assign to the field

Put the value of the named byte field into the persistent fields. @param name the name of the serializable field @param value the value to assign to the field

Put the value of the named char field into the persistent fields. @param name the name of the serializable field @param value the value to assign to the field

Put the value of the named double field into the persistent field. @param name the name of the serializable field @param value the value to assign to the field

Put the value of the named float field into the persistent fields. @param name the name of the serializable field @param value the value to assign to the field

Put the value of the named int field into the persistent fields. @param name the name of the serializable field @param value the value to assign to the field

Put the value of the named long field into the persistent fields. @param name the name of the serializable field @param value the value to assign to the field

Put the value of the named short field into the persistent fields. @param name the name of the serializable field @param value the value to assign to the field

Write the data and fields to the specified ObjectOutput stream. @param out the stream to write the data and fields to @throws IOException if I/O errors occur while writing to the underlying stream

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

If there is a security manager installed this method first calls the security manager's checkPermission method with a 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.securityio.SerializablePermission

Creates an ObjectOutputStream that writes to the specified OutputStream. The stream header is written to the stream. The caller may want to call flush immediately so that the corresponding ObjectInputStream can read the header immediately. @param out OutputStream to read from @exception IOException Any exception thrown by the underlying OutputStream.

Subclasses may implement this method to allow class data to be stored in the stream. By default this method does nothing. The corresponding method in ObjectInputStream is resolveClass. This method is called exactly once for each unique class in the stream. The class name and signature will have already been written to the stream. This method may make free use of the ObjectOutputStream to save any representation of the class it deems suitable (for example the bytes of the class file). The resolveClass method in the corresponding subclass of ObjectInputStream must read and use any data or objects written by annotateClass. @param cl the class to annotate custom data for @exception IOException Any exception thrown by the underlying OutputStream.

Write the non-static and non-transient fields of the current class to this stream. This may only be called from the writeObject method of the class being serialized. It will throw the NotActiveException if it is called otherwise. @throws IOException if I/O errors occur while writing to the underlying OutputStream

Drain any buffered data in ObjectOutputStream. Similar to flush but does not propagate the flush to the underlaying stream. @throws IOException if I/O errors occur while writing to the underlying stream

Enable the stream to do replacement of objects in the stream.

When enabled the replaceObject method is called for every object being serialized.

If enable is true and there is a security manager installed this method first calls the security manager's checkPermission method with a SerializablePermission("enableSubstitution") permission to ensure it's ok to enable the stream to do replacement of objects in the stream. @param enable boolean parameter to enable replacement of objects @return the previous setting before this method was invoked @throws SecurityException if a security manager exists and its checkPermission method denies enabling the stream to do replacement of objects in the stream. @see SecurityManager#checkPermission @see java.securityio.SerializablePermission

Retrieve the object used to buffer persistent fields to be written to the stream. The fields will be written to the stream when writeFields method is called. @return an instance of the class Putfield that holds the serializable fields @exception IOException if I/O errors occur @since JDK11.2

This method will allow trusted subclasses of ObjectOutputStream to substitute one object for another during serialization. Replacing objects is disabled until enableReplaceObject is called. The enableReplaceObject method checks that the stream requesting to do replacment can be trusted. Every reference to serializableThe first occurrence of objectseach object written into the serialization stream is passed to replaceObject. Subsequent references to the object are replaced by the object returned by the original call to replaceObject. To insureensure that the private state of objects is not unintentionally exposed only trusted streams may use replaceObject.

The ObjectOutputStream.writeObject method takes a parameter of type Object (as opposed to type Serializable) to allow for cases where non-serializable objects are replaced by serializable ones. When a subclass is replacing objects it must insure that either a complementary substitution must be made during deserialization or that the substituted object is compatible with every field where the reference will be stored. Objects whose type is not a subclass of the type of the field or array element abort the serialization by raising an exception and the object is not be stored.

This method is called only once when each object is first encountered. All subsequent references to the object will be redirected to the new object. This method should return the object to be substituted or the original object.

Null can be returned as the object to be substituted but may cause NullReferenceException in classes that contain references to the original object since they may be expecting an object instead of null.

@param obj the object to be replaced @return the alternate object that replaced the specified one @exception IOException Any exception thrown by the underlying OutputStream.

Reset will disregard the state of any objects already written to the stream. The state is reset to be the same as a new ObjectOutputStream. The current point in the stream is marked as reset so the corresponding ObjectInputStream will be reset at the same point. Objects previously written to the stream will not be refered to as already being in the stream. They will be written to the stream again. @throws IOException if reset() is invoked while serializing an object.

Specify stream protocol version to use when writing the stream.

This routine provides a hook to enable the current version of Serialization to write in a format that is backwards compatible to a previous version of the stream format.

Every effort will be made to avoid introducing additional backwards incompatibilities; however sometimes there is no other alternative.

@param version use ProtocolVersion from java.io.ObjectStreamConstants. @exception IllegalStateException Thrown if called after any objects have been serialized. @exception IllegalArgumentIllegalArgumentException if invalid version is passed in. @throws IOException if I/O errors occur @see java.io.ObjectStreamConstants#PROTOCOL_VERSION_1 @see java.io.ObjectStreamConstants#PROTOCOL_VERSION_2 @since 1.2

Writes a byte. This method will block until the byte is actually written. @param bdata the byte to be written to the stream @exception IOException If an I/O error has occurred.

Writes a boolean. @param data the boolean to be written @throws IOException if I/O errors occur while writing to the underlying stream

Writes an 8 bit byte. @param data the byte value to be written @throws IOException if I/O errors occur while writing to the underlying stream

Writes a String as a sequence of bytes. @param sdata the String of bytes to be written @throws IOException if I/O errors occur while writing to the underlying stream

Writes a 16 bit char. @param data the char value to be written @throws IOException if I/O errors occur while writing to the underlying stream

Writes a String as a sequence of chars. @param sdata the String of chars to be written @throws IOException if I/O errors occur while writing to the underlying stream

Writes a 64 bit double. @param data the double value to be written @throws IOException if I/O errors occur while writing to the underlying stream

Write the buffered fields to the stream. @sincethrows JDK1.2IOException if I/O errors occur while writing to the underlying stream @exceptionthrows NotActiveException Called when a classes writeObject method was not called to write the state of the object. @since 1.2

Writes a 32 bit float. @param data the float value to be written @throws IOException if I/O errors occur while writing to the underlying stream

Writes a 32 bit int. @param data the integer value to be written @throws IOException if I/O errors occur while writing to the underlying stream

Writes a 64 bit long. @param data the long value to be written @throws IOException if I/O errors occur while writing to the underlying stream

Method used by subclasses to override the default writeObject method. This method is called by trusted subclasses of ObjectInputStream that constructed ObjectInputStream using the protected no-arg constructor. The subclass is expected to provide an override method with the modifier "final". @param obj object to be written to the underlying stream @throws IOException if there are I/O errors while writing to the underlying stream @see #ObjectOutputStream() @see #writeObject(Object) @since JDK 1.2

Writes a 16 bit short. @param data the short value to be written @throws IOException if I/O errors occur while writing to the underlying stream

The writeStreamHeader method is provided so subclasses can append or prepend their own header to the stream. It writes the magic number and version to the stream. @throws IOException if I/O errors occur while writing to the underlying stream

Primitive data write of this String in UTF format. Note that there is a significant difference between writing a String into the stream as primitive data or as an Object. A String instance written by writeObject is written into the stream as a String initially. Future writeObject() calls write references to the string into the stream. @param strs the String in UTF format @throws IOException if I/O errors occur while writing to the underlying stream

Serialization's descriptor for classes. It contains the name and serialVersionUID of the class.
The ObjectStreamClass for a specific class loaded in this Java VM can be found/created using the lookup method.

The algorithm to compute the SerialVersionUID is described in Object Serialization Specification Section 4.4 Stream Unique Identifiers. @author Roger Riggs @version @(#)ObjectStreamClass.java 1.45 9798 02/0802/0300 @see ObjectStreamField @see Object Serialization Specification Section 4 Class Descriptors @since JDK1.1

Return the class in the local VM that this version is mapped to. Null is returned if there is no corresponding local class. @return the Class instance that this descriptor represents

Get the field of this class by name. @param name the name of the data field to look for @return The ObjectStreamField object of the named field or null if there is no such named field.

Return an array of the fields of this serializable class. @return an array containing an element for each persistent field of this class. Returns an array of length zero if there are no fields. @since JDK11.2

The name of the class described by this descriptor. @return a String representing the fully qualified name of the class

Return the serialVersionUID for this class. The serialVersionUID defines a set of classes all with the same name that have evolved from a common root class and agree to be serialized and deserialized using a common format. NonSerializable classes have a serialVersionUID of 0L. @return the SUID of the class described by this descriptor

Find the descriptor for a class that can be serialized. Creates an ObjectStreamClass instance if one does not exist yet for class. Null is returned if the specified class does not implement java.io.Serializable or java.io.Externalizable. @param cl class for which to get the descriptor @return the class descriptor for the specified class

Constants written into the Object Serialization Stream. @author unascribed @version 1.22 0729 02/1002/9800 @since JDK 1.1

A Stream Protocol Version.

All externalizable data is written in JDK 1.1 external data format after calling this method. This version is needed to write streams containing Externalizable data that can be read by pre-JDK 1.1.6 JVMs. @see java.io.ObjectOutputStream#useProtocolVersion(int) @since JDK 1.2

A Stream Protocol Version.

This protocol is written by JVM 1.2. Externalizable data is written in block data mode and is terminated with TC_ENDBLOCKDATA. Externalizable classdescriptor flags has SC_BLOCK_DATA enabled. JVM 1.1.6 and greater can read this format change. Enables writing a nonSerializable class descriptor into the stream. The serialVersionUID of a nonSerializable class is set to 0L. @see java.io.ObjectOutputStream#useProtocolVersion(int) @see #SC_BLOCK_DATA @since JDK 1.2

Bit mask for ObejctStreamClass flag. Indicates Externalizable data written in Block Data mode. Added for PROTOCOL_VERSION_2. @see #PROTOCOL_VERSION_2 @since JDK 1.2

Enable overriding of readObject and writeObject. @see java.io.ObjectOutputStream#writeObjectOverride(Object) @see java.io.ObjectInputStream#readObjectOverride() @since JDK 1.2

Enable substitution of one object for another during serialization/deserialization. @see java.io.ObjectOutputStream#enableReplaceObject(boolean) @see java.io.ObjectInputStream#enableResolveObject(boolean) @since JDK 1.2

new Array.

new Object.

new String.

Superclass of all exceptions specific to Object Stream classes. @author unascribed @version 1.7 0910 02/2102/9800 @since JDK1.1

Create an ObjectStreamException with the specified argument. @param classname the detailed message for the exception

A description of a Serializable field from a Serializable class. An array of ObjectStreamFields is used to declare the Serializable fields of a class. @author Roger Riggs @version 1.25 0430 02/3002/9800 @see ObjectStreamClass @since 1.2

Create a Serializable field with the specified type. This field should be documented with a serialField tag. @param n the name of the serializable field @param clazz the Class object of the serializable field

Get the name of this field. @return a String representing the name of the serializable field

Offset of field within instance data. @return the offset of this field @see #setOffset

Get the type of the field. @return the Class object of the serializable field

Returns character encoding of field type. The encoding is as follows:

 B byte C char D double F float I int J long L class or interface S short Z boolean [ array 

@return the typecode of the serializable field

Return the JVM type signature. @returnsreturn null if this field has a primitive type.

Return true if this field has a primitive type. @return true if and only if this field corresponds to a primitive type

Offset within instance data. @param offset the offset of the field @see #getOffset

This abstract class is the superclass of all classes representing an output stream of bytes. An output stream accepts output bytes and sends them to some sink.

Applications that need to define a subclass of OutputStream must always provide at least a method that writes one byte of output. @author Arthur van Hoff @version 1.21 0423 02/0902/9800 @see java.io.BufferedOutputStream @see java.io.ByteArrayOutputStream @see java.io.DataOutputStream @see java.io.FilterOutputStream @see java.io.InputStream @see java.io.OutputStream#write(int) @since JDK1.0

WriteAn characters to an outputOutputStreamWriter stream translating characters into bytes accordingis a bridge from character streams to a specifiedbyte characterstreams: encoding.Characters Each OutputStreamWriter incorporates its own CharToByteConverter and is thuswritten to it are translated into bytes according to a bridge fromspecified character streams to byte streamsencoding. The encoding used bythat an OutputStreamWriterit uses may be specified by name by providing a CharToByteConverter or by accepting the platform's default encoding which is defined by the systemmay propertybe file.encodingaccepted.

Each invocation of a write() method causes the encoding converter to be invoked on the given character(s). The resulting bytes are accumulated in a buffer before being written to the underlying output stream. The size of this buffer may be specified but by default it is large enough for most purposes. Note that the characters passed to the write() methods are not buffered.

For top efficiency consider wrapping an OutputStreamWriter within a BufferedWriter so as to avoid frequent converter invocations. For example:

 Writer out = new BufferedWriter(new OutputStreamWriter(System.out)); 

@see BufferedWriter @see OutputStream @see Character encodings @version 1.10 9728 02/0102/2700 @author Mark Reinhold @since JDK1.1

Create an OutputStreamWriter that uses the named character encoding. @param out An OutputStream @param enc Name of the encoding toThe name of a supported becharacter usedencoding @exception UnsupportedEncodingException If the named encoding is not supported

Returns the canonical name of the character encoding being used by this stream. If this OutputStreamWriter was created with the String) constructor then the returned encoding name being canonical may differ from the encoding name passed to the constructor. May return null if the stream has been closed. @return a String representing the encoding name or possibly null if the stream has been closed @see Character encodings

A piped input stream should be connected to a piped output stream; the piped input stream then provides whatever data bytes are written to the piped output stream. Typically data is read from a PipedInputStream object by one thread and data is written to the corresponding PipedOutputStream by some other thread. Attempting to use both objects from a single thread is not recommended as it may deadlock the thread. The piped input stream contains a buffer decoupling read operations from write operations within limits. @author James Gosling @version 1.28 0730 02/0702/9800 @see java.io.PipedOutputStream @since JDK1.0

A piped output stream can be connected to a piped input stream to create a communications pipe. The piped output stream is the sending end of the pipe. Typically data is written to a PipedOutputStream object by one thread and data is read from the connected PipedInputStream by some other thread. Attempting to use both objects from a single thread is not recommended as it may deadlock the thread. @author James Gosling @version 1.21 0423 02/0902/9800 @see java.io.PipedInputStream @since JDK1.0

Piped character-input streams. @version 1.10 9812 00/0702/0702 @author Mark Reinhold @since JDK1.1

Piped character-output streams. @version 1.10 9813 00/0702/0702 @author Mark Reinhold @since JDK1.1

A PrintStream adds functionality to another output stream namely the ability to print representations of various data values conveniently. Two other features are provided as well. Unlike other output streams a PrintStream never throws an IOException; instead exceptional situations merely set an internal flag that can be tested via the checkError method. Optionally a PrintStream can be created so as to flush automatically; this means that the flush method is automatically invoked after a byte array is written one of the println methods is invoked or a newline character or byte ('\n') is written.

All characters printed by a PrintStream are converted into bytes using the platform's default character encoding. The class should be used in situations that require writing characters rather than bytes. @version 1.18 9821 00/0702/3102 @author Frank Yellin @author Mark Reinhold @since JDK1.0

Print an object. The string produced by the {@link java.lang.String#valueOf(Object)} method is translated into bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param obj The Object to be printed @see java.lang.Object#toString()

Print a string. If the argument is null then the string "null" is printed. Otherwise the string's characters are converted into bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param s The String to be printed

Print a boolean value. The string produced by {@link java.lang.String#valueOf(boolean)} is translated into bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param b The boolean to be printed

Print a character. The character is translated into one or more bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param c The char to be printed

Print an array of characters. The characters are converted into bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param s The array of chars to be printed @throws NullPointerException If s is null

Print a double-precision floating-point number. The string produced by {@link java.lang.String#valueOf(double)} is translated into bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param d The double to be printed @see java.lang.Double#toString(double)

Print a floating-point number. The string produced by {@link java.lang.String#valueOf(float)} is translated into bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param f The float to be printed @see java.lang.Float#toString(float)

Print an integer. The string produced by {@link java.lang.String#valueOf(int)} is translated into bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param i The int to be printed @see java.lang.Integer#toString(int)

Print a long integer. The string produced by {@link java.lang.String#valueOf(long)} is translated into bytes according to the platform's default character encoding and these bytes are written in exactly the manner of the {@link #write(int)} method. @param l The long to be printed @see java.lang.Long#toString(long)

Print an Object and then terminate the line. This method behaves as though it invokes {@link #print(Object)} and then {@link #println()}. @param x The Object to be printed.

Print a String and then terminate the line. This method behaves as though it invokes {@link #print(String)} and then {@link #println()}. @param x The String to be printed.

Print a boolean and then terminate the line. This method behaves as though it invokes {@link #print(boolean)} and then {@link #println()}. @param x The boolean to be printed

Print a character and then terminate the line. This method behaves as though it invokes {@link #print(char)} and then {@link #println()}. @param x The char to be printed.

Print an array of characters and then terminate the line. This method behaves as though it invokes {@link #print(char[])} and then {@link #println()}. @param x an array of chars to print.

Print a double and then terminate the line. This method behaves as though it invokes {@link #print(double)} and then {@link #println()}. @param x The double to be printed.

Print a float and then terminate the line. This method behaves as though it invokes {@link #print(float)} and then {@link #println()}. @param x The float to be printed.

Print an integer and then terminate the line. This method behaves as though it invokes {@link #print(int)} and then {@link #println()}. @param x The int to be printed.

Print a long and then terminate the line. This method behaves as though it invokes {@link #print(long)} and then {@link #println()}. @param x a The long to be printed.

Print formatted representations of objects to a text-output stream. This class implements all of the print methods found in PrintStream. It does not contain methods for writing raw bytes for which a program should use unencoded byte streams.

Unlike the PrintStream class if automatic flushing is enabled it will be done only when one of the println() methods is invoked rather than whenever a newline character happens to be output. The println() methods use the platform's own notion of line separator rather than the newline character.

Methods in this class never throw I/O exceptions. The client may inquire as to whether any errors have occurred by invoking checkError(). @version 1.19 9824 02/0602/2900 @author Frank Yellin @author Mark Reinhold @since JDK1.1

Print an Object and then terminate the line. This method behaves as though it invokes {@link #print(Object)} and then {@link #println()}. @param x the Object value to be printed

Print a String and then terminate the line. This method behaves as though it invokes {@link #print(String)} and then {@link #println()}. @param x the String value to be printed

Print a boolean value and then terminate the line. This method behaves as though it invokes {@link #print(boolean)} and then {@link #println()}. @param x the boolean value to be printed

Print a character and then terminate the line. This method behaves as though it invokes {@link #print(char)} and then {@link #println()}. @param x the char value to be printed

Print an array of characters and then terminate the line. This method behaves as though it invokes {@link #print(char[])} and then {@link #println()}. @param x the array of char values to be printed

Print a double-precision floating-point number and then terminate the line. This method behaves as though it invokes {@link #print(double)} and then {@link #println()}. @param x the double value to be printed

Print a floating-point number and then terminate the line. This method behaves as though it invokes {@link #print(float)} and then {@link #println()}. @param x the float value to be printed

Print an integer and then terminate the line. This method behaves as though it invokes {@link #print(int)} and then {@link #println()}. @param x the int value to be printed

Print a long integer and then terminate the line. This method behaves as though it invokes {@link #print(long)} and then {@link #println()}. @param x the long value to be printed

The underlying character-output stream of this PrintWriter. @since JDK11.2

A PushbackInputStream adds functionality to another input stream namely the ability to "push back" or "unread" one byte. This is useful in situations where it is convenient for a fragment of code to read an indefinite number of data bytes that are delimited by a particular byte value; after reading the terminating byte the code fragment can "unread" it so that the next read operation on the input stream will reread the byte that was pushed back. For example bytes representing the characters constituting an identifier might be terminated by a byte representing an operator character; a method whose job is to read just an identifier can read until it sees the operator and then push the operator back to be re-read. @author David Connelly @author Jonathan Payne @version 1.25 0431 02/3002/9800 @since JDK1.0

Skips over and discards n bytes of data from this input stream. The skip method may for a variety of reasons end up skipping over some smaller number of bytes possibly zero. If n is negative no bytes are skipped.

The skip method of PushbackInputStream first skips over the bytes in the pushback buffer if any. It then calls the skip method of the underlying input stream if more bytes need to be skipped. The actual number of bytes skipped is returned. @param n the number of bytes to be skipped. @return the actual number of bytes skipped. @exception IOException if an I/O error occurs. @see java.io.FilterInputStream#in @see java.io.InputStream#skip(long n) @since JDK11.2

A character-stream reader that allows characters to be pushed back into the stream. @version 1.12 9814 00/0702/0702 @author Mark Reinhold @since JDK1.1

Instances of this class support both reading and writing to a random access file. A random access file behaves like a large array of bytes stored in the file system. There is a kind of cursor or index into the implied array called the file pointer; input operations read bytes starting at the file pointer and advance the file pointer past the bytes read. If the random access file is created in read/write mode then output operations are also available; output operations write bytes starting at the file pointer and advance the file pointer past the bytes written. Output operations that write past the current end of the implied array cause the array to be extended. The file pointer can be read by the getFilePointer method and set by the seek method.

It is generally true of all the reading routines in this class 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 stream has been closed. @author unascribed @version 1.50 0956 02/2402/9800 @since JDK1.0

Sets the length of this file.

If the present length of the file as returned by the length method is greater than the newLength argument then the file will be truncated. In this case if the file offset as returned by the getFilePointer method is greater then newLength then after this method returns the offset will be equal to newLength.

If the present length of the file as returned by the length method is smaller than the newLength argument then the file will be extended. In this case the contents of the extended portion of the file are not defined. @param newLength The desired length of the file @exception IOException If an I/O error occurs @since JDK11.2

Abstract class for reading character streams. The only methods that a subclass must implement are read(char[] int int) and close(). Most subclasses however will override some of the methods defined here in order to provide higher efficiency additional functionality or both. @see BufferedReader @see LineNumberReader @see CharArrayReader @see InputStreamReader @see FileReader @see FilterReader @see PushbackReader @see PipedReader @see StringReader @see Writer @version 1.16 9821 00/0902/2102 @author Mark Reinhold @since JDK1.1

Create a new character-stream reader whose critical sections will synchronize on the given object. @param lock The Object to synchronize on.

Tell whether this stream supports the mark() operation. The default implementation always returns false. Subclasses should override this method. @return true if and only if this stream supports the mark operation.

Read a single character. This method will block until a character is available an I/O error occurs or the end of the stream is reached.

Subclasses that intend to support efficient single-character input should override this method. @return The character read as an integer in the range 0 to 1638365535 (0x00-0xffff) or -1 if the end of the stream has been reached @exception IOException If an I/O error occurs

Skip characters. This method will block until some characters are available an I/O error occurs or the end of the stream is reached. @param n The number of characters to skip @return The number of characters actually skipped @exception IllegalArgumentException If n is negative. @exception IOException If an I/O error occurs

A SequenceInputStream represents the logical concatenation of other input streams. It starts out with an ordered collection of input streams and reads from the first one until end of file is reached whereupon it reads from the second one and so on until end of file is reached on the last of the contained input streams. @author Author van Hoff @version 1.20 0623 02/2902/9800 @since JDK1.0

Reads up to len bytes of data from this input stream into an array of bytes. This method blocks until at least 1 byte of input is available. If the first argument is null up to len bytes are read and discarded.

The read method of SequenceInputStream tries to read the data from the current substream. If it fails to read any characters because the substream has reached the end of the stream it calls the close method of the current substream and begins reading from the next substream. @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 int the number of bytes read. @exception IOException if an I/O error occurs.

Serializability of a class is enabled by the class implementing the java.io.Serializable interface. Classes that do not implement this interface will not have any of their state serialized or deserialized. All subtypes of a serializable class are themselves serializable. The serialization interface has no methods or fields and serves only to identify the semantics of being serializable.

To allow subtypes of non-serializable classes to be serialized the subtype may assume responsibility for saving and restoring the state of the supertype's public protected and (if accessible) package fields. The subtype may assume this responsibility only if the class it extends has an accessible no-arg constructor to initialize the class's state. It is an error to declare a class Serializable in this case. The error will be detected at runtime.

During deserialization the fields of non-serializable classes will be initialized using the public or protected no-arg constructor of the class. A no-arg constructor must be accessible to the subclass that is serializable. The fields of serializable subclasses will be restored from the stream.

When traversing a graph an object may be encountered that does not support the Serializable interface. In this case the NotSerializableException will be thrown and will identify the class of the non-serializable object.

Classes that require special handling during the serialization and deserialization process must implement special methods with these exact signatures:

 private void writeObject(java.io.ObjectOutputStream out) throws IOException private void readObject(java.io.ObjectInputStream in) throws IOException ClassNotFoundException; 

The writeObject method is responsible for writing the state of the object for its particular class so that the corresponding readObject method can restore it. The default mechanism for saving the Object's fields can be invoked by calling out.defaultWriteObject. The method does not need to concern itself with the state belonging to its superclasses or subclasses. State is saved by writing the individual fields to the ObjectOutputStream using the writeObject method or by using the methods for primitive data types supported by DataOutput.

The readObject method is responsible for reading from the stream and restoring the classes fields. It may call in.defaultReadObject to invoke the default mechanism for restoring the object's non-static and non-transient fields. The defaultReadObject method uses information in the stream to assign the fields of the object saved in the stream with the correspondingly named fields in the current object. This handles the case when the class has evolved to add new fields. The method does not need to concern itself with the state belonging to its superclasses or subclasses. State is saved by writing the individual fields to the ObjectOutputStream using the writeObject method or by using the methods for primitive data types supported by DataOutput.

Serializable classes that need to designate an alternative object to be used when writing an object to the stream should implement this special method with the exact signature:

 ANY-ACCESS-MODIFIER Object writeReplace() throws ObjectStreamException; 

This writeReplace method is invoked by serialization if the method exists and it would be accessible from a method defined within the class of the object being serialized. Thus the method can have private protected and package-private access. Subclass access to this method follows java accessibility rules.

Classes that need to designate a replacement when an instance of it is read from the stream should implement this special method with the exact signatute.

 ANY-ACCESS-MODIFIER Object readResolve() throws ObjectStreamException; 

This readResolve method follows the same invocation rules and accessibility rules as writeReplace. @author unascribed @version 1.14 0416 02/2202/9900 @see java.io.ObjectOutputStream @see java.io.ObjectInputStream @see java.io.ObjectOutput @see java.io.ObjectInput @see java.io.Externalizable @since JDK1.1

This class is for Serializable permissions. A SerializablePermission contains a name (also referred to as a "target name") but no actions list; you either have the named permission or you don't.

The target name is the name of the Serializable permission (see below).

The following table lists all the possible SerializablePermission target names and for each provides a description of what the permission allows and a discussion of the risks of granting code the permission.

Permission Target Name	What the Permission Allows	Risks of Allowing this Permission
enableSubclassImplementation	Subclass implementation of ObjectOutputStream or ObjectInputStream to override the default serialization or deserialization respectively of objects	Code can use this to serialize or deserialize classes in a purposefully malfeasant manner. For example during serialization malicious code can use this to purposefully store confidential private field data in a way easily accessible to attackers. Or during deserializaiton it could for example deserialize a class with all its private fields zeroed out.
enableSubstitution	Substitution of one object for another during serialization or deserialization	This is dangerous because malicious code can replace the actual object with one which has incorrect or malignant data.

@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.213 02/02/00 @author Joe Fialli @since 1.2

Creates a new SerializablePermission object with the specified name. The name is the symbolic name of the SerializablePermission and the actions String is currently unused and should be null. This constructor exists for use by the Policy object to instantiate new Permission objects. @param name the name of the SerializablePermission. @param actions currently unused and must be set to null

Thrown when control information that was read from an object stream violates internal consistency checks. @author unascribed @version 1.8 0611 02/2902/9800 @since JDK1.1

Create a StreamCorruptedException and list a reason why thrown. @param reason String describing the reason for the exception.

The StreamTokenizer class takes an input stream and parses it into "tokens" allowing the tokens to be read one at a time. The parsing process is controlled by a table and a number of flags that can be set to various states. The stream tokenizer can recognize identifiers numbers quoted strings and various comment styles.

Each byte read from the input stream is regarded as a character in the range '\u0000' through '\u00FF'. The character value is used to look up five possible attributes of the character: white space alphabetic numeric string quote and comment character. Each character can have zero or more of these attributes.

In addition an instance has four flags. These flags indicate:

• Whether line terminators are to be returned as tokens or treated as white space that merely separates tokens.
• Whether C-style comments are to be recognized and skipped.
• Whether C++-style comments are to be recognized and skipped.
• Whether the characters of identifiers are converted to lowercase.

A typical application first constructs an instance of this class sets up the syntax tables and then repeatedly loops calling the nextToken method in each iteration of the loop until it returns the value TT_EOF. @author James Gosling @version 1.31 0436 02/2202/9900 @see java.io.StreamTokenizer#nextToken() @see java.io.StreamTokenizer#TT_EOF @since JDK1.0

Create a tokenizer that parses the given character stream. @param r a Reader object providing the input stream. @since JDK1.1

If the current token is a number this field contains the value of that number. The current token is a number when the value of the ttype field is TT_NUMBER.

The initial value of this field is 0.0. @see java.io.StreamTokenizer#TT_NUMBER @see java.io.StreamTokenizer#ttype

If the current token is a word token this field contains a string giving the characters of the word token. When the current token is a quoted string token this field contains the body of the string.

The current token is a word when the value of the ttype field is TT_WORD. The current token is a quoted string token when the value of the ttype field is a quote character.

The initial value of this field is null. @see java.io.StreamTokenizer#quoteChar(int) @see java.io.StreamTokenizer#TT_WORD @see java.io.StreamTokenizer#ttype

After a call to the nextToken method this field contains the type of the token just read. For a single character token its value is the single character converted to an integer. For a quoted string token (see its value is the quote character. Otherwise its value is one of the following:

• TT_WORD indicates that the token is a word.
• TT_NUMBER indicates that the token is a number.
• TT_EOL indicates that the end of line has been read. The field can only have this value if the eolIsSignificant method has been called with the argument true.
• TT_EOF indicates that the end of the input stream has been reached.

The initial value of this field is -4. @see java.io.StreamTokenizer#eolIsSignificant(boolean) @see java.io.StreamTokenizer#nextToken() @see java.io.StreamTokenizer#quoteChar(int) @see java.io.StreamTokenizer#TT_EOF @see java.io.StreamTokenizer#TT_EOL @see java.io.StreamTokenizer#TT_NUMBER @see java.io.StreamTokenizer#TT_WORD

This class allows an application to create an input stream in which the bytes read are supplied by the contents of a string. Applications can also read bytes from a byte array by using a ByteArrayInputStream.

Only the low eight bits of each character in the string are used by this class. @author Arthur van Hoff @version 1.20 0622 02/2902/9800 @see java.io.ByteArrayInputStream @see java.io.StringReader @since JDK1.0 @deprecated This class does not properly convert characters into bytes. As of JDK 1.1 the preferred way to create a stream from a string is via the StringReader class.

A character stream whose source is a string. @version 1.12 9815 00/0702/0802 @author Mark Reinhold @since JDK1.1

Create a new string reader. @param s String providing the character stream.

A character stream that collects its output in a string buffer which can then be used to construct a string. @version 1.15 9818 00/0902/3002 @author Mark Reinhold @since JDK1.1

Create a new string writer using the specified initial string-buffer size. @param initialSize an int specifying the initial size of the buffer.

Return the string buffer itself. @return StringBuffer holding the current buffer value.

Constructs an SyncFailedException with a detail message. A detail message is a String that describes this particular exception. @param desc a String describing the exception.

Signals that a malformed UTF-8 string has been read in a data input stream or by any class that implements the data input interface. See the writeUTF method for the format in which UTF-8 strings are read and written. @author Frank Yellin @version 1.7 069 02/2902/9800 @see java.io.DataInput @see java.io.DataInputStream#readUTF(java.io.DataInput) @see java.io.IOException @since JDK1.0

The Character Encoding is not supported. @author Asmus Freytag @version 1.9 0913 02/2102/9800 @since JDK1.1

no detailedConstructs an UnsupportedEncodingException without a detail message.

detailedConstructs an UnsupportedEncodingException with a detail message. @param s - detailedDescribes the messagereason for the exception.

Thrown during a read operation when one of the ObjectStreamExceptions was thrown during a write operation. The exception that terminated the write can be found in the detail field. The stream is reset to it's initial state andd all references to objects already deserialized are discarded. @param s String describing the exception. @param ex Exception causing the abort.

Abstract class for writing to character streams. The only methods that a subclass must implement are write(char[] int int) flush() and close(). Most subclasses however will override some of the methods defined here in order to provide higher efficiency additional functionality or both. @see Writer @see BufferedWriter @see CharArrayWriter @see FilterWriter @see OutputStreamWriter @see FileWriter @see PipedWriter @see PrintWriter @see StringWriter @see Reader @version 1.16 9819 00/0902/2102 @author Mark Reinhold @since JDK1.1

Create a new character-stream writer whose critical sections will synchronize on the given object. @param lock Object to synchronize on.

Write a single character. The character to be written is contained in the 16 low-order bits of the given integer value; the 16 high-order bits are ignored.

Subclasses that intend to support efficient single-character output should override this method. @param c int specifying a character to be written. @exception IOException If an I/O error occurs