[PATCH] JDK-7033681 - Improve the documentation of Arrays.asList (original) (raw)

Mon Aug 20 12:26:07 UTC 2018

     *     List stooges = Arrays.asList("Larry", "Moe",
"Curly");
     * 
 /**
* Returns a fixed-size list backed by the specified array.  (Changes to
* the returned list "write through" to the array.)  This method acts
* as bridge between array-based and collection-based APIs, in
* combination with {@link Collection#toArray}.  The returned list is
* serializable and implements {@link RandomAccess}.
*
* <p>This method also provides a convenient way to create a fixed-size
* Returns a fixed-size list backed by the specified array. The passed
* array is held as a reference in the returned list. Any subsequent
* changes made to the array contents will be visible in the returned
* list. Similarly any changes that happen in the returned list will
* also be visible in the array. The returned list is serializable and
* implements {@link RandomAccess}.
*
* <p>The returned list can be changed only in certain ways. Operations
* like {@code add}, {@code remove}, {@code clear} and other such, that
* change the size of the list aren't allowed. Operations like
* {@code replaceAll}, {@code set}, that change the elements in the list
* are permitted.
*
* <p>This method acts as bridge between array-based and collection-based
* APIs, in combination with {@link Collection#toArray}.
*
* @apiNote
* This method also provides a convenient way to create a fixed-size
* list initialized to contain several elements:
* <pre>
*     List<String> stooges = Arrays.asList("Larry", "Moe", "Curly");
* </pre>
*
* <p>The returned list throws a {@link UnsupportedOperationException} for
* operations that aren't permitted. Certain implementations of the returned
* list might choose to throw the exception only if the call to such methods
* results in an actual change, whereas certain other implementations may
* always throw the exception when such methods are called.
*
* @param <T> the class of the objects in the array
* @param a the array by which the list will be backed
* @return a list view of the specified array