Arrays.asList returned List - Its modifying/write-through semantics

[Stuart Marks]

On 8/16/18 1:38 AM, Jaikiran Pai wrote:
>>> [1] https://bugs.openjdk.java.net/browse/JDK-7033681
> 
> Is this JIRA/change, something that I can contribute? If so, what would
> be the typical process for that? I have signed and approved OCA, but I
> don't know what's involved in submitting changes which involve javadoc
> changes - does this need CSR and will that CSR have to be filed after I
> submit the initial draft of the changed javadoc?

Hi Jaikiran,

I've unhidden some old comments, and I've added some new comments to 
JDK-7033681; please take a look. I was half-intending to fix this myself, but 
since you're volunteering, you're welcome to take a crack at it.

Note that while this is changing javadoc and doc comments the task is quite a 
bit more rigorous than merely updating documentation. The javadoc for public 
Java SE APIs is a *specification* and requires very precise language. It's not 
unusual for what are apparently small changes to go through several rounds of 
review. (Sorry if you already know this, but I wanted to make sure.)

Whether this requires a CSR depends on whether any normative text of the 
specification is changed. A simple clarification ("API note") can be added 
without a CSR. As the wording stands now, however, it seems like there is a 
mixture of normative and informative statements in the text; these should be 
teased apart and the informative statements placed into an API note. In 
addition, the normative text could probably be reworded to be more clear. (See 
my comments in the bug.) Such changes would probably need a CSR, even though 
they wouldn't actually change the intent of the specification.

If you're still with me, then dive right in! It'll probably be easiest to 
exchange drafts on the email list. I don't think a webrev is necessary, at least 
not yet. Once we've converged on final wording, I can help you file a CSR and 
push the change.

**

Regarding how mutator methods sometimes throw UOE and sometimes do not, this is 
an unfortunate inconsistency in the collections implementations. For example, 
consider the jshell transcript I've appended below. Some implementations throw 
UOE only if an actual mutation were to occur, whereas other implementations 
unconditionally throw UOE whenever a mutator method is called, even if it 
wouldn't result in any actual mutation. Personally, I prefer the stricter 
approach; the unmodifiable collections I added recently all behave strictly. 
However, other implementations do not, and we've been reluctant to change their 
behavior because of the possibility of introducing exceptions into previously 
working (but likely buggy, or at least sloppy) code.

Note that the behavior of the collections is *not* specified to this level of 
detail. It's unfortunately left rather vague, but I think it has to be this way, 
since different collections implementations have diverse behaviors.

Thanks,

s'marks




jshell> Arrays.asList("a")
$26 ==> [a]

jshell> $26.remove("b")
$27 ==> false

jshell> Collections.singletonList("a")
$28 ==> [a]

jshell> $28.remove("b")
$29 ==> false

jshell> Collections.unmodifiableList(Arrays.asList("a"))
$30 ==> [a]

jshell> $30.remove("b")
|  Exception java.lang.UnsupportedOperationException
|        at Collections$UnmodifiableCollection.remove (Collections.java:1061)
|        at (#31:1)

jshell> List.of("a")
$32 ==> [a]

jshell> $32.remove("b")
|  Exception java.lang.UnsupportedOperationException
|        at ImmutableCollections.uoe (ImmutableCollections.java:71)
|        at ImmutableCollections$AbstractImmutableCollection.remove 
(ImmutableCollections.java:78)
|        at (#33:1)