Generated by
JDiff

java.io Documentation Differences

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

Class DataInputStream

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

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

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

0 bits 6-0

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

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

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

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

@author Arthur van Hoff @version 1.5659 12/03/0126/02 @see java.io.DataOutputStream @since JDK1.0
Class DataInputStream, constructor DataInputStream(InputStream)

Creates a FilterInputStreamDataInputStream and savesthat uses its argument the input stream in forspecified later useunderlying InputStream. An internal @param in the specified input stream.
Class DataInputStream, String readUTF()

See the general contract of the readUTF method of DataInput.

Bytes for this operation are read from the contained input stream. @return a Unicode string. @exception EOFException if this input stream reaches the end before reading all the bytes. @exception IOException if an I/O error occurs. @exception UTFDataFormatException if the bytes do not represent a valid UTF-8 encoding of a string. @see java.io.DataInputStream#readUTF(java.io.DataInput)


Class DataOutput

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

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

Class DataOutput, void writeUTF(String)

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)(0xe0 | (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 UTFDataFormatErrorUTFDataFormatException 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.


Class File

An abstract representation of file and directory pathnames.

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

  1. An optional system-dependent prefix string such as a disk-drive specifier "/" for the UNIX root directory or "\\" for a Win32Microsoft Windows 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 Win32Microsoft Windows platforms as follows:

Instances of the File class are immutable; that is once created the abstract pathname represented by a File object will never change. @version 1.102 12110 05/0306/0102 @author unascribed @since JDK1.0

Class File, int compareTo(File)

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 Win32Microsoft Windows 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 1.2
Class File, boolean createNewFile()

Atomically creates a new empty file named by this abstract pathname if and only if a file with this name does not yet exist. The check for the existence of the file and the creation of the file if it does not exist are a single operation that is atomic with respect to all other filesystem activities that might affect the file. This

Note: this method inshould combinationnot with thebe used {@linkfor #deleteOnExit}file-locking method can therefore serve as the basis for aas the resulting protocol cannot be made to work simplereliably. butThe reliableFileLock cooperativefacility file-lockingshould protocolbe used instead. @return true if the named file does not exist and was successfully created; false if the named file already exists @throws IOException If an I/O error occurred @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method denies write access to the file @since 1.2

Class File, File createTempFile(String, String, File)

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

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

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

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

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

Class File, void deleteOnExit()

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.

Note: this method should not be used for file-locking as the resulting protocol cannot be made to work reliably. The FileLock facility should be used instead. @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkDelete} method denies delete access to the file @see #delete @since 1.2

Class File, boolean equals(Object)

Tests this abstract pathname for equality with the given object. Returns true if and only if the argument is not null and is an abstract pathname that denotes the same file or directory as this abstract pathname. Whether or not two abstract pathnames are equal depends upon the underlying system. On UNIX systems alphabetic case is significant in comparing pathnames; on Win32Microsoft Windows systems it is not. @param obj The object to be compared with this abstract pathname @return true if and only if the objects are the same; false otherwise
Class File, String getAbsolutePath()

Returns the absolute pathname string of this abstract pathname.

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

Class File, String getCanonicalPath()

Returns the canonical pathname string of this abstract pathname.

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

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

Class File, int hashCode()

Computes a hash code for this abstract pathname. Because equality of abstract pathnames is inherently system-dependent so is the computation of their hash codes. On UNIX systems the hash code of an abstract pathname is equal to the exclusive or of its pathname string and the decimal value 1234321. On Win32Microsoft Windows systems the hash code is equal to the exclusive or of its pathname string convered to lower case and the decimal value 1234321. @return A hash code for this abstract pathname
Class File, boolean isAbsolute()

Tests whether this abstract pathname is absolute. The definition of absolute pathname is system dependent. On UNIX systems a pathname is absolute if its prefix is "/". On Win32Microsoft Windows systems a pathname is absolute if its prefix is a drive specifier followed by "\\" or if its prefix is "\\". @return true if this abstract pathname is absolute false otherwise
Class File, boolean isHidden()

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

Renames the file denoted by this abstract pathname.

Whether or not this method can move a file from one filesystem to another is platform-dependent. The return value should always be checked to make sure that the rename operation was successful. @param dest The new abstract pathname for the named file @return true if and only if the renaming succeeded; false otherwise @throws SecurityException If a security manager exists and its {@link java.lang.SecurityManager#checkWrite(java.lang.String)} method denies write access to either the old or new pathnames @throws NullPointerException If parameter dest is null

Class File, char pathSeparatorChar

The system-dependent path-separator character. This field is initialized to contain the first character of the value of the system property path.separator. This character is used to separate filenames in a sequence of files given as a path list. On UNIX systems this character is ':'; on Win32Microsoft Windows systems it is ';'. @see java.lang.System#getProperty(java.lang.String)
Class File, char separatorChar

The system-dependent default name-separator character. This field is initialized to contain the first character of the value of the system property file.separator. On UNIX systems the value of this field is '/'; on Win32Microsoft Windows systems it is '\'. @see java.lang.System#getProperty(java.lang.String)

Class FileFilter

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.FileFilterFile} class. @since 1.2


Class FileInputStream

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

FileInputStream is meant for reading streams of raw bytes such as image data. For reading streams of characters consider using FileReader. @author Arthur van Hoff @version 1.57 1258 02/0306/0102 @see java.io.File @see java.io.FileDescriptor @see java.io.FileOutputStream @since JDK1.0


Class FileOutputStream

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

FileOutputStream is meant for writing streams of raw bytes such as image data. For writing streams of characters consider using FileWriter. @author Arthur van Hoff @version 1.53 1254 02/0306/0102 @see java.io.File @see java.io.FileDescriptor @see java.io.FileInputStream @since JDK1.0


Class FileReader

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

FileReader is meant for reading streams of characters. For reading streams of raw bytes consider using a FileInputStream. @see InputStreamReader @see FileInputStream @version 1.12 0113 02/1202/0306 @author Mark Reinhold @since JDK1.1

Class FileReader, constructor FileReader(File)

Creates a new FileReader given the File to read from. @param file the File to read from @throwsexception FileNotFoundException if the specified file isdoes not foundexist is a directory rather than a regular file or for some other reason cannot be opened for reading.
Class FileReader, constructor FileReader(String)

Creates a new FileReader given the name of the file to read from. @param fileName the name of the file to read from @throwsexception FileNotFoundException if the specifiednamed file isdoes not foundexist is a directory rather than a regular file or for some other reason cannot be opened for reading.

Class FileWriter

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

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

FileWriter is meant for writing streams of characters. For writing streams of raw bytes consider using a FileOutputStream. @see OutputStreamWriter @see FileOutputStream @version 1.15 0116 02/1202/0306 @author Mark Reinhold @since JDK1.1

Class FileWriter, constructor FileWriter(File)

Constructs a FileWriter object given a File object. @param file a File object to write to. @throws IOException if the specified file exists but is a directory rather than a regular file does not foundexist but cannot be created or if some othercannot be opened I/Ofor errorany occurs.other reason
Class FileWriter, constructor FileWriter(File, boolean)

Constructs a FileWriter object given a File object. If the second argument is true then bytes will be written to the end of the file rather than the beginning. @param file a File object to write to @param append if true then bytes will be written to the end of the file rather than the beginning @throws IOException if the specified file exists but is a directory rather than a regular file does not foundexist but cannot be created or ifcannot be some otheropened for I/Oany error occursother reason @since 1.4
Class FileWriter, constructor FileWriter(String)

Constructs a FileWriter object given a file name. @param fileName String The system-dependent filename. @throws IOException if the specifiednamed file exists but is a directory rather than a regular file does not foundexist but cannot be created or if some othercannot be opened I/Ofor errorany occurs.other reason
Class FileWriter, constructor FileWriter(String, boolean)

Constructs a FileWriter object given a file name with a boolean indicating whether or not to append the data written. @param fileName String The system-dependent filename. @param append boolean if true then data will be written to the end of the file rather than the beginning. @throws IOException if the specifiednamed file exists but is a directory rather than a regular file does not foundexist but cannot be created or if some othercannot be opened I/Ofor errorany occurs.other reason

Class ObjectInputStream

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

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

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

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

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

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

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

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

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

 FileInputStream istreamfis = new FileInputStream("t.tmp"); ObjectInputStream pois = new ObjectInputStream(istreamfis); int i = pois.readInt(); String today = (String)p ois.readObject(); Date date = (Date)p ois.readObject(); istreamois.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 the following methods:

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

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

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

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

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

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

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

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

Class ObjectInputStream, constructor ObjectInputStream(InputStream)

Creates an ObjectInputStream that reads from the specified InputStream. A serialization stream header is read from the stream and verified. This constructor will block until the corresponding ObjectOutputStream has written and flushed the header.

If a security manager is installed this constructor will check for the "enableSubclassImplementation" SerializablePermission when invoked directly or indirectly by the constructor of a subclass which overrides the ObjectInputStream.readFields or ObjectInputStream.readUnshared methods. @param in input stream to read from @throws StreamCorruptedException if the stream header is incorrect @throws IOException if an I/O error occurs while reading stream header @throws SecurityException if untrusted subclass illegally overrides security-sensitive methods @throws NullPointerException if in is null @see ObjectInputStream#ObjectInputStream() @see ObjectInputStream#readFields() @see ObjectOutputStream#ObjectOutputStream(OutputStream)

Class ObjectInputStream, String readUTF()

Reads a UTF format String. @return the String. @throws IOException if there are I/O errors while reading from the underlying InputStream @throws UTFDataFormatException if read bytes do not represent a valid UTF-8 encoding of a string
Class ObjectInputStream, Class resolveClass(ObjectStreamClass)

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 desc an instance of class ObjectStreamClass @return a Class object corresponding to vdesc @throws IOException Anyany of the usual Inputinput/Outputoutput exceptions. @throws ClassNotFoundException Ifif class of a serialized object cannot be found.

Class ObjectInputStream, Class resolveProxyClass(String[])

Returns a proxy class that implements the interfaces named in a proxy class descriptor; subclasses may implement this method to read custom data from the stream along with the descriptors for dynamic proxy classes allowing them to use an alternate loading mechanism for the interfaces and the proxy class.

This method is called exactly once for each unique proxy class descriptor in the stream.

The corresponding method in ObjectOutputStream is annotateProxyClass. For a given subclass of ObjectInputStream that overrides this method the annotateProxyClass method in the corresponding subclass of ObjectOutputStream must write any data or objects read by this method.

The default implementation of this method in ObjectInputStream returns the result of calling Proxy.getProxyClass with the list of Class objects for the interfaces that are named in the interfaces parameter. The Class object for each interface name i is the value returned by calling

 Class.forName(i false loader) 
where loader is that of the first non-null class loader up the execution stack or null if no non-null class loaders are on the stack (the same class loader choice used by the resolveClass method). Unless any of the resolved interfaces are non-public this same value of loader is also the class loader passed to Proxy.getProxyClass; if non-public interfaces are present their class loader is passed instead (if more than one non-public interface class loader is encountered an IllegalAccessError is thrown). If Proxy.getProxyClass throws an IllegalArgumentException resolveProxyClass will throw a ClassNotFoundException containing the IllegalArgumentException. @param interfaces the list of interface names that were deserialized in the proxy class descriptor @return a proxy class for the specified interfaces @throws IOException any exception thrown by the underlying InputStream @throws ClassNotFoundException if the proxy class or any of the named interfaces could not be found @see ObjectOutputStream#annotateProxyClass(Class) @since 1.3

Class ObjectOutputStream

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 ostreamfos = new FileOutputStream("t.tmp"); ObjectOutputStream poos = new ObjectOutputStream(ostreamfos); poos.writeInt(12345); poos.writeObject("Today"); poos.writeObject(new Date()); poos.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 Mike Warres @author Roger Riggs @version 1.130 01132 02/1204/0312 @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

Class ObjectOutputStream, constructor ObjectOutputStream(OutputStream)

Creates an ObjectOutputStream that writes to the specified OutputStream. This constructor writes the serialization stream header to the underlying stream; callers may wish to flush the stream immediately to ensure that constructors for receiving ObjectInputStreams will not block when reading the header.

If a security manager is installed this constructor will check for the "enableSubclassImplementation" SerializablePermission when invoked directly or indirectly by the constructor of a subclass which overrides the ObjectOutputStream.putFields or ObjectOutputStream.writeUnshared methods. @param out output stream to write to @throws IOException if an I/O error occurs while writing stream header @throws SecurityException if untrusted subclass illegally overrides security-sensitive methods @throws NullPointerException if out is null @see ObjectOutputStream#ObjectOutputStream() @see ObjectOutputStream#putFields() @see ObjectInputStream#ObjectInputStream(InputStream)


Class RandomAccessFile

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.67 1268 02/0306/0102 @since JDK1.0


Class SerializablePermission

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.14 1215 02/03/01/02 @author Joe Fialli @since 1.2

Class SerializablePermission, constructor SerializablePermission(String, String)

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

Class StreamTokenizer

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:

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.37 1238 02/0306/0102 @see java.io.StreamTokenizer#nextToken() @see java.io.StreamTokenizer#TT_EOF @since JDK1.0

Class StreamTokenizer, void commentChar(int)

Specified that the character argument starts a single-line comment. All characters from the comment character to the end of the line are ignored by this stream tokenizer.

Any other attribute settings for the specified character are cleared. @param ch the character.

Class StreamTokenizer, void quoteChar(int)

Specifies that matching pairs of this character delimit string constants in this tokenizer.

When the nextToken method encounters a string constant the ttype field is set to the string delimiter and the sval field is set to the body of the string.

If a string quote character is encountered then a string is recognized consisting of all characters after (but not including) the string quote character up to (but not including) the next occurrence of that same string quote character or a line terminator or end of file. The usual escape sequences such as "\n" and "\t" are recognized and converted to single characters as the string is parsed.

Any other attribute settings for the specified character are cleared. @param ch the character. @see java.io.StreamTokenizer#nextToken() @see java.io.StreamTokenizer#sval @see java.io.StreamTokenizer#ttype

Class StreamTokenizer, String toString()

Returns the string representation of the current stream token and the line number it occurs on. @return

The aprecise string representationreturned ofis unspecified although the token specified by thefollowing example can be ttypeconsidered nvaltypical: and

Token['a'] svalline fields.10
@return a string representation of the token @see java.io.StreamTokenizer#nval @see java.io.StreamTokenizer#sval @see java.io.StreamTokenizer#ttype
Class StreamTokenizer, void whitespaceChars(int, int)

Specifies that all characters c in the range low <= c <= high are white space characters. White space characters serve only to separate tokens in the input stream.

Any other attribute settings for the characters in the specified range are cleared. @param low the low end of the range. @param hi the high end of the range.