[TOC] [Prev] [Next]

Class Descriptors

The ObjectStreamClass provides information about classes that are saved in a Serialization stream. The descriptor provides the fully-qualified name of the class and its serialization version UID. A streamVersionUID identifies the unique original class version for which this class is capable of writing streams and from which it can read.

package java.io;

public class ObjectStreamClass
{
	public static ObjectStreamClass lookup(Class cl);

	public String getName();

	public Class forClass();

	public long getSerialVersionUID();

	public String toString();
}

The lookup method returns the ObjectStreamClass descriptor for the specified class in the Java VM. If the class has defined serialVersionUID it is retrieved from the class. If not defined by the class it is computed from the class's definition in the Java Virtual Machine. null is returned if the specified class is not Serializable or Externalizable. Only class descriptions for classes that implement the java.io.Serializable or java.io.Externalizable interfaces can be written to a stream.

The getName method returns the fully-qualified name of the class. The class name is saved in the stream and is used when the class must be loaded.

The forClass method returns the Class in the local Virtual Machine if one is known. Otherwise, it returns null.

The getSerialVersionUID method returns the serialVersionUID of this class. Refer to Stream Unique Identifiers. If not specified by the class, the value returned is a hash computed from the class's name, interfaces, methods, and fields using the Secure Hash Algorithm (SHA) as defined by the National Institute of Standard.

The toString method returns a printable representation of the class descriptor including the class's name and serialVersionUID.

Inspecting Serializable Classes

The program serialver can be used to find out if a class is serializable and to get its serialVersionUID. When invoked with -show it puts up a simple user interface. To find out if a class is serializable and to find out its serialVersionUID, enter its full class name and press either the Enter or the Show button. The string printed can be copied and pasted into the evolved class.

When invoked on the command line with one or more class names, serialver prints the serialVersionUID for each class in a form suitable for copying into an evolving class. When invoked with no arguments, it prints a usage line.

Stream Unique Identifiers

Each versioned class must identify the original class version for which it is capable of writing streams and from which it can read. For example, a versioned class must declare:

	static final long serialVersionUID = 3487495895819393L;

The stream-unique identifier is a 64-bit hash of the class name, interface class names, methods, and fields. The value must be declared in all versions of a class except the first. It may be declared in the original class but is not required. The value is fixed for all compatible classes. If the SUID is not declared for a class, the value defaults to the hash for that class. Classes do not need to anticipate versioning.

The serialVersionUID is computed using the signature of a stream of bytes that reflect the class definition. The National Institute of Standards and Technology (NIST) Secure Hash Algorithm (SHA-1) is used to compute a signature for the stream. The first two 32-bit quantities are used to form a 64-bit hash. A java.lang.DataOutputStream is used to convert primitive data types to a sequence of bytes. The values input to the stream are defined by the Java virtual machine (VM) specification for classes. The sequence of items in the stream is as follows:

The class name written using UTF encoding.
The class modifiers written as a 32-bit integer.
The name of each interface sorted by name written using UTF encoding.
For each field of the class sorted by field name (except private static and private transient fields):
- The name of the field in UTF encoding.
- The modifiers of the field written as an 32-bit integer.
- The descriptor of the field in UTF encoding.
For each method including constructors sorted by method name and signature, except private methods and constructors:
- The name of the method in UTF encoding.
- The modifiers of the method written as an 32-bit integer.
- The descriptor of the method in UTF encoding.
The SHA-1 algorithm is executed on the stream of bytes produced by DataOutputStream and produces five 32-bit values sha[0..4].
The hash value is assembled from the first and second 32-bit values. long hash = sha[1] << 32 + sha[0].

[TOC] [Prev] [Next]