What it is
Apache Commons Collections extends the Java Collections Framework with additional interfaces, implementations, and utilities for manipulating and transforming collections. It includes features like Bag, MultiMap, BidiMap, and advanced iterators.
Commons Collections provides enhanced collection types like Bag, MultiMap, BidiMap, and utilities for transforming, filtering, and decorating collections. It also offers specialized iterators and predicates for collection manipulation.
Installation
Add dependency in pom.xml:
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-collections4</artifactId>
<version>4.4</version>
</dependency>Getting started
The smallest useful thing you can do with it, and what each part means.
import org.apache.commons.collections4.Bag;
import org.apache.commons.collections4.bag.HashBag;
Bag<String> bag = new HashBag<>();
bag.add("apple", 3);
bag.add("banana");
System.out.println(bag.getCount("apple")); // 3import org.apache.commons.collections4.MultiMap;
import org.apache.commons.collections4.multimap.ArrayListValuedHashMap;
MultiMap<String, String> multiMap = new ArrayListValuedHashMap<>();
multiMap.put("fruit", "apple");
multiMap.put("fruit", "banana");
System.out.println(multiMap.get("fruit"));Advanced usage
Where the library earns its place over a simpler alternative.
import org.apache.commons.collections4.BidiMap;
import org.apache.commons.collections4.bidimap.HashBidiMap;
BidiMap<Integer, String> bidi = new HashBidiMap<>();
bidi.put(1, "one");
bidi.put(2, "two");
System.out.println(bidi.getKey("two")); // 2import org.apache.commons.collections4.CollectionUtils;
import org.apache.commons.collections4.Transformer;
Collection<String> input = Arrays.asList("a", "bb", "ccc");
Collection<String> output = CollectionUtils.collect(input, (Transformer<String, String>) String::toUpperCase);
System.out.println(output);import org.apache.commons.collections4.Predicate;
import org.apache.commons.collections4.CollectionUtils;
Collection<String> input = Arrays.asList("apple", "banana", "cherry");
Collection<String> result = CollectionUtils.select(input, (Predicate<String>) s -> s.startsWith("a"));
System.out.println(result);import org.apache.commons.collections4.list.LazyList;
import org.apache.commons.collections4.FactoryUtils;
import java.util.ArrayList;
List<String> lazy = LazyList.lazyList(new ArrayList<>(), FactoryUtils.constantFactory("default"));
lazy.add(0, "first");
lazy.add(2, null);
System.out.println(lazy);Errors and fixes
The failures you are most likely to hit, and what actually resolves them.
- NullPointerException
- Ensure collections are initialized and predicates are not null.
- UnsupportedOperationException
- Occurs when modifying immutable collections. Use modifiable variants or decorators.
Best practices
- Use Bag for counting occurrences instead of manual maps.
- Use MultiMap for key-to-multiple-values mappings.
- Use BidiMap for two-way lookup between keys and values.
- Use CollectionUtils for transformations, filtering, and null-safe operations.
- Avoid overusing legacy iterators when Java 8 streams provide equivalent functionality.
Background
Why it exists, and what it was reacting to.
Commons Collections was developed to provide powerful, reusable collection utilities beyond the standard Java Collections Framework. It simplifies tasks such as grouping, counting, bidirectional mapping, transforming, and filtering collections. It is widely used in enterprise Java applications, open-source projects, and frameworks that need enhanced collection handling.