0
# Factory Methods
1

2
Eclipse Collections provides static factory classes as the primary entry points for creating all collection types. These factories offer convenient methods for creating mutable, immutable, and fixed-size collections with various initialization options.
3

4
## Required Imports
5

6
```java
7
import java.util.stream.Stream;
8
import org.eclipse.collections.api.block.function.Function0;
9
```
10

11
## Capabilities
12

13
### Lists Factory
14

15
Main entry point for creating Lists of all types, located in `org.eclipse.collections.impl.factory.Lists`.
16

17
```java { .api }
18
/**
19
 * Main factory class for creating Lists
20
 */
21
public final class Lists {
22
    public static final ImmutableListFactory immutable;
23
    public static final MutableListFactory mutable;
24
    public static final FixedSizeListFactory fixedSize;
25
    public static final MultiReaderListFactory multiReader;
26
    
27
    /**
28
     * Adapt a JDK List to Eclipse Collections MutableList
29
     * @param list JDK List to adapt
30
     * @return MutableList wrapping the input list
31
     */
32
    public static <T> MutableList<T> adapt(List<T> list);
33
}
34

35
interface MutableListFactory {
36
    /**
37
     * Create an empty mutable list
38
     * @return empty MutableList
39
     */
40
    <T> MutableList<T> empty();
41
    
42
    /**
43
     * Create a mutable list with elements
44
     * @param elements varargs elements to include
45
     * @return MutableList containing the elements
46
     */
47
    <T> MutableList<T> with(T... elements);
48
    
49
    /**
50
     * Create a mutable list from an iterable
51
     * @param items iterable to copy from
52
     * @return MutableList containing all items
53
     */
54
    <T> MutableList<T> withAll(Iterable<? extends T> items);
55
    
56
    /**
57
     * Create a mutable list with initial capacity
58
     * @param initialCapacity initial capacity
59
     * @return empty MutableList with specified capacity
60
     */
61
    <T> MutableList<T> withInitialCapacity(int initialCapacity);
62
    
63
    /**
64
     * Create a mutable list from a Stream
65
     * @param stream Stream to copy from
66
     * @return MutableList containing all stream elements
67
     */
68
    <T> MutableList<T> fromStream(Stream<? extends T> stream);
69
    
70
    /**
71
     * Create a mutable list with generated values
72
     * @param size number of elements to generate
73
     * @param factory function to generate each element
74
     * @return MutableList with generated elements
75
     */
76
    <T> MutableList<T> withNValues(int size, Function0<? extends T> factory);
77
    
78
    /**
79
     * Create a mutable list copying from an array
80
     * @param array array to copy from
81
     * @return MutableList containing all array elements
82
     */
83
    <T> MutableList<T> wrapCopy(T... array);
84
}
85

86
interface ImmutableListFactory {
87
    /**
88
     * Create an empty immutable list
89
     * @return empty ImmutableList
90
     */
91
    <T> ImmutableList<T> empty();
92
    
93
    /**
94
     * Create an immutable list with elements
95
     * @param elements varargs elements to include
96
     * @return ImmutableList containing the elements
97
     */
98
    <T> ImmutableList<T> of(T... elements);
99
    
100
    /**
101
     * Create an immutable list from an iterable
102
     * @param items iterable to copy from
103
     * @return ImmutableList containing all items
104
     */
105
    <T> ImmutableList<T> ofAll(Iterable<? extends T> items);
106
}
107

108
interface FixedSizeListFactory {
109
    /**
110
     * Create a fixed-size list with elements
111
     * @param elements varargs elements to include
112
     * @return FixedSizeList that cannot be resized
113
     */
114
    <T> FixedSizeList<T> with(T... elements);
115
}
116
```
117

118
**Usage Examples:**
119

120
```java
121
import org.eclipse.collections.impl.factory.Lists;
122
import org.eclipse.collections.api.list.MutableList;
123
import org.eclipse.collections.api.list.ImmutableList;
124

125
// Create mutable lists
126
MutableList<String> emptyList = Lists.mutable.empty();
127
MutableList<String> names = Lists.mutable.with("Alice", "Bob", "Charlie");
128
MutableList<Integer> fromIterable = Lists.mutable.withAll(Arrays.asList(1, 2, 3));
129

130
// Create immutable lists  
131
ImmutableList<String> immutableNames = Lists.immutable.of("Alice", "Bob", "Charlie");
132
ImmutableList<Integer> immutableNumbers = Lists.immutable.ofAll(Arrays.asList(1, 2, 3));
133

134
// Adapt JDK collections
135
List<String> jdkList = new ArrayList<>(Arrays.asList("X", "Y", "Z"));
136
MutableList<String> adapted = Lists.adapt(jdkList);
137

138
// Fixed-size lists
139
FixedSizeList<String> fixed = Lists.fixedSize.with("A", "B", "C");
140
// fixed.add("D"); // Would throw UnsupportedOperationException
141
```
142

143
### Sets Factory
144

145
Main entry point for creating Sets and performing set operations, located in `org.eclipse.collections.impl.factory.Sets`.
146

147
```java { .api }
148
/**
149
 * Main factory class for creating Sets and set operations
150
 */
151
public final class Sets {
152
    public static final ImmutableSetFactory immutable;
153
    public static final MutableSetFactory mutable;
154
    public static final FixedSizeSetFactory fixedSize;
155
    public static final MultiReaderSetFactory multiReader;
156
    
157
    /**
158
     * Adapt a JDK Set to Eclipse Collections MutableSet
159
     * @param set JDK Set to adapt
160
     * @return MutableSet wrapping the input set
161
     */
162
    public static <T> MutableSet<T> adapt(Set<T> set);
163
    
164
    /**
165
     * Compute union of two sets
166
     * @param setA first set
167
     * @param setB second set  
168
     * @return new MutableSet containing union
169
     */
170
    public static <E> MutableSet<E> union(Set<? extends E> setA, Set<? extends E> setB);
171
    
172
    /**
173
     * Compute intersection of two sets
174
     * @param setA first set
175
     * @param setB second set
176
     * @return new MutableSet containing intersection
177
     */
178
    public static <E> MutableSet<E> intersect(Set<? extends E> setA, Set<? extends E> setB);
179
    
180
    /**
181
     * Compute difference of two sets (setA - setB)
182
     * @param minuend set to subtract from
183
     * @param subtrahend set to subtract
184
     * @return new MutableSet containing difference
185
     */
186
    public static <E> MutableSet<E> difference(Set<? extends E> minuend, Set<? extends E> subtrahend);
187
    
188
    /**
189
     * Compute symmetric difference of two sets
190
     * @param setA first set
191
     * @param setB second set
192
     * @return new MutableSet containing symmetric difference
193
     */
194
    public static <E> MutableSet<E> symmetricDifference(Set<? extends E> setA, Set<? extends E> setB);
195
    
196
    /**
197
     * Generate power set of a set
198
     * @param set input set
199
     * @return MutableSet of all subsets
200
     */
201
    public static <T> MutableSet<MutableSet<T>> powerSet(Set<T> set);
202
    
203
    /**
204
     * Compute cartesian product of two sets
205
     * @param set1 first set
206
     * @param set2 second set
207
     * @return LazyIterable of pairs representing cartesian product
208
     */
209
    public static <A, B> LazyIterable<Pair<A, B>> cartesianProduct(Set<A> set1, Set<B> set2);
210
    
211
    /**
212
     * Test if one set is a subset of another
213
     * @param candidate potential subset
214
     * @param superset potential superset
215
     * @return true if candidate is subset of superset
216
     */
217
    public static <E> boolean isSubsetOf(Set<? extends E> candidate, Set<? extends E> superset);
218
    
219
    /**
220
     * Test if one set is a proper subset of another
221
     * @param candidate potential proper subset  
222
     * @param superset potential superset
223
     * @return true if candidate is proper subset of superset
224
     */
225
    public static <E> boolean isProperSubsetOf(Set<? extends E> candidate, Set<? extends E> superset);
226
}
227

228
interface MutableSetFactory {
229
    <T> MutableSet<T> empty();
230
    <T> MutableSet<T> with(T... elements);
231
    <T> MutableSet<T> withAll(Iterable<? extends T> items);
232
    <T> MutableSet<T> withInitialCapacity(int initialCapacity);
233
}
234

235
interface ImmutableSetFactory {
236
    <T> ImmutableSet<T> empty();
237
    <T> ImmutableSet<T> of(T... elements);
238
    <T> ImmutableSet<T> ofAll(Iterable<? extends T> items);
239
}
240
```
241

242
**Usage Examples:**
243

244
```java
245
import org.eclipse.collections.impl.factory.Sets;
246

247
// Basic set creation
248
MutableSet<String> colors = Sets.mutable.with("red", "green", "blue");
249
ImmutableSet<Integer> numbers = Sets.immutable.of(1, 2, 3, 4, 5);
250

251
// Set algebra operations
252
Set<String> setA = Sets.mutable.with("A", "B", "C");  
253
Set<String> setB = Sets.mutable.with("B", "C", "D");
254

255
MutableSet<String> union = Sets.union(setA, setB); // [A, B, C, D]
256
MutableSet<String> intersection = Sets.intersect(setA, setB); // [B, C]  
257
MutableSet<String> difference = Sets.difference(setA, setB); // [A]
258
MutableSet<String> symmetric = Sets.symmetricDifference(setA, setB); // [A, D]
259

260
// Subset testing
261
boolean isSubset = Sets.isSubsetOf(
262
    Sets.mutable.with("A", "B"), 
263
    Sets.mutable.with("A", "B", "C")
264
); // true
265

266
// Power set
267
MutableSet<MutableSet<String>> powerSet = Sets.powerSet(Sets.mutable.with("X", "Y"));
268
// Contains: [], [X], [Y], [X,Y]
269
```
270

271
### Maps Factory
272

273
Main entry point for creating Maps, located in `org.eclipse.collections.impl.factory.Maps`.
274

275
```java { .api }
276
/**
277
 * Main factory class for creating Maps
278
 */
279
public final class Maps {
280
    public static final ImmutableMapFactory immutable;
281
    public static final MutableMapFactory mutable;
282
    public static final FixedSizeMapFactory fixedSize;
283
    
284
    /**
285
     * Adapt a JDK Map to Eclipse Collections MutableMap
286
     * @param map JDK Map to adapt  
287
     * @return MutableMap wrapping the input map
288
     */
289
    public static <K, V> MutableMap<K, V> adapt(Map<K, V> map);
290
}
291

292
interface MutableMapFactory {
293
    /**
294
     * Create an empty mutable map
295
     * @return empty MutableMap
296
     */
297
    <K, V> MutableMap<K, V> empty();
298
    
299
    /**
300
     * Create a mutable map with one key-value pair
301
     * @param key the key
302
     * @param value the value
303
     * @return MutableMap containing the pair
304
     */
305
    <K, V> MutableMap<K, V> with(K key, V value);
306
    
307
    /**
308
     * Create a mutable map with two key-value pairs
309
     * @param key1 first key
310
     * @param value1 first value  
311
     * @param key2 second key
312
     * @param value2 second value
313
     * @return MutableMap containing the pairs
314
     */
315
    <K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2);
316
    
317
    /**
318
     * Create a mutable map with three key-value pairs
319
     */
320
    <K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3);
321
    
322
    /**
323
     * Create a mutable map with four key-value pairs  
324
     */
325
    <K, V> MutableMap<K, V> with(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
326
    
327
    /**
328
     * Create a mutable map from pairs
329
     * @param keyValuePairs alternating keys and values
330
     * @return MutableMap containing the pairs
331
     */
332
    <K, V> MutableMap<K, V> of(Object... keyValuePairs);
333
    
334
    /**
335
     * Create a mutable map with initial capacity
336
     * @param initialCapacity initial capacity
337
     * @return empty MutableMap with specified capacity
338
     */
339
    <K, V> MutableMap<K, V> withInitialCapacity(int initialCapacity);
340
}
341

342
interface ImmutableMapFactory {
343
    <K, V> ImmutableMap<K, V> empty();
344
    <K, V> ImmutableMap<K, V> of(K key, V value);
345
    <K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2);
346
    <K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3);
347
    <K, V> ImmutableMap<K, V> of(K key1, V value1, K key2, V value2, K key3, V value3, K key4, V value4);
348
    <K, V> ImmutableMap<K, V> ofAll(Map<? extends K, ? extends V> map);
349
}
350
```
351

352
### Bags Factory
353

354
Main entry point for creating Bags (multisets), located in `org.eclipse.collections.impl.factory.Bags`.
355

356
```java { .api }
357
/**
358
 * Main factory class for creating Bags (multisets)
359
 */
360
public final class Bags {
361
    public static final ImmutableBagFactory immutable;
362
    public static final MutableBagFactory mutable;
363
    public static final MultiReaderBagFactory multiReader;
364
}
365

366
interface MutableBagFactory {
367
    <T> MutableBag<T> empty();
368
    <T> MutableBag<T> with(T... elements);
369
    <T> MutableBag<T> withAll(Iterable<? extends T> items);
370
}
371

372
interface ImmutableBagFactory {
373
    <T> ImmutableBag<T> empty();
374
    <T> ImmutableBag<T> of(T... elements);
375
    <T> ImmutableBag<T> ofAll(Iterable<? extends T> items);
376
}
377
```
378

379
### Stacks Factory  
380

381
Main entry point for creating Stacks, located in `org.eclipse.collections.impl.factory.Stacks`.
382

383
```java { .api }
384
/**
385
 * Main factory class for creating Stacks
386
 */
387
public final class Stacks {
388
    public static final ImmutableStackFactory immutable;
389
    public static final MutableStackFactory mutable;
390
}
391

392
interface MutableStackFactory {
393
    <T> MutableStack<T> empty();
394
    <T> MutableStack<T> with(T... elements);
395
    <T> MutableStack<T> withAll(Iterable<? extends T> items);
396
    <T> MutableStack<T> withReversed(T... elements);
397
}
398

399
interface ImmutableStackFactory {
400
    <T> ImmutableStack<T> empty();
401
    <T> ImmutableStack<T> of(T... elements);
402
    <T> ImmutableStack<T> ofAll(Iterable<? extends T> items);
403
    <T> ImmutableStack<T> ofReversed(T... elements);
404
}
405
```
406

407
### Multimaps Factory
408

409
Main entry point for creating Multimaps, located in `org.eclipse.collections.impl.factory.Multimaps`.
410

411
```java { .api }
412
/**
413
 * Main factory class for creating Multimaps
414
 */
415
public final class Multimaps {
416
    public static final ImmutableMultimaps immutable;
417
    public static final MutableMultimaps mutable;
418
}
419

420
/**
421
 * Container for immutable multimap factories
422
 */  
423
public final class ImmutableMultimaps {
424
    public static final ImmutableListMultimapFactory list;
425
    public static final ImmutableSetMultimapFactory set;
426
    public static final ImmutableSortedSetMultimapFactory sortedSet;
427
    public static final ImmutableBagMultimapFactory bag;
428
    public static final ImmutableSortedBagMultimapFactory sortedBag;
429
}
430

431
/**
432
 * Container for mutable multimap factories
433
 */
434
public final class MutableMultimaps {
435
    public static final MutableListMultimapFactory list;
436
    public static final MutableSetMultimapFactory set;
437
    public static final MutableSortedSetMultimapFactory sortedSet;
438
    public static final MutableBagMultimapFactory bag;
439
    public static final MutableSortedBagMultimapFactory sortedBag;
440
}
441

442
interface MutableListMultimapFactory {
443
    <K, V> MutableListMultimap<K, V> empty();
444
    <K, V> MutableListMultimap<K, V> with(K key, V value);
445
    <K, V> MutableListMultimap<K, V> withAll(Multimap<? extends K, ? extends V> multimap);
446
}
447

448
interface ImmutableListMultimapFactory {
449
    <K, V> ImmutableListMultimap<K, V> empty();
450
    <K, V> ImmutableListMultimap<K, V> of(K key, V value);
451
    <K, V> ImmutableListMultimap<K, V> ofAll(Multimap<? extends K, ? extends V> multimap);
452
}
453
```
454

455
**Usage Examples:**
456

457
```java
458
import org.eclipse.collections.impl.factory.Multimaps;
459

460
// Create multimaps
461
MutableListMultimap<String, Integer> scores = Multimaps.mutable.list.empty();
462
scores.put("Alice", 95);
463
scores.put("Alice", 87);
464
scores.put("Bob", 92);
465

466
ImmutableSetMultimap<String, String> tags = Multimaps.immutable.set.of(
467
    "java", "programming",
468
    "java", "collections", 
469
    "eclipse", "java"
470
);
471

472
// Sorted multimaps maintain order
473
MutableSortedSetMultimap<String, Integer> sorted = Multimaps.mutable.sortedSet.empty();
474
```
475

476
## Common Factory Patterns
477

478
All factory interfaces follow consistent patterns:
479

480
### Creation Methods
481

482
- `empty()` - Create empty collection
483
- `with(elements...)` / `of(elements...)` - Create with elements
484
- `withAll(iterable)` / `ofAll(iterable)` - Create from iterable  
485
- `withInitialCapacity(size)` - Create with capacity (where applicable)
486

487
### Naming Conventions
488

489
- **Mutable factories** use `with*` methods  
490
- **Immutable factories** use `of*` methods
491
- **Fixed-size** collections cannot be resized after creation
492
- **Multi-reader** collections are optimized for concurrent read access
493

494
### Thread Safety
495

496
- **Standard collections** are not thread-safe
497
- **MultiReader collections** are optimized for multiple readers with single writer
498
- **Immutable collections** are inherently thread-safe