public class ObjectOutputStream extends OutputStream implements ObjectOutput, ObjectStreamConstants
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
.DataOutputStream
,
Externalizable
,
ObjectInputStream
,
Serializable
Modifier and Type | Class and Description |
---|---|
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.
|
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
Modifier | Constructor and Description |
---|---|
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 . |
Modifier and Type | Method and Description |
---|---|
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()
This method closes the 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.
|
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()
This method forces any data that may have been buffered to be written
to the underlying output device.
|
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)
This method all the writes bytes from the passed array to the
output stream.
|
void |
write(byte[] b,
int off,
int len)
This method writes
len bytes from the specified array
b starting at index off into the array. |
void |
write(int data)
This method writes a single byte to the output stream.
|
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(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(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() |
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(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)
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 |
writeUnshared(Object obj)
Writes an object to the stream in the same manner as
writeObject(Object) , but without the use of
references. |
void |
writeUTF(String data)
This method writes a Java
String to the stream in a modified
UTF-8 format. |
public ObjectOutputStream(OutputStream out) throws IOException
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).IOException
- Writing stream header to underlying
stream cannot be completed.writeStreamHeader()
protected ObjectOutputStream() throws IOException, SecurityException
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.IOException
SecurityException
writeObjectOverride(Object)
public final void writeObject(Object obj) throws IOException
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.writeObject
in interface ObjectOutput
obj
- the object to serialize.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
.writeUnshared(Object)
public void writeUnshared(Object obj) throws IOException
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)
.obj
- the object to serialize.NotSerializableException
- if the object being
serialized does not implement
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
.writeObject(Object)
protected void writeClassDescriptor(ObjectStreamClass osc) throws IOException
IOException
public void defaultWriteObject() throws IOException, NotActiveException
private void writeObject (ObjectOutputStream)
method.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
.public void reset() throws IOException
IOException
- Exception from underlying
OutputStream
or reset called while serialization is
in progress.public void useProtocolVersion(int version) throws IOException
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.
version
- the version to use.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.ObjectStreamConstants.PROTOCOL_VERSION_1
,
ObjectStreamConstants.PROTOCOL_VERSION_2
protected void annotateClass(Class<?> cl) throws IOException
IOException
- Exception from underlying
OutputStream
.ObjectInputStream.resolveClass(java.io.ObjectStreamClass)
protected void annotateProxyClass(Class<?> cl) throws IOException
IOException
protected Object replaceObject(Object obj) throws IOException
IOException
- Exception from underlying
OutputStream
.enableReplaceObject(boolean)
protected boolean enableReplaceObject(boolean enable) throws SecurityException
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.SecurityException
- This class is not trusted.protected void writeStreamHeader() throws IOException
IOException
- Exception from underlying
OutputStream
.protected void writeObjectOverride(Object obj) throws NotActiveException, IOException
ObjectOutputStream
. To make this method be used for
writing objects, subclasses must invoke the 0-argument
constructor on this class from there constructor.NotActiveException
- Subclass has arranged for this
method to be called, but did not implement this method.IOException
ObjectOutputStream()
public void write(int data) throws IOException
OutputStream
int
passed and a argument.
Subclasses must provide an implementation of this abstract method
write
in interface DataOutput
write
in interface ObjectOutput
write
in class OutputStream
data
- The byte to be written to the output stream, passed as
the low eight bits of an int
IOException
- If an error occursDataOutputStream.write(int)
public void write(byte[] b) throws IOException
OutputStream
write(b, 0,
buf.length)
which is exactly how it is implemented in this
class.write
in interface DataOutput
write
in interface ObjectOutput
write
in class OutputStream
b
- The array of bytes to writeIOException
- If an error occursFilterOutputStream.write(byte[])
public void write(byte[] b, int off, int len) throws IOException
OutputStream
len
bytes from the specified array
b
starting at index off
into the array.
This method in this class calls the single byte write()
method in a loop until all bytes have been written. Subclasses should
override this method if possible in order to provide a more efficent
implementation.
write
in interface DataOutput
write
in interface ObjectOutput
write
in class OutputStream
b
- The array of bytes to write fromoff
- The index into the array to start writing fromlen
- The number of bytes to writeIOException
- If an error occursDataOutputStream.write(byte[],int,int)
public void flush() throws IOException
OutputStream
This method in this class does nothing.
flush
in interface Flushable
flush
in interface ObjectOutput
flush
in class OutputStream
IOException
- If an error occursDataOutputStream.flush()
protected void drain() throws IOException
IOException
- Exception from underlying
OutputStream
.public void close() throws IOException
OutputStream
This method in this class does nothing.
close
in interface Closeable
close
in interface ObjectOutput
close
in interface AutoCloseable
close
in class OutputStream
IOException
- If an error occurs()
public void writeBoolean(boolean data) throws IOException
DataOutput
value
is true
, 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 the readBoolean
method in DataInput
.writeBoolean
in interface DataOutput
data
- The boolean value to writeIOException
- If an error occurs(boolean)
public void writeByte(int data) throws IOException
DataOutput
int
value passed.
The value written can be read using the readByte
or
readUnsignedByte
methods in DataInput
.writeByte
in interface DataOutput
data
- The int value to writeIOException
- If an error occurs(int)
public void writeShort(int data) throws IOException
DataOutput
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
and
readUnsignedShort
methods in DataInput
.
writeShort
in interface DataOutput
data
- The int value to write as a 16-bit valueIOException
- If an error occurs(int)
public void writeChar(int data) throws IOException
DataOutput
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 in DataInput
.
writeChar
in interface DataOutput
data
- The char value to writeIOException
- If an error occurs(int)
public void writeInt(int data) throws IOException
DataOutput
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 in DataInput
.
writeInt
in interface DataOutput
data
- The int value to writeIOException
- If an error occurs(int)
public void writeLong(long data) throws IOException
DataOutput
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 in DataInput
.
writeLong
in interface DataOutput
data
- The long value to writeIOException
- If an error occurs(long)
public void writeFloat(float data) throws IOException
DataOutput
float
value to the stream. This
value is written by first calling the method
Float.floatToIntBits
to retrieve an int
representing the floating point number,
then writing this int
value to the stream exactly the same
as the writeInt()
method does.
The value written can be read using the readFloat
method in DataInput
.writeFloat
in interface DataOutput
data
- The float value to writeIOException
- If an error occurs(float)
public void writeDouble(double data) throws IOException
DataOutput
double
value to the stream. This
value is written by first calling the method
Double.doubleToLongBits
to retrieve an long
representing the floating point number,
then writing this long
value to the stream exactly the same
as the writeLong()
method does.
The value written can be read using the readDouble
method in DataInput
.writeDouble
in interface DataOutput
data
- The double value to writeIOException
- If any other error occurs(double)
public void writeBytes(String data) throws IOException
DataOutput
String
out to the
stream. One byte is written for each character in the
String
.
The high eight bits of each character are discarded, thus this
method is inappropriate for completely representing Unicode characters.writeBytes
in interface DataOutput
data
- The String
to writeIOException
- If an error occurs(java.lang.String)
public void writeChars(String data) throws IOException
DataOutput
String
to an
output stream as an array of char
's. Each character
is written using the method specified in the writeChar
method.writeChars
in interface DataOutput
data
- The String to writeIOException
- If an error occurs(java.lang.String)
public void writeUTF(String data) throws IOException
DataOutput
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 Java
short
value in the same manner used by the
writeShort
method. Note that this is the number of
bytes in the
encoded String
not the String
length. Next
come the encoded characters. Each character in the String
is encoded as either one, two or three bytes. For characters in the
range of
to
, one byte is used.
The character
value goes into bits 0-7 and bit eight is 0. For characters in the range
of
to F
, 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