Package com.cedarsoftware.util

Class CollectionUtilities

java.lang.Object

com.cedarsoftware.util.CollectionUtilities

public class CollectionUtilities
extends Object

A utility class providing enhanced operations for working with Java collections.

CollectionUtilities simplifies tasks such as null-safe checks, retrieving collection sizes, creating immutable collections, and wrapping collections in checked, synchronized, or unmodifiable views. It includes functionality compatible with JDK 8, providing alternatives to methods introduced in later versions of Java, such as List.of(Object...) and Set.of(Object...).

Key Features

• Null-Safe Checks:
  • isEmpty(Collection): Checks if a collection is null or empty.
  • hasContent(Collection): Checks if a collection is not null and contains at least one element.
  • size(Collection): Safely retrieves the size of a collection, returning 0 if it is null.
• Immutable Collection Creation:
  • listOf(Object...): Creates an immutable list of specified elements, compatible with JDK 8.
  • setOf(Object...): Creates an immutable set of specified elements, compatible with JDK 8.
• Collection Wrappers:
  • getUnmodifiableCollection(Collection): Wraps a collection in the most specific unmodifiable view based on its type (e.g., NavigableSet, SortedSet, List).
  • getCheckedCollection(Collection, Class): Wraps a collection in the most specific type-safe checked view based on its type (e.g., NavigableSet, SortedSet, List).
  • getSynchronizedCollection(Collection): Wraps a collection in the most specific thread-safe synchronized view based on its type (e.g., NavigableSet, SortedSet, List).
  • getEmptyCollection(Collection): Returns an empty collection of the same type as the input collection (e.g., NavigableSet, SortedSet, List).

Usage Examples

 // Null-safe checks
 boolean isEmpty = CollectionUtilities.isEmpty(myCollection);
 boolean hasContent = CollectionUtilities.hasContent(myCollection);
 int size = CollectionUtilities.size(myCollection);

 // Immutable collections
 List<String> list = CollectionUtilities.listOf("A", "B", "C");
 Set<String> set = CollectionUtilities.setOf("X", "Y", "Z");

 // Collection wrappers
 Collection<?> unmodifiable = CollectionUtilities.getUnmodifiableCollection(myCollection);
 Collection<?> checked = CollectionUtilities.getCheckedCollection(myCollection, String.class);
 Collection<?> synchronizedCollection = CollectionUtilities.getSynchronizedCollection(myCollection);
 Collection<?> empty = CollectionUtilities.getEmptyCollection(myCollection);
 

Design Notes

• This class is designed as a static utility class and should not be instantiated.
• It uses unmodifiable empty collections as constants to optimize memory usage and prevent unnecessary object creation.
• The collection wrappers apply type-specific operations based on the runtime type of the provided collection.

Author:

John DeRegnaucourt ([email protected])
Copyright (c) Cedar Software LLC

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

License

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See Also:

• Collection
• List
• Set
• Collections
• Collections.unmodifiableCollection(Collection)
• Collections.checkedCollection(Collection, Class)
• Collections.synchronizedCollection(Collection)
• Collections.emptyList()
• Collections.emptySet()

Method Summary

Modifier and Type	Method	Description
static <T extends Collection<?>, E> Collection<E>	getCheckedCollection(T collection, Class<E> type)	Wraps the provided collection in a checked wrapper that enforces type safety.
static <T> Collection<T>	getEmptyCollection(Collection<T> collection)	Returns an empty collection of the same type as the provided collection.
static <T> Collection<T>	getSynchronizedCollection(Collection<T> collection)	Wraps the provided collection in a thread-safe synchronized wrapper.
static <T> Collection<T>	getUnmodifiableCollection(Collection<T> collection)	Wraps the provided collection in an unmodifiable wrapper appropriate to its runtime type.
static boolean	hasContent(Collection<?> col)	Checks if the specified collection is not null and contains at least one element.
static boolean	isEmpty(Collection<?> col)	This is a null-safe isEmpty check.
static boolean	isSynchronized(Class<?> targetType)	Determines whether the specified class represents an synchronized collection type.
static boolean	isUnmodifiable(Class<?> targetType)	Determines whether the specified class represents an unmodifiable collection type.
static <T> List<T>	listOf(T... items)	Creates an unmodifiable list containing the specified elements.
static <T> Set<T>	setOf(T... items)	Creates an unmodifiable set containing the specified elements.
static int	size(Collection<?> col)	Returns the size of the specified collection in a null-safe manner.

Methods inherited from class java.lang.Object

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

Method Details

isEmpty

public static boolean isEmpty(Collection<?> col)

This is a null-safe isEmpty check.

Parameters:

col - the collection to check, may be null

Returns:

true if the collection is null or empty; false otherwise

hasContent

public static boolean hasContent(Collection<?> col)

Checks if the specified collection is not null and contains at least one element.

This method provides a null-safe way to verify that a collection has content, returning false if the collection is null or empty.

Parameters:

col - the collection to check, may be null

Returns:

true if the collection is not null and contains at least one element; false otherwise

size

public static int size(Collection<?> col)

Returns the size of the specified collection in a null-safe manner.

If the collection is null, this method returns 0. Otherwise, it returns the number of elements in the collection.

Parameters:

col - the collection to check, may be null

Returns:

the size of the collection, or 0 if the collection is null

listOf

@SafeVarargs
public static <T> List<T> listOf(T... items)

Creates an unmodifiable list containing the specified elements.

This method provides functionality similar to List.of(Object...) introduced in JDK 9, but is compatible with JDK 8. If the input array is null or empty, this method returns an unmodifiable empty list.

Usage Example

 List<String> list = listOf("A", "B", "C"); // Returns an unmodifiable list containing "A", "B", "C"
 List<String> emptyList = listOf();         // Returns an unmodifiable empty list
 

Type Parameters:

T - the type of elements in the list

Parameters:

items - the elements to be included in the list; may be null

Returns:

an unmodifiable list containing the specified elements, or an unmodifiable empty list if the input is null or empty

Throws:

NullPointerException - if any of the elements in the input array are null

See Also:

• Collections.unmodifiableList(List)

setOf

@SafeVarargs
public static <T> Set<T> setOf(T... items)

Creates an unmodifiable set containing the specified elements.

This method provides functionality similar to Set.of(Object...) introduced in JDK 9, but is compatible with JDK 8. If the input array is null or empty, this method returns an unmodifiable empty set.

Usage Example

 Set<String> set = setOf("A", "B", "C"); // Returns an unmodifiable set containing "A", "B", "C"
 Set<String> emptySet = setOf();         // Returns an unmodifiable empty set
 

Type Parameters:

T - the type of elements in the set

Parameters:

items - the elements to be included in the set; may be null

Returns:

an unmodifiable set containing the specified elements, or an unmodifiable empty set if the input is null or empty

Throws:

NullPointerException - if any of the elements in the input array are null

See Also:

• Collections.unmodifiableSet(Set)

isUnmodifiable

public static boolean isUnmodifiable(Class<?> targetType)

Determines whether the specified class represents an unmodifiable collection type.

This method checks if the provided targetType is assignable to the class of unmodifiable collections. It is commonly used to identify whether a given class type indicates a collection that cannot be modified (e.g., collections wrapped with Collections.unmodifiableCollection(Collection) or its specialized variants).

Null Handling: If targetType is null, this method will throw a NullPointerException with a clear error message.

Parameters:

targetType - the Class to check, must not be null

Returns:

true if the specified targetType indicates an unmodifiable collection; false otherwise

Throws:

NullPointerException - if targetType is null

See Also:

• Collections.unmodifiableCollection(Collection)
• Collections.unmodifiableList(List)
• Collections.unmodifiableSet(Set)

isSynchronized

public static boolean isSynchronized(Class<?> targetType)

Determines whether the specified class represents an synchronized collection type.

This method checks if the provided targetType is assignable to the class of synchronized collections. It is commonly used to identify whether a given class type indicates a collection that supports concurrent access (e.g., collections wrapped with Collections.synchronizedCollection(Collection) or its specialized variants).

Null Handling: If targetType is null, this method will throw a NullPointerException with a clear error message.

Parameters:

targetType - the Class to check, must not be null

Returns:

true if the specified targetType indicates a synchronized collection; false otherwise

Throws:

NullPointerException - if targetType is null

See Also:

• Collections.synchronizedCollection(Collection)
• Collections.synchronizedList(List)
• Collections.synchronizedSet(Set)

getUnmodifiableCollection

public static <T> Collection<T> getUnmodifiableCollection(Collection<T> collection)

Wraps the provided collection in an unmodifiable wrapper appropriate to its runtime type.

This method ensures that the collection cannot be modified by any client code and applies the most specific unmodifiable wrapper based on the runtime type of the provided collection:

• If the collection is a NavigableSet, it is wrapped using Collections.unmodifiableNavigableSet(NavigableSet).
• If the collection is a SortedSet, it is wrapped using Collections.unmodifiableSortedSet(SortedSet).
• If the collection is a Set, it is wrapped using Collections.unmodifiableSet(Set).
• If the collection is a List, it is wrapped using Collections.unmodifiableList(List).
• Otherwise, it is wrapped using Collections.unmodifiableCollection(Collection).

Attempting to modify the returned collection will result in an UnsupportedOperationException at runtime. For example:

 NavigableSet<String> set = new TreeSet<>(Set.of("A", "B", "C"));
 NavigableSet<String> unmodifiableSet = (NavigableSet<String>) getUnmodifiableCollection(set);
 unmodifiableSet.add("D"); // Throws UnsupportedOperationException
 

Null Handling

If the input collection is null, this method will throw a NullPointerException with a descriptive error message.

Type Parameters:

T - the type of elements in the collection

Parameters:

collection - the collection to be wrapped in an unmodifiable wrapper

Returns:

an unmodifiable view of the provided collection, preserving its runtime type

Throws:

NullPointerException - if the provided collection is null

See Also:

• Collections.unmodifiableNavigableSet(NavigableSet)
• Collections.unmodifiableSortedSet(SortedSet)
• Collections.unmodifiableSet(Set)
• Collections.unmodifiableList(List)
• Collections.unmodifiableCollection(Collection)

getEmptyCollection

public static <T> Collection<T> getEmptyCollection(Collection<T> collection)

Returns an empty collection of the same type as the provided collection.

This method determines the runtime type of the input collection and returns an appropriate empty collection instance:

• If the collection is a NavigableSet, it returns Collections.emptyNavigableSet().
• If the collection is a SortedSet, it returns Collections.emptySortedSet().
• If the collection is a Set, it returns Collections.emptySet().
• If the collection is a List, it returns Collections.emptyList().
• For all other collection types, it defaults to returning Collections.emptyList().

The returned collection is immutable and will throw an UnsupportedOperationException if any modification is attempted. For example:

 List<String> list = new ArrayList<>();
 Collection<String> emptyList = getEmptyCollection(list);

 emptyList.add("one"); // Throws UnsupportedOperationException
 

Null Handling

If the input collection is null, this method will throw a NullPointerException with a descriptive error message.

Usage Notes

• The returned collection is type-specific based on the input collection, ensuring compatibility with type-specific operations such as iteration or ordering.
• The method provides an empty collection that is appropriate for APIs requiring non-null collections as inputs or defaults.

Type Parameters:

T - the type of elements in the collection

Parameters:

collection - the collection whose type determines the type of the returned empty collection

Returns:

an empty, immutable collection of the same type as the input collection

Throws:

NullPointerException - if the provided collection is null

See Also:

• Collections.emptyNavigableSet()
• Collections.emptySortedSet()
• Collections.emptySet()
• Collections.emptyList()

getCheckedCollection

public static <T extends Collection<?>,
E>
Collection<E> getCheckedCollection(T collection,
 Class<E> type)

Wraps the provided collection in a checked wrapper that enforces type safety.

This method applies the most specific checked wrapper based on the runtime type of the collection:

• If the collection is a NavigableSet, it is wrapped using Collections.checkedNavigableSet(NavigableSet, Class).
• If the collection is a SortedSet, it is wrapped using Collections.checkedSortedSet(SortedSet, Class).
• If the collection is a Set, it is wrapped using Collections.checkedSet(Set, Class).
• If the collection is a List, it is wrapped using Collections.checkedList(List, Class).
• Otherwise, it is wrapped using Collections.checkedCollection(Collection, Class).

Attempting to add an element to the returned collection that is not of the specified type will result in a ClassCastException at runtime. For example:

 List<Object> list = new ArrayList<>(List.of("one", "two"));
 Collection<String> checkedCollection = getCheckedCollection(list, String.class);

 // Adding a String is allowed
 checkedCollection.add("three");

 // Adding an Integer will throw a ClassCastException
 checkedCollection.add(42); // Throws ClassCastException
 

Null Handling

If the input collection or the type class is null, this method will throw a NullPointerException with a descriptive error message.

Usage Notes

• The method enforces runtime type safety by validating all elements added to the collection.
• The returned collection retains the original type-specific behavior of the input collection (e.g., sorting for SortedSet or ordering for List).
• Use this method when you need to ensure that a collection only contains elements of a specific type.

Type Parameters:

T - the type of the input collection

E - the type of elements in the collection

Parameters:

collection - the collection to be wrapped, must not be null

type - the class of elements that the collection is permitted to hold, must not be null

Returns:

a checked view of the provided collection

Throws:

NullPointerException - if the provided collection or type is null

See Also:

• Collections.checkedNavigableSet(NavigableSet, Class)
• Collections.checkedSortedSet(SortedSet, Class)
• Collections.checkedSet(Set, Class)
• Collections.checkedList(List, Class)
• Collections.checkedCollection(Collection, Class)

getSynchronizedCollection

public static <T> Collection<T> getSynchronizedCollection(Collection<T> collection)

Wraps the provided collection in a thread-safe synchronized wrapper.

This method applies the most specific synchronized wrapper based on the runtime type of the collection:

• If the collection is a NavigableSet, it is wrapped using Collections.synchronizedNavigableSet(NavigableSet).
• If the collection is a SortedSet, it is wrapped using Collections.synchronizedSortedSet(SortedSet).
• If the collection is a Set, it is wrapped using Collections.synchronizedSet(Set).
• If the collection is a List, it is wrapped using Collections.synchronizedList(List).
• Otherwise, it is wrapped using Collections.synchronizedCollection(Collection).

The returned collection is thread-safe. However, iteration over the collection must be manually synchronized:

 List<String> list = new ArrayList<>(List.of("one", "two", "three"));
 Collection<String> synchronizedList = getSynchronizedCollection(list);

 synchronized (synchronizedList) {
     for (String item : synchronizedList) {
         System.out.println(item);
     }
 }
 

Null Handling

If the input collection is null, this method will throw a NullPointerException with a descriptive error message.

Usage Notes

• The method returns a synchronized wrapper that delegates all operations to the original collection.
• Any structural modifications (e.g., add, remove) must occur within a synchronized block to ensure thread safety during concurrent access.

Type Parameters:

T - the type of elements in the collection

Parameters:

collection - the collection to be wrapped in a synchronized wrapper

Returns:

a synchronized view of the provided collection, preserving its runtime type

Throws:

NullPointerException - if the provided collection is null

See Also:

• Collections.synchronizedNavigableSet(NavigableSet)
• Collections.synchronizedSortedSet(SortedSet)
• Collections.synchronizedSet(Set)
• Collections.synchronizedList(List)
• Collections.synchronizedCollection(Collection)