java.io

Class ObjectOutputStream

Implemented Interfaces:
Closeable, DataOutput, Flushable, ObjectOutput, ObjectStreamConstants

public class ObjectOutputStream
extends OutputStream
implements 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:
DataOutputStream, Externalizable, ObjectInputStream, Serializable

Nested Class Summary

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.

Fields inherited from interface java.io.ObjectStreamConstants

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

Constructor Summary

ObjectOutputStream()
Protected constructor that allows subclasses to override serialization.
ObjectOutputStream(OutputStream out)
Creates a new ObjectOutputStream that will do all of its writing onto out.

Method Summary

protected void
annotateClass(Class cl)
An empty hook that allows subclasses to write extra information about classes to the stream.
protected void
annotateProxyClass(Class cl)
void
close()
void
defaultWriteObject()
Writes the current objects non-transient, non-static fields from the current class to the underlying output stream.
protected void
drain()
Causes the block-data buffer to be written to the underlying stream, but does not flush underlying stream.
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).
void
flush()
ObjectOutputStream.PutField
putFields()
protected Object
replaceObject(Object obj)
Allows subclasses to replace objects that are written to the stream with other objects to be written in their place.
void
reset()
Resets stream to state equivalent to the state just after it was constructed.
void
useProtocolVersion(int version)
Informs this ObjectOutputStream to write data according to the specified protocol.
void
write(byte[] b)
void
write(byte[] b, int off, int len)
void
write(int data)
void
writeBoolean(boolean data)
void
writeByte(int data)
void
writeBytes(String data)
void
writeChar(int data)
void
writeChars(String data)
protected void
writeClassDescriptor(ObjectStreamClass osc)
void
writeDouble(double data)
void
writeFields()
void
writeFloat(float data)
void
writeInt(int data)
void
writeLong(long data)
void
writeObject(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.
protected void
writeObjectOverride(Object obj)
This method allows subclasses to override the default serialization mechanism provided by ObjectOutputStream.
void
writeShort(int data)
protected void
writeStreamHeader()
Writes stream magic and stream version information to the underlying stream.
void
writeUTF(String data)
void
writeUnshared(Object obj)
Writes an object to the stream in the same manner as writeObject(Object), but without the use of references.

Methods inherited from class java.io.OutputStream

close, flush, write, write, write

Methods inherited from class java.lang.Object

clone, equals, extends Object> getClass, finalize, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

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).
Throws:
IOException - Writing stream header to underlying stream cannot be completed.

Method Details

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.
Throws:
IOException - Exception from underlying OutputStream.

annotateProxyClass

protected void annotateProxyClass(Class cl)
            throws IOException

close

public void close()
            throws IOException
Specified by:
close in interface ObjectOutput
close in interface Closeable
Overrides:
close in interface OutputStream
See Also:
()

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.
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()
            throws IOException
Causes the block-data buffer to be written to the underlying stream, but does not flush underlying stream.
Throws:
IOException - Exception from underlying OutputStream.

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.
Throws:
SecurityException - This class is not trusted.

flush

public void flush()
            throws IOException
Specified by:
flush in interface ObjectOutput
flush in interface Flushable
Overrides:
flush in interface OutputStream

putFields

public ObjectOutputStream.PutField putFields()
            throws IOException

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.
Throws:
IOException - Exception from underlying OutputStream.

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

Parameters:
version - the version to use.
Throws:
IllegalArgumentException - if version is not a valid protocol.
IllegalStateException - if called after the first the first object was serialized.
IOException - if an I/O error occurs.
Since:
1.2

write

public void write(byte[] b)
            throws IOException
Specified by:
write in interface ObjectOutput
write in interface DataOutput
Overrides:
write in interface OutputStream

write

public void write(byte[] b,
                  int off,
                  int len)
            throws IOException
Specified by:
write in interface ObjectOutput
write in interface DataOutput
Overrides:
write in interface OutputStream

write

public void write(int data)
            throws IOException
Specified by:
write in interface ObjectOutput
write in interface DataOutput
Overrides:
write in interface OutputStream

writeBoolean

public void writeBoolean(boolean data)
            throws IOException
Specified by:
writeBoolean in interface DataOutput
See Also:
(boolean)

writeByte

public void writeByte(int data)
            throws IOException
Specified by:
writeByte in interface DataOutput
See Also:
(int)

writeBytes

public void writeBytes(String data)
            throws IOException
Specified by:
writeBytes in interface DataOutput

writeChar

public void writeChar(int data)
            throws IOException
Specified by:
writeChar in interface DataOutput
See Also:
(int)

writeChars

public void writeChars(String data)
            throws IOException
Specified by:
writeChars in interface DataOutput

writeClassDescriptor

protected void writeClassDescriptor(ObjectStreamClass osc)
            throws IOException

writeDouble

public void writeDouble(double data)
            throws IOException
Specified by:
writeDouble in interface DataOutput
See Also:
(double)

writeFields

public void writeFields()
            throws IOException

writeFloat

public void writeFloat(float data)
            throws IOException
Specified by:
writeFloat in interface DataOutput
See Also:
(float)

writeInt

public void writeInt(int data)
            throws IOException
Specified by:
writeInt in interface DataOutput
See Also:
(int)

writeLong

public void writeLong(long data)
            throws IOException
Specified by:
writeLong in interface DataOutput
See Also:
(long)

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.
Specified by:
writeObject in interface ObjectOutput
Parameters:
obj - the object to serialize.
Throws:
IOException - Exception from underlying OutputStream.

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.
Throws:
NotActiveException - Subclass has arranged for this method to be called, but did not implement this method.

writeShort

public void writeShort(int data)
            throws IOException
Specified by:
writeShort in interface DataOutput
See Also:
(int)

writeStreamHeader

protected void writeStreamHeader()
            throws IOException
Writes stream magic and stream version information to the underlying stream.
Throws:
IOException - Exception from underlying OutputStream.

writeUTF

public void writeUTF(String data)
            throws IOException
Specified by:
writeUTF in interface DataOutput

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).
Parameters:
obj - the object to serialize.
Throws:
IOException - if an I/O error occurs on the underlying OutputStream.
Since:
1.4

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.