RFR: JDK-8192935 Fix EnumSet's SerializationProxy javadoc (original) (raw)

Stuart Marks stuart.marks at oracle.com
Mon Dec 4 21:23:49 UTC 2017

On 12/4/17 12:36 PM, Martin Buchholz wrote:

On Mon, Dec 4, 2017 at 12:12 PM, Roger Riggs <Roger.Riggs at oracle.com> wrote:

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

Right. I was aware of the effort that java.time people put into their serialization code. They did a good job, and my proposed change makes it more like theirs (but even more like the ones in j.u.c.a.)

Hi Martin, Roger,

I disagree that the java.time approach is a Best Practice (capitalized), as Martin said, for dealing with documentation of serial proxies. It's a workaround for lack of support for this pattern in the javadoc tool.

Having the redeclare all the fields of EnumSet as transient is evidence of this. (IMO the java.time classes are worse, as they include the fields of objects that are replaced by the proxy.)

Having the original class appear in the serialized form documentation is a bug, since it never appears in the serial form. It sort-of helps define the relationship between the original class and the proxy, but in a confusing, roundabout way.

If you don't like my alternative, fine; it has its own set of tradeoffs that might be net positive or negative. If you want to proceed with the current approach, then I won't stand in the way. At the very least there should be some boilerplate added to EnumSet that makes it clear that EnumSet itself never appears in the serial form.

s'marks

More information about the core-libs-dev mailing list