Criteria for Including Classes in the Serialized Form Specification

The criteria for determining if a class should be included in the serialized form specification is:

  • 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.

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

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

Related docs: Writing API Specs , Writing Doc Comments