 |
Chapter 11 The java.io Package |
 |
|
Chapter 11 The java.io Package |
|
java.io.ObjectOutputStream
java.io.OutputStream
None
java.io.ObjectOutput
New as of JDK 1.1
The ObjectOutputStream class can write both primitive types and object instances to an underlying OutputStream. The objects and other data can then be read by an ObjectInputStream. These two classes provide persistent storage of objects when they are used in conjunction with FileInputStream and FileOutputStream. The classes can also be used with socket streams to pass objects across the network.
Only objects that are instances of classes that implement the Serializable or Externalizable interfaces can be serialized to an output stream. The default serialization mechanism is implemented by writeObject(). When an object is serialized, the class of the object is encoded, along with the class name, the signature of the class, the values of the non-static and non-transient fields of the object, including any other objects referenced by the object (except those that do not implement the Serializable interface themselves). Multiple references to the same object are encoded using a reference sharing mechanism, so that a graph of the object can be restored appropriately. Strings and arrays are objects in Java, so they are treated as objects during serialization.
For example, the following code opens a file called color.ser and writes out a Color object:
FileOutputStream fileOut;
ObjectOutputStream out;
try {
fileOut = new FileOutputStream("color.ser");
out = new ObjectOutputStream(fileOut);
out.writeObject(Color.blue);
out.close();
}
catch (IOException e) {
System.out.println("Error writing: " + e);
}
Classes that require special handling during serialization and deserialization must implement the following methods (with these exact signatures):
private void readObject(ObjectOutputStream stream)
throws IOException, ClassNotFoundException
private void writeObject(ObjectOutputStream stream) throws IOException
The writeObject() method is responsible for writing the state of the object for the particular class so that it can be restored by readObject(). The writeObject() method does not need to handle writing the state for the object's superclass or any of its subclasses except in the case where the superclass does not itself implement the Serializable interface. In this case, the nonserializable class must have a no-argument constructor that can be called to initialize its fields, and it is the responsibility of the subclass to save the state of its superclass.
A class that inherits the implementation of Serializable prevents itself from being serialized by defining readObject() and writeObject() methods that throw NotSerializableException objects.
If a class needs complete control over the contents and formatting of the serialized form of its objects, it should implement the Externalizable interface.
public class java.io.ObjectOutputStream extends java.io.OutputStream
implements java.io.ObjectOutput {
// Constructors
public ObjectOutputStream(OutputStream out);
// Instance Methods
public void close();
public final void defaultWriteObject();
public void flush();
public void reset();
public void write(int data);
public void write(byte[] b);
public void write(byte[] b, int off, int len);
public void writeBoolean(boolean data);
public void writeByte(int data);
public void writeBytes(String data);
public void writeChar(int data);
public void writeChars(String data);
public void writeDouble(double data);
public void writeFloat(float data);
public void writeInt(int data);
public void writeLong(long data);
public final void writeObject(Object obj);
public void writeShort(int data);
public void writeUTF(String data);
// Protected Instance Methods
protected void annotateClass(Class cl);
protected void drain();
protected final boolean enableReplaceObject(boolean enable);
protected Object replaceObject(Object obj);
protected void writeStreamHeader();
}
The underlying output stream.
If any kind of I/O error occurs.
This constructor creates an ObjectOutputStream that writes to the given output stream. The constructor writes the stream header, which consists of a magic number and version number, in preparation for serialization.
If any kind of I/O error occurs.
ObjectOutput.close()
OutputStream.close()
This method closes the stream and releases any system resources that are associated with it.
If any kind of I/O error occurs.
If serialization is not active.
This method writes the fields of the object that are not static or transient. The method can only be called from the private writeObject() method of an object that is being serialized; it throws a NotActiveException if it is called at any other time. This method implements the default serialization mechanism.
If any kind of I/O error occurs.
ObjectOutput.flush()
OutputStream.flush()
This method takes any buffered output and forces it to be written to the underlying stream.
If any kind of I/O error occurs.
This method sets the state of the ObjectOutputStream to the same state as when it was created. As objects are serialized to the stream, the ObjectOutputStream remembers which ones are already serialized. If the program requests that already serialized objects be written again, the ObjectOutputStream just writes out a reference to the previous object. Calling reset() causes the ObjectOutputStream to forget what it has done before, so all subsequent objects are fully serialized.
The value to write.
If any kind of I/O error occurs.
ObjectOutput.write(int)
OutputStream.write(int)
This method writes the lowest eight bits of b to the underlying stream as a byte.
An array of bytes to write.
If any kind of I/O error occurs.
ObjectOutput.write(byte[])
OutputStream.write(byte[])
This method writes the given array of bytes to the underlying stream.
An array of bytes to write to the stream.
An offset into the byte array.
The number of bytes to write.
If any kind of I/O error occurs.
ObjectOutput.write(byte[], int, int)
OutputStream.write(byte[], int, int)
This method writes len bytes from the given array, starting off elements from the beginning of the array, to the underlying stream.
The boolean value to write.
If any kind of I/O error occurs.
DataOutput.writeBoolean()
If data is true, this method writes a byte that contains the value 1 to the underlying stream. If data is false, the method writes a byte that contains the value 0.
The value to write.
If any kind of I/O error occurs.
DataOutput.writeByte()
This method writes an 8-bit byte to the underlying stream, using the lowest eight bits of the given integer data.
The String to write.
If any kind of I/O error occurs.
DataOutput.writeBytes()
This method writes the characters in the given String to the underlying stream as a sequence of 8-bit bytes. The high-order bytes of the characters in the string are ignored.
The value to write.
If any kind of I/O error occurs.
DataOutput.writeChar()
This method writes a 16-bit char to the underlying stream, using the lowest two bytes of the given integer data.
The String to write.
If any kind of I/O error occurs.
DataOutput.writeChars()
This method writes the characters in the given String object to the underlying stream as a sequence of 16-bit characters.
The double value to write.
If any kind of I/O error occurs.
DataOutput.writeDouble()
This method writes a 64-bit double to the underlying stream. The double value is converted to a long using doubleToLongBits() of Double; the long value is then written to the underlying stream as eight bytes with the highest byte first.
The float value to write.
If any kind of I/O error occurs.
DataOutput.writeFloat()
This method writes a 32-bit float to the underlying stream. The float value is converted to a int using floatToIntBits() of Float; the int value is then written to the underlying stream as four bytes with the highest byte first.
The int value to write.
If any kind of I/O error occurs.
DataOutput.writeInt()
This method writes a 32-bit int to the underlying stream. The value is written as four bytes with the highest byte first.
The long value to write.
If any kind of I/O error occurs.
DataOutput.writeLong()
This method writes a 64-bit long to the underlying stream. The value is written as eight bytes with the highest byte first.
public final void writeObject(Object obj) throws IOException, InvalidClassException, NotSerializableException
The object to be serialized.
If there is a problem with the class of the object.
If the object does not implement Serializable or Externalizable.
If any kind of I/O error occurs.
ObjectOutput.writeObject()
This method serializes the given object to the stream. The class of the object is encoded, along with the class name, the signature of the class, the values of the non-static and non-transient fields of the object, including any other objects referenced by the object (except those that do not implement the Serializable interface themselves). Multiple references to the same object are encoded using a reference sharing mechanism, so that a graph of object can be restored appropriately.
The value to write.
If any kind of I/O error occurs.
DataOutput.writeShort()
This method writes a 16-bit short to the underlying stream, using the lowest two bytes of the given integer data.
The String to write.
If any kind of I/O error occurs.
DataOutput.writeUTF()
This method writes the given String to the underlying stream using the UTF-8 encoding. See the description of DataOutputStream.writeUTF(String) for more information.
The class to be serialized.
If any kind of I/O error occurs.
This method is called once for each unique class during serialization. The implementation in ObjectOutputStream does nothing; subclasses can override this method to write out more information about a class. A corresponding subclass of ObjectInputStream should override the resolveClass() method to read the extra class information.
If any kind of I/O error occurs.
This method is a helper method for flush(). It forces a write of any buffered data in the ObjectOutputStream, but does not call flush() on the underlying stream.
protected final boolean enableReplaceObject(boolean enable) throws SecurityException
A boolean value that specifies whether or not object replacement is enabled.
true if object replacement was previously enabled; false otherwise.
If enable is true and getClassLoader()called on the class of the stream does not return null.
This method determines if a trusted subclass of ObjectOutputStream is allowed to replace serialized objects. If the method is called with true, replacement is enabled. Each time an object is serialized, replaceObject() is called to give the ObjectOutputStream a chance to replace the object. A trusted stream is one whose class has no ClassLoader.
The object to be replaced.
A replacement for the given object.
If any kind of I/O error occurs.
If object replacement is enabled for this ObjectOutputStream (see enableReplaceObject()), this method is called with each object to be serialized to give the stream a chance to replace the object. In ObjectOutputStream, this method simply returns the object that was passed to it. Subclasses can override this method to provide more useful functionality.
If any kind of I/O error occurs.
This method writes the serialization stream header, which consists of a magic number and a version number. This method is called by the constructor for ObjectOutputStream. If you subclass ObjectOutputStream, you can override this method to provide your own stream header.
| Method | Inherited From | Method | Inherited From |
|---|---|---|---|
|
clone() |
Object |
equals(Object) |
Object |
|
finalize() |
Object |
getClass() |
Object |
|
hashCode() |
Object |
notify() |
Object |
|
notifyAll() |
Object |
toString() |
Object |
|
wait() |
Object |
wait(long) |
Object |
|
wait(long, int) |
Object |
Class, DataOutput, Double, Externalizable, Float, InvalidClassException, IOException, NotActiveException, NotSerializableException, ObjectInputStream, ObjectOutput, OutputStream, SecurityException, Serializable, String
|
 |
|
| ObjectOutput |  |
ObjectStreamClass |
