0
# Factories and Utilities
1
2
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.
3
4
```java { .api }
5
// Required imports for types used in this documentation
6
import org.eclipse.collections.api.factory.Tuples;
7
```
8
9
## Static Factory Classes
10
11
### Lists Factory
12
Central factory for creating List collections of all variants.
13
14
```java { .api }
15
package org.eclipse.collections.api.factory;
16
17
public final class Lists {
18
// Mutable list factory
19
public static final MutableListFactory mutable = new MutableListFactory() {
20
public <T> MutableList<T> empty() { /* implementation */ }
21
public <T> MutableList<T> of() { /* implementation */ }
22
public <T> MutableList<T> with() { /* implementation */ }
23
public <T> MutableList<T> of(T element) { /* implementation */ }
24
public <T> MutableList<T> with(T element) { /* implementation */ }
25
public <T> MutableList<T> of(T... elements) { /* implementation */ }
26
public <T> MutableList<T> with(T... elements) { /* implementation */ }
27
public <T> MutableList<T> ofAll(Iterable<? extends T> items) { /* implementation */ }
28
public <T> MutableList<T> withAll(Iterable<? extends T> items) { /* implementation */ }
29
};
30
31
// Immutable list factory
32
public static final ImmutableListFactory immutable = new ImmutableListFactory() {
33
public <T> ImmutableList<T> empty() { /* implementation */ }
34
public <T> ImmutableList<T> of() { /* implementation */ }
35
public <T> ImmutableList<T> with() { /* implementation */ }
36
public <T> ImmutableList<T> of(T element) { /* implementation */ }
37
public <T> ImmutableList<T> with(T element) { /* implementation */ }
38
public <T> ImmutableList<T> of(T... elements) { /* implementation */ }
39
public <T> ImmutableList<T> with(T... elements) { /* implementation */ }
40
public <T> ImmutableList<T> ofAll(Iterable<? extends T> items) { /* implementation */ }
41
public <T> ImmutableList<T> withAll(Iterable<? extends T> items) { /* implementation */ }
42
};
43
44
// Fixed size list factory
45
public static final FixedSizeListFactory fixedSize = new FixedSizeListFactory() {
46
public <T> MutableList<T> empty() { /* implementation */ }
47
public <T> MutableList<T> of() { /* implementation */ }
48
public <T> MutableList<T> with() { /* implementation */ }
49
public <T> MutableList<T> of(T element) { /* implementation */ }
50
public <T> MutableList<T> with(T element) { /* implementation */ }
51
public <T> MutableList<T> of(T... elements) { /* implementation */ }
52
public <T> MutableList<T> with(T... elements) { /* implementation */ }
53
public <T> MutableList<T> ofAll(Iterable<? extends T> items) { /* implementation */ }
54
public <T> MutableList<T> withAll(Iterable<? extends T> items) { /* implementation */ }
55
};
56
57
// Multi-reader list factory (thread-safe mutable)
58
public static final MultiReaderListFactory multiReader = new MultiReaderListFactory() {
59
public <T> MutableList<T> empty() { /* implementation */ }
60
public <T> MutableList<T> of() { /* implementation */ }
61
public <T> MutableList<T> with() { /* implementation */ }
62
public <T> MutableList<T> of(T... elements) { /* implementation */ }
63
public <T> MutableList<T> with(T... elements) { /* implementation */ }
64
public <T> MutableList<T> ofAll(Iterable<? extends T> items) { /* implementation */ }
65
public <T> MutableList<T> withAll(Iterable<? extends T> items) { /* implementation */ }
66
};
67
}
68
```
69
70
### Sets Factory
71
Factory for creating Set collections with mathematical operations.
72
73
```java { .api }
74
package org.eclipse.collections.api.factory;
75
76
public final class Sets {
77
public static final MutableSetFactory mutable;
78
public static final ImmutableSetFactory immutable;
79
public static final FixedSizeSetFactory fixedSize;
80
public static final MultiReaderSetFactory multiReader;
81
}
82
```
83
84
### Maps Factory
85
Factory for creating Map collections with rich key-value operations.
86
87
```java { .api }
88
package org.eclipse.collections.api.factory;
89
90
public final class Maps {
91
public static final MutableMapFactory mutable;
92
public static final ImmutableMapFactory immutable;
93
public static final FixedSizeMapFactory fixedSize;
94
public static final MultiReaderMapFactory multiReader;
95
}
96
```
97
98
### Bags Factory
99
Factory for creating Bag collections (multisets with occurrence counting).
100
101
```java { .api }
102
package org.eclipse.collections.api.factory;
103
104
public final class Bags {
105
public static final MutableBagFactory mutable;
106
public static final ImmutableBagFactory immutable;
107
}
108
```
109
110
### Stacks Factory
111
Factory for creating Stack collections with LIFO operations.
112
113
```java { .api }
114
package org.eclipse.collections.api.factory;
115
116
public final class Stacks {
117
public static final MutableStackFactory mutable;
118
public static final ImmutableStackFactory immutable;
119
}
120
```
121
122
### Multimaps Factory
123
Factory for creating Multimap collections with one-to-many relationships.
124
125
```java { .api }
126
package org.eclipse.collections.api.factory;
127
128
public final class Multimaps {
129
public static final class mutable {
130
public static final MutableListMultimapFactory list;
131
public static final MutableSetMultimapFactory set;
132
public static final MutableBagMultimapFactory bag;
133
public static final MutableSortedSetMultimapFactory sortedSet;
134
public static final MutableSortedBagMultimapFactory sortedBag;
135
}
136
137
public static final class immutable {
138
public static final ImmutableListMultimapFactory list;
139
public static final ImmutableSetMultimapFactory set;
140
public static final ImmutableBagMultimapFactory bag;
141
public static final ImmutableSortedSetMultimapFactory sortedSet;
142
public static final ImmutableSortedBagMultimapFactory sortedBag;
143
}
144
}
145
```
146
147
### BiMaps Factory
148
Factory for creating bidirectional maps.
149
150
```java { .api }
151
package org.eclipse.collections.api.factory;
152
153
public final class BiMaps {
154
public static final MutableBiMapFactory mutable;
155
public static final ImmutableBiMapFactory immutable;
156
}
157
```
158
159
## Factory Interface Definitions
160
161
### Core Factory Interfaces
162
All collection factory interfaces follow a consistent pattern:
163
164
```java { .api }
165
// Mutable List Factory Interface
166
package org.eclipse.collections.api.factory.list;
167
168
public interface MutableListFactory {
169
// Empty collections
170
<T> MutableList<T> empty();
171
<T> MutableList<T> of();
172
<T> MutableList<T> with();
173
174
// Single element collections
175
<T> MutableList<T> of(T element);
176
<T> MutableList<T> with(T element);
177
178
// Variable argument collections
179
<T> MutableList<T> of(T... elements);
180
<T> MutableList<T> with(T... elements);
181
182
// From iterables
183
<T> MutableList<T> ofAll(Iterable<? extends T> items);
184
<T> MutableList<T> withAll(Iterable<? extends T> items);
185
186
// From initial capacity
187
<T> MutableList<T> ofInitialCapacity(int capacity);
188
<T> MutableList<T> withInitialCapacity(int capacity);
189
190
// From arrays
191
<T> MutableList<T> ofArray(T[] array);
192
<T> MutableList<T> withArray(T[] array);
193
}
194
195
// Immutable List Factory Interface
196
package org.eclipse.collections.api.factory.list;
197
198
public interface ImmutableListFactory {
199
<T> ImmutableList<T> empty();
200
<T> ImmutableList<T> of();
201
<T> ImmutableList<T> with();
202
203
<T> ImmutableList<T> of(T element);
204
<T> ImmutableList<T> with(T element);
205
206
<T> ImmutableList<T> of(T... elements);
207
<T> ImmutableList<T> with(T... elements);
208
209
<T> ImmutableList<T> ofAll(Iterable<? extends T> items);
210
<T> ImmutableList<T> withAll(Iterable<? extends T> items);
211
}
212
213
// Fixed Size List Factory Interface
214
package org.eclipse.collections.api.factory.list;
215
216
public interface FixedSizeListFactory {
217
<T> MutableList<T> empty();
218
<T> MutableList<T> of();
219
<T> MutableList<T> with();
220
221
<T> MutableList<T> of(T element);
222
<T> MutableList<T> with(T element);
223
224
<T> MutableList<T> of(T... elements);
225
<T> MutableList<T> with(T... elements);
226
227
<T> MutableList<T> ofAll(Iterable<? extends T> items);
228
<T> MutableList<T> withAll(Iterable<? extends T> items);
229
}
230
```
231
232
### Map Factory Interfaces
233
Map factories support key-value pair creation:
234
235
```java { .api }
236
// Mutable Map Factory Interface
237
package org.eclipse.collections.api.factory.map;
238
239
public interface MutableMapFactory {
240
<K, V> MutableMap<K, V> empty();
241
<K, V> MutableMap<K, V> of();
242
<K, V> MutableMap<K, V> with();
243
244
<K, V> MutableMap<K, V> of(K key, V value);
245
<K, V> MutableMap<K, V> with(K key, V value);
246
247
<K, V> MutableMap<K, V> of(K key1, V value1, K key2, V value2);
248
<K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2);
249
250
<K, V> MutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3);
251
<K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3);
252
253
<K, V> MutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
254
<K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
255
256
// From pairs
257
<K, V> MutableMap<K, V> ofMap(Map<? extends K, ? extends V> map);
258
<K, V> MutableMap<K, V> withMap(Map<? extends K, ? extends V> map);
259
260
// From initial capacity
261
<K, V> MutableMap<K, V> ofInitialCapacity(int initialCapacity);
262
<K, V> MutableMap<K, V> withInitialCapacity(int initialCapacity);
263
}
264
265
// Immutable Map Factory Interface
266
package org.eclipse.collections.api.factory.map;
267
268
public interface ImmutableMapFactory {
269
<K, V> ImmutableMap<K, V> empty();
270
<K, V> ImmutableMap<K, V> of();
271
<K, V> ImmutableMap<K, V> with();
272
273
<K, V> ImmutableMap<K, V> of(K key, V value);
274
<K, V> ImmutableMap<K, V> with(K key, V value);
275
276
<K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2);
277
<K, V> ImmutableMap<K, V> with(K key1, V value1, K key2, V value2);
278
279
<K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3);
280
<K, V> ImmutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3);
281
282
<K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
283
<K, V> ImmutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
284
285
<K, V> ImmutableMap<K, V> ofMap(Map<? extends K, ? extends V> map);
286
<K, V> ImmutableMap<K, V> withMap(Map<? extends K, ? extends V> map);
287
}
288
```
289
290
## Primitive Collection Factories
291
292
Each primitive type has its own factory classes following the same pattern:
293
294
### Primitive Lists Factories
295
296
```java { .api }
297
// Int Lists Factory
298
package org.eclipse.collections.api.factory.primitive;
299
300
public final class IntLists {
301
public static final MutableIntListFactory mutable = new MutableIntListFactory() {
302
public MutableIntList empty() { /* implementation */ }
303
public MutableIntList of() { /* implementation */ }
304
public MutableIntList with() { /* implementation */ }
305
public MutableIntList of(int element) { /* implementation */ }
306
public MutableIntList with(int element) { /* implementation */ }
307
public MutableIntList of(int... elements) { /* implementation */ }
308
public MutableIntList with(int... elements) { /* implementation */ }
309
public MutableIntList ofAll(IntIterable items) { /* implementation */ }
310
public MutableIntList withAll(IntIterable items) { /* implementation */ }
311
public MutableIntList ofInitialCapacity(int initialCapacity) { /* implementation */ }
312
public MutableIntList withInitialCapacity(int initialCapacity) { /* implementation */ }
313
};
314
315
public static final ImmutableIntListFactory immutable = new ImmutableIntListFactory() {
316
public ImmutableIntList empty() { /* implementation */ }
317
public ImmutableIntList of() { /* implementation */ }
318
public ImmutableIntList with() { /* implementation */ }
319
public ImmutableIntList of(int element) { /* implementation */ }
320
public ImmutableIntList with(int element) { /* implementation */ }
321
public ImmutableIntList of(int... elements) { /* implementation */ }
322
public ImmutableIntList with(int... elements) { /* implementation */ }
323
public ImmutableIntList ofAll(IntIterable items) { /* implementation */ }
324
public ImmutableIntList withAll(IntIterable items) { /* implementation */ }
325
};
326
}
327
328
// Similar factory classes exist for all primitive types:
329
// BooleanLists, ByteLists, CharLists, DoubleLists, FloatLists, LongLists, ShortLists
330
```
331
332
### Primitive Sets Factories
333
334
```java { .api }
335
// Int Sets Factory
336
package org.eclipse.collections.api.factory.primitive;
337
338
public final class IntSets {
339
public static final MutableIntSetFactory mutable;
340
public static final ImmutableIntSetFactory immutable;
341
}
342
343
// Similar for all primitive types:
344
// BooleanSets, ByteSets, CharSets, DoubleSets, FloatSets, LongSets, ShortSets
345
```
346
347
### Primitive Maps Factories
348
349
```java { .api }
350
// Object to Int Maps Factory
351
package org.eclipse.collections.api.factory.primitive;
352
353
public final class ObjectIntMaps {
354
public static final MutableObjectIntMapFactory<Object> mutable = new MutableObjectIntMapFactory<Object>() {
355
public <K> MutableObjectIntMap<K> empty() { /* implementation */ }
356
public <K> MutableObjectIntMap<K> of() { /* implementation */ }
357
public <K> MutableObjectIntMap<K> with() { /* implementation */ }
358
public <K> MutableObjectIntMap<K> of(K key, int value) { /* implementation */ }
359
public <K> MutableObjectIntMap<K> with(K key, int value) { /* implementation */ }
360
public <K> MutableObjectIntMap<K> ofInitialCapacity(int initialCapacity) { /* implementation */ }
361
public <K> MutableObjectIntMap<K> withInitialCapacity(int initialCapacity) { /* implementation */ }
362
};
363
364
public static final ImmutableObjectIntMapFactory<Object> immutable;
365
}
366
367
// Int to Object Maps Factory
368
public final class IntObjectMaps {
369
public static final MutableIntObjectMapFactory<Object> mutable;
370
public static final ImmutableIntObjectMapFactory<Object> immutable;
371
}
372
373
// Int to Int Maps Factory
374
public final class IntIntMaps {
375
public static final MutableIntIntMapFactory mutable;
376
public static final ImmutableIntIntMapFactory immutable;
377
}
378
379
// Complete coverage for all primitive type combinations exists
380
```
381
382
## Utility Interfaces and Classes
383
384
### Partition Interfaces
385
Result interfaces for splitting collections based on predicates.
386
387
```java { .api }
388
// Base Partition Interface
389
package org.eclipse.collections.api.partition;
390
391
public interface PartitionIterable<T> {
392
RichIterable<T> getSelected();
393
RichIterable<T> getRejected();
394
}
395
396
// Collection-specific partition interfaces
397
package org.eclipse.collections.api.partition.list;
398
399
public interface PartitionList<T> extends PartitionIterable<T> {
400
ListIterable<T> getSelected();
401
ListIterable<T> getRejected();
402
}
403
404
public interface PartitionMutableList<T> extends PartitionList<T> {
405
MutableList<T> getSelected();
406
MutableList<T> getRejected();
407
}
408
409
public interface PartitionImmutableList<T> extends PartitionList<T> {
410
ImmutableList<T> getSelected();
411
ImmutableList<T> getRejected();
412
}
413
414
// Similar partition interfaces exist for all collection types:
415
// PartitionSet, PartitionBag, PartitionStack
416
```
417
418
### Tuple Interfaces
419
Container interfaces for multiple values.
420
421
```java { .api }
422
// Two-element tuple
423
package org.eclipse.collections.api.tuple;
424
425
public interface Pair<T1, T2> {
426
T1 getOne();
427
T2 getTwo();
428
429
// Utility methods
430
Pair<T2, T1> swap();
431
Map.Entry<T1, T2> toEntry();
432
void put(Map<T1, T2> map);
433
}
434
435
// Three-element tuple
436
public interface Triple<T1, T2, T3> {
437
T1 getOne();
438
T2 getTwo();
439
T3 getThree();
440
}
441
442
// Homogeneous two-element tuple
443
public interface Twin<T> extends Pair<T, T> {
444
}
445
446
// Homogeneous three-element tuple
447
public interface Triplet<T> extends Triple<T, T, T> {
448
}
449
```
450
451
### Ordered Collection Interfaces
452
Interfaces for collections with defined ordering.
453
454
```java { .api }
455
// Base ordered interface
456
package org.eclipse.collections.api.ordered;
457
458
public interface OrderedIterable<T> extends RichIterable<T> {
459
T getFirst();
460
T getLast();
461
462
// Ordered operations
463
OrderedIterable<T> take(int count);
464
OrderedIterable<T> drop(int count);
465
OrderedIterable<T> takeWhile(Predicate<? super T> predicate);
466
OrderedIterable<T> dropWhile(Predicate<? super T> predicate);
467
468
// Functional operations preserve order
469
<V> OrderedIterable<V> collect(Function<? super T, ? extends V> function);
470
OrderedIterable<T> select(Predicate<? super T> predicate);
471
OrderedIterable<T> reject(Predicate<? super T> predicate);
472
473
// Zipping
474
<S> OrderedIterable<Pair<T, S>> zip(Iterable<S> that);
475
OrderedIterable<Pair<T, Integer>> zipWithIndex();
476
}
477
478
// Reversible iteration
479
package org.eclipse.collections.api.ordered;
480
481
public interface ReversibleIterable<T> extends OrderedIterable<T> {
482
ReversibleIterable<T> toReversed();
483
484
// Reverse iteration
485
void forEachInReverse(Procedure<? super T> procedure);
486
487
// Reverse detection
488
T detectLastWith(Predicate2<? super T, ? super P> predicate, P parameter);
489
Optional<T> detectLastWithOptional(Predicate2<? super T, ? super P> predicate, P parameter);
490
}
491
```
492
493
### Sorted Collection Interface
494
Interface for collections with comparator-based ordering.
495
496
```java { .api }
497
package org.eclipse.collections.api;
498
499
public interface SortedIterable<T> extends OrderedIterable<T> {
500
Comparator<? super T> comparator();
501
502
// Sorted-specific operations
503
int binarySearch(T key);
504
T min();
505
T max();
506
507
// Sorted transformations
508
<V> ListIterable<V> collect(Function<? super T, ? extends V> function);
509
SortedIterable<T> select(Predicate<? super T> predicate);
510
SortedIterable<T> reject(Predicate<? super T> predicate);
511
512
// Sorted range operations
513
SortedIterable<T> takeWhile(Predicate<? super T> predicate);
514
SortedIterable<T> dropWhile(Predicate<? super T> predicate);
515
}
516
```
517
518
## Usage Examples
519
520
### Using Static Factory Classes
521
```java { .api }
522
// Create collections using factory classes
523
MutableList<String> mutableList = Lists.mutable.with("a", "b", "c");
524
ImmutableList<String> immutableList = Lists.immutable.with("a", "b", "c");
525
MutableSet<Integer> mutableSet = Sets.mutable.with(1, 2, 3);
526
MutableMap<String, Integer> map = Maps.mutable.with("key1", 1, "key2", 2);
527
528
// Empty collections
529
MutableList<String> emptyList = Lists.mutable.empty();
530
ImmutableSet<Integer> emptySet = Sets.immutable.of();
531
532
// From existing collections
533
List<String> javaList = Arrays.asList("x", "y", "z");
534
MutableList<String> eclipseList = Lists.mutable.withAll(javaList);
535
ImmutableList<String> immutableFromJava = Lists.immutable.ofAll(javaList);
536
537
// Fixed size collections
538
MutableList<String> fixedList = Lists.fixedSize.with("a", "b", "c");
539
// fixedList.add("d"); // Would throw UnsupportedOperationException
540
fixedList.set(0, "x"); // Allowed - modification of existing elements
541
```
542
543
### Using Primitive Factory Classes
544
```java { .api }
545
// Create primitive collections
546
MutableIntList intList = IntLists.mutable.with(1, 2, 3, 4, 5);
547
ImmutableIntSet intSet = IntSets.immutable.with(1, 2, 3);
548
MutableObjectIntMap<String> objectIntMap = ObjectIntMaps.mutable.with("a", 1, "b", 2);
549
MutableIntObjectMap<String> intObjectMap = IntObjectMaps.mutable.with(1, "a", 2, "b");
550
551
// Empty primitive collections
552
MutableIntList emptyInts = IntLists.mutable.empty();
553
MutableDoubleSet emptyDoubles = DoubleSets.mutable.of();
554
555
// With initial capacity
556
MutableIntList largeList = IntLists.mutable.withInitialCapacity(1000);
557
```
558
559
### Using Multimap Factories
560
```java { .api }
561
// Create multimaps
562
MutableListMultimap<String, Integer> listMultimap =
563
Multimaps.mutable.list.with("key1", 1, "key1", 2, "key2", 3);
564
565
MutableSetMultimap<String, Integer> setMultimap =
566
Multimaps.mutable.set.with("key1", 1, "key1", 2, "key2", 3); // Only one "1" for key1
567
568
ImmutableBagMultimap<String, String> bagMultimap =
569
Multimaps.immutable.bag.with("colors", "red", "colors", "blue", "colors", "red");
570
```
571
572
### Using BiMap Factory
573
```java { .api }
574
// Create bidirectional maps
575
MutableBiMap<String, Integer> biMap = BiMaps.mutable.with("Alice", 1, "Bob", 2);
576
BiMap<Integer, String> inverse = biMap.inverse();
577
String name = inverse.get(1); // "Alice"
578
579
ImmutableBiMap<String, Integer> immutableBiMap =
580
BiMaps.immutable.with("Charlie", 3, "David", 4);
581
```
582
583
### Working with Partitions
584
```java { .api }
585
// Partition collections
586
MutableList<Integer> numbers = Lists.mutable.with(1, 2, 3, 4, 5, 6);
587
PartitionMutableList<Integer> partition = numbers.partition(n -> n % 2 == 0);
588
589
MutableList<Integer> evens = partition.getSelected(); // [2, 4, 6]
590
MutableList<Integer> odds = partition.getRejected(); // [1, 3, 5]
591
```
592
593
### Working with Tuples
594
```java { .api }
595
// Create and use pairs
596
Pair<String, Integer> nameAge = Tuples.pair("Alice", 30);
597
String name = nameAge.getOne(); // "Alice"
598
Integer age = nameAge.getTwo(); // 30
599
600
// Swap elements
601
Pair<Integer, String> ageNameSwapped = nameAge.swap(); // (30, "Alice")
602
603
// Convert to Map entry
604
Map.Entry<String, Integer> entry = nameAge.toEntry();
605
606
// Use in map
607
Map<String, Integer> map = new HashMap<>();
608
nameAge.put(map); // Adds "Alice" -> 30 to the map
609
```
610
611
### Advanced Factory Usage
612
```java { .api }
613
// Chaining factory methods
614
MutableList<String> processedList = Lists.mutable
615
.withAll(Arrays.asList("apple", "banana", "cherry"))
616
.select(s -> s.length() > 5)
617
.collect(String::toUpperCase);
618
619
// Creating collections with specific properties
620
MutableList<String> threadSafeList = Lists.multiReader.with("a", "b", "c");
621
622
// Converting between collection types using factories
623
Set<String> javaSet = new HashSet<>(Arrays.asList("x", "y", "z"));
624
ImmutableSet<String> eclipseSet = Sets.immutable.withAll(javaSet);
625
MutableBag<String> bag = Bags.mutable.withAll(eclipseSet);
626
```
627
628
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.