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,@serial
,@serialField
, and@serialData
, provide a way to document the serialized form for a Serializable class within the source code.
- The
@serial
tag should be placed in the javadoc comment for a default serializable field. The syntax is as follows:@serial
field-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@serial
provides serialization-specific documentation and is appended to the javadoc comment for the field within the serialized form documentation.- The
@serialField
tag is used to document anObjectStreamField
component of aserialPersistentFields
array. One of these tags should be used for eachObjectStreamField
component. The syntax is as follows:@serialField
field-name field-type field-description- The
@serialData
tag describes the sequences and types of data written or read. The tag describes the sequence and type of optional data written bywriteObject
or all data written by theExternalizable.writeExternal
method. The syntax is as follows:@serialData
data-description
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
writeObject
method of aSerializable
class. Optional data can be read by theSerializable
class'readObject
method 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."