A comprehensive collections framework API for Java providing interfaces for object collections, primitive collections and lazy iterables
—
Eclipse Collections provides advanced key-value collection types including traditional Maps with rich functional operations, Multimaps for one-to-many relationships, and BiMaps for bidirectional mapping. All types come in mutable and immutable variants with comprehensive functional programming support.
The base interface for all map collections providing rich functional operations on key-value pairs.
package org.eclipse.collections.api.map;
public interface MapIterable<K, V> extends RichIterable<V> {
// Basic map operations
V get(Object key);
V getIfAbsent(K key, Function0<? extends V> function);
V getIfAbsentPut(K key, Function0<? extends V> function);
V getIfAbsentWith(K key, Function<? super P, ? extends V> function, P parameter);
// Key-value iteration
void forEachKey(Procedure<? super K> procedure);
void forEachValue(Procedure<? super V> procedure);
void forEachKeyValue(Procedure2<? super K, ? super V> procedure);
// Views
RichIterable<K> keysView();
RichIterable<V> valuesView();
RichIterable<Pair<K, V>> keyValuesView();
// Functional transformations
<R> MapIterable<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
<VV> MapIterable<VV, V> groupByUniqueKey(Function<? super V, ? extends VV> function);
// Filtering
MapIterable<K, V> select(Predicate2<? super K, ? super V> predicate);
MapIterable<K, V> reject(Predicate2<? super K, ? super V> predicate);
// Aggregation and reduction
<R> R injectIntoKeyValue(R injectedValue, Function3<? super R, ? super K, ? super V, ? extends R> function);
// Map transformations
MapIterable<V, K> flipUniqueValues();
// Conversion
MutableMap<K, V> toMap();
ImmutableMap<K, V> toImmutableMap();
}Mutable map implementation extending Java's Map interface with Eclipse Collections enhancements.
package org.eclipse.collections.api.map;
public interface MutableMap<K, V> extends Map<K, V>, MapIterable<K, V> {
// Enhanced put operations
V getIfAbsentPut(K key, Function0<? extends V> function);
V getIfAbsentPut(K key, V value);
V getIfAbsentPutWith(K key, Function<? super P, ? extends V> function, P parameter);
// Update operations
V updateValue(K key, Function0<? extends V> factory, Function<? super V, ? extends V> function);
V updateValueWith(K key, Function0<? extends V> factory, Function2<? super V, ? super P, ? extends V> function, P parameter);
// Modification operations
MutableMap<K, V> withKeyValue(K key, V value);
MutableMap<K, V> withAllKeyValues(Iterable<? extends Pair<? extends K, ? extends V>> keyValues);
MutableMap<K, V> withAllKeyValueArguments(Pair<? extends K, ? extends V>... keyValuePairs);
MutableMap<K, V> withoutKey(K key);
MutableMap<K, V> withoutAllKeys(Iterable<? extends K> keys);
// Functional transformations (in-place when possible)
<R> MutableMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
MutableMap<K, V> select(Predicate2<? super K, ? super V> predicate);
MutableMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
// Map inversion
MutableBiMap<V, K> flipUniqueValues();
// Immutable copy
ImmutableMap<K, V> toImmutable();
}Thread-safe immutable map where all operations return new instances.
package org.eclipse.collections.api.map;
public interface ImmutableMap<K, V> extends MapIterable<K, V> {
// Modification operations return new instances
ImmutableMap<K, V> newWithKeyValue(K key, V value);
ImmutableMap<K, V> newWithAllKeyValues(Iterable<? extends Pair<? extends K, ? extends V>> keyValues);
ImmutableMap<K, V> newWithAllKeyValueArguments(Pair<? extends K, ? extends V>... keyValuePairs);
ImmutableMap<K, V> newWithoutKey(K key);
ImmutableMap<K, V> newWithoutAllKeys(Iterable<? extends K> keys);
// Functional transformations return new instances
<R> ImmutableMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
ImmutableMap<K, V> select(Predicate2<? super K, ? super V> predicate);
ImmutableMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
// Map inversion returns new instance
ImmutableBiMap<V, K> flipUniqueValues();
}Maps that maintain insertion order or iteration order.
Base interface for maps with defined iteration order.
package org.eclipse.collections.api.map;
public interface OrderedMap<K, V> extends MapIterable<K, V> {
// Ordered access
Pair<K, V> getKeyValueAtIndex(int index);
// Ordered views
OrderedMap<K, V> select(Predicate2<? super K, ? super V> predicate);
OrderedMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
<R> OrderedMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
}Mutable and immutable variants of ordered maps.
package org.eclipse.collections.api.map;
public interface MutableOrderedMap<K, V> extends MutableMap<K, V>, OrderedMap<K, V> {
// Ordered modification operations
MutableOrderedMap<K, V> withKeyValue(K key, V value);
MutableOrderedMap<K, V> withoutKey(K key);
// Ordered transformations
MutableOrderedMap<K, V> select(Predicate2<? super K, ? super V> predicate);
MutableOrderedMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
<R> MutableOrderedMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
ImmutableOrderedMap<K, V> toImmutable();
}
public interface ImmutableOrderedMap<K, V> extends ImmutableMap<K, V>, OrderedMap<K, V> {
// Ordered modification operations return new instances
ImmutableOrderedMap<K, V> newWithKeyValue(K key, V value);
ImmutableOrderedMap<K, V> newWithoutKey(K key);
// Ordered transformations return new instances
ImmutableOrderedMap<K, V> select(Predicate2<? super K, ? super V> predicate);
ImmutableOrderedMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
<R> ImmutableOrderedMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
}Maps with keys sorted according to a comparator.
Base interface for maps with sorted keys.
package org.eclipse.collections.api.map.sorted;
public interface SortedMapIterable<K, V> extends OrderedMap<K, V>, SortedIterable<K> {
// Comparator access
Comparator<? super K> comparator();
// Sorted range operations
SortedMapIterable<K, V> headMap(K toKey);
SortedMapIterable<K, V> tailMap(K fromKey);
SortedMapIterable<K, V> subMap(K fromKey, K toKey);
// Sorted transformations
SortedMapIterable<K, V> select(Predicate2<? super K, ? super V> predicate);
SortedMapIterable<K, V> reject(Predicate2<? super K, ? super V> predicate);
<R> MapIterable<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
}Mutable and immutable variants of sorted maps.
package org.eclipse.collections.api.map.sorted;
public interface MutableSortedMap<K, V> extends MutableOrderedMap<K, V>, SortedMapIterable<K, V> {
// Sorted modification operations
MutableSortedMap<K, V> withKeyValue(K key, V value);
MutableSortedMap<K, V> withoutKey(K key);
// Sorted range operations
MutableSortedMap<K, V> headMap(K toKey);
MutableSortedMap<K, V> tailMap(K fromKey);
MutableSortedMap<K, V> subMap(K fromKey, K toKey);
ImmutableSortedMap<K, V> toImmutable();
}
public interface ImmutableSortedMap<K, V> extends ImmutableOrderedMap<K, V>, SortedMapIterable<K, V> {
// Sorted modification operations return new instances
ImmutableSortedMap<K, V> newWithKeyValue(K key, V value);
ImmutableSortedMap<K, V> newWithoutKey(K key);
// Sorted range operations return new instances
ImmutableSortedMap<K, V> headMap(K toKey);
ImmutableSortedMap<K, V> tailMap(K fromKey);
ImmutableSortedMap<K, V> subMap(K fromKey, K toKey);
}Collections that allow multiple values per key, providing one-to-many key-value associations.
Base interface for multimap collections supporting multiple values per key.
package org.eclipse.collections.api.multimap;
public interface Multimap<K, V> extends RichIterable<V> {
// Basic multimap operations
RichIterable<V> get(K key);
boolean containsKey(Object key);
boolean containsValue(Object value);
boolean containsKeyAndValue(Object key, Object value);
// Size operations
int size();
int sizeDistinct();
boolean isEmpty();
boolean notEmpty();
// Key-value iteration
void forEachKey(Procedure<? super K> procedure);
void forEachValue(Procedure<? super V> procedure);
void forEachKeyValue(Procedure2<? super K, ? super V> procedure);
void forEachKeyMultiValues(Procedure2<? super K, ? super RichIterable<V>> procedure);
// Views
RichIterable<K> keysView();
RichIterable<V> valuesView();
RichIterable<Pair<K, V>> keyValuePairsView();
RichIterable<RichIterable<V>> multiValuesView();
// Conversion
MapIterable<K, RichIterable<V>> toMap();
MutableMultimap<K, V> toMutable();
ImmutableMultimap<K, V> toImmutable();
}Mutable multimap allowing modification of key-value associations.
package org.eclipse.collections.api.multimap;
public interface MutableMultimap<K, V> extends Multimap<K, V> {
// Modification operations
boolean put(K key, V value);
boolean remove(Object key, Object value);
boolean removeAll(Object key);
void clear();
// Bulk operations
boolean putAll(K key, Iterable<? extends V> values);
<KK extends K, VV extends V> boolean putAll(Multimap<KK, VV> multimap);
boolean putAllPairs(Pair<K, V>... pairs);
// Replacement operations
RichIterable<V> replaceValues(K key, Iterable<? extends V> values);
// Immutable copy
ImmutableMultimap<K, V> toImmutable();
}Thread-safe immutable multimap where all operations return new instances.
package org.eclipse.collections.api.multimap;
public interface ImmutableMultimap<K, V> extends Multimap<K, V> {
// Modification operations return new instances
ImmutableMultimap<K, V> newWith(K key, V value);
ImmutableMultimap<K, V> newWithout(Object key, Object value);
ImmutableMultimap<K, V> newWithoutAll(Object key);
ImmutableMultimap<K, V> newWithAll(K key, Iterable<? extends V> values);
}Multimaps with specific value collection types.
Multimap where values for each key are stored in a List (ordered, allows duplicates).
package org.eclipse.collections.api.multimap.list;
public interface ListMultimap<K, V> extends Multimap<K, V> {
ListIterable<V> get(K key);
MutableListMultimap<K, V> toMutable();
ImmutableListMultimap<K, V> toImmutable();
}
public interface MutableListMultimap<K, V> extends MutableMultimap<K, V>, ListMultimap<K, V> {
MutableList<V> get(K key);
MutableList<V> replaceValues(K key, Iterable<? extends V> values);
ImmutableListMultimap<K, V> toImmutable();
}
public interface ImmutableListMultimap<K, V> extends ImmutableMultimap<K, V>, ListMultimap<K, V> {
ImmutableList<V> get(K key);
ImmutableListMultimap<K, V> newWith(K key, V value);
ImmutableListMultimap<K, V> newWithout(Object key, Object value);
ImmutableListMultimap<K, V> newWithoutAll(Object key);
}Multimap where values for each key are stored in a Set (unique values).
package org.eclipse.collections.api.multimap.set;
public interface SetMultimap<K, V> extends Multimap<K, V> {
SetIterable<V> get(K key);
MutableSetMultimap<K, V> toMutable();
ImmutableSetMultimap<K, V> toImmutable();
}
public interface MutableSetMultimap<K, V> extends MutableMultimap<K, V>, SetMultimap<K, V> {
MutableSet<V> get(K key);
MutableSet<V> replaceValues(K key, Iterable<? extends V> values);
ImmutableSetMultimap<K, V> toImmutable();
}
public interface ImmutableSetMultimap<K, V> extends ImmutableMultimap<K, V>, SetMultimap<K, V> {
ImmutableSet<V> get(K key);
ImmutableSetMultimap<K, V> newWith(K key, V value);
ImmutableSetMultimap<K, V> newWithout(Object key, Object value);
ImmutableSetMultimap<K, V> newWithoutAll(Object key);
}Multimap where values for each key are stored in a Bag (allows duplicates with occurrence counting).
package org.eclipse.collections.api.multimap.bag;
public interface BagMultimap<K, V> extends Multimap<K, V> {
Bag<V> get(K key);
MutableBagMultimap<K, V> toMutable();
ImmutableBagMultimap<K, V> toImmutable();
}
public interface MutableBagMultimap<K, V> extends MutableMultimap<K, V>, BagMultimap<K, V> {
MutableBag<V> get(K key);
MutableBag<V> replaceValues(K key, Iterable<? extends V> values);
ImmutableBagMultimap<K, V> toImmutable();
}
public interface ImmutableBagMultimap<K, V> extends ImmutableMultimap<K, V>, BagMultimap<K, V> {
ImmutableBag<V> get(K key);
ImmutableBagMultimap<K, V> newWith(K key, V value);
ImmutableBagMultimap<K, V> newWithout(Object key, Object value);
ImmutableBagMultimap<K, V> newWithoutAll(Object key);
}Bidirectional maps providing one-to-one key-value mapping where both directions can be queried efficiently.
Base interface for bidirectional maps with one-to-one key-value mapping.
package org.eclipse.collections.api.bimap;
public interface BiMap<K, V> extends MapIterable<K, V> {
// Bidirectional operations
BiMap<V, K> inverse();
V forcePut(K key, V value); // Removes existing mapping for value if present
// BiMap-specific views
BiMap<K, V> select(Predicate2<? super K, ? super V> predicate);
BiMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
<R> BiMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
// Conversion
MutableBiMap<K, V> toMutable();
ImmutableBiMap<K, V> toImmutable();
}Mutable bidirectional map with modification operations.
package org.eclipse.collections.api.bimap;
public interface MutableBiMap<K, V> extends BiMap<K, V>, MutableMap<K, V> {
// Bidirectional operations
MutableBiMap<V, K> inverse();
V forcePut(K key, V value);
// Modification operations
MutableBiMap<K, V> withKeyValue(K key, V value);
MutableBiMap<K, V> withoutKey(K key);
MutableBiMap<K, V> withAllKeyValues(Iterable<? extends Pair<? extends K, ? extends V>> keyValues);
MutableBiMap<K, V> withoutAllKeys(Iterable<? extends K> keys);
// BiMap-specific transformations
MutableBiMap<K, V> select(Predicate2<? super K, ? super V> predicate);
MutableBiMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
<R> MutableBiMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
// Immutable copy
ImmutableBiMap<K, V> toImmutable();
}Thread-safe immutable bidirectional map where all operations return new instances.
package org.eclipse.collections.api.bimap;
public interface ImmutableBiMap<K, V> extends BiMap<K, V>, ImmutableMap<K, V> {
// Bidirectional operations return new instances
ImmutableBiMap<V, K> inverse();
ImmutableBiMap<K, V> newWithKeyValue(K key, V value);
// Modification operations return new instances
ImmutableBiMap<K, V> newWithoutKey(K key);
ImmutableBiMap<K, V> newWithAllKeyValues(Iterable<? extends Pair<? extends K, ? extends V>> keyValues);
ImmutableBiMap<K, V> newWithoutAllKeys(Iterable<? extends K> keys);
// BiMap-specific transformations return new instances
ImmutableBiMap<K, V> select(Predicate2<? super K, ? super V> predicate);
ImmutableBiMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
<R> ImmutableBiMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
}// Create and manipulate maps
MutableMap<String, Integer> ages = Maps.mutable.with("Alice", 30, "Bob", 25);
// Enhanced map operations
Integer age = ages.getIfAbsent("Charlie", () -> 0);
ages.getIfAbsentPut("David", () -> 28);
// Functional operations
MutableMap<String, String> categories = ages.collectValues((name, age) -> age >= 30 ? "Senior" : "Junior");
MutableMap<String, Integer> filtered = ages.select((name, age) -> age > 25);
// Key-value iteration
ages.forEachKeyValue((name, age) -> System.out.println(name + " is " + age + " years old"));// Create multimap
MutableListMultimap<String, String> phoneBook = Multimaps.mutable.list.empty();
// Add multiple values per key
phoneBook.put("Alice", "555-1234");
phoneBook.put("Alice", "555-5678");
phoneBook.put("Bob", "555-9999");
// Access values
ListIterable<String> aliceNumbers = phoneBook.get("Alice"); // ["555-1234", "555-5678"]
// Check containment
boolean hasValue = phoneBook.containsKeyAndValue("Alice", "555-1234"); // true// Create bidirectional map
MutableBiMap<String, Integer> studentIds = BiMaps.mutable.empty();
studentIds.put("Alice", 101);
studentIds.put("Bob", 102);
// Bidirectional lookup
BiMap<Integer, String> inverse = studentIds.inverse();
String student = inverse.get(101); // "Alice"
// Force put (removes existing mapping for value)
studentIds.forcePut("Charlie", 101); // Removes Alice -> 101, adds Charlie -> 101// Map transformations
MutableMap<String, List<String>> groups = people.groupBy(Person::getDepartment);
MapIterable<String, Integer> departmentSizes = groups.collectValues((dept, people) -> people.size());
// Map aggregation
int totalAge = ages.injectIntoKeyValue(0, (sum, name, age) -> sum + age);
// Map flipping
MutableBiMap<Integer, String> ageToName = ages.flipUniqueValues();Eclipse Collections provides sorted variants of maps that maintain key-value pairs in sorted order by their keys.
Base interface for sorted maps extending MapIterable with sorted key access.
package org.eclipse.collections.api.map.sorted;
public interface SortedMapIterable<K, V> extends MapIterable<K, V> {
// Sorted-specific access
K firstKey();
K lastKey();
// Range operations
SortedMapIterable<K, V> takeWhile(Predicate2<? super K, ? super V> predicate);
SortedMapIterable<K, V> dropWhile(Predicate2<? super K, ? super V> predicate);
// Submap operations
SortedMapIterable<K, V> subMap(K fromKey, K toKey);
SortedMapIterable<K, V> headMap(K toKey);
SortedMapIterable<K, V> tailMap(K fromKey);
// Views with sorting
RichIterable<K> keysView();
RichIterable<V> valuesView();
// Functional operations returning sorted maps
<R> SortedMapIterable<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
SortedMapIterable<K, V> select(Predicate2<? super K, ? super V> predicate);
SortedMapIterable<K, V> reject(Predicate2<? super K, ? super V> predicate);
// Conversion
MutableSortedMap<K, V> toSortedMap();
ImmutableSortedMap<K, V> toImmutableSortedMap();
}Mutable sorted map implementation extending Java's SortedMap interface.
package org.eclipse.collections.api.map.sorted;
public interface MutableSortedMap<K, V> extends MutableMap<K, V>, SortedMap<K, V>, SortedMapIterable<K, V> {
// Modification operations
MutableSortedMap<K, V> withKeyValue(K key, V value);
MutableSortedMap<K, V> withoutKey(K key);
MutableSortedMap<K, V> withAllKeyValues(Iterable<? extends Pair<? extends K, ? extends V>> keyValues);
MutableSortedMap<K, V> withoutAllKeys(Iterable<? extends K> keys);
// Functional operations
<R> MutableSortedMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
MutableSortedMap<K, V> select(Predicate2<? super K, ? super V> predicate);
MutableSortedMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
// Range operations
MutableSortedMap<K, V> subMap(K fromKey, K toKey);
MutableSortedMap<K, V> headMap(K toKey);
MutableSortedMap<K, V> tailMap(K fromKey);
// Immutable copy
ImmutableSortedMap<K, V> toImmutable();
}Thread-safe immutable sorted map where all operations return new instances.
package org.eclipse.collections.api.map.sorted;
public interface ImmutableSortedMap<K, V> extends SortedMapIterable<K, V> {
// Modification operations return new instances
ImmutableSortedMap<K, V> newWithKeyValue(K key, V value);
ImmutableSortedMap<K, V> newWithoutKey(K key);
ImmutableSortedMap<K, V> newWithAllKeyValues(Iterable<? extends Pair<? extends K, ? extends V>> keyValues);
ImmutableSortedMap<K, V> newWithoutAllKeys(Iterable<? extends K> keys);
// Functional operations return new instances
<R> ImmutableSortedMap<K, R> collectValues(Function2<? super K, ? super V, ? extends R> function);
ImmutableSortedMap<K, V> select(Predicate2<? super K, ? super V> predicate);
ImmutableSortedMap<K, V> reject(Predicate2<? super K, ? super V> predicate);
// Range operations return new instances
ImmutableSortedMap<K, V> subMap(K fromKey, K toKey);
ImmutableSortedMap<K, V> headMap(K toKey);
ImmutableSortedMap<K, V> tailMap(K fromKey);
}// Create sorted map
MutableSortedMap<String, Integer> scores = SortedMaps.mutable.with("zebra", 100, "apple", 85, "banana", 92);
// Keys are automatically sorted: {"apple": 85, "banana": 92, "zebra": 100}
// Access sorted keys
String firstKey = scores.firstKey(); // "apple"
String lastKey = scores.lastKey(); // "zebra"
// Range operations
SortedMapIterable<String, Integer> subMap = scores.subMap("apple", "zebra"); // {"apple": 85, "banana": 92}
SortedMapIterable<String, Integer> headMap = scores.headMap("banana"); // {"apple": 85}
// Functional operations preserve sorting
MutableSortedMap<String, String> grades = scores.collectValues((name, score) ->
score >= 90 ? "A" : "B");
// Result: {"apple": "B", "banana": "A", "zebra": "A"}This comprehensive map and multimap API provides powerful abstractions for key-value data structures with extensive functional programming capabilities, efficient bidirectional access, one-to-many relationships, and sorted key ordering.
Install with Tessl CLI
npx tessl i tessl/maven-org-eclipse-collections--eclipse-collections-api