java.io
Class ObjectOutputStream
java.lang.Object java.io.OutputStream java.io.ObjectOutputStream
- All Implemented Interfaces:
- DataOutput, 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
.
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. |
Field Summary | |
private byte[] |
blockData |
private int |
blockDataCount |
private DataOutputStream |
blockDataOutput |
private static int |
BUFFER_SIZE |
private java.lang.Object |
currentObject |
(package private) ObjectStreamClass |
currentObjectStreamClass |
private ObjectOutputStream.PutField |
currentPutField |
private DataOutputStream |
dataOutput |
private static boolean |
DEBUG |
private static int |
defaultProtocolVersion |
private int |
depth |
private boolean |
dump |
private boolean |
fieldsAlreadyWritten |
private boolean |
isSerializing |
private int |
nextOID |
private java.util.Hashtable |
OIDLookupTable |
private int |
protocolVersion |
private DataOutputStream |
realOutput |
private boolean |
replacementEnabled |
private gnu.java.security.action.SetAccessibleAction |
setAccessible |
private boolean |
useSubclassMethod |
private boolean |
writeDataAsBlocks |
Constructor Summary | |
protected |
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(java.lang.Class cl)
An empty hook that allows subclasses to write extra information about classes to the stream. |
protected void |
annotateProxyClass(java.lang.Class cl)
|
private int |
assignNewHandle(java.lang.Object obj)
|
private void |
callWriteMethod(java.lang.Object obj,
ObjectStreamClass osc) |
private void |
clearHandles() |
void |
close() This method closes the underlying stream. |
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. |
private void |
dumpElementln(java.lang.String msg)
|
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) . |
private java.lang.Integer |
findHandle(java.lang.Object obj)
|
void |
flush() This method causes any buffered data to be flushed out to the underlying stream |
private boolean |
getBooleanField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name) |
private byte |
getByteField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name) |
private char |
getCharField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name) |
private double |
getDoubleField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name) |
private java.lang.reflect.Field |
getField(java.lang.Class klass,
java.lang.String name) |
private float |
getFloatField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name) |
private int |
getIntField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name) |
private long |
getLongField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name) |
private java.lang.Object |
getObjectField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name,
java.lang.String type_code) |
private short |
getShortField(java.lang.Object obj,
java.lang.Class klass,
java.lang.String field_name) |
private void |
markFieldsWritten() |
ObjectOutputStream.PutField |
putFields() |
protected java.lang.Object |
replaceObject(java.lang.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. |
private void |
reset(boolean internal) |
(package private) boolean |
setBlockDataMode(boolean on) |
void |
useProtocolVersion(int version) Informs this ObjectOutputStream
to write data according to the specified protocol. |
void |
write(byte[] b) This method writes all the bytes in the specified byte array to the output stream. |
void |
write(byte[] b, int off, int len) This method writes len bytes
from the specified array starting at index
offset into that array. |
void |
write(int data) This method writes the specified byte to the output stream. |
private void |
writeArraySizeAndElements(java.lang.Object array,
java.lang.Class clazz) |
private void |
writeBlockDataHeader(int size) |
void |
writeBoolean(boolean data) This method writes a Java boolean value to an output stream. |
void |
writeByte(int data) This method writes a Java byte value to an output stream. |
void |
writeBytes(java.lang.String data)
This method writes all the bytes in a String out to the stream. |
void |
writeChar(int data) This method writes a Java char value to an output stream. |
void |
writeChars(java.lang.String data)
This method writes all the characters of a String to an output stream as an array
of char 's. |
protected void |
writeClassDescriptor(ObjectStreamClass osc)
|
void |
writeDouble(double data) This method writes a Java double
value to the stream. |
void |
writeFields() |
private void |
writeFields(java.lang.Object obj,
ObjectStreamClass osc) |
void |
writeFloat(float data) This method writes a Java float
value to the stream. |
void |
writeInt(int data) This method writes a Java int value to an output stream. |
void |
writeLong(long data) This method writes a Java long value to an output stream. |
void |
writeObject(java.lang.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(java.lang.Object obj)
This method allows subclasses to override the default serialization mechanism provided by ObjectOutputStream . |
void |
writeShort(int data) This method writes a Java short value to an output stream. |
protected void |
writeStreamHeader() Writes stream magic and stream version information to the underlying stream. |
void |
writeUTF(java.lang.String data)
This method writes a Java String
to the stream in a modified UTF-8 format. |
Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
Field Detail |
BUFFER_SIZE
private static final int BUFFER_SIZE
- See Also:
- Constant Field Values
defaultProtocolVersion
private static int defaultProtocolVersion
dataOutput
private DataOutputStream dataOutput
writeDataAsBlocks
private boolean writeDataAsBlocks
realOutput
private DataOutputStream realOutput
blockDataOutput
private DataOutputStream blockDataOutput
blockData
private byte[] blockData
blockDataCount
private int blockDataCount
currentObject
private java.lang.Object currentObject
currentObjectStreamClass
ObjectStreamClass currentObjectStreamClass
currentPutField
private ObjectOutputStream.PutField currentPutField
fieldsAlreadyWritten
private boolean fieldsAlreadyWritten
replacementEnabled
private boolean replacementEnabled
isSerializing
private boolean isSerializing
nextOID
private int nextOID
OIDLookupTable
private java.util.Hashtable OIDLookupTable
protocolVersion
private int protocolVersion
useSubclassMethod
private boolean useSubclassMethod
setAccessible
private gnu.java.security.action.SetAccessibleAction setAccessible
depth
private int depth
dump
private boolean dump
DEBUG
private static final boolean DEBUG
- See Also:
- Constant Field Values
Constructor Detail |
ObjectOutputStream
public ObjectOutputStream(OutputStream out) throws IOException
- Creates a new
ObjectOutputStream
that will do all of its writing ontoout
. This method also initializes the stream by writing the header information (stream magic number and stream version).
ObjectOutputStream
protected ObjectOutputStream() throws IOException, java.lang.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 informswriteObject (Object)
to call the subclasseswriteObjectOverride (Object)
method.
Method Detail |
writeObject
public final void writeObject(java.lang.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 implementingprivate void writeObject (ObjectOutputStream)
. If an exception is thrown from this method, the stream is left in an undefined state. -
- Specified by:
writeObject
in interfaceObjectOutput
writeClassDescriptor
protected void writeClassDescriptor(ObjectStreamClass osc) throws IOException
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.
markFieldsWritten
private void markFieldsWritten() throws IOException
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.
reset
private void reset(boolean internal) throws IOException
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 byPROTOCOL_VERSION_1
andPROTOCOL_VERSION_2
. This implementation writes data usingPROTOCOL_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.
-
- Since:
- 1.2
annotateClass
protected void annotateClass(java.lang.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.
annotateProxyClass
protected void annotateProxyClass(java.lang.Class cl) throws IOException
replaceObject
protected java.lang.Object replaceObject(java.lang.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.
enableReplaceObject
protected boolean enableReplaceObject(boolean enable) throws java.lang.SecurityException
- If
enable
istrue
and this object is trusted, thenreplaceObject (Object)
will be called in subsequent calls towriteObject (Object)
. Otherwise,replaceObject (Object)
will not be called.
writeStreamHeader
protected void writeStreamHeader() throws IOException
- Writes stream magic and stream version information
to the underlying stream.
writeObjectOverride
protected void writeObjectOverride(java.lang.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.
write
public void write(int data) throws IOException
- Description copied from interface:
ObjectOutput
- This method writes the specified byte to the output
stream.
-
- Specified by:
write
in interfaceObjectOutput
- Specified by:
write
in classOutputStream
write
public void write(byte[] b) throws IOException
- Description copied from interface:
ObjectOutput
- This method writes all the bytes in the specified
byte array to the output stream.
-
- Specified by:
write
in interfaceObjectOutput
- Overrides:
write
in classOutputStream
write
public void write(byte[] b, int off, int len) throws IOException
- Description copied from interface:
ObjectOutput
- This method writes
len
bytes from the specified array starting at indexoffset
into that array. -
- Specified by:
write
in interfaceObjectOutput
- Overrides:
write
in classOutputStream
flush
public void flush() throws IOException
- Description copied from interface:
ObjectOutput
- This method causes any buffered data to be flushed
out to the underlying stream
-
- Specified by:
flush
in interfaceObjectOutput
- Overrides:
flush
in classOutputStream
drain
protected void drain() throws IOException
- Causes the block-data buffer to be written to the
underlying stream, but does not flush underlying stream.
close
public void close() throws IOException
- Description copied from interface:
ObjectOutput
- This method closes the underlying stream.
-
- Specified by:
close
in interfaceObjectOutput
- Overrides:
close
in classOutputStream
writeBoolean
public void writeBoolean(boolean data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java boolean value to an output
stream. If
value
istrue
, a byte with the value of 1 will be written, otherwise a byte with the value of 0 will be written. The value written can be read using thereadBoolean
method inDataInput
. -
- Specified by:
writeBoolean
in interfaceDataOutput
writeByte
public void writeByte(int data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java byte value to an output
stream. The byte to be written will be in the lowest 8
bits of the
int
value passed. The value written can be read using thereadByte
orreadUnsignedByte
methods inDataInput
. -
- Specified by:
writeByte
in interfaceDataOutput
writeShort
public void writeShort(int data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java short value to an output
stream. The char to be written will be in the lowest 16
bits of the
int
value passed. These bytes will be written "big endian". That is, with the high byte written first in the following manner:byte0 = (byte)((value & 0xFF00) >> 8);
byte1 = (byte)(value & 0x00FF);The value written can be read using the
readShort
andreadUnsignedShort
methods inDataInput
. -
- Specified by:
writeShort
in interfaceDataOutput
writeChar
public void writeChar(int data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java char value to an output
stream. The char to be written will be in the lowest 16
bits of the
int
value passed. These bytes will be written "big endian". That is, with the high byte written first in the following manner:byte0 = (byte)((value & 0xFF00) >> 8);
byte1 = (byte)(value & 0x00FF);The value written can be read using the
readChar
method inDataInput
. -
- Specified by:
writeChar
in interfaceDataOutput
writeInt
public void writeInt(int data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java int value to an output
stream. The 4 bytes of the passed value will be written
"big endian". That is, with the high byte written first
in the following manner:
byte0 = (byte)((value & 0xFF000000) >> 24);
byte1 = (byte)((value & 0x00FF0000) >> 16);
byte2 = (byte)((value & 0x0000FF00) >> 8);
byte3 = (byte)(value & 0x000000FF);The value written can be read using the
readInt
method inDataInput
. -
- Specified by:
writeInt
in interfaceDataOutput
writeLong
public void writeLong(long data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java long value to an output
stream. The 8 bytes of the passed value will be written
"big endian". That is, with the high byte written first
in the following manner:
byte0 = (byte)((value & 0xFF00000000000000L) >> 56);
byte1 = (byte)((value & 0x00FF000000000000L) >> 48);
byte2 = (byte)((value & 0x0000FF0000000000L) >> 40);
byte3 = (byte)((value & 0x000000FF00000000L) >> 32);
byte4 = (byte)((value & 0x00000000FF000000L) >> 24);
byte5 = (byte)((value & 0x0000000000FF0000L) >> 16);
byte6 = (byte)((value & 0x000000000000FF00L) >> 8);
byte7 = (byte)(value & 0x00000000000000FFL);The value written can be read using the
readLong
method inDataInput
. -
- Specified by:
writeLong
in interfaceDataOutput
writeFloat
public void writeFloat(float data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java
float
value to the stream. This value is written by first calling the methodFloat.floatToIntBits
to retrieve anint
representing the floating point number, then writing thisint
value to the stream exactly the same as thewriteInt()
method does. The value written can be read using thereadFloat
method inDataInput
. -
- Specified by:
writeFloat
in interfaceDataOutput
writeDouble
public void writeDouble(double data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java
double
value to the stream. This value is written by first calling the methodDouble.doubleToLongBits
to retrieve anlong
representing the floating point number, then writing thislong
value to the stream exactly the same as thewriteLong()
method does. The value written can be read using thereadDouble
method inDataInput
. -
- Specified by:
writeDouble
in interfaceDataOutput
writeBytes
public void writeBytes(java.lang.String data) throws IOException
- Description copied from interface:
DataOutput
- This method writes all the bytes in a
String
out to the stream. One byte is written for each character in theString
. The high eight bits of each character are discarded, thus this method is inappropriate for completely representing Unicode characters. -
- Specified by:
writeBytes
in interfaceDataOutput
writeChars
public void writeChars(java.lang.String data) throws IOException
- Description copied from interface:
DataOutput
- This method writes all the characters of a
String
to an output stream as an array ofchar
's. Each character is written using the method specified in thewriteChar
method. -
- Specified by:
writeChars
in interfaceDataOutput
writeUTF
public void writeUTF(java.lang.String data) throws IOException
- Description copied from interface:
DataOutput
- This method writes a Java
String
to the stream in a modified UTF-8 format. First, two bytes are written to the stream indicating the number of bytes to follow. This is written in the form of a Javashort
value in the same manner used by thewriteShort
method. Note that this is the number of bytes in the encodedString
not theString
length. Next come the encoded characters. Each character in theString
is encoded as either one, two or three bytes. For characters in the range ofto
, one byte is used. The character value goes into bits 0-7 and bit eight is 0. For characters in the range of€
toF
, two bytes are used. Bits 6-10 of the character value are encoded bits 0-4 of the first byte, with the high bytes having a value of "110". Bits 0-5 of the character value are stored in bits 0-5 of the second byte, with the high bits set to "10". This type of encoding is also done for the null character . This eliminates any C style NUL character values in the output. All remaining characters are stored as three bytes. Bits 12-15 of the character value are stored in bits 0-3 of the first byte. The high bits of the first bytes are set to "1110". Bits 6-11 of the character value are stored in bits 0-5 of the second byte. The high bits of the second byte are set to "10". And bits 0-5 of the character value are stored in bits 0-5 of byte three, with the high bits of that byte set to "10". The value written can be read using thereadUTF
method inDataInput
. -
- Specified by:
writeUTF
in interfaceDataOutput
putFields
public ObjectOutputStream.PutField putFields() throws IOException
writeFields
public void writeFields() throws IOException
writeBlockDataHeader
private void writeBlockDataHeader(int size) throws IOException
findHandle
private java.lang.Integer findHandle(java.lang.Object obj)
assignNewHandle
private int assignNewHandle(java.lang.Object obj)
clearHandles
private void clearHandles()
writeArraySizeAndElements
private void writeArraySizeAndElements(java.lang.Object array, java.lang.Class clazz) throws IOException
writeFields
private void writeFields(java.lang.Object obj, ObjectStreamClass osc) throws IOException
setBlockDataMode
boolean setBlockDataMode(boolean on) throws IOException
callWriteMethod
private void callWriteMethod(java.lang.Object obj, ObjectStreamClass osc) throws IOException
getBooleanField
private boolean getBooleanField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name) throws IOException
getByteField
private byte getByteField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name) throws IOException
getCharField
private char getCharField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name) throws IOException
getDoubleField
private double getDoubleField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name) throws IOException
getFloatField
private float getFloatField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name) throws IOException
getIntField
private int getIntField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name) throws IOException
getLongField
private long getLongField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name) throws IOException
getShortField
private short getShortField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name) throws IOException
getObjectField
private java.lang.Object getObjectField(java.lang.Object obj, java.lang.Class klass, java.lang.String field_name, java.lang.String type_code) throws IOException
getField
private java.lang.reflect.Field getField(java.lang.Class klass, java.lang.String name) throws InvalidClassException
dumpElementln
private void dumpElementln(java.lang.String msg)