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

[Martin Buchholz]

Thanks.  This looks good, and finishes the effort started 12 years ago.
Apologies for not having made this spec change myself years ago.

I tried to find a less JLSese way to wordsmith it.  Nearby spec talks about
the "runtime type" of the array.  Maybe s/component/runtime component/ but
I'm not sure that's actually better.

On Wed, Nov 29, 2017 at 4:18 PM, 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/ja
> va/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();
>
>