Package java.io

Class ObjectOutputStream

java.lang.Object

java.io.OutputStream

java.io.ObjectOutputStream

All Implemented Interfaces:

Closeable, DataOutput, Flushable, ObjectOutput, ObjectStreamConstants, AutoCloseable

public class ObjectOutputStream
extends OutputStream
implements ObjectOutput, ObjectStreamConstants

A specialized OutputStream that is able to write (serialize) Java objects as well as primitive data types (int, byte, char etc.). The data can later be loaded using an ObjectInputStream.

See Also:

ObjectInputStream, ObjectOutput, Serializable, Externalizable

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ObjectOutputStream.PutField	PutField is an inner class to provide access to the persistent fields that are written to the target stream.

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

Constructors

Modifier	Constructor	Description
protected	ObjectOutputStream()	Constructs a new ObjectOutputStream.
	ObjectOutputStream(OutputStream output)	Constructs a new ObjectOutputStream that writes to the OutputStream output.

Method Summary

Modifier and Type	Method	Description
protected void	annotateClass(Class<?> aClass)	Writes optional information for class aClass to the output stream.
protected void	annotateProxyClass(Class<?> aClass)	Writes optional information for a proxy class to the target stream.
void	close()	Closes this stream.
void	defaultWriteObject()	Default method to write objects to this stream.
protected void	drain()	Writes buffered data to the target stream.
protected boolean	enableReplaceObject(boolean enable)	Enables object replacement for this stream.
void	flush()	Writes buffered data to the target stream and calls the flush method of the target stream.
ObjectOutputStream.PutField	putFields()	Gets this stream's PutField object.
protected Object	replaceObject(Object object)	Allows trusted subclasses to substitute the specified original object with a new object.
void	reset()	Resets the state of this stream.
void	useProtocolVersion(int version)	Sets the specified protocol version to be used by this stream.
void	write(byte[] buffer, int offset, int length)	Writes count bytes from the byte array buffer starting at offset index to the target stream.
void	write(int value)	Writes a single byte to the target stream.
void	writeBoolean(boolean value)	Writes a boolean to the target stream.
void	writeByte(int value)	Writes a byte (8 bit) to the target stream.
void	writeBytes(String value)	Writes the string value as a sequence of bytes to the target stream.
void	writeChar(int value)	Writes a character (16 bit) to the target stream.
void	writeChars(String value)	Writes the string value as a sequence of characters to the target stream.
protected void	writeClassDescriptor(ObjectStreamClass classDesc)	Writes a class descriptor to the target stream.
void	writeDouble(double value)	Writes a double (64 bit) to the target stream.
void	writeFields()	Writes the fields of the object currently being written to the target stream.
void	writeFloat(float value)	Writes a float (32 bit) to the target stream.
void	writeInt(int value)	Writes an integer (32 bit) to the target stream.
void	writeLong(long value)	Writes a long (64 bit) to the target stream.
void	writeObject(Object object)	Writes an object to the target stream.
protected void	writeObjectOverride(Object object)	Method to be overridden by subclasses to write object to the target stream.
void	writeShort(int value)	Writes a short (16 bit) to the target stream.
protected void	writeStreamHeader()	Writes the ObjectOutputStream header to the target stream.
void	writeUnshared(Object object)	Writes an unshared object to the target stream.
void	writeUTF(String value)	Writes a string encoded with modified UTF-8 to the target stream.

Methods inherited from class java.io.OutputStream

write

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.io.ObjectOutput

write

Constructor Detail

ObjectOutputStream

protected ObjectOutputStream()
                      throws IOException

Constructs a new ObjectOutputStream. This default constructor can be used by subclasses that do not want to use the public constructor if it allocates unneeded data.

Throws:

IOException - if an error occurs when creating this stream.

ObjectOutputStream

public ObjectOutputStream(OutputStream output)
                   throws IOException

Constructs a new ObjectOutputStream that writes to the OutputStream output.

Parameters:

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

Throws:

IOException - if an error occurs while writing the object stream header

Method Detail

annotateClass

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

Writes optional information for class aClass to the output stream. This optional data can be read when deserializing the class descriptor (ObjectStreamClass) for this class from an input stream. By default, no extra data is saved.

Parameters:

aClass - the class to annotate.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

ObjectInputStream.resolveClass(ObjectStreamClass)

annotateProxyClass

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

Writes optional information for a proxy class to the target stream. This optional data can be read when deserializing the proxy class from an input stream. By default, no extra data is saved.

Parameters:

aClass - the proxy class to annotate.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

ObjectInputStream.resolveProxyClass(String[])

close

public void close()
           throws IOException

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

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in interface ObjectOutput

Overrides:

close in class OutputStream

Throws:

IOException - if an error occurs while closing this stream.

defaultWriteObject

public void defaultWriteObject()
                        throws IOException

Default method to write objects to this stream. Serializable fields defined in the object's class and superclasses are written to the output stream.

Throws:

IOException - if an error occurs while writing to the target stream.

NotActiveException - if this method is not called from writeObject().

See Also:

ObjectInputStream.defaultReadObject()

drain

protected void drain()
              throws IOException

Writes buffered data to the target stream. This is similar to flush but the flush is not propagated to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

enableReplaceObject

protected boolean enableReplaceObject(boolean enable)

Enables object replacement for this stream. By default this is not enabled. Only trusted subclasses (loaded with system class loader) are allowed to change this status.

Parameters:

enable - true to enable object replacement; false to disable it.

Returns:

the previous setting.

See Also:

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

flush

public void flush()
           throws IOException

Writes buffered data to the target stream and calls the flush method of the target stream.

Specified by:

flush in interface Flushable

Specified by:

flush in interface ObjectOutput

Overrides:

flush in class OutputStream

Throws:

IOException - if an error occurs while writing to or flushing the output stream.

putFields

public ObjectOutputStream.PutField putFields()
                                      throws IOException

Gets this stream's PutField object. This object provides access to the persistent fields that are eventually written to the output stream. It is used to transfer the values from the fields of the object that is currently being written to the persistent fields.

Returns:

the PutField object from which persistent fields can be accessed by name.

Throws:

IOException - if an I/O error occurs.

NotActiveException - if this method is not called from writeObject().

See Also:

ObjectInputStream.defaultReadObject()

replaceObject

protected Object replaceObject(Object object)
                        throws IOException

Allows trusted subclasses to substitute the specified original object with a new object. Object substitution has to be activated first with calling enableReplaceObject(true). This implementation just returns object.

Parameters:

object - the original object for which a replacement may be defined.

Returns:

the replacement object for object.

Throws:

IOException - if any I/O error occurs while creating the replacement object.

See Also:

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

reset

public void reset()
           throws IOException

Resets the state of this stream. A marker is written to the stream, so that the corresponding input stream will also perform a reset 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 reset() is called during the serialization of an object.

useProtocolVersion

public void useProtocolVersion(int version)
                        throws IOException

Sets the specified protocol version to be used by this stream.

Parameters:

version - the protocol version to be used. Use a PROTOCOL_VERSION_x constant from java.io.ObjectStreamConstants.

Throws:

IllegalArgumentException - if an invalid version is specified.

IOException - if an I/O error occurs.

See Also:

ObjectStreamConstants.PROTOCOL_VERSION_1, ObjectStreamConstants.PROTOCOL_VERSION_2

write

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

Writes count bytes from the byte array buffer starting at offset index to the target stream. Blocks until all bytes are written.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Overrides:

write in class OutputStream

Parameters:

buffer - the buffer to write.

offset - the index of the first byte in buffer to write.

length - the number of bytes from buffer to write to the output stream.

Throws:

IOException - if an error occurs while writing to the target stream.

write

public void write(int value)
           throws IOException

Writes a single byte to the target stream. Only the least significant byte of the integer value is written to the stream. Blocks until the byte is actually written.

Specified by:

write in interface DataOutput

Specified by:

write in interface ObjectOutput

Specified by:

write in class OutputStream

Parameters:

value - the byte to write.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readByte()

writeBoolean

public void writeBoolean(boolean value)
                  throws IOException

Writes a boolean to the target stream.

Specified by:

writeBoolean in interface DataOutput

Parameters:

value - the boolean value to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readBoolean()

writeByte

public void writeByte(int value)
               throws IOException

Writes a byte (8 bit) to the target stream.

Specified by:

writeByte in interface DataOutput

Parameters:

value - the byte to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readByte(), DataInput.readUnsignedByte()

writeBytes

public void writeBytes(String value)
                throws IOException

Writes the string value as a sequence of bytes to the target stream. Only the least significant byte of each character in the string is written.

Specified by:

writeBytes in interface DataOutput

Parameters:

value - the string to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

writeChar

public void writeChar(int value)
               throws IOException

Writes a character (16 bit) to the target stream.

Specified by:

writeChar in interface DataOutput

Parameters:

value - the character to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readChar()

writeChars

public void writeChars(String value)
                throws IOException

Writes the string value as a sequence of characters to the target stream.

Specified by:

writeChars in interface DataOutput

Parameters:

value - the string to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readChar()

writeDouble

public void writeDouble(double value)
                 throws IOException

Writes a double (64 bit) to the target stream.

Specified by:

writeDouble in interface DataOutput

Parameters:

value - the double to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readDouble()

writeFields

public void writeFields()
                 throws IOException

Writes the fields of the object currently being written to the target stream. The field values are buffered in the currently active PutField object, which can be accessed by calling putFields().

Throws:

IOException - if an error occurs while writing to the target stream.

NotActiveException - if there are no fields to write to the target stream.

See Also:

putFields()

writeFloat

public void writeFloat(float value)
                throws IOException

Writes a float (32 bit) to the target stream.

Specified by:

writeFloat in interface DataOutput

Parameters:

value - the float to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readFloat()

writeInt

public void writeInt(int value)
              throws IOException

Writes an integer (32 bit) to the target stream.

Specified by:

writeInt in interface DataOutput

Parameters:

value - the integer to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readInt()

writeLong

public void writeLong(long value)
               throws IOException

Writes a long (64 bit) to the target stream.

Specified by:

writeLong in interface DataOutput

Parameters:

value - the long to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readLong()

writeClassDescriptor

protected void writeClassDescriptor(ObjectStreamClass classDesc)
                             throws IOException

Writes a class descriptor to the target stream.

Parameters:

classDesc - the class descriptor to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

writeObject

public final void writeObject(Object object)
                       throws IOException

Writes an object to the target stream.

Specified by:

writeObject in interface ObjectOutput

Parameters:

object - the object to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

ObjectInputStream.readObject()

writeUnshared

public void writeUnshared(Object object)
                   throws IOException

Writes an unshared object to the target stream. This method is identical to writeObject, except that it always writes a new object to the stream versus the use of back-referencing for identical objects by writeObject.

Parameters:

object - the object to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

ObjectInputStream.readUnshared()

writeObjectOverride

protected void writeObjectOverride(Object object)
                            throws IOException

Method to be overridden by subclasses to write object to the target stream.

Parameters:

object - the object to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

writeShort

public void writeShort(int value)
                throws IOException

Writes a short (16 bit) to the target stream.

Specified by:

writeShort in interface DataOutput

Parameters:

value - the short to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readShort(), DataInput.readUnsignedShort()

writeStreamHeader

protected void writeStreamHeader()
                          throws IOException

Writes the ObjectOutputStream header to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

writeUTF

public void writeUTF(String value)
              throws IOException

Writes a string encoded with modified UTF-8 to the target stream.

Specified by:

writeUTF in interface DataOutput

Parameters:

value - the string to write to the target stream.

Throws:

IOException - if an error occurs while writing to the target stream.

See Also:

DataInput.readUTF()