|
Generated by JDiff |
||||||||
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES |
This file contains all the changes in documentation in the packagejava.io
as colored differences. Deletions are shownlike 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 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.Class DataInputStream, constructor DataInputStream(InputStream)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.
- 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.
565912/03/0126/02 @see java.io.DataOutputStream @since JDK1.0
Creates aClass DataInputStream, String readUTF()FilterInputStreamDataInputStreamand savesthat usesits argumenttheinput stream in forspecifiedlater useunderlying InputStream.An internal@param in the specified input stream.
See the general contract of thereadUTF
method ofDataInput
.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)
TheClass DataOutput, void writeUTF(String)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 aString
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
Writes two bytes of length information to the output stream followed by the Java modified UTF representation of every character in the strings
. Ifs
isnull
aNullPointerException
is thrown. Each character in the strings
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)cIf 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
throughuffff
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 than65535
then ais thrown. Otherwise this length is written to the output stream in exactly the manner of the
UTFDataFormatErrorUTFDataFormatExceptionwriteShort
method; after this the one- two- or three-byte representation of each character in the strings
is written.The bytes written by this method may be read by the
readUTF
method of interfaceDataInput
which will then return aString
equal tos
. @param str the string value to be written. @exception IOException if an I/O error occurs.
An abstract representation of file and directory pathnames.Class File, int compareTo(File)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:
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.
- An optional system-dependent prefix string such as a disk-drive specifier
"/"
for the UNIX root directory or"\\"
for aWin32Microsoft Windows UNC pathname and- A sequence of zero or more string names.
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 propertyuser.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:
- 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
Win32Microsoft Windows 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 aFile
object will never change. @version 1.102 12110 05/0306/0102 @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; onClass File, boolean createNewFile()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
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.Class File, File createTempFile(String, String, File)ThisNote: this method
inshouldcombinationnotwith thebe used{@linkfor#deleteOnExit}file-lockingmethod can therefore serve as the basis for aas the resulting protocol cannot be made to worksimplereliably.butThereliableFileLockcooperativefacilityfile-lockingshouldprotocolbe used instead. @returntrue
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, void deleteOnExit()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:
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
- The file denoted by the returned abstract pathname did not exist before this method was invoked and
- Neither this method nor any of its variants will return the same abstract pathname again in the current invocation of the virtual machine.
{@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"
. Thesuffix
argument may benull
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 isnull
then the system-dependent default temporary-file directory will be used. The default temporary-file directory is specified by the system propertyjava.io.tmpdir
. On UNIX systems the default value of this property is typically"/tmp"
or"/var/tmp"
; onWin32Microsoft 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 benull
in which case the suffix".tmp"
will be used @param directory The directory in which the file is to be created ornull
if the default temporary-file directory is to be used @return An abstract pathname denoting a newly-created empty file @throws IllegalArgumentException If theprefix
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
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 SpecificationClass File, boolean equals(Object)(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
Tests this abstract pathname for equality with the given object. ReturnsClass File, String getAbsolutePath()true
if and only if the argument is notnull
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; onWin32Microsoft Windows systems it is not. @param obj The object to be compared with this abstract pathname @returntrue
if and only if the objects are the same;false
otherwise
Returns the absolute pathname string of this abstract pathname.Class File, String getCanonicalPath()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 propertyuser.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. OnWin32Microsoft 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()
Returns the canonical pathname string of this abstract pathname.Class File, int hashCode()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
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 valueClass File, boolean isAbsolute()1234321
. OnWin32Microsoft Windows systems the hash code is equal to the exclusive or of its pathname string convered to lower case and the decimal value1234321
. @return A hash code for this abstract pathname
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 isClass File, boolean isHidden()"/"
. OnWin32Microsoft Windows systems a pathname is absolute if its prefix is a drive specifier followed by"\\"
or if its prefix is"\\"
. @returntrue
if this abstract pathname is absolutefalse
otherwise
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 (Class File, boolean renameTo(File)'.'
). OnWin32Microsoft Windows systems a file is considered to be hidden if it has been marked as such in the filesystem. @returntrue
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
Renames the file denoted by this abstract pathname.Class File, char pathSeparatorCharWhether 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 parameterdest
isnull
The system-dependent path-separator character. This field is initialized to contain the first character of the value of the system propertyClass File, char separatorCharpath.separator
. This character is used to separate filenames in a sequence of files given as a path list. On UNIX systems this character is':'
; onWin32Microsoft Windows systems it is';'
. @see java.lang.System#getProperty(java.lang.String)
The system-dependent default name-separator character. This field is initialized to contain the first character of the value of the system propertyfile.separator
. On UNIX systems the value of this field is'/'
; onWin32Microsoft Windows systems it is'\'
. @see java.lang.System#getProperty(java.lang.String)
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.
class. @since 1.2FileFilterFile}
AFileInputStream
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 usingFileReader
. @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
A file output stream is an output stream for writing data to aFile
or to aFileDescriptor
. 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 usingFileWriter
. @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
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.Class FileReader, constructor FileReader(File)
FileReader
is meant for reading streams of characters. For reading streams of raw bytes consider using aFileInputStream
. @see InputStreamReader @see FileInputStream @version 1.12 0113 02/1202/0306 @author Mark Reinhold @since JDK1.1
Creates a new FileReader given the File to read from. @param file the File to read from @Class FileReader, constructor FileReader(String)throwsexception FileNotFoundException if thespecifiedfileisdoes notfoundexist is a directory rather than a regular file or for some other reason cannot be opened for reading.
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 thespecifiednamed fileisdoes notfoundexist is a directory rather than a regular file or for some other reason cannot be opened for reading.
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.Class FileWriter, constructor FileWriter(File)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 aFileOutputStream
. @see OutputStreamWriter @see FileOutputStream @version 1.15 0116 02/1202/0306 @author Mark Reinhold @since JDK1.1
Constructs a FileWriter object given a File object. @param file a File object to write to. @throws IOException if theClass FileWriter, constructor FileWriter(File, boolean)specifiedfile exists but is a directory rather than a regular file does notfoundexist but cannot be created orif some othercannot be openedI/Oforerroranyoccurs.other reason
Constructs a FileWriter object given a File object. If the second argument isClass FileWriter, constructor FileWriter(String)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 iftrue
then bytes will be written to the end of the file rather than the beginning @throws IOException if thespecifiedfile exists but is a directory rather than a regular file does notfoundexist but cannot be created orifcannot besome otheropened forI/Oanyerror occursother reason @since 1.4
Constructs a FileWriter object given a file name. @param fileName String The system-dependent filename. @throws IOException if theClass FileWriter, constructor FileWriter(String, boolean)specifiednamed file exists but is a directory rather than a regular file does notfoundexist but cannot be created orif some othercannot be openedI/Oforerroranyoccurs.other reason
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 iftrue
then data will be written to the end of the file rather than the beginning. @throws IOException if thespecifiednamed file exists but is a directory rather than a regular file does notfoundexist but cannot be created orif some othercannot be openedI/Oforerroranyoccurs.other reason
An ObjectInputStream deserializes primitive data and objects previously written using an ObjectOutputStream.Class ObjectInputStream, constructor ObjectInputStream(InputStream)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:
FileInputStreamistreamfis = new FileInputStream("t.tmp"); ObjectInputStreampois = new ObjectInputStream(istreamfis); int i =pois.readInt(); String today = (String)pois.readObject(); Date date = (Date)pois.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.
1361420102/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
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.Class ObjectInputStream, String readUTF()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
isnull
@see ObjectInputStream#ObjectInputStream() @see ObjectInputStream#readFields() @see ObjectOutputStream#ObjectOutputStream(OutputStream)
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.Class ObjectInputStream, Class resolveProxyClass(String[])The corresponding method in
ObjectOutputStream
isannotateClass
. 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 aClass
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 classObjectStreamClass
@return aClass
object corresponding to@throws IOException
vdescAnyany of the usualInputinput/Outputoutput exceptions.@throws ClassNotFoundExceptionIfif class of a serialized object cannot be found.
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
isannotateProxyClass
. For a given subclass ofObjectInputStream
that overrides this method theannotateProxyClass
method in the corresponding subclass ofObjectOutputStream
must write any data or objects read by this method.The default implementation of this method in
ObjectInputStream
returns the result of callingProxy.getProxyClass
with the list ofClass
objects for the interfaces that are named in theinterfaces
parameter. TheClass
object for each interface namei
is the value returned by callingClass.forName(i false loader)whereloader
is that of the first non-null
class loader up the execution stack ornull
if no non-null
class loaders are on the stack (the same class loader choice used by theresolveClass
method). Unless any of the resolved interfaces are non-public this same value ofloader
is also the class loader passed toProxy.getProxyClass
; if non-public interfaces are present their class loader is passed instead (if more than one non-public interface class loader is encountered anIllegalAccessError
is thrown). IfProxy.getProxyClass
throws anIllegalArgumentException
resolveProxyClass
will throw aClassNotFoundException
containing theIllegalArgumentException
. @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 underlyingInputStream
@throws ClassNotFoundException if the proxy class or any of the named interfaces could not be found @see ObjectOutputStream#annotateProxyClass(Class) @since 1.3
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.Class ObjectOutputStream, constructor ObjectOutputStream(OutputStream)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:
FileOutputStreamostreamfos = new FileOutputStream("t.tmp"); ObjectOutputStreampoos = 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 IOExceptionThe 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
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
isnull
@see ObjectOutputStream#ObjectOutputStream() @see ObjectOutputStream#putFields() @see ObjectInputStream#ObjectInputStream(InputStream)
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 thegetFilePointer
method and set by theseek
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 ofIOException
) is thrown. If any byte cannot be read for any reason other than end-of-file anIOException
other thanEOFException
is thrown. In particular anIOException
may be thrown if the stream has been closed. @author unascribed @version 1.67 1268 02/0306/0102 @since JDK1.0
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.Class SerializablePermission, constructor SerializablePermission(String, String)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.
@see java.security.BasicPermission @see java.security.Permission @see java.security.Permissions @see java.security.PermissionCollection @see java.lang.SecurityManager @version 1.
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. 14 1215 02/03/01/02 @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
TheClass StreamTokenizer, void commentChar(int)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 valueTT_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
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.Class StreamTokenizer, void quoteChar(int)Any other attribute settings for the specified character are cleared. @param ch the character.
Specifies that matching pairs of this character delimit string constants in this tokenizer.Class StreamTokenizer, String toString()When the
nextToken
method encounters a string constant thettype
field is set to the string delimiter and thesval
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
Returns the string representation of the current stream token and the line number it occurs on.Class StreamTokenizer, void whitespaceChars(int, int)@returnThe
aprecise stringrepresentationreturnedofis unspecified although thetoken specified by thefollowing example can bettypeconsiderednvaltypical:and@return a string representation of the token @see java.io.StreamTokenizer#nval @see java.io.StreamTokenizer#sval @see java.io.StreamTokenizer#ttypeToken['a']svallinefields.10
Specifies that all characters c in the rangelow <= 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.