Class CollectionsExt
Collection
objects.
This is an extension to the standard Collections
utility class.
Some worthy methods are:
toCollection(Object)
for wrapping or copying arbitrary objects to list or collection.modifiableCopy(Collection)
method for taking a snapshot of an arbitrary implementation into an unsynchronized, modifiable, in-memory object.unmodifiableOrCopy(Set)
methods, which may be slightly more compact than the standardCollections.unmodifiableSet(Set)
equivalent when the unmodifiable collection is not required to be a view over the original collection.
- Since:
- 0.3
- Version:
- 1.1
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic <K,
V> List <V> addToMultiValuesMap
(Map<K, List<V>> map, K key, V value) Adds a value in a pseudo multi-values map.static <E> HashSet
<E> Returns a clone of the given set.static <E> List
<E> Returns a more compact representation of the given list.static <K,
V> Map <K, V> Returns a more compact representation of the given map.static <E> Set
<E> Returns a more compact representation of the given set.static <E> Set
<E> createSetForType
(Class<E> type, int count) Creates an initially empty set for elements of the given type.static Collection
<?> Returns an empty collection of the given type, ornull
if the given type is unknown to this method.static <E> Queue
<E> Returns a queue which is always empty and accepts no element.static <E> Iterator
<E> Returns an iterator over the elements of the given iterator where the predicate returnstrue
.static <T> T
Returns the first element of the given iterable, ornull
if none.static boolean
identityEquals
(Iterator<?> it1, Iterator<?> it2) Returnstrue
if the next elements returned by the given iterators are the same.static <E> Set
<E> immutableSet
(boolean excludeNull, E... array) Returns the specified array as an immutable set, ornull
if the array is null.static <E> Collection
<E> modifiableCopy
(Collection<E> collection) Copies the content of the given collection to a new, unsynchronized, modifiable, in-memory collection.static <K,
V> Map <K, V> modifiableCopy
(Map<K, V> map) Copies the content of the given map to a new unsynchronized, modifiable, in-memory map.static <E> E[]
nonEmpty
(E[] array) Returns the given array if non-empty, ornull
if the given array is null or empty.static <T extends Collection<E>,
E>
TnonEmpty
(T c) Returns the given collection if non-empty, ornull
if the given collection is null or empty.static <T> Set
<T> nonEmptySet
(T... elements) Returns a copy of the given array as a non-empty immutable set.static <E> Collection
<E> nonNull
(Collection<E> c) Returns the given collection, orCollections.EMPTY_SET
if the given collection is null.static <E> Set
<E> Returns the given set, orCollections.EMPTY_SET
if the given set is null.static <E> E[]
nonNullArraySet
(String name, Object value, E[] emptyArray) Given a value which is eithernull
, an instance of<E>
or an array of<E>
, returns a non-null array containing all elements without null and without duplicated values.static <K,
V> List <V> removeFromMultiValuesMap
(Map<K, List<V>> map, K key, V value) Removes a value in a pseudo multi-values map.static <E> Set
<E> singletonOrEmpty
(E element) Returns the given value as a singleton if non-null, or returns an empty set otherwise.static <T> T
singletonOrNull
(Iterable<T> collection) If the given iterable contains exactly one non-null element, returns that element.static int
Returns the number of elements if the given object is a collection or a map.static <E> List
<E> Returns a snapshot of the given list.static <T> T[]
toArray
(Collection<? extends T> collection, Class<T> valueClass) Returns the elements of the given collection as an array.toCaseInsensitiveNameMap
(Collection<Map.Entry<String, E>> entries, Locale namesLocale) Creates a (name, element) mapping for the given collection of elements.static Collection
<?> toCollection
(Object value) Returns the given value as a collection.static <T> List
<T> toList
(Collection<T> collection) Casts or copies the given collection to a list.static <E> List
<E> unmodifiableOrCopy
(List<E> list) Returns a unmodifiable version of the given list.static <K,
V> Map <K, V> unmodifiableOrCopy
(Map<K, V> map) Returns a unmodifiable version of the given map.static <E> Set
<E> unmodifiableOrCopy
(Set<E> set) Returns a unmodifiable version of the given set.
-
Constructor Details
-
CollectionsExt
private CollectionsExt()Do not allow instantiation of this class.
-
-
Method Details
-
emptyQueue
Returns a queue which is always empty and accepts no element. This method will be removed if a future JDK version provides such method inCollections
.- Type Parameters:
E
- the type of elements in the empty collection.- Returns:
- an empty collection.
- See Also:
-
empty
Returns an empty collection of the given type, ornull
if the given type is unknown to this method.- Parameters:
type
- the desired collection type.- Returns:
- an empty collection of the given type, or
null
if the type is unknown. - Since:
- 0.8
-
size
Returns the number of elements if the given object is a collection or a map. Otherwise returns 0 if the given object if null or 1 otherwise.- Parameters:
c
- the collection or map for which to get the size, ornull
.- Returns:
- the size or pseudo-size of the given object.
- Since:
- 1.0
-
first
Returns the first element of the given iterable, ornull
if none. This method does not emit warning if more than one element is found. Consequently, this method should be used only when multi-occurrence is not ambiguous.This method is null-safe. Note however that the first element may be null.
- Type Parameters:
T
- the type of elements contained in the iterable.- Parameters:
collection
- the iterable from which to get the first element, ornull
.- Returns:
- the first element, or
null
if the given iterable is null or empty.
-
singletonOrNull
If the given iterable contains exactly one non-null element, returns that element. Otherwise returnsnull
.- Type Parameters:
T
- the type of elements contained in the iterable.- Parameters:
collection
- the iterable from which to get the singleton element, ornull
.- Returns:
- the singleton element, or
null
if the given iterable is null or does not contain exactly one non-null element. - Since:
- 0.8
-
singletonOrEmpty
Returns the given value as a singleton if non-null, or returns an empty set otherwise.- Type Parameters:
E
- the element type.- Parameters:
element
- the element to returns in a collection if non-null.- Returns:
- a collection containing the given element if non-null, or an empty collection otherwise.
-
nonEmptySet
Returns a copy of the given array as a non-empty immutable set. If the given array is empty, then this method returnsnull
.- Type Parameters:
T
- the type of elements.- Parameters:
elements
- the elements to copy in a set.- Returns:
- an unmodifiable set which contains all the given elements, or
null
. - Since:
- 0.6
-
nonEmpty
public static <E> E[] nonEmpty(E[] array) Returns the given array if non-empty, ornull
if the given array is null or empty. This method is generally not recommended, since public API should prefer empty array instead of null. However, this method is occasionally useful for managing private fields.- Type Parameters:
E
- the type of elements in the array.- Parameters:
array
- the array, ornull
.- Returns:
- the given array, or
null
if the given array was empty.
-
nonEmpty
Returns the given collection if non-empty, ornull
if the given collection is null or empty. This method is generally not recommended, since public API should prefer empty collection instead of null. However, this method is occasionally useful for managing private fields, especially for inter-operability with frameworks that may expect or return null (e.g. if we want to exclude completely an empty collection from marshalling with JAXB).- Type Parameters:
T
- the type of the collection.E
- the type of elements in the collection.- Parameters:
c
- the collection, ornull
.- Returns:
- the given collection, or
null
if the given collection was empty.
-
nonNull
Returns the given collection, orCollections.EMPTY_SET
if the given collection is null.- Type Parameters:
E
- the type of elements in the collection.- Parameters:
c
- the collection, ornull
.- Returns:
- the given collection, or an empty set if the given collection was null.
-
nonNull
Returns the given set, orCollections.EMPTY_SET
if the given set is null.- Type Parameters:
E
- the type of elements in the collection.- Parameters:
c
- the collection, ornull
.- Returns:
- the given collection, or an empty set if the given collection was null.
-
nonNullArraySet
public static <E> E[] nonNullArraySet(String name, Object value, E[] emptyArray) throws IllegalArgumentException Given a value which is eithernull
, an instance of<E>
or an array of<E>
, returns a non-null array containing all elements without null and without duplicated values. More specifically:- If the given value is
null
, then this method returnsemptyArray
. - If the given value is an instance of
<E>
, then this method returns an array of length 1 which contain onlyvalue
. - If the given value is an array of
<E>
, then this method returns copy of that array, omittingnull
elements and duplicated elements. - Otherwise this method throws
IllegalArgumentException
.
Note: It would be very easy to add support forvalue
argument of typeObject[]
or collections. But we do not provide such support for now because this method is used mostly as a helper method for constructors ofAbstractIdentifiedObject
subclasses receiving a map of properties, and the contract of our constructors do not allow those other types for now.- Type Parameters:
E
- the type of elements in the array to be returned.- Parameters:
name
- the parameter name, used only for formatting an error message in case of failure.value
- the value to return as an array, ornull
.emptyArray
- an instance ofnew E[0]
. This argument cannot be null.- Returns:
- the given value as an array of
<E>
. Never null. throws IllegalArgumentException if the given value is not null, an instance of<E>
or an array of<E>
. - Throws:
IllegalArgumentException
- Since:
- 0.4
- If the given value is
-
createSetForType
Creates an initially empty set for elements of the given type. This method will creates specialized set for code lists and enumerations.- Type Parameters:
E
- the type of elements in the set.- Parameters:
type
- the type of elements in the set.count
- the expected number of elements to put in the set.- Returns:
- a new set for elements of the given type.
-
immutableSet
Returns the specified array as an immutable set, ornull
if the array is null. If the given array contains duplicated elements, i.e. elements that are equal in the sense ofObject.equals(Object)
, then only the last instance of the duplicated values will be included in the returned set.- Type Parameters:
E
- the type of array elements.- Parameters:
excludeNull
-true
for excluding thenull
element from the returned set.array
- the array to copy in a set. May benull
or contain null elements.- Returns:
- a set containing the array elements, or
null
if the given array was null. - See Also:
-
unmodifiableOrCopy
Returns a unmodifiable version of the given set. This method is different than the standardCollections.unmodifiableSet(Set)
in that it tries to returns a more efficient object when there is zero or one element. Such small set occurs frequently in Apache SIS, especially forAbstractIdentifiedObject
names or identifiers.The set returned by this method may or may not be a view of the given set. Consequently, this method shall be used only if the given set will not be modified after this method call. In case of doubt, use the standard
Collections.unmodifiableSet(Set)
method instead.- Type Parameters:
E
- the type of elements in the set.- Parameters:
set
- the set to make unmodifiable, ornull
.- Returns:
- a unmodifiable version of the given set, or
null
if the given set was null. - See Also:
-
unmodifiableOrCopy
Returns a unmodifiable version of the given map. This method is different than the standardCollections.unmodifiableMap(Map)
in that it tries to returns a more efficient object when there is zero or one entry. Such small maps occur frequently in Apache SIS.The map returned by this method may or may not be a view of the given map. Consequently, this method shall be used only if the given map will not be modified after this method call. In case of doubt, use the standard
Collections.unmodifiableMap(Map)
method instead.- Type Parameters:
K
- the type of keys in the map.V
- the type of values in the map.- Parameters:
map
- the map to make unmodifiable, ornull
.- Returns:
- a unmodifiable version of the given map, or
null
if the given map was null. - See Also:
-
unmodifiableOrCopy
Returns a unmodifiable version of the given list.The collection returned by this method may or may not be a view of the given list. Consequently, this method shall be used only if the given list will not be modified after this method call. In case of doubt, use the standard
Collections.unmodifiableList(List)
method instead.- Type Parameters:
E
- the type of elements in the list.- Parameters:
list
- the list to make unmodifiable, ornull
.- Returns:
- a unmodifiable version of the given list, or
null
if the given list was null.
-
modifiableCopy
Copies the content of the given collection to a new, unsynchronized, modifiable, in-memory collection. The implementation class of the returned collection may be different than the class of the collection given in argument. The following table gives the types mapping applied by this method:Implementations for types Input type Output type SortedSet
TreeSet
HashSet
HashSet
Set
other than aboveLinkedHashSet
Queue
LinkedList
List
or otherCollection
ArrayList
CheckedContainer
interface.- Type Parameters:
E
- the type of elements in the collection.- Parameters:
collection
- the collection to copy, ornull
.- Returns:
- a copy of the given collection, or
null
if the given collection was null.
-
modifiableCopy
Copies the content of the given map to a new unsynchronized, modifiable, in-memory map. The implementation class of the returned map may be different than the class of the map given in argument. The following table gives the types mapping applied by this method:Implementations for types Input type Output type SortedMap
TreeMap
HashMap
HashMap
Map
other than aboveLinkedHashMap
- Type Parameters:
K
- the type of keys in the map.V
- the type of values in the map.- Parameters:
map
- the map to copy, ornull
.- Returns:
- a copy of the given map, or
null
if the given map was null.
-
compact
Returns a more compact representation of the given map. This method is similar tounmodifiableOrCopy(Map)
except that it does not wrap the map in an unmodifiable view. The intent is to avoid one level of indirection for performance and memory reasons. This is okay only if the map is kept in a private field and never escape outside that class.- Type Parameters:
K
- the type of keys in the map.V
- the type of values in the map.- Parameters:
map
- the map to compact, ornull
.- Returns:
- a potentially compacted map, or
null
if the given map was null. - See Also:
-
compact
Returns a more compact representation of the given set. This method is similar tounmodifiableOrCopy(Set)
except that it does not wrap the set in an unmodifiable view. The intent is to avoid one level of indirection for performance and memory reasons. This is okay only if the set is kept in a private field and never escape outside that class.- Type Parameters:
E
- the type of elements in the set.- Parameters:
set
- the set to compact, ornull
.- Returns:
- a unmodifiable version of the given set, or
null
if the given set was null. - See Also:
-
compact
Returns a more compact representation of the given list. This method is similar tounmodifiableOrCopy(List)
except that it does not wrap the list in an unmodifiable view. The intent is to avoid one level of indirection for performance and memory reasons. This is okay only if the list is kept in a private field and never escape outside that class.- Type Parameters:
E
- the type of elements in the list.- Parameters:
list
- the list to compact, ornull
.- Returns:
- a unmodifiable version of the given list, or
null
if the given list was null. - See Also:
-
snapshot
Returns a snapshot of the given list. The returned list will not be affected by changes in the given list after this method call. This method makes no guaranteed about whether the returned list is modifiable or not.- Type Parameters:
E
- the type of elements in the list.- Parameters:
list
- the list for which to take a snapshot, ornull
if none.- Returns:
- a snapshot of the given list, or
list
itself if null or unmodifiable.
-
clone
Returns a clone of the given set. This method is only intended to avoid the "unchecked cast" warning.- Type Parameters:
E
- type of elements in the set.- Parameters:
set
- the set to clone.- Returns:
- a clone of the given set.
-
toCollection
Returns the given value as a collection. Special cases:- If the value is null, then this method returns an empty list.
- If the value is an instance of
Collection
, then it is returned unchanged. - If the value is an array of objects, then it is returned as a list.
- If the value is an array of primitive type, then it is returned as a list of their wrapper class.
- If the value is an instance of
Iterable
,Iterator
orEnumeration
, copies the values in a new list. - Otherwise the value is returned as a singleton list.
Note that in the
Iterator
andEnumeration
cases, the given value object is not valid anymore after this method call since it has been used for the iteration.If the returned object needs to be a list, then this method can be chained with
toList(Collection)
as below:- Parameters:
value
- the value to return as a collection, ornull
.- Returns:
- the value as a collection, or wrapped in a collection (never
null
).
-
toList
Casts or copies the given collection to a list. Special cases:- If the given collection is
null
, then this method returnsnull
. - If the given collection is already a list, then it is returned unchanged.
- Otherwise the elements are copied in a new list, which is returned.
toCollection(Object)
for handling a wider range of types:- Type Parameters:
T
- the type of elements in the given collection.- Parameters:
collection
- the collection to cast or copy to a list.- Returns:
- the given collection as a list, or a copy of the given collection.
- If the given collection is
-
toArray
Returns the elements of the given collection as an array. This method can be used when thevalueClass
argument is not known at compile-time. If thevalueClass
is known at compile-time, then callers should useCollection.toArray(Object[])
instead.- Type Parameters:
T
- the compile-time value ofvalueClass
.- Parameters:
collection
- the collection from which to get the elements.valueClass
- the runtime type of collection elements.- Returns:
- the collection elements as an array, or
null
ifcollection
is null. - Since:
- 0.6
-
addToMultiValuesMap
Adds a value in a pseudo multi-values map. The multi-values map is simulated by a map of lists. The map can be initially empty - lists will be created as needed.- Type Parameters:
K
- the type of key elements in the map.V
- the type of value elements in the lists.- Parameters:
map
- the multi-values map where to add an element.key
- the key of the element to add. Can be null if the given map supports null keys.value
- the value of the element to add. Can be null.- Returns:
- the list where the given value has been added. May be unmodifiable.
-
removeFromMultiValuesMap
Removes a value in a pseudo multi-values map. The multi-values map is simulated by a map of lists. If more than one occurrence of the given value is found in the list, only the first occurrence is removed. If the list become empty after this method call, that list is removed from the map.- Type Parameters:
K
- the type of key elements in the map.V
- the type of value elements in the lists.- Parameters:
map
- the multi-values map where to remove an element.key
- the key of the element to remove. Can be null if the given map supports null keys.value
- the value of the element to remove. Can be null.- Returns:
- list of remaining elements after the removal, or
null
if no list is mapped to the given key.
-
toCaseInsensitiveNameMap
public static <E> Map<String,E> toCaseInsensitiveNameMap(Collection<Map.Entry<String, E>> entries, Locale namesLocale) Creates a (name, element) mapping for the given collection of elements. If the name of an element is not all lower cases, then this method also adds an entry for the lower cases version of that name in order to allow case-insensitive searches.Code searching in the returned map shall ask for the original (non lower-case) name before to ask for the lower-cases version of that name.
Iteration order in map entries is the same than iteration order in the given collection. If lower-case names have been generated, they appear immediately after the original names.
- Type Parameters:
E
- the type of elements.- Parameters:
entries
- the entries to store in the map, ornull
if none.namesLocale
- the locale to use for creating the "all lower cases" names.- Returns:
- a (name, element) mapping with lower cases entries where possible.
- Throws:
org.opengis.parameter.InvalidParameterCardinalityException
- if the same name is used for more than one element.
-
filter
Returns an iterator over the elements of the given iterator where the predicate returnstrue
. The iterator may returnnull
elements.- Type Parameters:
E
- type of elements in the iterator to return.- Parameters:
it
- the iterator to filter.filter
- the predicate to use for filtering elements.- Returns:
- an iterator over filtered elements.
-
identityEquals
Returnstrue
if the next elements returned by the given iterators are the same. This method compares using the identity operation (==
), notequals(Object)
.- Parameters:
it1
- the first iterator.it2
- the second iterator.- Returns:
- if both iterators return the same objects.
-