RFR: 8296935: Arrays.asList().set() with wrong types throws undocumented ArrayStoreException [v7]

[Stuart Marks]

On Mon, 23 Jan 2023 07:33:21 GMT, Tingjun Yuan <duke at openjdk.org> wrote:

>> Document `java.util.Arrays.asList` that the list will throw an `ArrayStoreException` when attempting to set an element with a wrong type.
>
> Tingjun Yuan has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update `implSpec` and remove the docs of the impl.

I've added my recommended text for an apiNote as a comment in the bug report:

https://bugs.openjdk.org/browse/JDK-8296935?focusedCommentId=14555728&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-14555728

Even though this is non-normative text, I'd say it still requires a CSR to document the decision that this issue is NOT a conformance issue. That is, even though the various List methods are documented to throw certain runtime exceptions in various circumstances, an implementation is permitted to throw other runtime exceptions without violating the specification. The flip side is that it's good practice for method specifications to specify what exceptions are thrown in what circumstances, but it's not required for them to specify all exceptions in all circumstances. Indeed, in this specific case, it seems unreasonable to add throwing of ArrayStoreException to all the List methods because of this one edge case of this particular implementation.

-------------

PR: https://git.openjdk.org/jdk/pull/12135