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 Collection 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. + *

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 Collection 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 + *

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 Map 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 + *

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 Map createMap(Class mapType, Class keyType, int capacity) {