CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-eclipse-collections--eclipse-collections-api

A comprehensive collections framework API for Java providing interfaces for object collections, primitive collections and lazy iterables

—

Pending
Overview
Eval results
Files

factories-utilities.mddocs/

Factories and Utilities

Eclipse Collections provides comprehensive factory classes and utility interfaces for convenient collection creation and manipulation. The factory system follows a consistent pattern across all collection types, offering mutable, immutable, and fixed-size variants with fluent APIs for construction.

// Required imports for types used in this documentation
import org.eclipse.collections.api.factory.Tuples;

Static Factory Classes

Lists Factory

Central factory for creating List collections of all variants.

package org.eclipse.collections.api.factory;

public final class Lists {
    // Mutable list factory
    public static final MutableListFactory mutable = new MutableListFactory() {
        public <T> MutableList<T> empty() { /* implementation */ }
        public <T> MutableList<T> of() { /* implementation */ }
        public <T> MutableList<T> with() { /* implementation */ }
        public <T> MutableList<T> of(T element) { /* implementation */ }
        public <T> MutableList<T> with(T element) { /* implementation */ }
        public <T> MutableList<T> of(T... elements) { /* implementation */ }
        public <T> MutableList<T> with(T... elements) { /* implementation */ }
        public <T> MutableList<T> ofAll(Iterable<? extends T> items) { /* implementation */ }
        public <T> MutableList<T> withAll(Iterable<? extends T> items) { /* implementation */ }
    };
    
    // Immutable list factory
    public static final ImmutableListFactory immutable = new ImmutableListFactory() {
        public <T> ImmutableList<T> empty() { /* implementation */ }
        public <T> ImmutableList<T> of() { /* implementation */ }
        public <T> ImmutableList<T> with() { /* implementation */ }
        public <T> ImmutableList<T> of(T element) { /* implementation */ }
        public <T> ImmutableList<T> with(T element) { /* implementation */ }
        public <T> ImmutableList<T> of(T... elements) { /* implementation */ }
        public <T> ImmutableList<T> with(T... elements) { /* implementation */ }
        public <T> ImmutableList<T> ofAll(Iterable<? extends T> items) { /* implementation */ }
        public <T> ImmutableList<T> withAll(Iterable<? extends T> items) { /* implementation */ }
    };
    
    // Fixed size list factory
    public static final FixedSizeListFactory fixedSize = new FixedSizeListFactory() {
        public <T> MutableList<T> empty() { /* implementation */ }
        public <T> MutableList<T> of() { /* implementation */ }
        public <T> MutableList<T> with() { /* implementation */ }
        public <T> MutableList<T> of(T element) { /* implementation */ }
        public <T> MutableList<T> with(T element) { /* implementation */ }
        public <T> MutableList<T> of(T... elements) { /* implementation */ }
        public <T> MutableList<T> with(T... elements) { /* implementation */ }
        public <T> MutableList<T> ofAll(Iterable<? extends T> items) { /* implementation */ }
        public <T> MutableList<T> withAll(Iterable<? extends T> items) { /* implementation */ }
    };
    
    // Multi-reader list factory (thread-safe mutable)
    public static final MultiReaderListFactory multiReader = new MultiReaderListFactory() {
        public <T> MutableList<T> empty() { /* implementation */ }
        public <T> MutableList<T> of() { /* implementation */ }
        public <T> MutableList<T> with() { /* implementation */ }
        public <T> MutableList<T> of(T... elements) { /* implementation */ }
        public <T> MutableList<T> with(T... elements) { /* implementation */ }
        public <T> MutableList<T> ofAll(Iterable<? extends T> items) { /* implementation */ }
        public <T> MutableList<T> withAll(Iterable<? extends T> items) { /* implementation */ }
    };
}

Sets Factory

Factory for creating Set collections with mathematical operations.

package org.eclipse.collections.api.factory;

public final class Sets {
    public static final MutableSetFactory mutable;
    public static final ImmutableSetFactory immutable;
    public static final FixedSizeSetFactory fixedSize;
    public static final MultiReaderSetFactory multiReader;
}

Maps Factory

Factory for creating Map collections with rich key-value operations.

package org.eclipse.collections.api.factory;

public final class Maps {
    public static final MutableMapFactory mutable;
    public static final ImmutableMapFactory immutable;
    public static final FixedSizeMapFactory fixedSize;
    public static final MultiReaderMapFactory multiReader;
}

Bags Factory

Factory for creating Bag collections (multisets with occurrence counting).

package org.eclipse.collections.api.factory;

public final class Bags {
    public static final MutableBagFactory mutable;
    public static final ImmutableBagFactory immutable;
}

Stacks Factory

Factory for creating Stack collections with LIFO operations.

package org.eclipse.collections.api.factory;

public final class Stacks {
    public static final MutableStackFactory mutable;
    public static final ImmutableStackFactory immutable;
}

Multimaps Factory

Factory for creating Multimap collections with one-to-many relationships.

package org.eclipse.collections.api.factory;

public final class Multimaps {
    public static final class mutable {
        public static final MutableListMultimapFactory list;
        public static final MutableSetMultimapFactory set;
        public static final MutableBagMultimapFactory bag;
        public static final MutableSortedSetMultimapFactory sortedSet;
        public static final MutableSortedBagMultimapFactory sortedBag;
    }
    
    public static final class immutable {
        public static final ImmutableListMultimapFactory list;
        public static final ImmutableSetMultimapFactory set;
        public static final ImmutableBagMultimapFactory bag;
        public static final ImmutableSortedSetMultimapFactory sortedSet;
        public static final ImmutableSortedBagMultimapFactory sortedBag;
    }
}

BiMaps Factory

Factory for creating bidirectional maps.

package org.eclipse.collections.api.factory;

public final class BiMaps {
    public static final MutableBiMapFactory mutable;
    public static final ImmutableBiMapFactory immutable;
}

Factory Interface Definitions

Core Factory Interfaces

All collection factory interfaces follow a consistent pattern:

// Mutable List Factory Interface
package org.eclipse.collections.api.factory.list;

public interface MutableListFactory {
    // Empty collections
    <T> MutableList<T> empty();
    <T> MutableList<T> of();
    <T> MutableList<T> with();
    
    // Single element collections
    <T> MutableList<T> of(T element);
    <T> MutableList<T> with(T element);
    
    // Variable argument collections
    <T> MutableList<T> of(T... elements);
    <T> MutableList<T> with(T... elements);
    
    // From iterables
    <T> MutableList<T> ofAll(Iterable<? extends T> items);
    <T> MutableList<T> withAll(Iterable<? extends T> items);
    
    // From initial capacity
    <T> MutableList<T> ofInitialCapacity(int capacity);
    <T> MutableList<T> withInitialCapacity(int capacity);
    
    // From arrays
    <T> MutableList<T> ofArray(T[] array);
    <T> MutableList<T> withArray(T[] array);
}

// Immutable List Factory Interface
package org.eclipse.collections.api.factory.list;

public interface ImmutableListFactory {
    <T> ImmutableList<T> empty();
    <T> ImmutableList<T> of();
    <T> ImmutableList<T> with();
    
    <T> ImmutableList<T> of(T element);
    <T> ImmutableList<T> with(T element);
    
    <T> ImmutableList<T> of(T... elements);
    <T> ImmutableList<T> with(T... elements);
    
    <T> ImmutableList<T> ofAll(Iterable<? extends T> items);
    <T> ImmutableList<T> withAll(Iterable<? extends T> items);
}

// Fixed Size List Factory Interface
package org.eclipse.collections.api.factory.list;

public interface FixedSizeListFactory {
    <T> MutableList<T> empty();
    <T> MutableList<T> of();
    <T> MutableList<T> with();
    
    <T> MutableList<T> of(T element);
    <T> MutableList<T> with(T element);
    
    <T> MutableList<T> of(T... elements);
    <T> MutableList<T> with(T... elements);
    
    <T> MutableList<T> ofAll(Iterable<? extends T> items);
    <T> MutableList<T> withAll(Iterable<? extends T> items);
}

Map Factory Interfaces

Map factories support key-value pair creation:

// Mutable Map Factory Interface
package org.eclipse.collections.api.factory.map;

public interface MutableMapFactory {
    <K, V> MutableMap<K, V> empty();
    <K, V> MutableMap<K, V> of();
    <K, V> MutableMap<K, V> with();
    
    <K, V> MutableMap<K, V> of(K key, V value);
    <K, V> MutableMap<K, V> with(K key, V value);
    
    <K, V> MutableMap<K, V> of(K key1, V value1, K key2, V value2);
    <K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2);
    
    <K, V> MutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3);
    <K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3);
    
    <K, V> MutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
    <K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
    
    // From pairs
    <K, V> MutableMap<K, V> ofMap(Map<? extends K, ? extends V> map);
    <K, V> MutableMap<K, V> withMap(Map<? extends K, ? extends V> map);
    
    // From initial capacity
    <K, V> MutableMap<K, V> ofInitialCapacity(int initialCapacity);
    <K, V> MutableMap<K, V> withInitialCapacity(int initialCapacity);
}

// Immutable Map Factory Interface
package org.eclipse.collections.api.factory.map;

public interface ImmutableMapFactory {
    <K, V> ImmutableMap<K, V> empty();
    <K, V> ImmutableMap<K, V> of();
    <K, V> ImmutableMap<K, V> with();
    
    <K, V> ImmutableMap<K, V> of(K key, V value);
    <K, V> ImmutableMap<K, V> with(K key, V value);
    
    <K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2);
    <K, V> ImmutableMap<K, V> with(K key1, V value1, K key2, V value2);
    
    <K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3);
    <K, V> ImmutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3);
    
    <K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
    <K, V> ImmutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
    
    <K, V> ImmutableMap<K, V> ofMap(Map<? extends K, ? extends V> map);
    <K, V> ImmutableMap<K, V> withMap(Map<? extends K, ? extends V> map);
}

Primitive Collection Factories

Each primitive type has its own factory classes following the same pattern:

Primitive Lists Factories

// Int Lists Factory
package org.eclipse.collections.api.factory.primitive;

public final class IntLists {
    public static final MutableIntListFactory mutable = new MutableIntListFactory() {
        public MutableIntList empty() { /* implementation */ }
        public MutableIntList of() { /* implementation */ }
        public MutableIntList with() { /* implementation */ }
        public MutableIntList of(int element) { /* implementation */ }
        public MutableIntList with(int element) { /* implementation */ }
        public MutableIntList of(int... elements) { /* implementation */ }
        public MutableIntList with(int... elements) { /* implementation */ }
        public MutableIntList ofAll(IntIterable items) { /* implementation */ }
        public MutableIntList withAll(IntIterable items) { /* implementation */ }
        public MutableIntList ofInitialCapacity(int initialCapacity) { /* implementation */ }
        public MutableIntList withInitialCapacity(int initialCapacity) { /* implementation */ }
    };
    
    public static final ImmutableIntListFactory immutable = new ImmutableIntListFactory() {
        public ImmutableIntList empty() { /* implementation */ }
        public ImmutableIntList of() { /* implementation */ }
        public ImmutableIntList with() { /* implementation */ }
        public ImmutableIntList of(int element) { /* implementation */ }
        public ImmutableIntList with(int element) { /* implementation */ }
        public ImmutableIntList of(int... elements) { /* implementation */ }
        public ImmutableIntList with(int... elements) { /* implementation */ }
        public ImmutableIntList ofAll(IntIterable items) { /* implementation */ }
        public ImmutableIntList withAll(IntIterable items) { /* implementation */ }
    };
}

// Similar factory classes exist for all primitive types:
// BooleanLists, ByteLists, CharLists, DoubleLists, FloatLists, LongLists, ShortLists

Primitive Sets Factories

// Int Sets Factory
package org.eclipse.collections.api.factory.primitive;

public final class IntSets {
    public static final MutableIntSetFactory mutable;
    public static final ImmutableIntSetFactory immutable;
}

// Similar for all primitive types:
// BooleanSets, ByteSets, CharSets, DoubleSets, FloatSets, LongSets, ShortSets

Primitive Maps Factories

// Object to Int Maps Factory
package org.eclipse.collections.api.factory.primitive;

public final class ObjectIntMaps {
    public static final MutableObjectIntMapFactory<Object> mutable = new MutableObjectIntMapFactory<Object>() {
        public <K> MutableObjectIntMap<K> empty() { /* implementation */ }
        public <K> MutableObjectIntMap<K> of() { /* implementation */ }
        public <K> MutableObjectIntMap<K> with() { /* implementation */ }
        public <K> MutableObjectIntMap<K> of(K key, int value) { /* implementation */ }
        public <K> MutableObjectIntMap<K> with(K key, int value) { /* implementation */ }
        public <K> MutableObjectIntMap<K> ofInitialCapacity(int initialCapacity) { /* implementation */ }
        public <K> MutableObjectIntMap<K> withInitialCapacity(int initialCapacity) { /* implementation */ }
    };
    
    public static final ImmutableObjectIntMapFactory<Object> immutable;
}

// Int to Object Maps Factory
public final class IntObjectMaps {
    public static final MutableIntObjectMapFactory<Object> mutable;
    public static final ImmutableIntObjectMapFactory<Object> immutable;
}

// Int to Int Maps Factory
public final class IntIntMaps {
    public static final MutableIntIntMapFactory mutable;
    public static final ImmutableIntIntMapFactory immutable;
}

// Complete coverage for all primitive type combinations exists

Utility Interfaces and Classes

Partition Interfaces

Result interfaces for splitting collections based on predicates.

// Base Partition Interface
package org.eclipse.collections.api.partition;

public interface PartitionIterable<T> {
    RichIterable<T> getSelected();
    RichIterable<T> getRejected();
}

// Collection-specific partition interfaces
package org.eclipse.collections.api.partition.list;

public interface PartitionList<T> extends PartitionIterable<T> {
    ListIterable<T> getSelected();
    ListIterable<T> getRejected();
}

public interface PartitionMutableList<T> extends PartitionList<T> {
    MutableList<T> getSelected();
    MutableList<T> getRejected();
}

public interface PartitionImmutableList<T> extends PartitionList<T> {
    ImmutableList<T> getSelected();
    ImmutableList<T> getRejected();
}

// Similar partition interfaces exist for all collection types:
// PartitionSet, PartitionBag, PartitionStack

Tuple Interfaces

Container interfaces for multiple values.

// Two-element tuple
package org.eclipse.collections.api.tuple;

public interface Pair<T1, T2> {
    T1 getOne();
    T2 getTwo();
    
    // Utility methods
    Pair<T2, T1> swap();
    Map.Entry<T1, T2> toEntry();
    void put(Map<T1, T2> map);
}

// Three-element tuple
public interface Triple<T1, T2, T3> {
    T1 getOne();
    T2 getTwo();
    T3 getThree();
}

// Homogeneous two-element tuple
public interface Twin<T> extends Pair<T, T> {
}

// Homogeneous three-element tuple  
public interface Triplet<T> extends Triple<T, T, T> {
}

Ordered Collection Interfaces

Interfaces for collections with defined ordering.

// Base ordered interface
package org.eclipse.collections.api.ordered;

public interface OrderedIterable<T> extends RichIterable<T> {
    T getFirst();
    T getLast();
    
    // Ordered operations
    OrderedIterable<T> take(int count);
    OrderedIterable<T> drop(int count);
    OrderedIterable<T> takeWhile(Predicate<? super T> predicate);
    OrderedIterable<T> dropWhile(Predicate<? super T> predicate);
    
    // Functional operations preserve order
    <V> OrderedIterable<V> collect(Function<? super T, ? extends V> function);
    OrderedIterable<T> select(Predicate<? super T> predicate);
    OrderedIterable<T> reject(Predicate<? super T> predicate);
    
    // Zipping
    <S> OrderedIterable<Pair<T, S>> zip(Iterable<S> that);
    OrderedIterable<Pair<T, Integer>> zipWithIndex();
}

// Reversible iteration
package org.eclipse.collections.api.ordered;

public interface ReversibleIterable<T> extends OrderedIterable<T> {
    ReversibleIterable<T> toReversed();
    
    // Reverse iteration
    void forEachInReverse(Procedure<? super T> procedure);
    
    // Reverse detection
    T detectLastWith(Predicate2<? super T, ? super P> predicate, P parameter);
    Optional<T> detectLastWithOptional(Predicate2<? super T, ? super P> predicate, P parameter);
}

Sorted Collection Interface

Interface for collections with comparator-based ordering.

package org.eclipse.collections.api;

public interface SortedIterable<T> extends OrderedIterable<T> {
    Comparator<? super T> comparator();
    
    // Sorted-specific operations
    int binarySearch(T key);
    T min();
    T max();
    
    // Sorted transformations
    <V> ListIterable<V> collect(Function<? super T, ? extends V> function);
    SortedIterable<T> select(Predicate<? super T> predicate);
    SortedIterable<T> reject(Predicate<? super T> predicate);
    
    // Sorted range operations
    SortedIterable<T> takeWhile(Predicate<? super T> predicate);
    SortedIterable<T> dropWhile(Predicate<? super T> predicate);
}

Usage Examples

Using Static Factory Classes

// Create collections using factory classes
MutableList<String> mutableList = Lists.mutable.with("a", "b", "c");
ImmutableList<String> immutableList = Lists.immutable.with("a", "b", "c");
MutableSet<Integer> mutableSet = Sets.mutable.with(1, 2, 3);
MutableMap<String, Integer> map = Maps.mutable.with("key1", 1, "key2", 2);

// Empty collections
MutableList<String> emptyList = Lists.mutable.empty();
ImmutableSet<Integer> emptySet = Sets.immutable.of();

// From existing collections
List<String> javaList = Arrays.asList("x", "y", "z");
MutableList<String> eclipseList = Lists.mutable.withAll(javaList);
ImmutableList<String> immutableFromJava = Lists.immutable.ofAll(javaList);

// Fixed size collections
MutableList<String> fixedList = Lists.fixedSize.with("a", "b", "c");
// fixedList.add("d"); // Would throw UnsupportedOperationException
fixedList.set(0, "x"); // Allowed - modification of existing elements

Using Primitive Factory Classes

// Create primitive collections
MutableIntList intList = IntLists.mutable.with(1, 2, 3, 4, 5);
ImmutableIntSet intSet = IntSets.immutable.with(1, 2, 3);
MutableObjectIntMap<String> objectIntMap = ObjectIntMaps.mutable.with("a", 1, "b", 2);
MutableIntObjectMap<String> intObjectMap = IntObjectMaps.mutable.with(1, "a", 2, "b");

// Empty primitive collections
MutableIntList emptyInts = IntLists.mutable.empty();
MutableDoubleSet emptyDoubles = DoubleSets.mutable.of();

// With initial capacity
MutableIntList largeList = IntLists.mutable.withInitialCapacity(1000);

Using Multimap Factories

// Create multimaps
MutableListMultimap<String, Integer> listMultimap = 
    Multimaps.mutable.list.with("key1", 1, "key1", 2, "key2", 3);

MutableSetMultimap<String, Integer> setMultimap = 
    Multimaps.mutable.set.with("key1", 1, "key1", 2, "key2", 3); // Only one "1" for key1

ImmutableBagMultimap<String, String> bagMultimap = 
    Multimaps.immutable.bag.with("colors", "red", "colors", "blue", "colors", "red");

Using BiMap Factory

// Create bidirectional maps
MutableBiMap<String, Integer> biMap = BiMaps.mutable.with("Alice", 1, "Bob", 2);
BiMap<Integer, String> inverse = biMap.inverse();
String name = inverse.get(1); // "Alice"

ImmutableBiMap<String, Integer> immutableBiMap = 
    BiMaps.immutable.with("Charlie", 3, "David", 4);

Working with Partitions

// Partition collections
MutableList<Integer> numbers = Lists.mutable.with(1, 2, 3, 4, 5, 6);
PartitionMutableList<Integer> partition = numbers.partition(n -> n % 2 == 0);

MutableList<Integer> evens = partition.getSelected();   // [2, 4, 6]
MutableList<Integer> odds = partition.getRejected();    // [1, 3, 5]

Working with Tuples

// Create and use pairs
Pair<String, Integer> nameAge = Tuples.pair("Alice", 30);
String name = nameAge.getOne();      // "Alice"
Integer age = nameAge.getTwo();      // 30

// Swap elements
Pair<Integer, String> ageNameSwapped = nameAge.swap(); // (30, "Alice")

// Convert to Map entry
Map.Entry<String, Integer> entry = nameAge.toEntry();

// Use in map
Map<String, Integer> map = new HashMap<>();
nameAge.put(map); // Adds "Alice" -> 30 to the map

Advanced Factory Usage

// Chaining factory methods
MutableList<String> processedList = Lists.mutable
    .withAll(Arrays.asList("apple", "banana", "cherry"))
    .select(s -> s.length() > 5)
    .collect(String::toUpperCase);

// Creating collections with specific properties
MutableList<String> threadSafeList = Lists.multiReader.with("a", "b", "c");

// Converting between collection types using factories
Set<String> javaSet = new HashSet<>(Arrays.asList("x", "y", "z"));
ImmutableSet<String> eclipseSet = Sets.immutable.withAll(javaSet);
MutableBag<String> bag = Bags.mutable.withAll(eclipseSet);

The factory system in Eclipse Collections provides a consistent, fluent API for creating collections of all types while maintaining type safety and offering convenient method overloads for common use cases.

Install with Tessl CLI

npx tessl i tessl/maven-org-eclipse-collections--eclipse-collections-api

docs

core-collections.md

factories-utilities.md

functional-interfaces.md

index.md

maps-multimaps.md

primitive-collections.md

tile.json