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

[Peter Levart]

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