RFR: JDK-8192935 Fix EnumSet's SerializationProxy javadoc

[Martin Buchholz]

Interesting.  You are trying to define a new Best Practice for the
Serialization Proxy Pattern.

Serialization is weird/broken in many ways - one of its weirdnesses is
documenting behavior indirectly by publishing javadoc for private (!)
methods (and fixing that would be a huge project (and I'm definitely not
signing up to fix serialization!)).  So the writeReplace and readResolve
methods together describe how to serialize and deserialize these classes.
But the methods are in different classes!  Further, there's the serial spec
for readObject which ensures that bogus serial forms are rejected, which is
another reason to publish a serial form spec for EnumSet.  There's also a
reasonable expectation that public Serializable classes have an entry in
the serialized form page.  So I'd like to go with what I've got.

http://cr.openjdk.java.net/~martin/webrevs/jdk/EnumSet-SerializationProxy/

(I had to modify the BogusEnumSet test, probably due to my added
"transient")


On Fri, Dec 1, 2017 at 5:20 PM, Stuart Marks <stuart.marks at oracle.com>
wrote:

> On 12/1/17 4:42 PM, Martin Buchholz wrote:
>
>>     1. JDK-8192935 <https://bugs.openjdk.java.net/browse/JDK-8192935>
>>
>> http://cr.openjdk.java.net/~martin/webrevs/openjdk10/EnumSet
>> -SerializationProxy/EnumSet-SerializationProxy.patch
>>
>
> --- a/src/java.base/share/classes/java/util/EnumSet.java
> +++ b/src/java.base/share/classes/java/util/EnumSet.java
> @@ -75,7 +75,6 @@
>   * @author Josh Bloch
>   * @since 1.5
>   * @see EnumMap
> - * @serial exclude
>   */
>
> I suspect you're following other examples in the JDK that include the
> serial form documentation for a class that uses a serialization proxy, but
> I think this is a mistake. It's a mistake because this will cause EnumSet
> to appear in serialized-form.html, but EnumSet actually should *never*
> appear in any serialized byte stream. This is quite confusing. I think
> those other places should be fixed, instead.
>
> Instead of including EnumSet itself in the serialized-form.html, how about
> restoring its "@serial exclude" and then putting a link directly from the
> EnumSet class doc to the EnumSet.SerializationProxy serial form doc?
> Something like
>
>  * <p>When an instance of this class is serialized, it is replaced with
> the
>  * serial form of an instance of
>  * <a href="../../serialized-form.html#java.util.EnumSet.SerializationProxy">
>
>  * {@code EnumSet.SerializationProxy}</a>.
>
> The changes to EnumSet.SerializationProxy class are good.
>
> s'marks
>