RFR(m): JEP 269 initial API and skeleton implementation (JDK-8139232)

[Chris Hegarty]

Stuart,

This is looking very good, and simple. Nice.

Sorry if this has come up already, but is the "@return the newly
created xxx” too restrictive? Will it require the implementation to
return a NEW instance of xxx for each invocation, even of() ?

-Chris.

On 24 Nov 2015, at 06:26, Stuart Marks <stuart.marks at oracle.com> wrote:

> Hi all,
> 
> Please review these API and implementation changes that comprise the first integration of JEP 269. I intend to push this under the "initial API and skeleton implementation" subtask, JDK-8139232.
> 
> Changes since the previous review:
> - more precise wording regarding static factory methods (thanks Remi)
> - add defensive copy and test for List.of(E...) (thanks Michael Hixson)
> - more null checking and tests
> - various small wording cleanups
> - @since 9
> 
> I've left the fixed-arg overloads at ten for all three interfaces. The fixed-arg methods provide a useful fast path for initialization and non-desktop, non-server cases. The cost is some API clutter; ten elements or pairs is rather a lot. This number should be sufficient, though, to handle the vast majority of cases without having to switch to varargs. Note that the clutter is only in the API definitions, and it doesn't intrude into the point of call (at least for List and Set). For the Map case, it's particularly useful to have lots of fixed-arg overloads, since the varargs case requires switching APIs and adding more boilerplate.
> 
> I've also updated the JEP text to reflect the current proposal, mainly the removal of the static factory methods from the concrete classes.
> 
> JEP:
> 
> 	http://openjdk.java.net/jeps/269
> 
> API spec (basically List, Map, and Set):
> 
> 	http://cr.openjdk.java.net/~smarks/reviews/jep269/api.20151123/
> 
> Specdiff:
> 
> 	http://cr.openjdk.java.net/~smarks/reviews/jep269/specdiff.20151123/overview-summary.html
> 
> Webrev:
> 
> 	http://cr.openjdk.java.net/~smarks/reviews/jep269/webrev.20151123/
> 
> Thanks,
> 
> s'marks