java.io

Class ObjectOutputStream

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
abstract static classObjectOutputStream.PutField
This class allows a class to specify exactly which fields should be written, and what values should be written for these fields.
Constructor Summary
ObjectOutputStream(OutputStream out)
Creates a new ObjectOutputStream that will do all of its writing onto out.
protected ObjectOutputStream()
Protected constructor that allows subclasses to override serialization.
Method Summary
protected voidannotateClass(Class<?> cl)
An empty hook that allows subclasses to write extra information about classes to the stream.
protected voidannotateProxyClass(Class<?> cl)
voidclose()
voiddefaultWriteObject()
Writes the current objects non-transient, non-static fields from the current class to the underlying output stream.
protected voiddrain()
Causes the block-data buffer to be written to the underlying stream, but does not flush underlying stream.
protected booleanenableReplaceObject(boolean enable)
If enable is true and this object is trusted, then replaceObject (Object) will be called in subsequent calls to writeObject (Object).
voidflush()
ObjectOutputStream.PutFieldputFields()
protected ObjectreplaceObject(Object obj)
Allows subclasses to replace objects that are written to the stream with other objects to be written in their place.
voidreset()
Resets stream to state equivalent to the state just after it was constructed.
voiduseProtocolVersion(int version)
Informs this ObjectOutputStream to write data according to the specified protocol.
voidwrite(int data)
voidwrite(byte[] b)
voidwrite(byte[] b, int off, int len)
voidwriteBoolean(boolean data)
voidwriteByte(int data)
voidwriteBytes(String data)
voidwriteChar(int data)
voidwriteChars(String data)
protected voidwriteClassDescriptor(ObjectStreamClass osc)
voidwriteDouble(double data)
voidwriteFields()
voidwriteFloat(float data)
voidwriteInt(int data)
voidwriteLong(long data)
voidwriteObject(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 voidwriteObjectOverride(Object obj)
This method allows subclasses to override the default serialization mechanism provided by ObjectOutputStream.
voidwriteShort(int data)
protected voidwriteStreamHeader()
Writes stream magic and stream version information to the underlying stream.
voidwriteUnshared(Object obj)
Writes an object to the stream in the same manner as {@link #writeObject(Object)}, but without the use of references.
voidwriteUTF(String data)

Constructor Detail

ObjectOutputStream

public ObjectOutputStream(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).

Throws: IOException Writing stream header to underlying stream cannot be completed.

See Also: writeStreamHeader

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: writeObjectOverride

Method Detail

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.

Throws: IOException Exception from underlying OutputStream.

See Also: resolveClass

annotateProxyClass

protected void annotateProxyClass(Class<?> cl)

close

public void close()

See Also: DataOutputStream

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

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.

Throws: SecurityException This class is not trusted.

flush

public void flush()

See Also: flush

putFields

public ObjectOutputStream.PutField putFields()

replaceObject

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

See Also: ObjectOutputStream

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.

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

See Also: PROTOCOL_VERSION_1 PROTOCOL_VERSION_2

write

public void write(int data)

See Also: DataOutputStream

write

public void write(byte[] b)

See Also: (byte[])

write

public void write(byte[] b, int off, int len)

See Also: (byte[],int,int)

writeBoolean

public void writeBoolean(boolean data)

See Also: DataOutputStream

writeByte

public void writeByte(int data)

See Also: DataOutputStream

writeBytes

public void writeBytes(String data)

See Also: writeBytes

writeChar

public void writeChar(int data)

See Also: DataOutputStream

writeChars

public void writeChars(String data)

See Also: writeChars

writeClassDescriptor

protected void writeClassDescriptor(ObjectStreamClass osc)

writeDouble

public void writeDouble(double data)

See Also: DataOutputStream

writeFields

public void writeFields()

writeFloat

public void writeFloat(float data)

See Also: DataOutputStream

writeInt

public void writeInt(int data)

See Also: DataOutputStream

writeLong

public void writeLong(long data)

See Also: DataOutputStream

writeObject

public final 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. 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: obj the object to serialize.

Throws: NotSerializableException An attempt was made to serialize an Object that is not serializable. InvalidClassException Somebody tried to serialize an object which is wrongly formatted. IOException Exception from underlying OutputStream.

See Also: writeUnshared

writeObjectOverride

protected void writeObjectOverride(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.

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)

See Also: DataOutputStream

writeStreamHeader

protected void writeStreamHeader()
Writes stream magic and stream version information to the underlying stream.

Throws: IOException Exception from underlying OutputStream.

writeUnshared

public void writeUnshared(Object obj)
Writes an object to the stream in the same manner as {@link #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 {@link #writeObject(Object)}, both calls will write out the object in full, as the later call to {@link #writeObject(Object)} will know nothing of the earlier use of {@link #writeUnshared(Object)}.

Parameters: obj the object to serialize.

Throws: NotSerializableException if the object being serialized does not implement {@link Serializable}. InvalidClassException if a problem occurs with the class of the object being serialized. IOException if an I/O error occurs on the underlying OutputStream.

Since: 1.4

See Also: writeObject

writeUTF

public void writeUTF(String data)

See Also: writeUTF