RFR(s): 8133977 add specification for serial form of immutable collections

[Stephen Colebourne]

CollSer should not be public, especially not just for serialization
reasons.

Stuart, I disagree with using an int for the flags, it should be a byte. If
you need future expansion you can use 0xff to indicate it with the parser
reacting accordingly. That is the strategy for JSR 310

Stephen
On 17 May 2016 8:29 a.m., "Peter Levart" <peter.levart at gmail.com> wrote:

Hi Stuart,



On 05/17/2016 12:48 AM, Stuart Marks wrote:

> Hi all,
>
> Please review this changeset that adds specifications of the serialized
> forms (really, a single serialization proxy class) for the immutable
> collections implementation. There are no code changes in this changeset,
> just documentation.
>
> It's somewhat odd, but the class doc for the serialization proxy isn't
> actually included in the serialized-form.html output. I had to jigger
> around the method doc for readResolve() to include some general information
> about the class.
>
> I also added links manually from the List, Map, and Set interfaces to the
> serialized form and vice-versa. I'm not aware of another way for a private
> class to link to its (proxied) serialized form.
>
> I was able to coerce specdiff into giving a diff of serialized-form.html.
> It's not very convenient, though; like serialized-form.html, the html diff
> is one big file. The only difference is the addition of java.util.CollSer.
>
> Webrev:
>
>     http://cr.openjdk.java.net/~smarks/reviews/8133977/webrev.0/
>
> API specdiff:
>
>
>
> http://cr.openjdk.java.net/~smarks/reviews/8133977/specdiff.0/api.specdiff/overview-summary.html
>
> serialized-form.html diff:
>
>
>
> http://cr.openjdk.java.net/~smarks/reviews/8133977/specdiff.0/serial.specdiff/specdiff-summary.html
>
> Thanks,
>
> s'marks
>

Perhaps java.util.CollSer could be promoted to be a public class. It does,
after all, specify the API (serialization form == API). I don't see a point
in hiding it and then jiggering around the method doc for readResolve()...
You could just restrict its use by keeping the constructor(s)
package-private...

What do you think?

Regards, Peter