JDK17升级21，java.util 的更新

Author: diguage

src/jdk/java.base/java/util/AbstractCollection.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -25,33 +25,37 @@
 
 package java.util;
 
+import jdk.internal.util.ArraysSupport;
+
 /**
- * This class provides a skeletal implementation of the <tt>Collection</tt>
+ * This class provides a skeletal implementation of the {@code Collection}
  * interface, to minimize the effort required to implement this interface. <p>
  *
  * To implement an unmodifiable collection, the programmer needs only to
- * extend this class and provide implementations for the <tt>iterator</tt> and
- * <tt>size</tt> methods.  (The iterator returned by the <tt>iterator</tt>
- * method must implement <tt>hasNext</tt> and <tt>next</tt>.)<p>
+ * extend this class and provide implementations for the {@code iterator} and
+ * {@code size} methods.  (The iterator returned by the {@code iterator}
+ * method must implement {@code hasNext} and {@code next}.)<p>
  *
  * To implement a modifiable collection, the programmer must additionally
- * override this class's <tt>add</tt> method (which otherwise throws an
- * <tt>UnsupportedOperationException</tt>), and the iterator returned by the
- * <tt>iterator</tt> method must additionally implement its <tt>remove</tt>
+ * override this class's {@code add} method (which otherwise throws an
+ * {@code UnsupportedOperationException}), and the iterator returned by the
+ * {@code iterator} method must additionally implement its {@code remove}
  * method.<p>
  *
  * The programmer should generally provide a void (no argument) and
- * <tt>Collection</tt> constructor, as per the recommendation in the
- * <tt>Collection</tt> interface specification.<p>
+ * {@code Collection} constructor, as per the recommendation in the
+ * {@code Collection} interface specification.<p>
  *
  * The documentation for each non-abstract method in this class describes its
  * implementation in detail.  Each of these methods may be overridden if
  * the collection being implemented admits a more efficient implementation.<p>
  *
  * This class is a member of the
- * <a href="{@docRoot}/../technotes/guides/collections/index.html">
+ * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
  * Java Collections Framework</a>.
  *
+ * @param <E> the type of elements in this collection
+ *
  * @author  Josh Bloch
  * @author  Neal Gafter
  * @see Collection
@@ -80,7 +84,8 @@ protected AbstractCollection() {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns <tt>size() == 0</tt>.
+     * @implSpec
+     * This implementation returns {@code size() == 0}.
      */
     public boolean isEmpty() {
         return size() == 0;
@@ -89,7 +94,8 @@ public boolean isEmpty() {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over the elements in the collection,
+     * @implSpec
+     * This implementation iterates over the elements in the collection,
      * checking each element in turn for equality with the specified element.
      *
      * @throws ClassCastException   {@inheritDoc}
@@ -112,7 +118,8 @@ public boolean contains(Object o) {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns an array containing all the elements
+     * @implSpec
+     * This implementation returns an array containing all the elements
      * returned by this collection's iterator, in the same order, stored in
      * consecutive elements of the array, starting with index {@code 0}.
      * The length of the returned array is equal to the number of elements
@@ -146,7 +153,8 @@ public Object[] toArray() {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns an array containing all the elements
+     * @implSpec
+     * This implementation returns an array containing all the elements
      * returned by this collection's iterator in the same order, stored in
      * consecutive elements of the array, starting with index {@code 0}.
      * If the number of elements returned by the iterator is too large to
@@ -199,14 +207,6 @@ public <T> T[] toArray(T[] a) {
         return it.hasNext() ? finishToArray(r, it) : r;
     }
 
-    /**
-     * The maximum size of array to allocate.
-     * Some VMs reserve some header words in an array.
-     * Attempts to allocate larger arrays may result in
-     * OutOfMemoryError: Requested array size exceeds VM limit
-     */
-    private static final int MAX_ARRAY_SIZE = Integer.MAX_VALUE - 8;
-
     /**
      * Reallocates the array being used within toArray when the iterator
      * returned more elements than expected, and finishes filling it from
@@ -219,38 +219,29 @@ public <T> T[] toArray(T[] a) {
      */
     @SuppressWarnings("unchecked")
     private static <T> T[] finishToArray(T[] r, Iterator<?> it) {
-        int i = r.length;
+        int len = r.length;
+        int i = len;
         while (it.hasNext()) {
-            int cap = r.length;
-            if (i == cap) {
-                int newCap = cap + (cap >> 1) + 1;
-                // overflow-conscious code
-                if (newCap - MAX_ARRAY_SIZE > 0)
-                    newCap = hugeCapacity(cap + 1);
-                r = Arrays.copyOf(r, newCap);
+            if (i == len) {
+                len = ArraysSupport.newLength(len,
+                        1,             /* minimum growth */
+                        (len >> 1) + 1 /* preferred growth */);
+                r = Arrays.copyOf(r, len);
             }
             r[i++] = (T)it.next();
         }
         // trim if overallocated
-        return (i == r.length) ? r : Arrays.copyOf(r, i);
-    }
-
-    private static int hugeCapacity(int minCapacity) {
-        if (minCapacity < 0) // overflow
-            throw new OutOfMemoryError
-                ("Required array size too large");
-        return (minCapacity > MAX_ARRAY_SIZE) ?
-            Integer.MAX_VALUE :
-            MAX_ARRAY_SIZE;
+        return (i == len) ? r : Arrays.copyOf(r, i);
     }
 
     // Modification Operations
 
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation always throws an
-     * <tt>UnsupportedOperationException</tt>.
+     * @implSpec
+     * This implementation always throws an
+     * {@code UnsupportedOperationException}.
      *
      * @throws UnsupportedOperationException {@inheritDoc}
      * @throws ClassCastException            {@inheritDoc}
@@ -265,13 +256,14 @@ public boolean add(E e) {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over the collection looking for the
+     * @implSpec
+     * This implementation iterates over the collection looking for the
      * specified element.  If it finds the element, it removes the element
      * from the collection using the iterator's remove method.
      *
      * <p>Note that this implementation throws an
-     * <tt>UnsupportedOperationException</tt> if the iterator returned by this
-     * collection's iterator method does not implement the <tt>remove</tt>
+     * {@code UnsupportedOperationException} if the iterator returned by this
+     * collection's iterator method does not implement the {@code remove}
      * method and this collection contains the specified object.
      *
      * @throws UnsupportedOperationException {@inheritDoc}
@@ -304,10 +296,11 @@ public boolean remove(Object o) {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over the specified collection,
+     * @implSpec
+     * This implementation iterates over the specified collection,
      * checking each element returned by the iterator in turn to see
      * if it's contained in this collection.  If all elements are so
-     * contained <tt>true</tt> is returned, otherwise <tt>false</tt>.
+     * contained {@code true} is returned, otherwise {@code false}.
      *
      * @throws ClassCastException            {@inheritDoc}
      * @throws NullPointerException          {@inheritDoc}
@@ -323,11 +316,12 @@ public boolean containsAll(Collection<?> c) {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over the specified collection, and adds
+     * @implSpec
+     * This implementation iterates over the specified collection, and adds
      * each object returned by the iterator to this collection, in turn.
      *
      * <p>Note that this implementation will throw an
-     * <tt>UnsupportedOperationException</tt> unless <tt>add</tt> is
+     * {@code UnsupportedOperationException} unless {@code add} is
      * overridden (assuming the specified collection is non-empty).
      *
      * @throws UnsupportedOperationException {@inheritDoc}
@@ -349,14 +343,15 @@ public boolean addAll(Collection<? extends E> c) {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over this collection, checking each
+     * @implSpec
+     * This implementation iterates over this collection, checking each
      * element returned by the iterator in turn to see if it's contained
      * in the specified collection.  If it's so contained, it's removed from
-     * this collection with the iterator's <tt>remove</tt> method.
+     * this collection with the iterator's {@code remove} method.
      *
      * <p>Note that this implementation will throw an
-     * <tt>UnsupportedOperationException</tt> if the iterator returned by the
-     * <tt>iterator</tt> method does not implement the <tt>remove</tt> method
+     * {@code UnsupportedOperationException} if the iterator returned by the
+     * {@code iterator} method does not implement the {@code remove} method
      * and this collection contains one or more elements in common with the
      * specified collection.
      *
@@ -383,14 +378,15 @@ public boolean removeAll(Collection<?> c) {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over this collection, checking each
+     * @implSpec
+     * This implementation iterates over this collection, checking each
      * element returned by the iterator in turn to see if it's contained
      * in the specified collection.  If it's not so contained, it's removed
-     * from this collection with the iterator's <tt>remove</tt> method.
+     * from this collection with the iterator's {@code remove} method.
      *
      * <p>Note that this implementation will throw an
-     * <tt>UnsupportedOperationException</tt> if the iterator returned by the
-     * <tt>iterator</tt> method does not implement the <tt>remove</tt> method
+     * {@code UnsupportedOperationException} if the iterator returned by the
+     * {@code iterator} method does not implement the {@code remove} method
      * and this collection contains one or more elements not present in the
      * specified collection.
      *
@@ -417,15 +413,16 @@ public boolean retainAll(Collection<?> c) {
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over this collection, removing each
-     * element using the <tt>Iterator.remove</tt> operation.  Most
+     * @implSpec
+     * This implementation iterates over this collection, removing each
+     * element using the {@code Iterator.remove} operation.  Most
      * implementations will probably choose to override this method for
      * efficiency.
      *
      * <p>Note that this implementation will throw an
-     * <tt>UnsupportedOperationException</tt> if the iterator returned by this
-     * collection's <tt>iterator</tt> method does not implement the
-     * <tt>remove</tt> method and this collection is non-empty.
+     * {@code UnsupportedOperationException} if the iterator returned by this
+     * collection's {@code iterator} method does not implement the
+     * {@code remove} method and this collection is non-empty.
      *
      * @throws UnsupportedOperationException {@inheritDoc}
      */
@@ -444,8 +441,8 @@ public void clear() {
      * Returns a string representation of this collection.  The string
      * representation consists of a list of the collection's elements in the
      * order they are returned by its iterator, enclosed in square brackets
-     * (<tt>"[]"</tt>).  Adjacent elements are separated by the characters
-     * <tt>", "</tt> (comma and space).  Elements are converted to strings as
+     * ({@code "[]"}).  Adjacent elements are separated by the characters
+     * {@code ", "} (comma and space).  Elements are converted to strings as
      * by {@link String#valueOf(Object)}.
      *
      * @return a string representation of this collection