United StatesChange Country, Oracle Worldwide Web Sites Communities I am a... I want to...
JDK-4525039 : stddoclet: include serialVersionUID in Serialized Forms

Details
Type:
Enhancement
Submit Date:
2001-11-08
Status:
Resolved
Updated Date:
2002-11-20
Project Name:
JDK
Resolved Date:
2002-11-20
Component:
docs
OS:
generic
Sub-Component:
doclet
CPU:
generic
Priority:
P4
Resolution:
Fixed
Affected Versions:
1.4.0
Fixed Versions:
1.4.2 (mantis)

Related Reports
Relates:
Relates:
Relates:
Relates:
Relates:

Sub Tasks

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

                                    

Comments
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
                                     
2002-10-14
PUBLIC COMMENTS

We decided for the value to be displayed as:

  <CODE><B>serialVersionUID:</B> -5836846270535785031L</CODE> 

###@###.### 2002-10-31
                                     
2002-10-31
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.
                                     
2002-11-01
CONVERTED DATA

BugTraq+ Release Management Values

COMMIT TO FIX:
mantis

FIXED IN:
mantis

INTEGRATED IN:
mantis
mantis-b08


                                     
2004-06-14



Hardware and Software, Engineered to Work Together