Document type safety limitations of the CollectionFactory API
Issue: SPR-12596
This commit is contained in:
Sam Brannen
parent
60cee7f526
commit
4a49a6535d
|
|
@ -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) {
|
||||
|
|
|
|||
Loading…
Reference in New Issue