Explicit explanation that no resize/rehash operations will be needed

See gh-25349

Author: jhoeller

spring-core/src/main/java/org/springframework/util/CollectionUtils.java

@@ -73,33 +73,36 @@ public static boolean isEmpty(@Nullable Map<?, ?> map) {
 
 	/**
 	 * Instantiate a new {@link HashMap} with an initial capacity
-	 * that can accommodate the given number of elements.
+	 * that can accommodate the specified number of elements without
+	 * any immediate resize/rehash operations to be expected.
 	 * <p>This differs from the regular {@link HashMap} constructor
 	 * which takes an initial capacity relative to a load factor
 	 * but is effectively aligned with the JDK's
 	 * {@link java.util.concurrent.ConcurrentHashMap#ConcurrentHashMap(int)}.
-	 * @param expectedSize the expected number of elements
+	 * @param expectedSize the expected number of elements (with a corresponding
+	 * capacity to be derived so that no resize/rehash operations are needed)
 	 * @since 5.3
 	 * @see #newLinkedHashMap(int)
 	 */
-	@SuppressWarnings({"rawtypes", "unchecked"})
 	public static <K, V> HashMap<K, V> newHashMap(int expectedSize) {
-		return new HashMap((int) (expectedSize / DEFAULT_LOAD_FACTOR), DEFAULT_LOAD_FACTOR);
+		return new HashMap<>((int) (expectedSize / DEFAULT_LOAD_FACTOR), DEFAULT_LOAD_FACTOR);
 	}
 
 	/**
 	 * Instantiate a new {@link LinkedHashMap} with an initial capacity
-	 * that can accommodate the given number of elements.
+	 * that can accommodate the specified number of elements without
+	 * any immediate resize/rehash operations to be expected.
 	 * <p>This differs from the regular {@link LinkedHashMap} constructor
 	 * which takes an initial capacity relative to a load factor but is
 	 * aligned with Spring's own {@link LinkedCaseInsensitiveMap} and
 	 * {@link LinkedMultiValueMap} constructor semantics as of 5.3.
-	 * @param expectedSize the expected number of elements
+	 * @param expectedSize the expected number of elements (with a corresponding
+	 * capacity to be derived so that no resize/rehash operations are needed)
 	 * @since 5.3
+	 * @see #newHashMap(int)
 	 */
-	@SuppressWarnings({"rawtypes", "unchecked"})
 	public static <K, V> LinkedHashMap<K, V> newLinkedHashMap(int expectedSize) {
-		return new LinkedHashMap((int) (expectedSize / DEFAULT_LOAD_FACTOR), DEFAULT_LOAD_FACTOR);
+		return new LinkedHashMap<>((int) (expectedSize / DEFAULT_LOAD_FACTOR), DEFAULT_LOAD_FACTOR);
 	}
 
 	/**

spring-core/src/main/java/org/springframework/util/LinkedCaseInsensitiveMap.java

@@ -81,14 +81,17 @@ public LinkedCaseInsensitiveMap() {
 	 * @see #convertKey(String)
 	 */
 	public LinkedCaseInsensitiveMap(@Nullable Locale locale) {
-		this(16, locale);
+		this(12, locale);  // equivalent to LinkedHashMap's initial capacity of 16
 	}
 
 	/**
 	 * Create a new LinkedCaseInsensitiveMap that wraps a {@link LinkedHashMap}
-	 * with an initial capacity that can accommodate the given number of elements,
+	 * with an initial capacity that can accommodate the specified number of
+	 * elements without any immediate resize/rehash operations to be expected,
 	 * storing case-insensitive keys according to the default Locale (in lower case).
-	 * @param expectedSize the expected number of elements
+	 * @param expectedSize the expected number of elements (with a corresponding
+	 * capacity to be derived so that no resize/rehash operations are needed)
+	 * @see CollectionUtils#newHashMap(int)
 	 * @see #convertKey(String)
 	 */
 	public LinkedCaseInsensitiveMap(int expectedSize) {
@@ -97,10 +100,13 @@ public LinkedCaseInsensitiveMap(int expectedSize) {
 
 	/**
 	 * Create a new LinkedCaseInsensitiveMap that wraps a {@link LinkedHashMap}
-	 * with an initial capacity that can accommodate the given number of elements,
+	 * with an initial capacity that can accommodate the specified number of
+	 * elements without any immediate resize/rehash operations to be expected,
 	 * storing case-insensitive keys according to the given Locale (in lower case).
-	 * @param expectedSize the expected number of elements
+	 * @param expectedSize the expected number of elements (with a corresponding
+	 * capacity to be derived so that no resize/rehash operations are needed)
 	 * @param locale the Locale to use for case-insensitive key conversion
+	 * @see CollectionUtils#newHashMap(int)
 	 * @see #convertKey(String)
 	 */
 	public LinkedCaseInsensitiveMap(int expectedSize, @Nullable Locale locale) {

spring-core/src/main/java/org/springframework/util/LinkedMultiValueMap.java

@@ -49,8 +49,11 @@ public LinkedMultiValueMap() {
 
 	/**
 	 * Create a new LinkedMultiValueMap that wraps a {@link LinkedHashMap}
-	 * with an initial capacity that can accommodate the given number of elements.
-	 * @param expectedSize the expected number of elements
+	 * with an initial capacity that can accommodate the specified number of
+	 * elements without any immediate resize/rehash operations to be expected.
+	 * @param expectedSize the expected number of elements (with a corresponding
+	 * capacity to be derived so that no resize/rehash operations are needed)
+	 * @see CollectionUtils#newLinkedHashMap(int)
 	 */
 	public LinkedMultiValueMap(int expectedSize) {
 		super(CollectionUtils.newLinkedHashMap(expectedSize));