Java Object Serialization Specification: 3 - Object Input Classes

3.1 The ObjectInputStream Class

Class ObjectInputStream implements object deserialization. It maintains the state of the stream including the set of objects already deserialized. Its methods allow primitive types and objects to be read from a stream written by ObjectOutputStream. It manages restoration of the object and the objects that it refers to from the stream.

package java.io;

public class ObjectInputStream
    extends InputStream
    implements ObjectInput, ObjectStreamConstants
{
    public ObjectInputStream(InputStream in)
        throws StreamCorruptedException, IOException;

    public final Object readObject()
        throws OptionalDataException, ClassNotFoundException,
            IOException;

    public Object readUnshared()
        throws OptionalDataException, ClassNotFoundException,
            IOException;

    public void defaultReadObject()
        throws IOException, ClassNotFoundException,
            NotActiveException;

    public GetField readFields()
        throws IOException;

    public void registerValidation(
        ObjectInputValidation obj, int prio)
        throws NotActiveException, InvalidObjectException;

    protected ObjectStreamClass readClassDescriptor()
        throws IOException, ClassNotFoundException;

    protected Class<?> resolveClass(ObjectStreamClass v)
        throws IOException, ClassNotFoundException;

    protected Class<?> resolveProxyClass(String[] interfaces)
            throws IOException, ClassNotFoundException;
            
    protected Object resolveObject(Object obj)
        throws IOException;

    protected boolean enableResolveObject(boolean enable)
        throws SecurityException;

    protected void readStreamHeader()
        throws IOException, StreamCorruptedException;

    public int read() throws IOException;

    public int read(byte[] data, int offset, int length)
        throws IOException

    public int available() throws IOException;

    public void close() throws IOException;

    public boolean readBoolean() throws IOException;

    public byte readByte() throws IOException;

    public int readUnsignedByte() throws IOException;

    public short readShort() throws IOException;

    public int readUnsignedShort() throws IOException;

    public char readChar() throws IOException;

    public int readInt() throws IOException;

    public long readLong() throws IOException;

    public float readFloat() throws IOException;

    public double readDouble() throws IOException;

    public void readFully(byte[] data) throws IOException;

    public void readFully(byte[] data, int offset, int size)
        throws IOException;

    public int skipBytes(int len) throws IOException;

    public String readLine() throws IOException;

    public String readUTF() throws IOException;

    // Class to provide access to serializable fields.
    public abstract static class GetField
    {
        public abstract ObjectStreamClass getObjectStreamClass();

        public abstract boolean defaulted(String name)
            throws IOException, IllegalArgumentException;

        public abstract char get(String name, char default)
            throws IOException, IllegalArgumentException;

        public abstract boolean get(String name, boolean default)
            throws IOException, IllegalArgumentException;

        public abstract byte get(String name, byte default)
            throws IOException, IllegalArgumentException;

        public abstract short get(String name, short default)
            throws IOException, IllegalArgumentException;

        public abstract int get(String name, int default)
            throws IOException, IllegalArgumentException;

        public abstract long get(String name, long default)
            throws IOException, IllegalArgumentException;

        public abstract float get(String name, float default)
            throws IOException, IllegalArgumentException;

        public abstract double get(String name, double default)
            throws IOException, IllegalArgumentException;

        public abstract Object get(String name, Object default)
            throws IOException, IllegalArgumentException;
    }

    protected ObjectInputStream()
        throws StreamCorruptedException, IOException;

    protected readObjectOverride()
        throws OptionalDataException, ClassNotFoundException,
            IOException;
}

The single-argument ObjectInputStream constructor requires an InputStream. The constructor calls readStreamHeader to read and verifies the header and version written by the corresponding ObjectOutputStream.writeStreamHeader method. If a security manager is installed, this constructor checks for the "enableSubclassImplementation" SerializablePermission when invoked directly or indirectly by the constructor of a subclass which overrides the readFields and/or readUnshared methods.

Note: The ObjectInputStream constructor blocks until it completes reading the serialization stream header. Code which waits for an ObjectInputStream to be constructed before creating the corresponding ObjectOutputStream for that stream will deadlock, since the ObjectInputStream constructor will block until a header is written to the stream, and the header will not be written to the stream until the ObjectOutputStream constructor executes. This problem can be resolved by creating the ObjectOutputStream before the ObjectInputStream, or otherwise removing the timing dependency between completion of ObjectInputStream construction and the creation of the ObjectOutputStream.

The readObject method is used to deserialize an object from the stream. It reads from the stream to reconstruct an object.

  1. If the ObjectInputStream subclass is overriding the implementation, call the readObjectOverride method and return. Reimplementation is described at the end of this section.

  2. If a block data record occurs in the stream, throw a BlockDataException with the number of available bytes.

  3. If the object in the stream is null, return null.

  4. If the object in the stream is a handle to a previous object, return the object.

  5. If the object in the stream is a Class, read its ObjectStreamClass descriptor, add it and its handle to the set of known objects, and return the corresponding Class object.

  6. If the object in the stream is an ObjectStreamClass, read in its data according to the formats described in Section 4.3, "Serialized Form". Add it and its handle to the set of known objects. In versions 1.3 and later of the Java 2 SDK, Standard Edition, the readClassDescriptor method is called to read in the ObjectStreamClass if it represents a class that is not a dynamic proxy class, as indicated in the stream data. If the class descriptor represents a dynamic proxy class, call the resolveProxyClass method on the stream to get the local class for the descriptor; otherwise, call the resolveClass method on the stream to get the local class. If the class cannot be resolved, throw a ClassNotFoundException. Return the resulting ObjectStreamClass object.

  7. If the object in the stream is a String, read its length information followed by the contents of the string encoded in modified UTF-8. For details, refer to Section 6.2, "Stream Elements". Add the String and its handle to the set of known objects, and proceed to Step 13.

  8. If the object in the stream is an array, read its ObjectStreamClass and the length of the array. Allocate the array, and add it and its handle in the set of known objects. Read each element using the appropriate method for its type and assign it to the array. Proceed to Step 13.

  9. If the object in the stream is an enum constant, read its ObjectStreamClass and the enum constant name. If the ObjectStreamClass represents a class that is not an enum type, an InvalidClassException is thrown. Obtain a reference to the enum constant by calling the java.lang.Enum.valueOf method, passing the enum type bound to the received ObjectStreamClass along with the received name as arguments. If the valueOf method throws an IllegalArgumentException, an InvalidObjectException is thrown with the IllegalArgumentException as its cause. Add the enum constant and its handle in the set of known objects, and proceed to Step 13.

  10. For all other objects, the ObjectStreamClass of the object is read from the stream. The local class for that ObjectStreamClass is retrieved. The class must be serializable or externalizable, and must not be an enum type. If the class does not satisfy these criteria, an InvalidClassException is thrown.

  11. If the class is a record class. A handle, with an initial value of null, is added to the set of known objects.

    The record object will be constructed by an invocation of its canonical constructor. The canonical constructor for record class, R, is found by, first building a method descriptor from the number, order, and declared types of the record R's components, as returned by R::getRecordComponents; and then locating R's declared constructor matching the descriptor. If the canonical constructor cannot be found, an InvalidClassException is thrown.

    The contents are restored as follows:

    1. Read and restore all the field values from the stream. Match the stream fields to that of the appropriate constructor parameter, used to initialize the record component. The matching is based on the equality of the name of the stream field and the name of the record component, their names must be identical. That is, for each record component, as returned by Class::getRecordComponents, first determine the components's name, n; and then find the stream value for the stream field whose name equals n. The concrete type of a stream value for a matched field, must be assignable (Class::isAssignableFrom) to that of the type of its matched record component, or else a ClassCastException will be thrown -- all matches are type-checked. Stream fields not matched are effectively discarded.

    2. Invoke the record 's canonical constructor, with the matched stream field values. The stream field values are passed in the corresponding record component positions of the constructor parameters. Unmatched components have the default value appropriate for their type passed. If the constructor invocation throws an exception, an InvalidObjectException is thrown with that exception as its cause. Otherwise, the newly created record object is assigned to its handle of known objects. Proceed to Step 13.

  12. An instance of the class is allocated. The instance and its handle are added to the set of known objects. The contents restored appropriately:

    1. For serializable objects, the no-arg constructor for the first non-serializable supertype is run. For serializable classes, the fields are initialized to the default value appropriate for its type. Then the fields of each class are restored by calling class-specific readObject methods, or if these are not defined, by calling the defaultReadObject method. Note that field initializers and constructors are not executed for serializable classes during deserialization. In the normal case, the version of the class that wrote the stream will be the same as the class reading the stream. In this case, all of the supertypes of the object in the stream will match the supertypes in the currently-loaded class. If the version of the class that wrote the stream had different supertypes than the loaded class, the ObjectInputStream must be more careful about restoring or initializing the state of the differing classes. It must step through the classes, matching the available data in the stream with the classes of the object being restored. Data for classes that occur in the stream, but do not occur in the object, is discarded. For classes that occur in the object, but not in the stream, the class fields are set to default values by default serialization.

    2. For externalizable objects, the no-arg constructor for the class is run and then the readExternal method is called to restore the contents of the object.

  13. Process potential substitutions by the class of the object and/or by a subclass of ObjectInputStream:

    1. If the class of the object is not an enum type and defines the appropriate readResolve method, the method is called to allow the object to replace itself.

    2. Then if previously enabled by enableResolveObject, the resolveObject method is called to allow subclasses of the stream to examine and replace the object. If the previous step did replace the original object, the resolveObject method is called with the replacement object. If a replacement took place, the table of known objects is updated so the replacement object is associated with the handle. The replacement object is then returned from readObject.

All of the methods for reading primitives types only consume bytes from the block data records in the stream. If a read for primitive data occurs when the next item in the stream is an object, the read methods return -1 or the EOFException as appropriate. The value of a primitive type is read by a DataInputStream from the block data record.

The exceptions thrown reflect errors during the traversal or exceptions that occur on the underlying stream. If any exception is thrown, the underlying stream is left in an unknown and unusable state.

When the reset token occurs in the stream, all of the state of the stream is discarded. The set of known objects is cleared.

When the exception token occurs in the stream, the exception is read and a new WriteAbortedException is thrown with the terminating exception as an argument. The stream context is reset as described earlier.

The readUnshared method is used to read "unshared" objects from the stream. This method is identical to readObject, except that it prevents subsequent calls to readObject and readUnshared from returning additional references to the deserialized instance returned by the original call to readUnshared. Specifically:

Deserializing an object via readUnshared invalidates the stream handle associated with the returned object. Note that this in itself does not always guarantee that the reference returned by readUnshared is unique; the deserialized object may define a readResolve method which returns an object visible to other parties, or readUnshared may return a Class object or enum constant obtainable elsewhere in the stream or through external means. If the deserialized object defines a readResolve method and the invocation of that method returns an array, then readUnshared returns a shallow clone of that array; this guarantees that the returned array object is unique and cannot be obtained a second time from an invocation of readObject or readUnshared on the ObjectInputStream, even if the underlying data stream has been manipulated.

The defaultReadObject method is used to read the fields and object from the stream. It uses the class descriptor in the stream to read the fields in the canonical order by name and type from the stream. The values are assigned to the matching fields by name in the current class. Details of the versioning mechanism can be found in Section 5.5, "Compatible Java Type Evolution". Any field of the object that does not appear in the stream is set to its default value. Values that appear in the stream, but not in the object, are discarded. This occurs primarily when a later version of a class has written additional fields that do not occur in the earlier version. This method may only be called from the readObject method while restoring the fields of a class. When called at any other time, the NotActiveException is thrown.

The readFields method reads the values of the serializable fields from the stream and makes them available via the GetField class. The readFields method is only callable from within the readObject method of a serializable class. It cannot be called more than once or if defaultReadObject has been called. The GetFields object uses the current object's ObjectStreamClass to verify the fields that can be retrieved for this class. The GetFields object returned by readFields is only valid during this call to the classes readObject method. The fields may be retrieved in any order. Additional data may only be read directly from stream after readFields has been called.

The registerValidation method can be called to request a callback when the entire graph has been restored but before the object is returned to the original caller of readObject. The order of validate callbacks can be controlled using the priority. Callbacks registered with higher values are called before those with lower values. The object to be validated must support the ObjectInputValidation interface and implement the validateObject method. It is only correct to register validations during a call to a class's readObject method. Otherwise, a NotActiveException is thrown. If the callback object supplied to registerValidation is null, an InvalidObjectException is thrown.

Starting with the Java SDK, Standard Edition, v1.3, the readClassDescriptor method is used to read in all ObjectStreamClass objects. readClassDescriptor is called when the ObjectInputStream expects a class descriptor as the next item in the serialization stream. Subclasses of ObjectInputStream may override this method to read in class descriptors that have been written in non-standard formats (by subclasses of ObjectOutputStream which have overridden the writeClassDescriptor method). By default, this method reads class descriptors according to the format described in Section 6.4, "Grammar for the Stream Format".

The resolveClass method is called while a class is being deserialized, and after the class descriptor has been read. Subclasses may extend this method to read other information about the class written by the corresponding subclass of ObjectOutputStream. The method must find and return the class with the given name and serialVersionUID. The default implementation locates the class by calling the class loader of the closest caller of readObject that has a class loader. If the class cannot be found ClassNotFoundException should be thrown. Prior to JDK 1.1.6, the resolveClass method was required to return the same fully qualified class name as the class name in the stream. In order to accommodate package renaming across releases, method resolveClass only needs to return a class with the same base class name and SerialVersionUID in JDK 1.1.6 and later versions.

The resolveObject method is used by trusted subclasses to monitor or substitute one object for another during deserialization. Resolving objects must be enabled explicitly by calling enableResolveObject before calling readObject for the first object to be resolved. Once enabled, resolveObject is called once for each serializable object just prior to the first time it is being returned from readObject. Note that the resolveObject method is not called for objects of the specially handled classes, Class, ObjectStreamClass, String, and arrays. A subclass's implementation of resolveObject may return a substitute object that will be assigned or returned instead of the original. The object returned must be of a type that is consistent and assignable to every reference of the original object or else a ClassCastException will be thrown. All assignments are type-checked. All references in the stream to the original object will be replaced by references to the substitute object.

The enableResolveObject method is called by trusted subclasses of ObjectOutputStream to enable the monitoring or substitution of one object for another during deserialization. Replacing objects is disabled until enableResolveObject is called with a true value. It may thereafter be disabled by setting it to false. The previous setting is returned. The enableResolveObject method checks if the stream has permission to request substitution during serialization. To ensure that the private state of objects is not unintentionally exposed, only trusted streams may use resolveObject. Trusted classes are those classes with a class loader equal to null or belong to a security protection domain that provides permission to enable substitution.

If the subclass of ObjectInputStream is not considered part of the system domain, a line has to be added to the security policy file to provide to a subclass of ObjectInputStream permission to call enableResolveObject. The SerializablePermission to add is "enableSubstitution". AccessControlException is thrown if the protection domain of the subclass of ObjectStreamClass does not have permission to "enableSubstitution" by calling enableResolveObject. See the document Java Security Architecture (JDK 1.2) for additional information about the security model.

The readStreamHeader method reads and verifies the magic number and version of the stream. If they do not match, the StreamCorruptedMismatch is thrown.

To override the implementation of deserialization, a subclass of ObjectInputStream should call the protected no-arg ObjectInputStream, constructor. There is a security check within the no-arg constructor for SerializablePermission "enableSubclassImplementation" to ensure that only trusted classes are allowed to override the default implementation. This constructor does not allocate any private data for ObjectInputStream and sets a flag that indicates that the final readObject method should invoke the readObjectOverride method and return. All other ObjectInputStream methods are not final and can be directly overridden by the subclass.

3.2 The ObjectInputStream.GetField Class

The class ObjectInputStream.GetField provides the API for getting the values of serializable fields. The protocol of the stream is the same as used by defaultReadObject. Using readFields to access the serializable fields does not change the format of the stream. It only provides an alternate API to access the values which does not require the class to have the corresponding non-transient and non-static fields for each named serializable field. The serializable fields are those declared using serialPersistentFields or if it is not declared the non-transient and non-static fields of the object. When the stream is read the available serializable fields are those written to the stream when the object was serialized. If the class that wrote the stream is a different version not all fields will correspond to the serializable fields of the current class. The available fields can be retrieved from the ObjectStreamClass of the GetField object.

The getObjectStreamClass method returns an ObjectStreamClass object representing the class in the stream. It contains the list of serializable fields.

The defaulted method returns true if the field is not present in the stream. An IllegalArgumentException is thrown if the requested field is not a serializable field of the current class.

Each get method returns the specified serializable field from the stream. I/O exceptions will be thrown if the underlying stream throws an exception. An IllegalArgumentException is thrown if the name or type does not match the name and type of an field serializable field of the current class. The default value is returned if the stream does not contain an explicit value for the field.

3.3 The ObjectInputValidation Interface

This interface allows an object to be called when a complete graph of objects has been deserialized. If the object cannot be made valid, it should throw the ObjectInvalidException. Any exception that occurs during a call to validateObject will terminate the validation process, and the InvalidObjectException will be thrown.

package java.io;

public interface ObjectInputValidation
{
    public void validateObject()
        throws InvalidObjectException;
}

3.4 The readObject Method

For serializable objects, the readObject method allows a class to control the deserialization of its own fields. Here is its signature:

private void readObject(ObjectInputStream stream)
    throws IOException, ClassNotFoundException;

Each subclass of a serializable object may define its own readObject method. If a class does not implement the method, the default serialization provided by defaultReadObject will be used. When implemented, the class is only responsible for restoring its own fields, not those of its supertypes or subtypes.

The readObject method of the class, if implemented, is responsible for restoring the state of the class. The values of every field of the object whether transient or not, static or not are set to the default value for the fields type. Either ObjectInputStream's defaultReadObject or readFields method must be called once (and only once) before reading any optional data written by the corresponding writeObject method; even if no optional data is read, defaultReadObject or readFields must still be invoked once. If the readObject method of the class attempts to read more data than is present in the optional part of the stream for this class, the stream will return -1 for bytewise reads, throw an EOFException for primitive data reads (e.g., readInt, readFloat), or throw an OptionalDataException with the eof field set to true for object reads.

The responsibility for the format, structure, and versioning of the optional data lies completely with the class. The @serialData javadoc tag within the javadoc comment for the readObject method should be used to document the format and structure of the optional data.

If the class being restored is not present in the stream being read, then its readObjectNoData method, if defined, is invoked (instead of readObject); otherwise, its fields are initialized to the appropriate default values. For further detail, see Section 3.5, "The readObjectNoData Method".

Reading an object from the ObjectInputStream is analogous to creating a new object. Just as a new object's constructors are invoked in the order from the superclass to the subclass, an object being read from a stream is deserialized from superclass to subclass. The readObject or readObjectNoData method is called instead of the constructor for each Serializable subclass during deserialization.

One last similarity between a constructor and a readObject method is that both provide the opportunity to invoke a method on an object that is not fully constructed. Any overridable (neither private, static nor final) method called while an object is being constructed can potentially be overridden by a subclass. Methods called during the construction phase of an object are resolved by the actual type of the object, not the type currently being initialized by either its constructor or readObject/readObjectNoData method. Therefore, calling an overridable method from within a readObject or readObjectNoData method may result in the unintentional invocation of a subclass method before the superclass has been fully initialized.

3.5 The readObjectNoData Method

For serializable objects, the readObjectNoData method allows a class to control the initialization of its own fields in the event that a subclass instance is deserialized and the serialization stream does not list the class in question as a superclass of the deserialized object. This may occur in cases where the receiving party uses a different version of the deserialized instance's class than the sending party, and the receiver's version extends classes that are not extended by the sender's version. This may also occur if the serialization stream has been tampered; hence, readObjectNoData is useful for initializing deserialized objects properly despite a "hostile" or incomplete source stream.

private void readObjectNoData() throws ObjectStreamException;

Each serializable class may define its own readObjectNoData method. If a serializable class does not define a readObjectNoData method, then in the circumstances listed above the fields of the class will be initialized to their default values (as listed in The Java Language Specification); this behavior is consistent with that of ObjectInputStream prior to version 1.4 of the Java 2 SDK, Standard Edition, when support for readObjectNoData methods was introduced. If a serializable class does define a readObjectNoData method and the aforementioned conditions arise, then readObjectNoData will be invoked at the point during deserialization when a class-defined readObject method would otherwise be called had the class in question been listed by the stream as a superclass of the instance being deserialized.

3.6 The readExternal Method

Objects implementing java.io.Externalizable must implement the readExternal method to restore the entire state of the object. It must coordinate with its superclasses to restore their state. All of the methods of ObjectInput are available to restore the object's primitive typed fields and object fields.

public void readExternal(ObjectInput stream)
    throws IOException;

Note: The readExternal method is public, and it raises the risk of a client being able to overwrite an existing object from a stream. The class may add its own checks to insure that this is only called when appropriate.

A new stream protocol version has been introduced in JDK 1.2 to correct a problem with Externalizable objects. The old definition of Externalizable objects required the local virtual machine to find a readExternal method to be able to properly read an Externalizable object from the stream. The new format adds enough information to the stream protocol so serialization can skip an Externalizable object when the local readExternal method is not available. Due to class evolution rules, serialization must be able to skip an Externalizable object in the input stream if there is not a mapping for the object using the local classes.

An additional benefit of the new Externalizable stream format is that ObjectInputStream can detect attempts to read more External data than is available, and can also skip by any data that is left unconsumed by a readExternal method. The behavior of ObjectInputStream in response to a read past the end of External data is the same as the behavior when a class-defined readObject method attempts to read past the end of its optional data: bytewise reads will return -1, primitive reads will throw EOFExceptions, and object reads will throw OptionalDataExceptions with the eof field set to true.

Due to the format change, JDK 1.1.6 and earlier releases are not able to read the new format. StreamCorruptedException is thrown when JDK 1.1.6 or earlier attempts to read an Externalizable object from a stream written in PROTOCOL_VERSION_2. Compatibility issues are discussed in more detail in Section 6.3, "Stream Protocol Versions".

3.7 The readResolve Method

For Serializable and Externalizable classes, the readResolve method allows a class to replace/resolve the object read from the stream before it is returned to the caller. By implementing the readResolve method, a class can directly control the types and instances of its own instances being deserialized. The method is defined as follows:

ANY-ACCESS-MODIFIER Object readResolve()
            throws ObjectStreamException;

The readResolve method is called when ObjectInputStream has read an object from the stream and is preparing to return it to the caller. ObjectInputStream checks whether the class of the object defines the readResolve method. If the method is defined, the readResolve method is called to allow the object in the stream to designate the object to be returned. The object returned should be of a type that is compatible with all uses. If it is not compatible, a ClassCastException will be thrown when the type mismatch is discovered.

For example, a Symbol class could be created for which only a single instance of each symbol binding existed within a virtual machine. The readResolve method would be implemented to determine if that symbol was already defined and substitute the preexisting equivalent Symbol object to maintain the identity constraint. In this way the uniqueness of Symbol objects can be maintained across serialization.

Note: The readResolve method is not invoked on the object until the object is fully constructed, so any references to this object in its object graph will not be updated to the new object nominated by readResolve. However, during the serialization of an object with the writeReplace method, all references to the original object in the replacement object's object graph are replaced with references to the replacement object. Therefore in cases where an object being serialized nominates a replacement object whose object graph has a reference to the original object, deserialization will result in an incorrect graph of objects. Furthermore, if the reference types of the object being read (nominated by writeReplace) and the original object are not compatible, the construction of the object graph will raise a ClassCastException.