RFR: JDK-8192935 Fix EnumSet's SerializationProxy javadoc

[Roger Riggs]

Hi Martin,

The java.time APIs refined the pattern used for Serialization proxies to 
document the relationship between
the original class and its serialization proxies methods.

It is important the EnumSet appear in the serialized form to document 
the behavior
that it should no appear in the stream and to provide links to the 
expected serial proxy type
and its behaviors.  The SerializationProxy (though a private class) is 
part of the public API for serialization.

EnumSet should have a serialVersion uid anyway; to avoid the kind of 
touchup needed in the test.
(And you would not need to suppress the warning). There is no harm in it 
having a fixed suid.

452: SerializationProxy.readResolve doesn't need the comment about 
elementType.cast
since EnumSet.add method checks each element that is added.

Regards, Roger


On 12/4/2017 2:45 PM, Martin Buchholz wrote:
> 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
>>