System Architecture

Chapter   1

Topics:

Overview
Writing to an Object Stream
Reading from an Object Stream
Object Streams as Containers
Defining Serializable Fields for a Class
Documenting Serializable Fields and Data for a Class
Accessing Serializable Fields of a Class
The ObjectOutput Interface
The ObjectInput Interface
The Serializable Interface
The Externalizable Interface
Protecting Sensitive Information

1.1 Overview

The ability to store and retrieve Java™ objects is essential to building all but the most transient applications. The key to storing and retrieving objects in a serialized form is representing the state of objects sufficient to reconstruct the object(s). Objects to be saved in the stream may support either the Serializable or the Externalizable interface. For Java™ objects, the serialized form must be able to identify and verify the Java™ class from which the contents of the object were saved and to restore the contents to a new instance. For serializable objects, the stream includes sufficient information to restore the fields in the stream to a compatible version of the class. For Externalizable objects, the class is solely responsible for the external format of its contents.

Objects to be stored and retrieved frequently refer to other objects. Those other objects must be stored and retrieved at the same time to maintain the relationships between the objects. When an object is stored, all of the objects that are reachable from that object are stored as well.

The goals for serializing Java™ objects are to:

Have a simple yet extensible mechanism.
Maintain the Java™ object type and safety properties in the serialized form.
Be extensible to support marshaling and unmarshaling as needed for remote objects.
Be extensible to support simple persistence of Java™ objects.
Require per class implementation only for customization.
Allow the object to define its external format.

1.2 Writing to an Object Stream

Writing objects and primitives to a stream is a straightforward process. For example:

// Serialize today’s date to a file.    
	FileOutputStream f = new FileOutputStream("tmp");    
	ObjectOutput s = new ObjectOutputStream(f);    
	s.writeObject("Today");    
	s.writeObject(new Date());    
	s.flush(); 

First an OutputStream, in this case a FileOutputStream, is needed to receive the bytes. Then an ObjectOutputStream is created that writes to the FileOutputStream. Next, the string “Today” and a Date object are written to the stream. More generally, objects are written with the writeObject method and primitives are written to the stream with the methods of DataOutput.

The writeObject method (see Section 1.3 "The writeObject Method”) serializes the specified object and traverses its references to other objects in the object graph recursively to create a complete serialized representation of the graph. Within a stream, the first reference to any object results in the object being serialized or externalized and the assignment of a handle for that object. Subsequent references to that object are encoded as the handle. Using object handles preserves sharing and circular references that occur naturally in object graphs. Subsequent references to an object use only the handle allowing a very compact representation.

Special handling is required for objects of type Class, ObjectStreamClass, String, and arrays. Other objects must implement either the Serializable or the Externalizable interface to be saved in or restored from a stream.

Primitive data types are written to the stream with the methods in the DataOutput interface, such as writeInt, writeFloat, or writeUTF. Individual bytes and arrays of bytes are written with the methods of OutputStream. Except for serializable fields, primitive data is written to the stream in block-data records, with each record prefixed by a marker and an indication of the number of bytes in the record.

ObjectOutputStream can be extended to customize the information about classes in the stream or to replace objects to be serialized. Refer to the annotateClass and replaceObject method descriptions for details.

1.3 Reading from an Object Stream

Reading an object from a stream, like writing, is straightforward:

// Deserialize a string and date from a file.    
	FileInputStream in = new FileInputStream(“tmp”);    
	ObjectInputStream s = new ObjectInputStream(in);    
	String today = (String)s.readObject();    
	Date date = (Date)s.readObject(); 

First an InputStream, in this case a FileInputStream, is needed as the source stream. Then an ObjectInputStream is created that reads from the InputStream. Next, the string “Today” and a Date object are read from the stream. Generally, objects are read with the readObject method and primitives are read from the stream with the methods of DataInput.

The readObject method deserializes the next object in the stream and traverses its references to other objects recursively to create the complete graph of objects serialized.

Primitive data types are read from the stream with the methods in the DataInput interface, such as readInt, readFloat, or readUTF. Individual bytes and arrays of bytes are read with the methods of InputStream. Except for serializable fields, primitive data is read from block-data records.

ObjectInputStream can be extended to utilize customized information in the stream about classes or to replace objects that have been deserialized. Refer to the resolveClass and resolveObject method descriptions for details.

1.4 Object Streams as Containers

Object Serialization produces and consumes a stream of bytes that contain one or more primitives and objects. The objects written to the stream, in turn, refer to other objects, which are also represented in the stream. Object Serialization produces just one stream format that encodes and stores the contained objects.

Each object that acts as a container implements an interface which allows primitives and objects to be stored in or retrieved from it. These interfaces are the ObjectOutput and ObjectInput interfaces which:

Provide a stream to write to and to read from
Handle requests to write primitive types and objects to the stream
Handle requests to read primitive types and objects from the stream

Each object which is to be stored in a stream must explicitly allow itself to be stored and must implement the protocols needed to save and restore its state. Object Serialization defines two such protocols. The protocols allow the container to ask the object to write and read its state.

To be stored in an Object Stream, each object must implement either the Serializable or the Externalizable interface:

For a Serializable class, Object Serialization can automatically save and restore fields of each class of an object and automatically handle classes that evolve by adding fields or supertypes. A serializable class can declare which of its fields are saved or restored, and write and read optional values and objects.
For an Externalizable class, Object Serialization delegates to the class complete control over its external format and how the state of the supertype(s) is saved and restored.

1.5 Defining Serializable Fields for a Class

The serializable fields of a class can be defined two different ways. Default serializable fields of a class are defined to be the non-transient and non-static fields. This default computation can be overridden by declaring a special field in the Serializable class, serialPersistentFields. This field must be initialized with an array of ObjectStreamField objects that list the names and types of the serializable fields. The modifiers for the field are required to be private, static, and final.

For example, the following declaration duplicates the default behavior.

class List implements Serializable {    
	List next;    
	
	private static final ObjectStreamField[] serialPersistentFields
			= {new ObjectStreamField(“next”, List.class)}; 
} 

By using serialPersistentFields to define the Serializable fields for a class, there no longer is a limitation that a serializable field must be a field within the current definition of the Serializable class. The writeObject and readObject methods of the Serializable class can map the current implementation of the class to the serializable fields of the class using the interface that is described in Section 1.7 "Accessing Serializable Fields of a Class.” Therefore, the fields for a Serializable class can change in a later release, as long as it maintains the mapping back to its Serializable fields that must remain compatible across release boundaries.

package java.io;

public interface ObjectOutput extends DataOutput
{    
	public void writeObject(Object obj) throws IOException;    
	public void write(int b) throws IOException;    
	public void write(byte b[]) throws IOException;     
	public void write(byte b[], int off, int len) throws IOException;    
	public void flush() throws IOException;    
	public void close() throws IOException;
} 

package java.io;

public interface ObjectInput extends DataInput
{    
	public Object readObject()        
		throws ClassNotFoundException, IOException;    
	public int read() throws IOException;    
	public int read(byte b[]) throws IOException;    
	public int read(byte b[], int off, int len) throws IOException;    
	public long skip(long n) throws IOException;    
	public int available() throws IOException;    
	public void close() throws IOException;
} 

package java.io;public interface Serializable {}; 

package java.io;

public interface Externalizable extends Serializable
{    
	public void writeExternal(ObjectOutput out)        
		throws IOException;    
	public void readExternal(ObjectInput in)        
		throws IOException, java.lang.ClassNotFoundException;
}