Bug ID: JDK-4525039 stddoclet: include serialVersionUID in Serialized Forms

Type: Enhancement
Component: tools
Sub-Component: javadoc(tool)
Affected Version: 1.4.0

Priority: P4
Status: Resolved
Resolution: Fixed
OS: generic
CPU: generic

Submitted: 2001-11-08
Updated: 2014-05-05
Resolved: 2002-11-20

Other
1.4.2 mantisFixed

The serialVersionUID should be included in the Serialized Form generated for each class. This is important for a complete specification of serialization.
There might be an issue with determining if a class initializer exists if you need to compute the serialVersionUID, but it seems like it should at least be possible now to include values that have been explicitly specified.

CONVERTED DATA BugTraq+ Release Management Values COMMIT TO FIX: mantis FIXED IN: mantis INTEGRATED IN: mantis mantis-b08
14-06-2004
EVALUATION Check with joe.fialli@east on details ###@###.### 2002-04-26 Doug asked of Josh: >Do I have your blessing to add the serialVersionUID to the Serialized Form > page? Josh wrote: Absolutely. Encouragement, even. It's a bug that it wasn't there. ###@###.### 2002-10-14 Let's go with this format: <CODE><B>serialVersionUID:</B> -5836846270535785031L</CODE> (computed) ###@###.### 2002-10-23 Doclets do not provide enough information to compute the serialVersionUID when none is specified by the user. Specifically, no synthetic fields are visible to the doclet. The method in java.io.ObjectStreamClass can only be used to get that information for currently loaded classes. Javadoc does not operate on loaded classes. ###@###.### 2002-10-23 The serialVersionUID is a long. Here is the one from java.applet.Applet: /* version ID for serialized form. */ private static final long serialVersionUID = -5836846270535785031L; > Can you please confirm who will use the serialVersionUID -- > will it be basically reimplementors of the platform and not developers? With extemely rare exception, this is correct. ###@###.### 2002-10-23 (copied by ###@###.###) Developers will need to know the serialVersionUID of different versions of a class when the exception "InvalidClassException" is thrown by deserialization readObject(). Here is the code that composes the actual exception: throw new InvalidClassException(localDesc.name, "local class incompatible: " + "stream classdesc serialVersionUID = " + suid + ", local class serialVersionUID = " + localDesc.getSerialVersionUID()); An application developer needs to locate the javadoc for the two different versions of the class to figure out which version of the class is in the serialization stream and what version of the class is being found by the classpath in the deserializing JVM. Currently, one needs to run serialver to figure this out. Also, the developer of a an alternative implementation of serializable class needs to know the serialVersionUID of a class so they can place it in their alternative class implementation. They need to type in the same number. Thus, if one wanted to make a clean-room implementation of package java serializable classes, they need to know the serialVersionUID's in those classes. The serialVersionUID's purpose in life is to indicate whether two different version of a class are "serializable-compatible". If one allowed a newer class to not be "serializable-compatible" with a previous version of the serializable class, one would specify a different serialVersionUID in the later version. Since we never formally allow incompatibilities between versions of a class in package Java, this problem never occurs with JDK classes. However, a class designer within an application can make the decision to not preserve serializable compatibility between two different releases of a class. In this instance, the class designer would specify a different serialVersionUID than the previous class. When there is an incompatibility between serialVersionUID between a class description in a serialization stream of data and the serialVersionUID in the class found by the deserializing JVM, an exception is thrown by the readObject method stating mismatched serialVersionUID. The application programmer, not the class designer, needs to look at the actual serialVersionUID to try to determine what version of the class is described in the serialization stream and what version of the class is being found on the classpath. This discrepancy must be resolved. Thus, serialVersionUID is important to state its number. The computed number is quite horrible; however, one could just as easily assign "1" to the first version of the class and bump the "serialVersionUID" if one wishes that two versions of the class are not serializable compatible, i.e. one can not serialize an instance of one version of the class and then deserialize into the incompatible alternative version of the class. People don't like to make classes incompatible obviously, sometimes it is not possible to avoid it when not enough thought was put at first in serializing the first version of the class. Regrettfully, it is too easy to make a class serializable and it is very hard to maintain that contract in the future. Additionally, a novice mistake made by newer users of serialization is to forget to place an explicit serialVersionUID in the follow up release of a class. (Actually, recommendation is to just add the serialVersionUID in the first version of the class but not everyone follows this.) Thus, any change to accessor API's results in a computed incompatible serialVersionUID. This confuses people since the computed serialVersionUID includes much more than just the actual serializable fields. ###@###.### 2002-10-23 (copied by ###@###.###) ccc wrote: Could you please resubmit the above with a modification to the implementation i.e., To only display values that currently exist in the java source and not to generate new serialized VersionUID field. ###@###.### 2002-10-30 I should mention that is it, in general, impossible for javadoc to correctly compute the serialVersionUID. The UID is very sensitive to the compiler used, the version of the compiler used, the set of compiler flags, and the target classfile format. In general javadoc has access to the source but not access to the class file of the class being documented. While the serialVersionUID can be computed from the class, it cannot in general be computed from the source. Therefore I'm afraid that javadoc cannot in general provide the serialVersionUID as part of the documentation when documentation is generated only from source. ###@###.### 2002-10-31 The convention now will be to require class authors to add static fields that define the serialVersionUID, rather than compute it. There is now a warning if this field is missing: ###@###.### wrote: I already implemented this warning in the compiler, and filed 20 bugs against the different areas in J2SE that the 1050 or so resulting warning messages are given. I suppress the diagnostic for exception classes (that is, classes that extend Throwable), because that would have more than doubled the number of warnings. ###@###.### 2002-11-01 Correction: this change was done in an internal development version of the compiler, and will not be in the product until 1.5 at the earliest. ###@###.### 2002-11-01 The serial version UID is now shown in the serialized form for serializable classes that declare it.
01-11-2002
PUBLIC COMMENTS We decided for the value to be displayed as: <CODE><B>serialVersionUID:</B> -5836846270535785031L</CODE> ###@###.### 2002-10-31
31-10-2002
SUGGESTED FIX Within stddoclet when computing the serialized form: If the static field serialVersionUID exists within a Serializable class, the stddoclet needs to output it and its value in javadoc. This was a problem in the past since constant values were not set when accessed in the stddoclet. (The phase of the java compiler that assigns values to constants had not been run yet. Thus, the serialVersionUID was always zero when I originally implemented this, thus I backed off this incomplete implementation.) If the static field serialVersionUID does not exist, the the serialVersionUID computation algorithm needs to be run to produce a serialVersionUID. This method is in java.io.OutputStreamClass. ###@###.### 2002-10-14
14-10-2002

Relates :	JDK-5010245 - Javadoc doesn't specify serialVersionUID for javax.sql.rowset.* classes
Relates :	JDK-4884443 - Javadoc doesn't specify serialVersionUID for several JMX classes
Relates :	JDK-4147326 - Doclet API: Need serialVersionUID to be included in Serialized Form page
Relates :	JDK-4921754 - java.nio exception classes don't specify serialVersionUID
Relates :	JDK-6338881 - Javadoc should provide a way to include a non-constant serialVersionUID in the Serialized Form page