Package util

Class CollectionUtils

  • public class CollectionUtils
extends java.lang.Object
    A collection of utility methods that prevent you from having to do unsafe casts of Collection classes due to runtime type erasure.

    Be sure to check Guava and Apache collection utils before using this class, as they are standard utilities and often more efficient.

    Some examples:

    1. Iterators
    2. Iterables
    3. CollectionUtils
    4. IterableUtils
    5. IteratorUtils
    6. Maps
    7. Sets
    8. StringUtils.join(Iterable, char) - for pretty printing collections with newlines
    9. Apache CollectionUtils.collect(Collection, Transformer) - to turn a collection in to collection of strings when the default toString() is lacking

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T> T any​(java.lang.Iterable<T> iterable)
      Returns an element from the given iterable; null if the iterable is null or empty.
      static <T> T any​(java.util.Collection<T> c)
      Returns an element from the given collection; null if the collection is null or empty.
      static <T> java.util.Collection<T> asCollection​(java.util.Collection<?> collection, java.lang.Class<T> clazz)
      Checks that the elements in the given collection are of the type specified by clazz and then casts the collection to be of the specified type.
      static <T> java.util.Collection<T> asCollection​(java.util.Collection<T> c)
      Returns the given collection if not null, an empty collection otherwise.
      static <T> java.lang.Iterable<T> asIterable​(java.lang.Iterable<T>... iterables)
      Combines all collections passed-in, using Iterables, into a pass-through (not creating a new collection) Iterable.
      static <T> java.lang.Iterable<T> asIterable​(java.util.Iterator<T> iterator)
      Returns an iterable over an iterator
      static <T> java.lang.Iterable<T> asIterable​(T t)
      Turns the given item into an iterable
      static <T> java.util.List<T> asList​(java.lang.Iterable<T> it)  
      static <T> java.util.List<T> asList​(java.util.Collection<T> c)
      A convenient way to check for null and whether the given collection is a List.
      static <T> java.util.List<T> asList​(java.util.Enumeration<T> enumeration)  
      static <T> java.util.List<T> asList​(java.util.Iterator<T> it)  
      static <T> java.util.List<T> asList​(java.util.List<?> list, java.lang.Class<T> clazz)
      Checks that the elements in the given list are of the type specified by clazz and then casts the list to be of the specified type.
      static <T> java.util.List<T> asList​(java.util.List<T> list)
      Returns the given list if not null, otherwise returns an empty list.
      static <T> java.util.List<T> asList​(T... items)
      Similar to Arrays.asList(Object...), except that this method will turn a single null parameter into an empty list.
      static <T> java.util.Set<T> asSet​(java.lang.Iterable<T> iterable)
      Turns the given iterable into a new Set, returning it directly if it is a set, draining it into a set if it is not already.
      static <T> java.util.Set<T> asSet​(java.util.Collection<T> c)  
      static <T> java.util.Set<T> asSet​(java.util.Iterator<T> it)
      Drains the given iterator into a new Set
      static <T> java.util.Set<T> asSet​(T... items)
      Turns the given items into a set.
      static <T> java.util.stream.Stream<T> asStream​(java.lang.Iterable<T>... iterables)
      Combines all iterables passed-in, using Iterables, into a pass-through (not creating a new collection) Stream.
      static <T> java.util.stream.Stream<T> asStream​(java.util.Iterator<T> iterator)
      Turns the given iterator into a stream
      static boolean isAllNull​(java.lang.Object... objects)
      Returns true if all the given objects are null.
      static <T> boolean isAllNull​(java.util.Collection<T> c)
      Returns true if all the given objects are null.
      static <T> boolean isAllSameType​(java.util.Collection<?> list, java.lang.Class<T> clazz)
      Returns true if each item in the list is of type clazz.
      static <T> boolean isBlank​(java.util.Collection<T> c)
      Returns true if the given array is null or has 0 length
      static <T> boolean isBlank​(T... t)
      Returns true if the given array is null or has 0 length
      static <T> boolean isOneOf​(T t, T... possibles)
      Returns true if the given item is in the collection of possible items
      static <T> java.util.Collection<T> nonNull​(java.util.Collection<T> c)
      Returns the given collection if not null, an empty collection (a Set) otherwise.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • asSet

        @SafeVarargs
public static <T> java.util.Set<T> asSet​(T... items)
        Turns the given items into a set. If there is only a single item and it is null, then an empty set will be returned.
        Parameters:
        items - the items to put in the set
        Returns:
        the list of items

      • asSet

        public static <T> java.util.Set<T> asSet​(java.util.Collection<T> c)

      • asSet

        public static <T> java.util.Set<T> asSet​(java.util.Iterator<T> it)
        Drains the given iterator into a new Set
        Parameters:
        it - the iterator
        Returns:
        the set

      • asSet

        public static <T> java.util.Set<T> asSet​(java.lang.Iterable<T> iterable)
        Turns the given iterable into a new Set, returning it directly if it is a set, draining it into a set if it is not already.
        Parameters:
        iterable - the iterable
        Returns:
        the set

      • asList

        @SafeVarargs
public static <T> java.util.List<T> asList​(T... items)
        Similar to Arrays.asList(Object...), except that this method will turn a single null parameter into an empty list. Also, this method creates a new, mutable array, whereas the former's array is not mutable.
        Parameters:
        items - the items to add to the list
        Returns:
        the list

      • asList

        public static <T> java.util.List<T> asList​(java.util.List<T> list)
        Returns the given list if not null, otherwise returns an empty list. This is useful for clients avoid null checks.
        Parameters:
        list - the list to check
        Returns:
        a non-null collection

      • asList

        public static <T> java.util.List<T> asList​(java.util.Collection<T> c)
        A convenient way to check for null and whether the given collection is a List. If the value is a list, then it is returned. If the value is null, an empty list is returned. Otherwise, a new list is created from the given collection.
        Parameters:
        c - the collection to check
        Returns:
        a list

      • nonNull

        public static <T> java.util.Collection<T> nonNull​(java.util.Collection<T> c)
        Returns the given collection if not null, an empty collection (a Set) otherwise. This is useful for clients avoid null checks.
        Parameters:
        c - the collection to check
        Returns:
        a non-null collection

      • asCollection

        public static <T> java.util.Collection<T> asCollection​(java.util.Collection<T> c)
        Returns the given collection if not null, an empty collection otherwise. This is useful for clients avoid null checks.
        Parameters:
        c - the collection to check
        Returns:
        a non-null collection

      • asList

        public static <T> java.util.List<T> asList​(java.util.Enumeration<T> enumeration)

      • asList

        public static <T> java.util.List<T> asList​(java.lang.Iterable<T> it)

      • asList

        public static <T> java.util.List<T> asList​(java.util.Iterator<T> it)

      • asList

        public static <T> java.util.List<T> asList​(java.util.List<?> list,
                                           java.lang.Class<T> clazz)
        Checks that the elements in the given list are of the type specified by clazz and then casts the list to be of the specified type.
        Parameters:
        list - the source list
        clazz - the class of T
        Returns:
        a casted list of type T
        Throws:
        java.lang.IllegalArgumentException - if the given list contains elements that are not of the type specified by clazz.

      • asCollection

        public static <T> java.util.Collection<T> asCollection​(java.util.Collection<?> collection,
                                                       java.lang.Class<T> clazz)
        Checks that the elements in the given collection are of the type specified by clazz and then casts the collection to be of the specified type.
        Parameters:
        collection - the source collection
        clazz - the class of T
        Returns:
        a casted list of type T
        Throws:
        java.lang.IllegalArgumentException - if the given collection contains elements that are not of the type specified by clazz.

      • isAllSameType

        public static <T> boolean isAllSameType​(java.util.Collection<?> list,
                                        java.lang.Class<T> clazz)
        Returns true if each item in the list is of type clazz.
        Type Parameters:
        T - the type
        Parameters:
        list - the list to inspect
        clazz - the class type
        Returns:
        true if each item in the list is of type clazz

      • isOneOf

        @SafeVarargs
public static <T> boolean isOneOf​(T t,
                                  T... possibles)
        Returns true if the given item is in the collection of possible items
        Parameters:
        t - the item in question
        possibles - the set of things
        Returns:
        true if the given item is in the collection of possible items

      • isAllNull

        public static boolean isAllNull​(java.lang.Object... objects)
        Returns true if all the given objects are null.

        See also apache ObjectUtils.anyNotNull(Object...) and ObjectUtils.allNotNull(Object...)

        Parameters:
        objects - the objects to check
        Returns:
        true if all the given objects are null

      • isAllNull

        public static <T> boolean isAllNull​(java.util.Collection<T> c)
        Returns true if all the given objects are null.

        See also apache ObjectUtils.anyNotNull(Object...) and ObjectUtils.allNotNull(Object...)

        Parameters:
        c - the objects to check
        Returns:
        true if all the given objects are null

      • isBlank

        public static <T> boolean isBlank​(java.util.Collection<T> c)
        Returns true if the given array is null or has 0 length
        Parameters:
        c - the collection to check
        Returns:
        true if blank

      • isBlank

        public static <T> boolean isBlank​(T... t)
        Returns true if the given array is null or has 0 length
        Parameters:
        t - the items to check
        Returns:
        true if blank

      • asIterable

        public static <T> java.lang.Iterable<T> asIterable​(T t)
        Turns the given item into an iterable
        Parameters:
        t - the object from which to create an iterable
        Returns:
        an iterable over the given iterator

      • asIterable

        public static <T> java.lang.Iterable<T> asIterable​(java.util.Iterator<T> iterator)
        Returns an iterable over an iterator
        Parameters:
        iterator - the iterator to create an iterable from
        Returns:
        an iterable over the given iterator

      • asIterable

        @SafeVarargs
public static <T> java.lang.Iterable<T> asIterable​(java.lang.Iterable<T>... iterables)
        Combines all collections passed-in, using Iterables, into a pass-through (not creating a new collection) Iterable.

        This is just a convenience method for Iterables.concat(Iterable)

        Parameters:
        iterables - the iterables to combine
        Returns:
        the iterable

      • asStream

        public static <T> java.util.stream.Stream<T> asStream​(java.util.Iterator<T> iterator)
        Turns the given iterator into a stream
        Parameters:
        iterator - the iterator
        Returns:
        the stream

      • asStream

        @SafeVarargs
public static <T> java.util.stream.Stream<T> asStream​(java.lang.Iterable<T>... iterables)
        Combines all iterables passed-in, using Iterables, into a pass-through (not creating a new collection) Stream.
        Parameters:
        iterables - the iterables to combine
        Returns:
        the stream

      • any

        public static <T> T any​(java.util.Collection<T> c)
        Returns an element from the given collection; null if the collection is null or empty. This is meant for clients that have a collection with any number of items and just need to get one.
        Parameters:
        c - the collection
        Returns:
        the item

      • any

        public static <T> T any​(java.lang.Iterable<T> iterable)
        Returns an element from the given iterable; null if the iterable is null or empty. This is meant for clients that have a collection with any number of items and just need to get one.
        Parameters:
        iterable - the items
        Returns:
        the item