JDK14 RFR of JDK-8234381: API docs should mention special handling of enums in serialization

[Roger Riggs]

Hi Joe,

The clarification looks fine to me.

Roger


On 11/19/19 1:21 PM, Joe Darcy wrote:
> Hello,
>
> Please review this small doc changes to more explicitly discuss the 
> special handling of enum types by serialization:
>
>     JDK-8234381: API docs should mention special handling of enums in 
> serialization
>     http://cr.openjdk.java.net/~darcy/8234381.0/
>
> Patch below; thanks,
>
> -Joe
>
> --- old/src/java.base/share/classes/java/io/Serializable.java 
> 2019-11-19 10:17:45.803443000 -0800
> +++ new/src/java.base/share/classes/java/io/Serializable.java 
> 2019-11-19 10:17:45.399241001 -0800
> @@ -134,6 +134,11 @@
>   * This readResolve method follows the same invocation rules and
>   * accessibility rules as writeReplace.<p>
>   *
> + * <p>Enum types are all serializable and receive treatment defined by
> + * the <cite>Java Object Serialization Specification</cite> during
> + * serialization and deserialization. Any declarations of the special
> + * handling methods discussed above are ignored for enum types.
> + *
>   * The serialization runtime associates with each serializable class 
> a version
>   * number, called a serialVersionUID, which is used during 
> deserialization to
>   * verify that the sender and receiver of a serialized object have 
> loaded
> @@ -152,8 +157,9 @@
>   * If a serializable class does not explicitly declare a 
> serialVersionUID, then
>   * the serialization runtime will calculate a default 
> serialVersionUID value
>   * for that class based on various aspects of the class, as described 
> in the
> - * Java(TM) Object Serialization Specification.  However, it is 
> <em>strongly
> - * recommended</em> that all serializable classes explicitly declare
> + * Java Object Serialization Specification.  This specification 
> defines the
> + * serialVersionUID of an enum type to be 0L. However, it is 
> <em>strongly
> + * recommended</em> that all serializable classes other than enum 
> types explicitly declare
>   * serialVersionUID values, since the default serialVersionUID 
> computation is
>   * highly sensitive to class details that may vary depending on compiler
>   * implementations, and can thus result in unexpected
> --- old/src/java.base/share/classes/java/lang/Enum.java 2019-11-19 
> 10:17:46.807945000 -0800
> +++ new/src/java.base/share/classes/java/lang/Enum.java 2019-11-19 
> 10:17:46.371727000 -0800
> @@ -47,6 +47,13 @@
>   * found in section 8.9 of
>   * <cite>The Java™ Language Specification</cite>.
>   *
> + * Enumeration types are all serializable and receive special handling
> + * by the serialization mechanism. The serialized representation used
> + * for enum constants cannot be customized. Declarations of methods
> + * and fields that would otherwise interact with serialization are
> + * ignored, including {@code serialVersionUID}; see the <cite>Java
> + * Object Serialization Specification</cite> for details.
> + *
>   * <p> Note that when using an enumeration type as the type of a set
>   * or as the type of the keys in a map, specialized and efficient
>   * {@linkplain java.util.EnumSet set} and {@linkplain
>