java.io
Class ObjectOutputStream
- Closeable, DataOutput, Flushable, 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.
static class | ObjectOutputStream.PutField- This class allows a class to specify exactly which fields should
be written, and what values should be written for these fields.
|
PROTOCOL_VERSION_1, PROTOCOL_VERSION_2, SC_BLOCK_DATA, SC_ENUM, SC_EXTERNALIZABLE, SC_SERIALIZABLE, SC_WRITE_METHOD, STREAM_MAGIC, STREAM_VERSION, SUBCLASS_IMPLEMENTATION_PERMISSION, SUBSTITUTION_PERMISSION, TC_ARRAY, TC_BASE, TC_BLOCKDATA, TC_BLOCKDATALONG, TC_CLASS, TC_CLASSDESC, TC_ENDBLOCKDATA, TC_ENUM, TC_EXCEPTION, TC_LONGSTRING, TC_MAX, TC_NULL, TC_OBJECT, TC_PROXYCLASSDESC, TC_REFERENCE, TC_RESET, TC_STRING, baseWireHandle |
clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait |
ObjectOutputStream
protected ObjectOutputStream()
throws IOException,
SecurityException 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.
ObjectOutputStream
public ObjectOutputStream(OutputStream out)
throws IOException 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).
IOException - Writing stream header to underlying
stream cannot be completed.
annotateClass
protected void annotateClass(Class cl)
throws IOException 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.
defaultWriteObject
public void defaultWriteObject()
throws IOException,
NotActiveException 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.
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()
throws IOException Causes the block-data buffer to be written to the underlying
stream, but does not flush underlying stream.
enableReplaceObject
protected boolean enableReplaceObject(boolean enable)
throws SecurityException 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.
replaceObject
protected Object replaceObject(Object obj)
throws IOException 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.
reset
public void reset()
throws IOException 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.
IOException - Exception from underlying
OutputStream or reset called while serialization is
in progress.
useProtocolVersion
public void useProtocolVersion(int version)
throws IOException 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_2 by default, as is done
since the JDK 1.2.
For an explanation of the differences between the two protocols
see the Java Object Serialization Specification.
version - the version to use.
writeObject
public final void writeObject(Object obj)
throws IOException 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.
- writeObject in interface ObjectOutput
obj - the object to serialize.
writeObjectOverride
protected void writeObjectOverride(Object obj)
throws NotActiveException,
IOException 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.
NotActiveException - Subclass has arranged for this
method to be called, but did not implement this method.
writeStreamHeader
protected void writeStreamHeader()
throws IOException Writes stream magic and stream version information to the
underlying stream.
writeUnshared
public void writeUnshared(Object obj)
throws IOException Writes an object to the stream in the same manner as
writeObject(Object), but without the use of
references. As a result, the object is always written
to the stream in full. Likewise, if an object is written
by this method and is then later written again by
writeObject(Object), both calls will write out
the object in full, as the later call to
writeObject(Object) will know nothing of the
earlier use of
writeUnshared(Object).
obj - the object to serialize.
IOException - if an I/O error occurs on the underlying
OutputStream.
ObjectOutputStream.java -- Class used to write serialized objects
Copyright (C) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006
Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version.