diff --git a/spring-core/src/main/java/org/springframework/core/CollectionFactory.java b/spring-core/src/main/java/org/springframework/core/CollectionFactory.java index b1c1cac38a7..6cd952414ed 100644 --- a/spring-core/src/main/java/org/springframework/core/CollectionFactory.java +++ b/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. *
Mainly for internal use within the framework. *
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 + *
Warning: 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. *
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 Warning: 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 Warning: 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.
* 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 Warning: 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