A BufferedInputStream adds
functionality to another input stream-namely,
the ability to buffer the input and to
support the mark and reset
methods. When  the BufferedInputStream
is created, an internal buffer array is
created. As bytes  from the stream are read
or skipped, the internal buffer is refilled
as necessary  from the contained input stream,
many bytes at a time. The mark
operation  remembers a point in the input
stream and the reset operation
causes all the  bytes read since the most
recent mark operation to be
reread before new bytes are  taken from
the contained input stream.

The class implements a buffered output stream. By setting up such
an output stream, an application can write bytes to the underlying
output stream without necessarily causing a call to the underlying
system for each byte written.

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

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

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



BufferedReader in
  = new BufferedReader(new FileReader("foo.in"));

will buffer the input from the specified file.  Without buffering, each
invocation of read() or readLine() could cause bytes to be read from the
file, converted into characters, and then returned, which can be very
inefficient.

 Programs that use DataInputStreams for textual input can be localized by
replacing each DataInputStream with an appropriate BufferedReader.

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

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

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

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



PrintWriter out
  = new PrintWriter(new BufferedWriter(new FileWriter("foo.out")));

will buffer the PrintWriter's output to the file.  Without buffering, each
invocation of a print() method would cause characters to be converted into
bytes that would then be written immediately to the file, which can be very
inefficient.

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

Closing a ByteArrayInputStream has no effect. The methods in
this class can be called after the stream has been closed without
generating an IOException.

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

Closing a ByteArrayOutputStream has no effect. The methods in
this class can be called after the stream has been closed without
generating an IOException.

This class implements a character buffer that can be used as a
character-input stream.

This class implements a character buffer that can be used as an Writer.
The buffer automatically grows when data is written to the stream.  The data
can be retrieved using toCharArray() and toString().

Note: Invoking close() on this class has no effect, and methods
of this class can be called after the stream has closed
without generating an IOException.

Base class for character conversion exceptions.

A Closeable is a source or destination of data that can be closed.
The close method is invoked to release resources that the object is
holding (such as open files).

Methods to access the character-based console device, if any, associated
with the current Java virtual machine.

 Whether a virtual machine has a console is dependent upon the
underlying platform and also upon the manner in which the virtual
machine is invoked.  If the virtual machine is started from an
interactive command line without redirecting the standard input and
output streams then its console will exist and will typically be
connected to the keyboard and display from which the virtual machine
was launched.  If the virtual machine is started automatically, for
example by a background job scheduler, then it will typically not
have a console.

If this virtual machine has a console then it is represented by a
unique instance of this class which can be obtained by invoking the
System.console() method.  If no console device is
available then an invocation of that method will return null.

Read and write operations are synchronized to guarantee the atomic
completion of critical operations; therefore invoking methods
readLine(), readPassword(), format(),
printf() as well as the read, format and write operations
on the objects returned by reader() and writer() may
block in multithreaded scenarios.

Invoking close() on the objects returned by the reader()
and the writer() will not close the underlying stream of those
objects.

The console-read methods return null when the end of the
console input stream is reached, for example by typing control-D on
Unix or control-Z on Windows.  Subsequent read operations will succeed
if additional characters are later entered on the console's input
device.

Unless otherwise specified, passing a null argument to any method
in this class will cause a NullPointerException to be thrown.

Security note:
If an application needs to read a password or other secure data, it should
use readPassword() or readPassword(String, Object...) and
manually zero the returned character array after processing to minimize the
lifetime of sensitive data in memory.



Console cons;
char[] passwd;
if ((cons = System.console()) != null &&
    (passwd = cons.readPassword("[%s]", "Password:")) != null) {
    ...
    java.util.Arrays.fill(passwd, ' ');
}

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



  Bit Values


  Byte 1
  0
  bits 6-0



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



  Bit Values


  Byte 1
  1
  1
  0
  bits 10-6


  Byte 2
  1
  0
  bits 5-0



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



  Bit Values


  Byte 1
  1
  1
  1
  0
  bits 15-12


  Byte 2
  1
  0
  bits 11-6


  Byte 3
  1
  0
  bits 5-0

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

It is generally true of all the reading
routines in this interface that if end of
file is reached before the desired number
of bytes has been read, an EOFException
(which is a kind of IOException)
is thrown. If any byte cannot be read for
any reason other than end of file, an IOException
other than EOFException is
thrown. In particular, an IOException
may be thrown if the input stream has been
closed.

Modified UTF-8

Implementations of the DataInput and DataOutput interfaces represent
Unicode strings in a format that is a slight modification of UTF-8.
(For information regarding the standard UTF-8 format, see section
3.9 Unicode Encoding Forms of The Unicode Standard, Version
4.0).
Note that in the following table, 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:



      Bit Values


      Byte 1
      0
      bits 6-0



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



      Bit Values


      Byte 1
      1
      1
      0
      bits 10-6


      Byte 2
      1
      0
      bits 5-0



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



      Bit Values


      Byte 1
      1
      1
      1
      0
      bits 15-12


      Byte 2
      1
      0
      bits 11-6


      Byte 3
      1
      0
      bits 5-0




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

The null byte '\u0000' is encoded in 2-byte format
    rather than 1-byte, so that the encoded strings never have
    embedded nulls.
Only the 1-byte, 2-byte, and 3-byte formats are used.
Supplementary characters
    are represented in the form of surrogate pairs.

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.

DataInputStream is not necessarily safe for multithreaded access.
Thread safety is optional and is the responsibility of users of
methods in this class.

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

A data output stream lets an application write primitive Java data
types to an output stream in a portable way. An application can
then use a data input stream to read the data back in.

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

This exception is mainly used by data input streams to signal end of
stream. Note that many other input operations return a special value on
end of stream rather than throwing an exception.

Only the identity of the class of an Externalizable instance is
written in the serialization stream and it is the responsibility
of the class to save and restore the contents of its instances.

The writeExternal and readExternal methods of the Externalizable
interface are implemented by a class to give the class complete
control over the format and contents of the stream for an object
and its supertypes. These methods must explicitly
coordinate with the supertype to save its state. These methods supersede
customized implementations of writeObject and readObject methods.

Object Serialization uses the Serializable and Externalizable
interfaces.  Object persistence mechanisms can use them as well.  Each
object to be stored is tested for the Externalizable interface. If
the object supports Externalizable, the writeExternal method is called. If the
object does not support Externalizable and does implement
Serializable, the object is saved using
ObjectOutputStream.  When an Externalizable object is
reconstructed, an instance is created using the public no-arg
constructor, then the readExternal method called.  Serializable
objects are restored by reading them from an ObjectInputStream.

An Externalizable instance can designate a substitution object via
the writeReplace and readResolve methods documented in the Serializable
interface.

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:


 An optional system-dependent prefix string,
     such as a disk-drive specifier, "/" for the UNIX root
     directory, or "\\\\" for a Microsoft Windows UNC pathname, and
 A sequence of zero or more string names.


The first name in an abstract pathname may be a directory name or, in the
case of Microsoft Windows UNC pathnames, a hostname.  Each subsequent name
in an abstract pathname 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 separator and 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 parent of an abstract pathname may be obtained by invoking
the getParent() method of this class and consists of the pathname's
prefix and each name in the pathname's name sequence except for the last.
Each directory's absolute pathname is an ancestor of any File
object with an absolute abstract pathname which begins with the directory's
absolute pathname.  For example, the directory denoted by the abstract
pathname "/usr" is an ancestor of the directory denoted by the
pathname "/usr/local/bin".

 The prefix concept is used to handle root directories on UNIX platforms,
and drive specifiers, root directories and UNC pathnames on Microsoft 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 Microsoft 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 this class may or may not denote an actual file-system
object such as a file or a directory.  If it does denote such an object
then that object resides in a partition.  A partition is an
operating system-specific portion of storage for a file system.  A single
storage device (e.g. a physical disk-drive, flash memory, CD-ROM) may
contain multiple partitions.  The object, if any, will reside on the
partition named by some ancestor of the absolute
form of this pathname.

 A file system may implement restrictions to certain operations on the
actual file-system object, such as reading, writing, and executing.  These
restrictions are collectively known as access permissions.  The file
system may have multiple sets of access permissions on a single object.
For example, one set may apply to the object's owner, and another
may apply to all other users.  The access permissions on an object may
cause some methods in this class to fail.

 Instances of the File class are immutable; that is, once
created, the abstract pathname represented by a File object
will never change.

Interoperability with java.nio.file package

 The java.nio.file
package defines interfaces and classes for the Java virtual machine to access
files, file attributes, and file systems. This API may be used to overcome
many of the limitations of the java.io.File class.
The toPath method may be used to obtain a Path that uses the abstract path represented by a File object to
locate a file. The resulting Path may be used with the Files class to provide more efficient and extensive access to
additional file operations, file attributes, and I/O exceptions to help
diagnose errors when an operation on a file fails.

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

Applications should not create their own file descriptors.

A filter for abstract pathnames.

 Instances of this interface may be passed to the listFiles(FileFilter) method
of the File class.

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.

Instances of classes that implement this interface are used to
filter filenames. These instances are used to filter directory
listings in the list method of class
File, and by the Abstract Window Toolkit's file
dialog component.

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

 This exception will be thrown by the FileInputStream, FileOutputStream, and RandomAccessFile constructors when a file
with the specified pathname does not exist.  It will also be thrown by these
constructors if the file does exist but for some reason is inaccessible, for
example when an attempt is made to open a read-only file for writing.

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.

read  read permission
write  write permission
execute
execute permission. Allows Runtime.exec to
    be called. Corresponds to SecurityManager.checkExec.
delete
delete permission. Allows File.delete to
    be called. Corresponds to SecurityManager.checkDelete.
readlink
read link permission. Allows the target of a
    symbolic link
    to be read by invoking the readSymbolicLink  method.

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

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

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

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


    read  read permission
    write  write permission
    execute
    execute permission. Allows Runtime.exec to
        be called. Corresponds to SecurityManager.checkExec.
    delete
    delete permission. Allows File.delete to
        be called. Corresponds to SecurityManager.checkDelete.
    readlink
    read link permission. Allows the target of a
        symbolic link
        to be read by invoking the readSymbolicLink  method.


The actions string is converted to lowercase before processing.

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

Please note: Code can always read a file from the same
directory it's in (or a subdirectory of that directory); it does not
need explicit permission to do so.

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.

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.

A FilterInputStream contains
some other input stream, which it uses as
its  basic source of data, possibly transforming
the data along the way or providing  additional
functionality. The class FilterInputStream
itself simply overrides all  methods of
InputStream with versions that
pass all requests to the contained  input
stream. Subclasses of FilterInputStream
may further override some of  these methods
and may also provide additional methods
and fields.

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

The class FilterOutputStream itself simply overrides
all methods of OutputStream with versions that pass
all requests to the underlying output stream. Subclasses of
FilterOutputStream may further override some of these
methods as well as provide additional methods and fields.

Abstract class for reading filtered character streams.
The abstract class FilterReader itself
provides default methods that pass all requests to
the contained stream. Subclasses of FilterReader
should override some of these methods and may also provide
additional methods and fields.

Abstract class for writing filtered character streams.
The abstract class FilterWriter itself
provides default methods that pass all requests to the
contained stream. Subclasses of FilterWriter
should override some of these methods and may also
provide additional methods and fields.

A Flushable is a destination of data that can be flushed.  The
flush method is invoked to write any buffered output to the underlying
stream.

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

 Applications that need to define a subclass of InputStream
must always provide a method that returns the next byte of input.

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

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

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



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

Signals that an I/O operation has been interrupted. An
InterruptedIOException is thrown to indicate that an
input or output transfer has been terminated because the thread
performing it was interrupted. The field bytesTransferred
indicates how many bytes were successfully transferred before
the interruption occurred.

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

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

Indicates that one or more deserialized objects failed validation
tests.  The argument should provide the reason for the failure.

Thrown when a serious I/O error has occurred.

Signals that an I/O exception of some sort has occurred. This
class is the general class of exceptions produced by failed or
interrupted I/O operations.

Deprecated.
This class incorrectly assumes that bytes adequately represent
             characters.  As of JDK 1.1, the preferred way to operate on
             character streams is via the new character-stream classes, which
             include a class for counting line numbers.

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

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

 A line is considered to be terminated by any one of a
line feed ('\n'), a carriage return ('\r'), or a carriage return followed
immediately by a linefeed.

Thrown when serialization or deserialization is not active.

Thrown when an instance is required to have a Serializable interface.
The serialization runtime or the class of the instance can throw
this exception. The argument should be the name of the class.

ObjectInput extends the DataInput interface to include the reading of
objects. DataInput includes methods for the input of primitive types,
ObjectInput extends that interface to include objects, arrays, and Strings.

 FileInputStream fis = new FileInputStream("t.tmp");
 ObjectInputStream ois = new ObjectInputStream(fis);

 int i = ois.readInt();
 String today = (String) ois.readObject();
 Date date = (Date) ois.readObject();

 ois.close();

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 fis = new FileInputStream("t.tmp");
     ObjectInputStream ois = new ObjectInputStream(fis);

     int i = ois.readInt();
     String today = (String) ois.readObject();
     Date date = (Date) ois.readObject();

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

Enum constants are deserialized differently than ordinary serializable or
externalizable objects.  The serialized form of an enum constant consists
solely of its name; field values of the constant are not transmitted.  To
deserialize an enum constant, ObjectInputStream reads the constant name from
the stream; the deserialized constant is then obtained by calling the static
method Enum.valueOf(Class, String) with the enum constant's
base type and the received constant name as arguments.  Like other
serializable or externalizable objects, enum constants can function as the
targets of back references appearing subsequently in the serialization
stream.  The process by which enum constants are deserialized cannot be
customized: any class-specific readObject, readObjectNoData, and readResolve
methods defined by enum types are ignored during deserialization.
Similarly, any serialPersistentFields or serialVersionUID field declarations
are also ignored--all enum types have a fixed serialVersionUID of 0L.

Provide access to the persistent fields read from the input stream.

Callback interface to allow validation of objects within a graph.
Allows an object to be called when a complete graph of objects has
been deserialized.

ObjectOutput extends the DataOutput interface to include writing of objects.
DataOutput includes methods for output of primitive types, ObjectOutput
extends that interface to include objects, arrays, and Strings.

 FileOutputStream fos = new FileOutputStream("t.tmp");
 ObjectOutputStream oos = new ObjectOutputStream(fos);

 oos.writeInt(12345);
 oos.writeObject("Today");
 oos.writeObject(new Date());

 oos.close();

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 reconstituted 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 fos = new FileOutputStream("t.tmp");
     ObjectOutputStream oos = new ObjectOutputStream(fos);

     oos.writeInt(12345);
     oos.writeObject("Today");
     oos.writeObject(new Date());

     oos.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
private void readObjectNoData()
    throws ObjectStreamException;

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.

Enum constants are serialized differently than ordinary serializable or
externalizable objects.  The serialized form of an enum constant consists
solely of its name; field values of the constant are not transmitted.  To
serialize an enum constant, ObjectOutputStream writes the string returned by
the constant's name method.  Like other serializable or externalizable
objects, enum constants can function as the targets of back references
appearing subsequently in the serialization stream.  The process by which
enum constants are serialized cannot be customized; any class-specific
writeObject and writeReplace methods defined by enum types are ignored
during serialization.  Similarly, any serialPersistentFields or
serialVersionUID field declarations are also ignored--all enum types have a
fixed serialVersionUID of 0L.

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.

Provide programmatic access to the persistent fields to be written
to ObjectOutput.

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

The algorithm to compute the SerialVersionUID is described in
Object
Serialization Specification, Section 4.6, Stream Unique Identifiers.

Constants written into the Object Serialization Stream.

Superclass of all exceptions specific to Object Stream classes.

A description of a Serializable field from a Serializable class.  An array
of ObjectStreamFields is used to declare the Serializable fields of a class.

Exception indicating the failure of an object read operation due to
unread primitive data, or the end of data belonging to a serialized
object in the stream.  This exception may be thrown in two cases:


  An attempt was made to read an object when the next element in the
      stream is primitive data.  In this case, the OptionalDataException's
      length field is set to the number of bytes of primitive data
      immediately readable from the stream, and the eof field is set to
      false.

  An attempt was made to read past the end of data consumable by a
      class-defined readObject or readExternal method.  In this case, the
      OptionalDataException's eof field is set to true, and the length field
      is set to 0.

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

Applications that need to define a subclass of
OutputStream must always provide at least a method
that writes one byte of output.

An OutputStreamWriter is a bridge from character streams to byte streams:
Characters written to it are encoded into bytes using a specified charset.  The charset that it uses
may be specified by name or may be given explicitly, or the platform's
default charset may be accepted.

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

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



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

 A surrogate pair is a character represented by a sequence of two
char values: A high surrogate in the range '\uD800' to
'\uDBFF' followed by a low surrogate in the range '\uDC00' to
'\uDFFF'.

 A malformed surrogate element is a high surrogate that is not
followed by a low surrogate or a low surrogate that is not preceded by a
high surrogate.

 This class always replaces malformed surrogate elements and unmappable
character sequences with the charset's default substitution sequence.
The java.nio.charset.CharsetEncoder class should be used when more
control over the encoding process is required.

A piped input stream should be connected
to a piped output stream; the piped  input
stream then provides whatever data bytes
are written to the piped output  stream.
Typically, data is read from a PipedInputStream
object by one thread  and data is written
to the corresponding PipedOutputStream
by some  other thread. Attempting to use
both objects from a single thread is not
recommended, as it may deadlock the thread.
The piped input stream contains a buffer,
decoupling read operations from write operations,
within limits.
A pipe is said to be  broken  if a
thread that was providing data bytes to the connected
piped output stream is no longer alive.

A piped output stream can be connected to a piped input stream
to create a communications pipe. The piped output stream is the
sending end of the pipe. Typically, data is written to a
PipedOutputStream object by one thread and data is
read from the connected PipedInputStream by some
other thread. Attempting to use both objects from a single thread
is not recommended as it may deadlock the thread.
The pipe is said to be  broken  if a
thread that was reading data bytes from the connected piped input
stream is no longer alive.

Piped character-input streams.

Piped character-output streams.

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

 All characters printed by a PrintStream are converted into
bytes using the platform's default character encoding.  The PrintWriter class should be used in situations that require writing
characters rather than bytes.

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

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

 Methods in this class never throw I/O exceptions, although some of its
constructors may.  The client may inquire as to whether any errors have
occurred by invoking checkError().

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

A character-stream reader that allows characters to be pushed back into the
stream.

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.

Abstract class for reading character streams.  The only methods that a
subclass must implement are read(char[], int, int) and close().  Most
subclasses, however, will override some of the methods defined here in order
to provide higher efficiency, additional functionality, or both.

A SequenceInputStream represents
the logical concatenation of other input
streams. It starts out with an ordered
collection of input streams and reads from
the first one until end of file is reached,
whereupon it reads from the second one,
and so on, until end of file is reached
on the last of the contained input streams.

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

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

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

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

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



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

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

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

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.

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



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

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

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



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

This readResolve method follows the same invocation rules and
accessibility rules as writeReplace.

The serialization runtime associates with each serializable class a version
number, called a serialVersionUID, which is used during deserialization to
verify that the sender and receiver of a serialized object have loaded
classes for that object that are compatible with respect to serialization.
If the receiver has loaded a class for the object that has a different
serialVersionUID than that of the corresponding sender's class, then
deserialization will result in an InvalidClassException.  A
serializable class can declare its own serialVersionUID explicitly by
declaring a field named "serialVersionUID" that must be static,
final, and of type long:



ANY-ACCESS-MODIFIER static final long serialVersionUID = 42L;

If a serializable class does not explicitly declare a serialVersionUID, then
the serialization runtime will calculate a default serialVersionUID value
for that class based on various aspects of the class, as described in the
Java(TM) Object Serialization Specification.  However, it is strongly
recommended that all serializable classes explicitly declare
serialVersionUID values, since the default serialVersionUID computation is
highly sensitive to class details that may vary depending on compiler
implementations, and can thus result in unexpected
InvalidClassExceptions during deserialization.  Therefore, to
guarantee a consistent serialVersionUID value across different java compiler
implementations, a serializable class must declare an explicit
serialVersionUID value.  It is also strongly advised that explicit
serialVersionUID declarations use the private modifier where
possible, since such declarations apply only to the immediately declaring
class--serialVersionUID fields are not useful as inherited members. Array
classes cannot declare an explicit serialVersionUID, so they always have
the default computed value, but the requirement for matching
serialVersionUID values is waived for array classes.

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

Thrown when control information that was read from an object stream
violates internal consistency checks.

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

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

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

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


A typical application first constructs an instance of this class,
sets up the syntax tables, and then repeatedly loops calling the
nextToken method in each iteration of the loop until
it returns the value TT_EOF.

Deprecated.
This class does not properly convert characters into bytes.  As
             of JDK 1.1, the preferred way to create a stream from a
             string is via the StringReader class.

A character stream whose source is a string.

A character stream that collects its output in a string buffer, which can
then be used to construct a string.

Closing a StringWriter has no effect. The methods in this class
can be called after the stream has been closed without generating an
IOException.

Signals that a sync operation has failed.

Wraps an IOException with an unchecked exception.

The Character Encoding is not supported.

Signals that a malformed string in
modified UTF-8
format has been read in a data
input stream or by any class that implements the data input
interface.
See the
DataInput
class description for the format in
which modified UTF-8 strings are read and written.

Signals that one of the ObjectStreamExceptions was thrown during a
write operation.  Thrown during a read operation when one of the
ObjectStreamExceptions was thrown during a write operation.  The
exception that terminated the write can be found in the detail
field. The stream is reset to it's initial state and all references
to objects already deserialized are discarded.

As of release 1.4, this exception has been retrofitted to conform to
the general purpose exception-chaining mechanism.  The "exception causing
the abort" that is provided at construction time and
accessed via the public detail field is now known as the
cause, and may be accessed via the Throwable.getCause()
method, as well as the aforementioned "legacy field."

Abstract class for writing to character streams.  The only methods that a
subclass must implement are write(char[], int, int), flush(), and close().
Most subclasses, however, will override some of the methods defined here in
order to provide higher efficiency, additional functionality, or both.