RFR(s): 8160406: Collection.toArray() spec should be explicit about returning precisely an Object[]

[Paul Sandoz]

+1

Paul.

> On 29 Nov 2017, at 16:18, Stuart Marks <stuart.marks at oracle.com> wrote:
> 
> Hi all,
> 
> Please review this small spec change / clarification regarding Collection.toArray(). The runtime type of the array returned has always been intended to be exactly Object[] and not an array of some subtype. This requirement is actually implied by the spec already, but in the wrong place; the spec for
> 
>    <T> T[] toArray​(T[] a)
> 
> says
> 
>> Note that toArray(new Object[0]) is identical in function to toArray().
> 
> Clearly, this should also be specified on toArray() itself.
> 
> Patch is below.
> 
> Thanks,
> 
> s'marks
> 
> 
> 
> diff -r 9bb771005928 -r c3d5e370e06f src/java.base/share/classes/java/util/Collection.java
> --- a/src/java.base/share/classes/java/util/Collection.java	Tue Nov 28 17:14:30 2017 -0800
> +++ b/src/java.base/share/classes/java/util/Collection.java	Wed Nov 29 14:29:14 2017 -0800
> @@ -268,7 +268,7 @@
>      * Returns an array containing all of the elements in this collection.
>      * If this collection makes any guarantees as to what order its elements
>      * are returned by its iterator, this method must return the elements in
> -     * the same order.
> +     * the same order. The returned array's component type is {@code Object}.
>      *
>      * <p>The returned array will be "safe" in that no references to it are
>      * maintained by this collection.  (In other words, this method must
> @@ -278,7 +278,8 @@
>      * <p>This method acts as bridge between array-based and collection-based
>      * APIs.
>      *
> -     * @return an array containing all of the elements in this collection
> +     * @return an array, whose component type is {@code Object}, containing all
> +     * of the elements in this collection
>      */
>     Object[] toArray();
>