Class CollectionsExt

java.lang.Object
org.apache.sis.util.Static
org.apache.sis.internal.util.CollectionsExt

public final class CollectionsExt extends Static
Static methods working on Collection objects. This is an extension to the standard Collections utility class. Some worthy methods are: This class is not in public API because some functionality provided there are not really the purpose of a geospatial library and may change at any time. Some method contracts are a little bit tedious to explain, which is another indication that they should not be in public API.
Since:
0.3
Version:
1.1
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Do not allow instantiation of this class.
  • Method Summary

    Modifier and Type
    Method
    Description
    static <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>
    clone(HashSet<E> set)
    Returns a clone of the given set.
    static <E> List<E>
    compact(List<E> list)
    Returns a more compact representation of the given list.
    static <K, V> Map<K,V>
    compact(Map<K,V> map)
    Returns a more compact representation of the given map.
    static <E> Set<E>
    compact(Set<E> set)
    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<?>
    empty(Class<?> type)
    Returns an empty collection of the given type, or null 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>
    filter(Iterator<E> it, Predicate<? super E> filter)
    Returns an iterator over the elements of the given iterator where the predicate returns true.
    static <T> T
    first(Iterable<T> collection)
    Returns the first element of the given iterable, or null if none.
    static boolean
    identityEquals(Iterator<?> it1, Iterator<?> it2)
    Returns true 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, or null 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, or null if the given array is null or empty.
    static <T extends Collection<E>, E>
    T
    nonEmpty(T c)
    Returns the given collection if non-empty, or null 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>
    Returns the given collection, or Collections.EMPTY_SET if the given collection is null.
    static <E> Set<E>
    nonNull(Set<E> c)
    Returns the given set, or Collections.EMPTY_SET if the given set is null.
    static <E> E[]
    nonNullArraySet(String name, Object value, E[] emptyArray)
    Given a value which is either null, 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>
    snapshot(List<E> list)
    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.
    static <E> Map<String,E>
    Creates a (name, element) mapping for the given collection of elements.
    static Collection<?>
    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>
    Returns a unmodifiable version of the given list.
    static <K, V> Map<K,V>
    Returns a unmodifiable version of the given map.
    static <E> Set<E>
    Returns a unmodifiable version of the given set.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Constructor Details

    • CollectionsExt

      private CollectionsExt()
      Do not allow instantiation of this class.
  • Method Details

    • emptyQueue

      public static <E> Queue<E> 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 in Collections.
      Type Parameters:
      E - the type of elements in the empty collection.
      Returns:
      an empty collection.
      See Also:
    • empty

      public static Collection<?> empty(Class<?> type)
      Returns an empty collection of the given type, or null 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

      public static int size(Object c)
      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, or null.
      Returns:
      the size or pseudo-size of the given object.
      Since:
      1.0
    • first

      public static <T> T first(Iterable<T> collection)
      Returns the first element of the given iterable, or null 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, or null.
      Returns:
      the first element, or null if the given iterable is null or empty.
    • singletonOrNull

      public static <T> T singletonOrNull(Iterable<T> collection)
      If the given iterable contains exactly one non-null element, returns that element. Otherwise returns null.
      Type Parameters:
      T - the type of elements contained in the iterable.
      Parameters:
      collection - the iterable from which to get the singleton element, or null.
      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

      public static <E> Set<E> singletonOrEmpty(E element)
      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

      @SafeVarargs public static <T> Set<T> nonEmptySet(T... elements)
      Returns a copy of the given array as a non-empty immutable set. If the given array is empty, then this method returns null.
      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, or null 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, or null.
      Returns:
      the given array, or null if the given array was empty.
    • nonEmpty

      public static <T extends Collection<E>, E> T nonEmpty(T c)
      Returns the given collection if non-empty, or null 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, or null.
      Returns:
      the given collection, or null if the given collection was empty.
    • nonNull

      public static <E> Collection<E> nonNull(Collection<E> c)
      Returns the given collection, or Collections.EMPTY_SET if the given collection is null.
      Type Parameters:
      E - the type of elements in the collection.
      Parameters:
      c - the collection, or null.
      Returns:
      the given collection, or an empty set if the given collection was null.
    • nonNull

      public static <E> Set<E> nonNull(Set<E> c)
      Returns the given set, or Collections.EMPTY_SET if the given set is null.
      Type Parameters:
      E - the type of elements in the collection.
      Parameters:
      c - the collection, or null.
      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 either null, 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 returns emptyArray.
      • If the given value is an instance of <E>, then this method returns an array of length 1 which contain only value.
      • If the given value is an array of <E>, then this method returns copy of that array, omitting null elements and duplicated elements.
      • Otherwise this method throws IllegalArgumentException.
      Note: It would be very easy to add support for value argument of type Object[] or collections. But we do not provide such support for now because this method is used mostly as a helper method for constructors of AbstractIdentifiedObject 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, or null.
      emptyArray - an instance of new 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
    • createSetForType

      public static <E> Set<E> createSetForType(Class<E> type, int count)
      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

      @SafeVarargs public static <E> Set<E> immutableSet(boolean excludeNull, E... array)
      Returns the specified array as an immutable set, or null if the array is null. If the given array contains duplicated elements, i.e. elements that are equal in the sense of Object.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 the null element from the returned set.
      array - the array to copy in a set. May be null or contain null elements.
      Returns:
      a set containing the array elements, or null if the given array was null.
      See Also:
    • unmodifiableOrCopy

      public static <E> Set<E> unmodifiableOrCopy(Set<E> set)
      Returns a unmodifiable version of the given set. This method is different than the standard Collections.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 for AbstractIdentifiedObject 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, or null.
      Returns:
      a unmodifiable version of the given set, or null if the given set was null.
      See Also:
    • unmodifiableOrCopy

      public static <K, V> Map<K,V> unmodifiableOrCopy(Map<K,V> map)
      Returns a unmodifiable version of the given map. This method is different than the standard Collections.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, or null.
      Returns:
      a unmodifiable version of the given map, or null if the given map was null.
      See Also:
    • unmodifiableOrCopy

      public static <E> List<E> unmodifiableOrCopy(List<E> list)
      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, or null.
      Returns:
      a unmodifiable version of the given list, or null if the given list was null.
    • modifiableCopy

      public static <E> Collection<E> modifiableCopy(Collection<E> collection)
      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 above LinkedHashSet
      Queue LinkedList
      List or other CollectionArrayList
      This method may not preserve the CheckedContainer interface.
      Type Parameters:
      E - the type of elements in the collection.
      Parameters:
      collection - the collection to copy, or null.
      Returns:
      a copy of the given collection, or null if the given collection was null.
    • modifiableCopy

      public 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. 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, or null.
      Returns:
      a copy of the given map, or null if the given map was null.
    • compact

      public static <K, V> Map<K,V> compact(Map<K,V> map)
      Returns a more compact representation of the given map. This method is similar to unmodifiableOrCopy(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, or null.
      Returns:
      a potentially compacted map, or null if the given map was null.
      See Also:
    • compact

      public static <E> Set<E> compact(Set<E> set)
      Returns a more compact representation of the given set. This method is similar to unmodifiableOrCopy(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, or null.
      Returns:
      a unmodifiable version of the given set, or null if the given set was null.
      See Also:
    • compact

      public static <E> List<E> compact(List<E> list)
      Returns a more compact representation of the given list. This method is similar to unmodifiableOrCopy(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, or null.
      Returns:
      a unmodifiable version of the given list, or null if the given list was null.
      See Also:
    • snapshot

      public static <E> List<E> snapshot(List<E> list)
      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, or null if none.
      Returns:
      a snapshot of the given list, or list itself if null or unmodifiable.
    • clone

      public static <E> HashSet<E> clone(HashSet<E> set)
      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

      public static Collection<?> toCollection(Object value)
      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 or Enumeration, copies the values in a new list.
      • Otherwise the value is returned as a singleton list.

      Note that in the Iterator and Enumeration 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, or null.
      Returns:
      the value as a collection, or wrapped in a collection (never null).
    • toList

      public static <T> List<T> toList(Collection<T> collection)
      Casts or copies the given collection to a list. Special cases:
      • If the given collection is null, then this method returns null.
      • 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.
      This method can be chained with 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.
    • toArray

      public static <T> T[] toArray(Collection<? extends T> collection, Class<T> valueClass)
      Returns the elements of the given collection as an array. This method can be used when the valueClass argument is not known at compile-time. If the valueClass is known at compile-time, then callers should use Collection.toArray(Object[]) instead.
      Type Parameters:
      T - the compile-time value of valueClass.
      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 if collection is null.
      Since:
      0.6
    • addToMultiValuesMap

      public static <K, V> List<V> addToMultiValuesMap(Map<K,List<V>> map, K key, V value)
      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

      public static <K, V> List<V> removeFromMultiValuesMap(Map<K,List<V>> map, K key, V value)
      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, or null 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

      public static <E> Iterator<E> filter(Iterator<E> it, Predicate<? super E> filter)
      Returns an iterator over the elements of the given iterator where the predicate returns true. The iterator may return null 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

      public static boolean identityEquals(Iterator<?> it1, Iterator<?> it2)
      Returns true if the next elements returned by the given iterators are the same. This method compares using the identity operation (==), not equals(Object).
      Parameters:
      it1 - the first iterator.
      it2 - the second iterator.
      Returns:
      if both iterators return the same objects.