java.io
Class ObjectOutputStream

java.lang.Object
  java.io.OutputStream
      java.io.ObjectOutputStream

All Implemented Interfaces:

Closeable, DataOutput, Flushable, ObjectOutput, ObjectStreamConstants

public class ObjectOutputStream
extends OutputStream
implements ObjectOutput, ObjectStreamConstants

An ObjectOutputStream can be used to save Java objects into a stream where the objects can be loaded later with an ObjectInputStream. Primitive data (ints, bytes, chars, etc) can also be saved.

See Also:

ObjectInputStream, ObjectOutput, Serializable, Externalizable

Nested Class Summary

static class

ObjectOutputStream.PutField Inner class to provide access to serializable fields

Field Summary

Fields inherited from interface java.io.ObjectStreamConstants

baseWireHandle, 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

Constructor Summary

protected	ObjectOutputStream() Constructs a new ObjectOutputStream.
	ObjectOutputStream(OutputStream output) Constructs a new ObjectOutputStream on the OutputStream output.

Method Summary

protected void	annotateClass(Class<?> aClass) Writes optional information for class aClass into the stream represented by the receiver.
protected void	annotateProxyClass(Class<?> aClass) Writes optional information for a proxy class into the stream represented by the receiver.
void	close() Close this ObjectOutputStream.
void	defaultWriteObject() Default method to write objects into the receiver.
protected void	drain() Flushes buffered primitive data into the receiver.
protected boolean	enableReplaceObject(boolean enable) Enables/disables object replacement for the receiver.
void	flush() Flush this ObjectOutputStream.
ObjectOutputStream.PutField	putFields() Return the PutField object for the receiver.
protected Object	replaceObject(Object object) If enableReplaceObject() was activated, computes the replacement object for the original object object and returns the replacement.
void	reset() Reset the receiver.
void	useProtocolVersion(int version) Set the receiver to use the given protocol version.
void	write(byte[] buffer) Writes the entire contents of the byte array buffer to this ObjectOutputStream.
void	write(byte[] buffer, int offset, int length) Writes length bytes from the byte array buffer starting at offset offset to the ObjectOutputStream.
void	write(int value) Write one byte (value) into the receiver's underlying stream.
void	writeBoolean(boolean value) Write primitive data of type boolean (value)into the receiver's underlying stream.
void	writeByte(int value) Write primitive data of type byte (value)into the receiver's underlying stream.
void	writeBytes(String value) Write a String as a sequence of bytes (only lower-order 8 bits of each char are written), as primitive data (value) into the receiver's underlying stream.
void	writeChar(int value) Write primitive data of type char (value)into the receiver's underlying stream.
void	writeChars(String value) Write a String as a sequence of char, as primitive data (value) into the receiver's underlying stream.
protected void	writeClassDescriptor(ObjectStreamClass classDesc) Write class descriptor classDesc into the receiver.
void	writeDouble(double value) Write primitive data of type double (value)into the receiver's underlying stream.
void	writeFields() Write the fields of the object being dumped.
void	writeFloat(float value) Write primitive data of type float (value)into the receiver's underlying stream.
void	writeInt(int value) Write primitive data of type int (value)into the receiver's underlying stream.
void	writeLong(long value) Write primitive data of type long (value)into the receiver's underlying stream.
void	writeObject(Object object) Write object object into the receiver's underlying stream.
protected void	writeObjectOverride(Object object) Method to be overridden by subclasses to write object into the receiver's underlying stream.
void	writeShort(int value) Write primitive data of type short (value)into the receiver's underlying stream.
protected void	writeStreamHeader() Writes the ObjectOutputStream header into the underlying stream.
void	writeUnshared(Object object) Write object object into the receiver's underlying stream unshared with previously written identical objects.
void	writeUTF(String value) Write primitive data of type String (value) in UTF format into the receiver's underlying stream.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ObjectOutputStream

protected ObjectOutputStream()
                      throws IOException,
                             SecurityException

Constructs a new ObjectOutputStream. The representation and proper initialization is in the hands of subclasses.

Throws:

IOException

SecurityException - if subclassing this is not allowed

See Also:

SecurityManager.checkPermission(java.security.Permission)

ObjectOutputStream

public ObjectOutputStream(OutputStream output)
                   throws IOException

Constructs a new ObjectOutputStream on the OutputStream output. All writes are now filtered through this stream.

Parameters:

output - The non-null OutputStream to filter writes on.

Throws:

IOException - If an IO exception happened when writing the object stream header

Method Detail

annotateClass

protected void annotateClass(Class<?> aClass)
                      throws IOException

Writes optional information for class aClass into the stream represented by the receiver. This optional data can be read when deserializing the class descriptor (ObjectStreamClass) for this class from the input stream. By default no extra data is saved.

Parameters:

aClass - The class to annotate

Throws:

IOException - If an IO exception happened when annotating the class.

See Also:

ObjectInputStream.resolveClass(java.io.ObjectStreamClass)

annotateProxyClass

protected void annotateProxyClass(Class<?> aClass)
                           throws IOException

Writes optional information for a proxy class into the stream represented by the receiver. This optional data can be read when deserializing the proxy class from the input stream. By default no extra data is saved.

Parameters:

aClass - The proxy class to annotate

Throws:

IOException - If an IO exception happened when annotating the class.

See Also:

ObjectInputStream.resolveProxyClass(java.lang.String[])

close

public void close()
           throws IOException

Close this ObjectOutputStream. Any buffered data is flushed. This implementation closes the target stream.

Specified by:

close in interface Closeable

Specified by:

close in interface ObjectOutput

Overrides:

close in class OutputStream

Throws:

IOException - If an error occurs attempting to close this stream.

defaultWriteObject

public void defaultWriteObject()
                        throws IOException

Default method to write objects into the receiver. Fields defined in the object's class and superclasses (which are Serializable) will be saved.

Throws:

IOException - If an IO error occurs attempting to write the object data

See Also:

ObjectInputStream.defaultReadObject()

drain

protected void drain()
              throws IOException

Flushes buffered primitive data into the receiver.

Throws:

IOException - If an error occurs attempting to drain the data

enableReplaceObject

protected boolean enableReplaceObject(boolean enable)
                               throws SecurityException

Enables/disables object replacement for the receiver. By default this is not enabled. Only trusted subclasses (loaded with system class loader) can override this behavior.

Parameters:

enable - if true, enables replacement. If false, disables replacement.

Returns:

boolean the previous configuration (if it was enabled or disabled)

Throws:

SecurityException - If the class of the receiver is not trusted

See Also:

replaceObject(java.lang.Object), ObjectInputStream.enableResolveObject(boolean)

flush

public void flush()
           throws IOException

Flush this ObjectOutputStream. Any pending writes to the underlying stream are written out when this method is invoked.

Specified by:

flush in interface Flushable

Specified by:

flush in interface ObjectOutput

Overrides:

flush in class OutputStream

Throws:

IOException - If an error occurs attempting to flush this ObjectOutputStream.

putFields

public ObjectOutputStream.PutField putFields()
                                      throws IOException

Return the PutField object for the receiver. This allows users to transfer values from actual object fields in the object being dumped to the emulated fields represented by the PutField returned by this method.

Returns:

the PutFieldObject for the receiver

Throws:

IOException - If an IO error occurs

NotActiveException - If this method is not called from writeObject()

See Also:

ObjectInputStream.defaultReadObject()

replaceObject

protected Object replaceObject(Object object)
                        throws IOException

If enableReplaceObject() was activated, computes the replacement object for the original object object and returns the replacement. Otherwise returns object.

Parameters:

object - Original object for which a replacement may be defined

Returns:

a possibly new, replacement object for object

Throws:

IOException - If any IO problem occurred when trying to resolve the object.

See Also:

enableReplaceObject(boolean), ObjectInputStream.enableResolveObject(boolean), ObjectInputStream.resolveObject(java.lang.Object)

reset

public void reset()
           throws IOException

Reset the receiver. A marker is written to the stream, so that deserialization will also perform a rest at the same point. Objects previously written are no longer remembered, so they will be written again (instead of a cyclical reference) if found in the object graph.

Throws:

IOException - If any IO problem occurred when trying to reset the receiver

useProtocolVersion

public void useProtocolVersion(int version)
                        throws IOException

Set the receiver to use the given protocol version.

Parameters:

version - protocol version to be used

Throws:

IOException - If an IO error occurs

write

public void write(byte[] buffer)
           throws IOException

Writes the entire contents of the byte array buffer to this ObjectOutputStream.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Overrides:

write in class OutputStream

Parameters:

buffer - the buffer to be written

Throws:

IOException - If an error occurs attempting to write to this ObjectOutputStream.

See Also:

DataInput.readFully(byte[]), DataInput.readFully(byte[], int, int)

write

public void write(byte[] buffer,
                  int offset,
                  int length)
           throws IOException

Writes length bytes from the byte array buffer starting at offset offset to the ObjectOutputStream.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Overrides:

write in class OutputStream

Parameters:

buffer - the buffer to be written

offset - offset in buffer to get bytes

length - number of bytes in buffer to write

Throws:

IOException - If an error occurs attempting to write to this OutputStream.

See Also:

DataInput.readFully(byte[]), DataInput.readFully(byte[], int, int)

write

public void write(int value)
           throws IOException

Write one byte (value) into the receiver's underlying stream.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Specified by:

write in class OutputStream

Parameters:

value - The primitive data to write. Only the lower byte is written.

Throws:

IOException - If an IO exception happened when writing the byte.

See Also:

DataInput.readByte()

writeBoolean

public void writeBoolean(boolean value)
                  throws IOException

Write primitive data of type boolean (value)into the receiver's underlying stream.

Specified by:

writeBoolean in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readBoolean()

writeByte

public void writeByte(int value)
               throws IOException

Write primitive data of type byte (value)into the receiver's underlying stream.

Specified by:

writeByte in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readByte(), DataInput.readUnsignedByte()

writeBytes

public void writeBytes(String value)
                throws IOException

Write a String as a sequence of bytes (only lower-order 8 bits of each char are written), as primitive data (value) into the receiver's underlying stream.

Specified by:

writeBytes in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readFully(byte[]), DataInput.readFully(byte[],int,int)

writeChar

public void writeChar(int value)
               throws IOException

Write primitive data of type char (value)into the receiver's underlying stream.

Specified by:

writeChar in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readChar()

writeChars

public void writeChars(String value)
                throws IOException

Write a String as a sequence of char, as primitive data (value) into the receiver's underlying stream.

Specified by:

writeChars in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readChar()

writeDouble

public void writeDouble(double value)
                 throws IOException

Write primitive data of type double (value)into the receiver's underlying stream.

Specified by:

writeDouble in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readDouble()

writeFields

public void writeFields()
                 throws IOException

Write the fields of the object being dumped. The stream will use the currently active PutField object, allowing users to dump emulated fields, for cross-loading compatibility when a class definition changes.

Throws:

IOException - If an IO error occurs

See Also:

putFields()

writeFloat

public void writeFloat(float value)
                throws IOException

Write primitive data of type float (value)into the receiver's underlying stream.

Specified by:

writeFloat in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readFloat()

writeInt

public void writeInt(int value)
              throws IOException

Write primitive data of type int (value)into the receiver's underlying stream.

Specified by:

writeInt in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readInt()

writeLong

public void writeLong(long value)
               throws IOException

Write primitive data of type long (value)into the receiver's underlying stream.

Specified by:

writeLong in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readLong()

writeClassDescriptor

protected void writeClassDescriptor(ObjectStreamClass classDesc)
                             throws IOException

Write class descriptor classDesc into the receiver.

Parameters:

classDesc - The ObjectStreamClass object to dump

Throws:

IOException - If an IO exception happened when writing the class descriptor.

writeObject

public final void writeObject(Object object)
                       throws IOException

Write object object into the receiver's underlying stream.

Specified by:

writeObject in interface ObjectOutput

Parameters:

object - The object to write

Throws:

IOException - If an IO exception happened when writing the object

See Also:

ObjectInputStream.readObject()

writeUnshared

public void writeUnshared(Object object)
                   throws IOException

Write object object into the receiver's underlying stream unshared with previously written identical objects.

Parameters:

object - The object to write

Throws:

IOException - If an IO exception happened when writing the object

See Also:

ObjectInputStream.readObject()

writeObjectOverride

protected void writeObjectOverride(Object object)
                            throws IOException

Method to be overridden by subclasses to write object into the receiver's underlying stream.

Parameters:

object - the object

Throws:

IOException - If an IO exception happened when writing the object

writeShort

public void writeShort(int value)
                throws IOException

Write primitive data of type short (value)into the receiver's underlying stream.

Specified by:

writeShort in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readShort(), DataInput.readUnsignedShort()

writeStreamHeader

protected void writeStreamHeader()
                          throws IOException

Writes the ObjectOutputStream header into the underlying stream.

Throws:

IOException - If an IO exception happened when writing the stream header.

writeUTF

public void writeUTF(String value)
              throws IOException

Write primitive data of type String (value) in UTF format into the receiver's underlying stream.

Specified by:

writeUTF in interface DataOutput

Parameters:

value - The primitive data to write

Throws:

IOException - If an IO exception happened when writing the primitive data.

See Also:

DataInput.readUTF()