RFR: JDK-8192935 Fix EnumSet's SerializationProxy javadoc

[Roger Riggs]

Correction below.

On 12/4/2017 3:12 PM, Roger Riggs wrote:
> 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.
Never mind, the proxy's suid has nothing to do with the BogusEnumSet 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
>>>
>