|CONTENTS | PREV | NEXT||Java Object Serialization Specification|
It is important to document the serializable state of a class to enable interoperability with alternative implementations of a Serializable class and to document class evolution. Documenting a serializable field gives one a final opportunity to review whether or not the field should be serializable. The serialization javadoc tags,
@serialData, provide a way to document the serialized form for a Serializable class within the source code.
@serialtag should be placed in the javadoc comment for a default serializable field. The syntax is as follows:
@serialfield-descriptionThe optional field-description describes the meaning of the field and its acceptable values. The field-description can span multiple lines. When a field is added after the initial release, a @since tag indicates the version the field was added. The field-description for
@serialprovides serialization-specific documentation and is appended to the javadoc comment for the field within the serialized form documentation.
@serialFieldtag is used to document an
ObjectStreamFieldcomponent of a
serialPersistentFieldsarray. One of these tags should be used for each
ObjectStreamFieldcomponent. The syntax is as follows:
@serialFieldfield-name field-type field-description
@serialDatatag describes the sequences and types of data written or read. The tag describes the sequence and type of optional data written by
writeObjector all data written by the
Externalizable.writeExternalmethod. The syntax is as follows:
The javadoc application recognizes the serialization javadoc tags and generates a specification for each Serializable and Externalizable class. See Section C.1, "Example Alternate Implementation of java.io.File" for an example that uses these tags.
When a class is declared Serializable, the serializable state of the object is defined by serializable fields (by name and type) plus optional data. Optional data can only be written explicitly by the
writeObjectmethod of a
Serializableclass. Optional data can be read by the
readObjectmethod or serialization will skip unread optional data.
When a class is declared Externalizable, the data that is written to the stream by the class itself defines the serialized state. The class must specify the order, types, and meaning of each datum that is written to the stream. The class must handle its own evolution, so that it can continue to read data written by and write data that can be read by previous versions. The class must coordinate with the superclass when saving and restoring data. The location of the superclasses data in the stream must be specified.
The designer of a Serializable class must ensure that the information saved for the class is appropriate for persistence and follows the serialization-specified rules for interoperability and evolution. Class evolution is explained in greater detail in Chapter 5, "Versioning of Serializable Objects."