java.io
Class ObjectOutputStream
java.lang.Object
|
+--java.io.OutputStream
|
+--java.io.ObjectOutputStream
All Implemented Interfaces:
ObjectOutput, ObjectStreamConstants
An
ObjectOutputStream
can be used to write objects
as well as primitive data in a platform-independent manner to an
OutputStream
.
The data produced by an
ObjectOutputStream
can be read
and reconstituted by an
ObjectInputStream
.
writeObject (Object)
is used to write Objects, the
write<type>
methods are used to write primitive
data (as in
DataOutputStream
). Strings can be written
as objects or as primitive data.
Not all objects can be written out using an
ObjectOutputStream
. Only those objects that are an
instance of
java.io.Serializable
can be written.
Using default serialization, information about the class of an
object is written, all of the non-transient, non-static fields of
the object are written, if any of these fields are objects, they are
written out in the same manner.
An object is only written out the first time it is encountered. If
the object is encountered later, a reference to it is written to
the underlying stream. Thus writing circular object graphs
does not present a problem, nor are relationships between objects
in a graph lost.
Example usage:
Hashtable map = new Hashtable ();
map.put ("one", new Integer (1));
map.put ("two", new Integer (2));
ObjectOutputStream oos =
new ObjectOutputStream (new FileOutputStream ("numbers"));
oos.writeObject (map);
oos.close ();
ObjectInputStream ois =
new ObjectInputStream (new FileInputStream ("numbers"));
Hashtable newmap = (Hashtable)ois.readObject ();
System.out.println (newmap);
The default serialization can be overriden in two ways.
By defining a method
private void
writeObject (ObjectOutputStream)
, a class can dictate exactly
how information about itself is written.
defaultWriteObject ()
may be called from this method to
carry out default serialization. This method is not
responsible for dealing with fields of super-classes or subclasses.
By implementing
java.io.Externalizable
. This gives
the class complete control over the way it is written to the
stream. If this approach is used the burden of writing superclass
and subclass data is transfered to the class implementing
java.io.Externalizable
.
See Also:
ObjectOutputStream
protected ObjectOutputStream()
Protected constructor that allows subclasses to override
serialization. This constructor should be called by subclasses
that wish to override writeObject (Object)
. This
method does a security check NOTE: currently not
implemented, then sets a flag that informs
writeObject (Object)
to call the subclasses
writeObjectOverride (Object)
method.
See Also:
ObjectOutputStream
public ObjectOutputStream(java.io.OutputStream out)
Creates a new ObjectOutputStream
that will do all of
its writing onto out
. This method also initializes
the stream by writing the header information (stream magic number
and stream version).
Parameters:
Throws:
IOException
- Writing stream header to underlying
stream cannot be completed.
See Also:
annotateClass
protected void annotateClass(Class cl)
An empty hook that allows subclasses to write extra information
about classes to the stream. This method is called the first
time each class is seen, and after all of the standard
information about the class has been written.
Parameters:
Throws:
See Also:
annotateProxyClass
protected void annotateProxyClass(Class cl)
Parameters:
close
public void close()
See Also:
defaultWriteObject
public void defaultWriteObject()
Writes the current objects non-transient, non-static fields from
the current class to the underlying output stream.
This method is intended to be called from within a object's
private void writeObject (ObjectOutputStream)
method.
Throws:
NotActiveException
- This method was called from a
context other than from the current object's and current class's
private void writeObject (ObjectOutputStream)
method.IOException
- Exception from underlying
OutputStream
.
drain
protected void drain()
Causes the block-data buffer to be written to the underlying
stream, but does not flush underlying stream.
Throws:
enableReplaceObject
protected boolean enableReplaceObject(boolean enable)
If enable
is true
and this object is
trusted, then replaceObject (Object)
will be called
in subsequent calls to writeObject (Object)
.
Otherwise, replaceObject (Object)
will not be called.
Parameters:
Throws:
flush
public void flush()
See Also:
putFields
public ObjectOutputStream.PutField putFields()
replaceObject
protected Object replaceObject(java.lang.Object obj)
Allows subclasses to replace objects that are written to the
stream with other objects to be written in their place. This
method is called the first time each object is encountered
(modulo reseting of the stream).
This method must be enabled before it will be called in the
serialization process.
Parameters:
Throws:
See Also:
reset
public void reset()
Resets stream to state equivalent to the state just after it was
constructed.
Causes all objects previously written to the stream to be
forgotten. A notification of this reset is also written to the
underlying stream.
Throws:
IOException
- Exception from underlying
OutputStream
or reset called while serialization is
in progress.
setDefaultProtocolVersion
public static void setDefaultProtocolVersion(int version)
GNU $classpath specific
Changes the default stream protocol used by all
ObjectOutputStream
s. There are currently two
different protocols, specified by PROTOCOL_VERSION_1
and PROTOCOL_VERSION_2
. The default default is
PROTOCOL_VERSION_1
.
Parameters:
Throws:
See Also:
useProtocolVersion
public void useProtocolVersion(int version)
Informs this ObjectOutputStream
to write data
according to the specified protocol. There are currently two
different protocols, specified by PROTOCOL_VERSION_1
and PROTOCOL_VERSION_2
. This implementation writes
data using PROTOCOL_VERSION_1
by default, as is done
by the JDK 1.1.
A non-portable method, setDefaultProtocolVersion (int
version)
is provided to change the default protocol
version.
For an explination of the differences beween the two protocols
see XXX: the Java ObjectSerialization Specification.
Parameters:
Throws:
See Also:
write
public void write(byte[] b)
Parameters:
See Also:
write
public void write(byte[] b, int off, int len)
Parameters:
See Also:
write
public void write(int data)
Parameters:
See Also:
writeBoolean
public void writeBoolean(boolean data)
Parameters:
See Also:
writeByte
public void writeByte(int data)
Parameters:
See Also:
writeBytes
public void writeBytes(java.lang.String data)
Parameters:
See Also:
writeChar
public void writeChar(int data)
Parameters:
See Also:
writeChars
public void writeChars(java.lang.String data)
Parameters:
See Also:
writeDouble
public void writeDouble(double data)
Parameters:
See Also:
writeFields
public void writeFields()
writeFloat
public void writeFloat(float data)
Parameters:
See Also:
writeInt
public void writeInt(int data)
Parameters:
See Also:
writeLong
public void writeLong(long data)
Parameters:
See Also:
writeObject
public final void writeObject(java.lang.Object obj)
Writes a representation of obj
to the underlying
output stream by writing out information about its class, then
writing out each of the objects non-transient, non-static
fields. If any of these fields are other objects,
they are written out in the same manner.
This method can be overriden by a class by implementing
private void writeObject (ObjectOutputStream)
.
If an exception is thrown from this method, the stream is left in
an undefined state.
Parameters:
Throws:
writeObjectOverride
protected void writeObjectOverride(java.lang.Object obj)
This method allows subclasses to override the default
serialization mechanism provided by
ObjectOutputStream
. To make this method be used for
writing objects, subclasses must invoke the 0-argument
constructor on this class from there constructor.
Parameters:
Throws:
NotActiveException
- Subclass has arranged for this
method to be called, but did not implement this method.
See Also:
writeShort
public void writeShort(int data)
Parameters:
See Also:
writeStreamHeader
protected void writeStreamHeader()
Writes stream magic and stream version information to the
underlying stream.
Throws:
writeUTF
public void writeUTF(java.lang.String data)
Parameters:
See Also:
ObjectOutputStream
can be used to write objects as well as primitive data in a platform-independent manner to anOutputStream
. The data produced by anObjectOutputStream
can be read and reconstituted by anObjectInputStream
.writeObject (Object)
is used to write Objects, thewrite<type>
methods are used to write primitive data (as inDataOutputStream
). Strings can be written as objects or as primitive data. Not all objects can be written out using anObjectOutputStream
. Only those objects that are an instance ofjava.io.Serializable
can be written. Using default serialization, information about the class of an object is written, all of the non-transient, non-static fields of the object are written, if any of these fields are objects, they are written out in the same manner. An object is only written out the first time it is encountered. If the object is encountered later, a reference to it is written to the underlying stream. Thus writing circular object graphs does not present a problem, nor are relationships between objects in a graph lost. Example usage: The default serialization can be overriden in two ways. By defining a methodprivate void writeObject (ObjectOutputStream)
, a class can dictate exactly how information about itself is written.defaultWriteObject ()
may be called from this method to carry out default serialization. This method is not responsible for dealing with fields of super-classes or subclasses. By implementingjava.io.Externalizable
. This gives the class complete control over the way it is written to the stream. If this approach is used the burden of writing superclass and subclass data is transfered to the class implementingjava.io.Externalizable
.