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

[Chris Hegarty]

On 17 May 2016, at 09:55, Stephen Colebourne <scolebourne at joda.org> wrote:

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

Right, and I see no reason to refer to it by name in the javadoc, the 
link should be sufficient.

> 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

The JSR 310 Serialization framework is a little more involved, as you know.
I wonder if it is worth following that pattern more closely here? That way
java.util.Ser could be a generic proxy for all new Serializable types in the
java.util package, and not just the immutable collections. The 310 pattern
also results in a reasonable place to document the serial form.

-Chris.

> 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