Summary

Clarify the specification of Arrays.asList to include the possibility of ArrayStoreException being thrown.

Problem

The List.set specification includes the throws clause:

ClassCastException - if the class of the specified element prevents it from being added to this list

The complaint is that in these circumstances, ArrayStoreException is thrown instead of ClassCastException.

Solution

Potential solutions are to (1) change the class that implements Arrays.asList() to catch ArrayStoreException and rethrow ClassCastException, or (2) document that ArrayStoreException can also be thrown in a bunch of places where ClassCastException can currently be thrown. Both are untenable.

(1) is a change in behavior that adds to the complexity of the code for essentially no benefit.

(2) is a part of the implementation leaking into the specification in a widespread way. It also interprets the throws-clauses of method specifications to be exclusive in the sense that they describe the only exceptions that are allowed to be thrown by the method, and under only the circumstances that are described. This is not the case. For example, many Collection operations can throw ConcurrentModificationException if the circumstances warrant it, but that exception isn't listed in most of the methods from which it can be thrown.

We interpret the throws-clauses to non-exclusive in that they specify exceptions that can occur under some circumstances, but allow other exceptions to be thrown under other circumstances as well.

The throwing of ArrayStoreException is peculiar to the implementation of Arrays.asList(), and it occurs only in the cases where the array's component type disagrees with that method's type parameter T, which occurs in the return type of List. In such cases, future operations on that list can throw ArrayStoreException.

Specification

Add the following to the normative (that is, not the API Note) section of the Arrays.asList() specification:

 * <p>If the specified array's actual component type differs from the type
 * parameter T, this can result in operations on the returned list throwing an
 * {@code ArrayStoreException}.