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

[Stuart Marks]

On 11/24/15 3:17 AM, Chris Hegarty wrote:
> This is looking very good, and simple. Nice.

Great, thanks.

> 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() ?

No, this hasn't come up already. Good catch. I'm clearly too close to this, 
because this is definitely a spec issue that I ought to have addressed earlier.

Thanks to Mohammad Rezaei and Paul Benedict for raising similar concerns.

Taking the zero-element factory methods as an example, we want to permit the 
current implementation, which returns the same instance every time. So we 
clearly don't want to require it to create a *new* instance every time.

But in the hypothetical value-typed future, we might want to return value types 
from at least some of the factory methods. Value types have no notion of 
identity, so we don't want to make any statements that lead to thinking about 
the identity of the returned object, even to the extent of saying that it 
"might" be the "same" instance as one previously returned.

Based on this, it occurs to me that I should add the "value-based" disclaimer to 
the relevant section of class doc. (I also note that, off-line, John Rose had 
already prompted me to do this, so I should heed his advice.)

I'll also change the method docs to say something like,

  * Returns an immutable list containing <N> elements.
  * ...
  * @return a list containing the specified elements

s'marks