Criteria for Including Classes
in the Serialized Form Specification

The purpose of the Serialized Form specification is to ensure that a serialized object can successfully be passed between different implementations of the Java Platform.

This is Sun's criteria for determining if a class should be included in the serialized form specification:

Public and protected classes
If a class is public or protected and implements Serializable (directly or indirectly through implements or extends) then its serial form must be included in the spec. An example is the public class java.applet.Applet (which indirectly extends Component which implements Serializable).
Private and package-private classes
If a private or package-private class implements Serializable, and a user of a public class can, via a factory method, access that object, and if the spec (doc comment) explicitly guarantees that the object is serializable, then the serial form must be included. An example is the private class java.util.Arrays.ArrayList.

In both cases, rare exceptions can be made where the class in question was never intended to be serialized across implementations or releases. (The excluded Swing classes fall into this category. Swing uses a different mechanism to provide the needed functionality.)

To satisfy this criteria, the design engineer of each class needs to verify whether that class is actually part of the published serialized form of a public or protected API class, rather than just a class used in the implementation that also happens to be serializable.

Note - Interfaces do not have serialized forms, and so would not appear in the Serialized Form specification.

Doc Comment @serial Tag

By default, version 1.3 of Javadoc includes public and protected classes that implement Serializable, and excludes private and package-private classes that implement Serializable. Version 1.3 of Javadoc has no mechanism for excluding the former from or including the latter in the Serialized Form spec, as may be needed in satisfying the above criteria.

We have instituted a mechanism in Javadoc 1.4 for marking serializable classes for inclusion or exclusion in the spec. (We used it for generating the 1.3 serialized form spec, but the mechanism was implemented too late to be included in Javadoc 1.3.) It does the following:

Includes public and protected classes that implement Serializable, unless they or their packages are marked with @serial exclude
Excludes private and package-private classes that implement Serializable, unless they or their packages are marked with @serial include

The Javdaoc 1.4 reference page also describes this.

Contact the Documentation Team

Last modified: Fri Jan 21 12:25:38 PST 2000

Criteria for Including Classes in the Serialized Form Specification

Doc Comment @serial Tag

Criteria for Including Classes
in the Serialized Form Specification