8160406: Collection.toArray() spec should be explicit about returning precisely an Object[]
authorsmarks
Thu, 30 Nov 2017 14:49:36 -0800
changeset 48034 81b5e3f70d98
parent 48033 47b764e0a38a
child 48035 69d409f1b81e
8160406: Collection.toArray() spec should be explicit about returning precisely an Object[] Reviewed-by: psandoz, martin, redestad
src/java.base/share/classes/java/util/Collection.java
--- a/src/java.base/share/classes/java/util/Collection.java	Thu Nov 30 16:38:31 2017 -0500
+++ b/src/java.base/share/classes/java/util/Collection.java	Thu Nov 30 14:49:36 2017 -0800
@@ -192,7 +192,8 @@
      * 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 {@linkplain Class#getComponentType
+     * runtime 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
@@ -202,7 +203,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 {@linkplain Class#getComponentType runtime component
+     * type} is {@code Object}, containing all of the elements in this collection
      */
     Object[] toArray();
 
@@ -239,14 +241,14 @@
      * Note that {@code toArray(new Object[0])} is identical in function to
      * {@code toArray()}.
      *
-     * @param <T> the runtime type of the array to contain the collection
+     * @param <T> the component type of the array to contain the collection
      * @param a the array into which the elements of this collection are to be
      *        stored, if it is big enough; otherwise, a new array of the same
      *        runtime type is allocated for this purpose.
      * @return an array containing all of the elements in this collection
-     * @throws ArrayStoreException if the runtime type of the specified array
-     *         is not a supertype of the runtime type of every element in
-     *         this collection
+     * @throws ArrayStoreException if the runtime type of any element in this
+     *         collection is not assignable to the {@linkplain Class#getComponentType
+     *         runtime component type} of the specified array
      * @throws NullPointerException if the specified array is null
      */
     <T> T[] toArray(T[] a);