Document type safety limitations of the CollectionFactory API

Issue: SPR-12596

spring-core/src/main/java/org/springframework/core/CollectionFactory.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -40,7 +40,8 @@ import org.springframework.util.LinkedMultiValueMap;
 import org.springframework.util.MultiValueMap;
 
 /**
- * Factory for collections that is aware of Java 5 and Java 6 collection types.
+ * Factory for collections that is aware of Java 5, Java 6, and Spring
+ * collection types.
  * <p>Mainly for internal use within the framework.
  * <p>The goal of this class is to avoid runtime dependencies on a specific
  * Java version, while nevertheless using the best collection implementation
@@ -96,9 +97,17 @@ public abstract class CollectionFactory {
 
 	/**
 	 * Create the most approximate collection for the given collection.
-	 * @param collection the original collection object
+	 * <p><strong>Warning</strong>: Since the parameterized type {@code E} is
+	 * not bound to the type of elements contained in the supplied
+	 * {@code collection}, type safety cannot be guaranteed if the supplied
+	 * {@code collection} is an {@link EnumSet}. In such scenarios, the caller
+	 * is responsible for ensuring that the element type for the supplied
+	 * {@code collection} is an enum type matching type {@code E}. As an
+	 * alternative, the caller may wish to treat the return value as a raw
+	 * collection or collection of {@link Object}.
+	 * @param collection the original collection object, potentially {@code null}
 	 * @param capacity the initial capacity
-	 * @return the new, empty collection instance
+	 * @return a new, empty collection instance
 	 * @see #isApproximableCollectionType
 	 * @see java.util.LinkedList
 	 * @see java.util.ArrayList
@@ -132,9 +141,11 @@ public abstract class CollectionFactory {
 	 * Create the most appropriate collection for the given collection type.
 	 * <p>Delegates to {@link #createCollection(Class, Class, int)} with a
 	 * {@code null} element type.
-	 * @param collectionType the desired type of the target collection
+	 * @param collectionType the desired type of the target collection; never {@code null}
 	 * @param capacity the initial capacity
-	 * @return the new collection instance
+	 * @return a new collection instance
+	 * @throws IllegalArgumentException if the supplied {@code collectionType}
+	 * is {@code null} or of type {@link EnumSet}
 	 */
 	public static <E> Collection<E> createCollection(Class<?> collectionType, int capacity) {
 		return createCollection(collectionType, null, capacity);
@@ -142,16 +153,26 @@ public abstract class CollectionFactory {
 
 	/**
 	 * Create the most appropriate collection for the given collection type.
+	 * <p><strong>Warning</strong>: Since the parameterized type {@code E} is
+	 * not bound to the supplied {@code elementType}, type safety cannot be
+	 * guaranteed if the desired {@code collectionType} is {@link EnumSet}.
+	 * In such scenarios, the caller is responsible for ensuring that the
+	 * supplied {@code elementType} is an enum type matching type {@code E}.
+	 * As an alternative, the caller may wish to treat the return value as a
+	 * raw collection or collection of {@link Object}.
 	 * @param collectionType the desired type of the target collection; never {@code null}
-	 * @param elementType the collection's element type, or {@code null} if not known
+	 * @param elementType the collection's element type, or {@code null} if unknown
 	 * (note: only relevant for {@link EnumSet} creation)
 	 * @param capacity the initial capacity
-	 * @return the new collection instance
+	 * @return a new collection instance
 	 * @since 4.1.3
 	 * @see java.util.LinkedHashSet
 	 * @see java.util.ArrayList
 	 * @see java.util.TreeSet
 	 * @see java.util.EnumSet
+	 * @throws IllegalArgumentException if the supplied {@code collectionType} is
+	 * {@code null}; or if the desired {@code collectionType} is {@link EnumSet} and
+	 * the supplied {@code elementType} is not a subtype of {@link Enum}
 	 */
 	@SuppressWarnings({ "unchecked", "cast" })
 	public static <E> Collection<E> createCollection(Class<?> collectionType, Class<?> elementType, int capacity) {
@@ -201,9 +222,16 @@ public abstract class CollectionFactory {
 
 	/**
 	 * Create the most approximate map for the given map.
-	 * @param map the original Map object
+	 * <p><strong>Warning</strong>: Since the parameterized type {@code K} is
+	 * not bound to the type of keys contained in the supplied {@code map},
+	 * type safety cannot be guaranteed if the supplied {@code map} is an
+	 * {@link EnumMap}. In such scenarios, the caller is responsible for
+	 * ensuring that the key type in the supplied {@code map} is an enum type
+	 * matching type {@code K}. As an alternative, the caller may wish to
+	 * treat the return value as a raw map or map keyed by {@link Object}.
+	 * @param map the original map object, potentially {@code null}
 	 * @param capacity the initial capacity
-	 * @return the new, empty Map instance
+	 * @return a new, empty map instance
 	 * @see #isApproximableMapType
 	 * @see java.util.EnumMap
 	 * @see java.util.TreeMap
@@ -228,9 +256,11 @@ public abstract class CollectionFactory {
 	 * Create the most appropriate map for the given map type.
 	 * <p>Delegates to {@link #createMap(Class, Class, int)} with a
 	 * {@code null} key type.
-	 * @param mapType the desired type of the target Map
+	 * @param mapType the desired type of the target map
 	 * @param capacity the initial capacity
-	 * @return the new Map instance
+	 * @return a new map instance
+	 * @throws IllegalArgumentException if the supplied {@code mapType} is
+	 * {@code null} or of type {@link EnumMap}
 	 */
 	public static <K, V> Map<K, V> createMap(Class<?> mapType, int capacity) {
 		return createMap(mapType, null, capacity);
@@ -238,16 +268,27 @@ public abstract class CollectionFactory {
 
 	/**
 	 * Create the most appropriate map for the given map type.
-	 * @param mapType the desired type of the target Map
-	 * @param keyType the map's key type, or {@code null} if not known
+	 * <p><strong>Warning</strong>: Since the parameterized type {@code K}
+	 * is not bound to the supplied {@code keyType}, type safety cannot be
+	 * guaranteed if the desired {@code mapType} is {@link EnumMap}. In such
+	 * scenarios, the caller is responsible for ensuring that the {@code keyType}
+	 * is an enum type matching type {@code K}. As an alternative, the caller
+	 * may wish to treat the return value as a raw map or map keyed by
+	 * {@link Object}. Similarly, type safety cannot be enforced if the
+	 * desired {@code mapType} is {@link MultiValueMap}.
+	 * @param mapType the desired type of the target map; never {@code null}
+	 * @param keyType the map's key type, or {@code null} if unknown
 	 * (note: only relevant for {@link EnumMap} creation)
 	 * @param capacity the initial capacity
-	 * @return the new Map instance
+	 * @return a new map instance
 	 * @since 4.1.3
 	 * @see java.util.LinkedHashMap
 	 * @see java.util.TreeMap
 	 * @see org.springframework.util.LinkedMultiValueMap
 	 * @see java.util.EnumMap
+	 * @throws IllegalArgumentException if the supplied {@code mapType} is
+	 * {@code null}; or if the desired {@code mapType} is {@link EnumMap} and
+	 * the supplied {@code keyType} is not a subtype of {@link Enum}
 	 */
 	@SuppressWarnings({"unchecked", "rawtypes"})
 	public static <K, V> Map<K, V> createMap(Class<?> mapType, Class<?> keyType, int capacity) {