0
# Immutable Collections
1

2
High-performance immutable collection implementations providing List, Set, and Map variants with efficient copy-on-write semantics and builder patterns. These collections are designed for zero-copy operations and thread safety while maintaining familiar Java Collections Framework interfaces.
3

4
## Capabilities
5

6
### Immutable Lists
7

8
Factory methods and implementations for immutable List collections.
9

10
```java { .api }
11
/**
12
 * Factory for immutable List implementations
13
 */
14
public class Lists {
15
    /**
16
     * Create empty immutable list
17
     * @return Empty immutable list
18
     */
19
    public static <E> List<E> of();
20
    
21
    /**
22
     * Create immutable list with single element
23
     * @param e1 First element
24
     * @return Immutable list containing one element
25
     */
26
    public static <E> List<E> of(E e1);
27
    
28
    /**
29
     * Create immutable list with two elements
30
     * @param e1 First element
31
     * @param e2 Second element
32
     * @return Immutable list containing two elements
33
     */
34
    public static <E> List<E> of(E e1, E e2);
35
    
36
    /**
37
     * Create immutable list with three elements
38
     * @param e1 First element
39
     * @param e2 Second element  
40
     * @param e3 Third element
41
     * @return Immutable list containing three elements
42
     */
43
    public static <E> List<E> of(E e1, E e2, E e3);
44
    
45
    /**
46
     * Create immutable list with four elements
47
     * @param e1 First element
48
     * @param e2 Second element
49
     * @param e3 Third element
50
     * @param e4 Fourth element
51
     * @return Immutable list containing four elements
52
     */
53
    public static <E> List<E> of(E e1, E e2, E e3, E e4);
54
    
55
    /**
56
     * Create immutable list with five elements
57
     * @param e1 First element
58
     * @param e2 Second element
59
     * @param e3 Third element
60
     * @param e4 Fourth element
61
     * @param e5 Fifth element
62
     * @return Immutable list containing five elements
63
     */
64
    public static <E> List<E> of(E e1, E e2, E e3, E e4, E e5);
65
    
66
    /**
67
     * Create immutable list with six elements
68
     * @param e1 First element
69
     * @param e2 Second element
70
     * @param e3 Third element
71
     * @param e4 Fourth element
72
     * @param e5 Fifth element
73
     * @param e6 Sixth element
74
     * @return Immutable list containing six elements
75
     */
76
    public static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6);
77
    
78
    /**
79
     * Create immutable list with seven elements
80
     * @param e1 First element
81
     * @param e2 Second element
82
     * @param e3 Third element
83
     * @param e4 Fourth element
84
     * @param e5 Fifth element
85
     * @param e6 Sixth element
86
     * @param e7 Seventh element
87
     * @return Immutable list containing seven elements
88
     */
89
    public static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7);
90
    
91
    /**
92
     * Create immutable list with eight elements
93
     * @param e1 First element
94
     * @param e2 Second element
95
     * @param e3 Third element
96
     * @param e4 Fourth element
97
     * @param e5 Fifth element
98
     * @param e6 Sixth element
99
     * @param e7 Seventh element
100
     * @param e8 Eighth element
101
     * @return Immutable list containing eight elements
102
     */
103
    public static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8);
104
    
105
    /**
106
     * Create immutable list with nine elements
107
     * @param e1 First element
108
     * @param e2 Second element
109
     * @param e3 Third element
110
     * @param e4 Fourth element
111
     * @param e5 Fifth element
112
     * @param e6 Sixth element
113
     * @param e7 Seventh element
114
     * @param e8 Eighth element
115
     * @param e9 Ninth element
116
     * @return Immutable list containing nine elements
117
     */
118
    public static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9);
119
    
120
    /**
121
     * Create immutable list with ten elements
122
     * @param e1 First element
123
     * @param e2 Second element
124
     * @param e3 Third element
125
     * @param e4 Fourth element
126
     * @param e5 Fifth element
127
     * @param e6 Sixth element
128
     * @param e7 Seventh element
129
     * @param e8 Eighth element
130
     * @param e9 Ninth element
131
     * @param e10 Tenth element
132
     * @return Immutable list containing ten elements
133
     */
134
    public static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10);
135
    
136
    /**
137
     * Create immutable list from varargs
138
     * @param elements Elements to include in list
139
     * @return Immutable list containing all elements
140
     */
141
    public static <E> List<E> of(E... elements);
142
    
143
    /**
144
     * Create immutable list by copying from collection
145
     * @param collection Source collection to copy
146
     * @return Immutable list containing all elements from collection
147
     */
148
    public static <E> List<E> copyOf(Collection<? extends E> collection);
149
    
150
    /**
151
     * Create collector for immutable lists
152
     * @return Collector that produces immutable lists
153
     */
154
    public static <E> Collector<E, ?, List<E>> toList();
155
}
156
```
157

158
**Usage Examples:**
159

160
```java
161
import aQute.bnd.unmodifiable.Lists;
162
import java.util.stream.Stream;
163

164
// Create with factory methods
165
List<String> empty = Lists.of();
166
List<String> single = Lists.of("hello");
167
List<String> multiple = Lists.of("a", "b", "c", "d");
168

169
// Copy from existing collection
170
List<String> original = Arrays.asList("x", "y", "z");
171
List<String> immutable = Lists.copyOf(original);
172

173
// Use with streams
174
List<Integer> squares = Stream.of(1, 2, 3, 4, 5)
175
    .map(x -> x * x)
176
    .collect(Lists.toList());
177

178
// Immutable lists throw UnsupportedOperationException on modification
179
try {
180
    immutable.add("new"); // Throws exception
181
} catch (UnsupportedOperationException e) {
182
    System.out.println("Cannot modify immutable list");
183
}
184
```
185

186
### Immutable Sets
187

188
Factory methods and implementations for immutable Set collections.
189

190
```java { .api }
191
/**
192
 * Factory for immutable Set implementations
193
 */
194
public class Sets {
195
    /**
196
     * Create empty immutable set
197
     * @return Empty immutable set
198
     */
199
    public static <E> Set<E> of();
200
    
201
    /**
202
     * Create immutable set with single element
203
     * @param e1 First element
204
     * @return Immutable set containing one element
205
     */
206
    public static <E> Set<E> of(E e1);
207
    
208
    /**
209
     * Create immutable set with two elements
210
     * @param e1 First element
211
     * @param e2 Second element
212
     * @return Immutable set containing two elements
213
     */
214
    public static <E> Set<E> of(E e1, E e2);
215
    
216
    /**
217
     * Create immutable set with three elements
218
     * @param e1 First element
219
     * @param e2 Second element
220
     * @param e3 Third element
221
     * @return Immutable set containing three elements
222
     */
223
    public static <E> Set<E> of(E e1, E e2, E e3);
224
    
225
    /**
226
     * Create immutable set with four elements
227
     * @param e1 First element
228
     * @param e2 Second element
229
     * @param e3 Third element
230
     * @param e4 Fourth element
231
     * @return Immutable set containing four elements
232
     */
233
    public static <E> Set<E> of(E e1, E e2, E e3, E e4);
234
    
235
    /**
236
     * Create immutable set with five elements
237
     * @param e1 First element
238
     * @param e2 Second element
239
     * @param e3 Third element
240
     * @param e4 Fourth element
241
     * @param e5 Fifth element
242
     * @return Immutable set containing five elements
243
     */
244
    public static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5);
245
    
246
    /**
247
     * Create immutable set with six elements
248
     * @param e1 First element
249
     * @param e2 Second element
250
     * @param e3 Third element
251
     * @param e4 Fourth element
252
     * @param e5 Fifth element
253
     * @param e6 Sixth element
254
     * @return Immutable set containing six elements
255
     */
256
    public static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6);
257
    
258
    /**
259
     * Create immutable set with seven elements
260
     * @param e1 First element
261
     * @param e2 Second element
262
     * @param e3 Third element
263
     * @param e4 Fourth element
264
     * @param e5 Fifth element
265
     * @param e6 Sixth element
266
     * @param e7 Seventh element
267
     * @return Immutable set containing seven elements
268
     */
269
    public static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7);
270
    
271
    /**
272
     * Create immutable set with eight elements
273
     * @param e1 First element
274
     * @param e2 Second element
275
     * @param e3 Third element
276
     * @param e4 Fourth element
277
     * @param e5 Fifth element
278
     * @param e6 Sixth element
279
     * @param e7 Seventh element
280
     * @param e8 Eighth element
281
     * @return Immutable set containing eight elements
282
     */
283
    public static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8);
284
    
285
    /**
286
     * Create immutable set with nine elements
287
     * @param e1 First element
288
     * @param e2 Second element
289
     * @param e3 Third element
290
     * @param e4 Fourth element
291
     * @param e5 Fifth element
292
     * @param e6 Sixth element
293
     * @param e7 Seventh element
294
     * @param e8 Eighth element
295
     * @param e9 Ninth element
296
     * @return Immutable set containing nine elements
297
     */
298
    public static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9);
299
    
300
    /**
301
     * Create immutable set with ten elements
302
     * @param e1 First element
303
     * @param e2 Second element
304
     * @param e3 Third element
305
     * @param e4 Fourth element
306
     * @param e5 Fifth element
307
     * @param e6 Sixth element
308
     * @param e7 Seventh element
309
     * @param e8 Eighth element
310
     * @param e9 Ninth element
311
     * @param e10 Tenth element
312
     * @return Immutable set containing ten elements
313
     */
314
    public static <E> Set<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10);
315
    
316
    /**
317
     * Create immutable set from varargs
318
     * @param elements Elements to include in set
319
     * @return Immutable set containing all unique elements
320
     */
321
    public static <E> Set<E> of(E... elements);
322
    
323
    /**
324
     * Create immutable set by copying from collection
325
     * @param collection Source collection to copy
326
     * @return Immutable set containing all unique elements from collection
327
     */
328
    public static <E> Set<E> copyOf(Collection<? extends E> collection);
329
    
330
    /**
331
     * Create collector for immutable sets
332
     * @return Collector that produces immutable sets
333
     */
334
    public static <E> Collector<E, ?, Set<E>> toSet();
335
}
336
```
337

338
### Immutable Maps
339

340
Factory methods and implementations for immutable Map collections.
341

342
```java { .api }
343
/**
344
 * Factory for immutable Map implementations
345
 */
346
public class Maps {
347
    /**
348
     * Create empty immutable map
349
     * @return Empty immutable map
350
     */
351
    public static <K, V> Map<K, V> of();
352
    
353
    /**
354
     * Create immutable map with single key-value pair
355
     * @param k1 First key
356
     * @param v1 First value
357
     * @return Immutable map containing one entry
358
     */
359
    public static <K, V> Map<K, V> of(K k1, V v1);
360
    
361
    /**
362
     * Create immutable map with two key-value pairs
363
     * @param k1 First key
364
     * @param v1 First value
365
     * @param k2 Second key
366
     * @param v2 Second value
367
     * @return Immutable map containing two entries
368
     */
369
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2);
370
    
371
    /**
372
     * Create immutable map with three key-value pairs
373
     * @param k1 First key
374
     * @param v1 First value
375
     * @param k2 Second key
376
     * @param v2 Second value
377
     * @param k3 Third key
378
     * @param v3 Third value
379
     * @return Immutable map containing three entries
380
     */
381
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3);
382
    
383
    /**
384
     * Create immutable map with four key-value pairs
385
     * @param k1 First key
386
     * @param v1 First value
387
     * @param k2 Second key
388
     * @param v2 Second value
389
     * @param k3 Third key
390
     * @param v3 Third value
391
     * @param k4 Fourth key
392
     * @param v4 Fourth value
393
     * @return Immutable map containing four entries
394
     */
395
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4);
396
    
397
    /**
398
     * Create immutable map with five key-value pairs
399
     * @param k1 First key
400
     * @param v1 First value
401
     * @param k2 Second key
402
     * @param v2 Second value
403
     * @param k3 Third key
404
     * @param v3 Third value
405
     * @param k4 Fourth key
406
     * @param v4 Fourth value
407
     * @param k5 Fifth key
408
     * @param v5 Fifth value
409
     * @return Immutable map containing five entries
410
     */
411
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5);
412
    
413
    /**
414
     * Create immutable map with six key-value pairs
415
     * @param k1 First key
416
     * @param v1 First value
417
     * @param k2 Second key
418
     * @param v2 Second value
419
     * @param k3 Third key
420
     * @param v3 Third value
421
     * @param k4 Fourth key
422
     * @param v4 Fourth value
423
     * @param k5 Fifth key
424
     * @param v5 Fifth value
425
     * @param k6 Sixth key
426
     * @param v6 Sixth value
427
     * @return Immutable map containing six entries
428
     */
429
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6);
430
    
431
    /**
432
     * Create immutable map with seven key-value pairs
433
     * @param k1 First key
434
     * @param v1 First value
435
     * @param k2 Second key
436
     * @param v2 Second value
437
     * @param k3 Third key
438
     * @param v3 Third value
439
     * @param k4 Fourth key
440
     * @param v4 Fourth value
441
     * @param k5 Fifth key
442
     * @param v5 Fifth value
443
     * @param k6 Sixth key
444
     * @param v6 Sixth value
445
     * @param k7 Seventh key
446
     * @param v7 Seventh value
447
     * @return Immutable map containing seven entries
448
     */
449
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7);
450
    
451
    /**
452
     * Create immutable map with eight key-value pairs
453
     * @param k1 First key
454
     * @param v1 First value
455
     * @param k2 Second key
456
     * @param v2 Second value
457
     * @param k3 Third key
458
     * @param v3 Third value
459
     * @param k4 Fourth key
460
     * @param v4 Fourth value
461
     * @param k5 Fifth key
462
     * @param v5 Fifth value
463
     * @param k6 Sixth key
464
     * @param v6 Sixth value
465
     * @param k7 Seventh key
466
     * @param v7 Seventh value
467
     * @param k8 Eighth key
468
     * @param v8 Eighth value
469
     * @return Immutable map containing eight entries
470
     */
471
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8);
472
    
473
    /**
474
     * Create immutable map with nine key-value pairs
475
     * @param k1 First key
476
     * @param v1 First value
477
     * @param k2 Second key
478
     * @param v2 Second value
479
     * @param k3 Third key
480
     * @param v3 Third value
481
     * @param k4 Fourth key
482
     * @param v4 Fourth value
483
     * @param k5 Fifth key
484
     * @param v5 Fifth value
485
     * @param k6 Sixth key
486
     * @param v6 Sixth value
487
     * @param k7 Seventh key
488
     * @param v7 Seventh value
489
     * @param k8 Eighth key
490
     * @param v8 Eighth value
491
     * @param k9 Ninth key
492
     * @param v9 Ninth value
493
     * @return Immutable map containing nine entries
494
     */
495
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9);
496
    
497
    /**
498
     * Create immutable map with ten key-value pairs
499
     * @param k1 First key
500
     * @param v1 First value
501
     * @param k2 Second key
502
     * @param v2 Second value
503
     * @param k3 Third key
504
     * @param v3 Third value
505
     * @param k4 Fourth key
506
     * @param v4 Fourth value
507
     * @param k5 Fifth key
508
     * @param v5 Fifth value
509
     * @param k6 Sixth key
510
     * @param v6 Sixth value
511
     * @param k7 Seventh key
512
     * @param v7 Seventh value
513
     * @param k8 Eighth key
514
     * @param v8 Eighth value
515
     * @param k9 Ninth key
516
     * @param v9 Ninth value
517
     * @param k10 Tenth key
518
     * @param v10 Tenth value
519
     * @return Immutable map containing ten entries
520
     */
521
    public static <K, V> Map<K, V> of(K k1, V v1, K k2, V v2, K k3, V v3, K k4, V v4, K k5, V v5, K k6, V v6, K k7, V v7, K k8, V v8, K k9, V v9, K k10, V v10);
522
    
523
    /**
524
     * Create immutable map from Entry varargs
525
     * @param entries Entries to include in map
526
     * @return Immutable map containing all entries
527
     */
528
    public static <K, V> Map<K, V> ofEntries(Entry<? extends K, ? extends V>... entries);
529
    
530
    /**
531
     * Create immutable map by copying from existing map
532
     * @param map Source map to copy
533
     * @return Immutable map containing all entries from source map
534
     */
535
    public static <K, V> Map<K, V> copyOf(Map<? extends K, ? extends V> map);
536
    
537
    /**
538
     * Create Entry instance for use with ofEntries
539
     * @param key Entry key
540
     * @param value Entry value
541
     * @return Map Entry instance
542
     */
543
    public static <K, V> Entry<K, V> entry(K key, V value);
544
    
545
    /**
546
     * Create collector for immutable maps
547
     * @return Collector that produces immutable maps
548
     */
549
    public static <K, V> Collector<Entry<? extends K, ? extends V>, ?, Map<K, V>> toMap();
550
}
551
```
552

553
**Usage Examples:**
554

555
```java
556
import aQute.bnd.unmodifiable.Maps;
557
import aQute.bnd.unmodifiable.Sets;
558
import java.util.stream.Stream;
559

560
// Create with factory methods
561
Map<String, Integer> empty = Maps.of();
562
Map<String, Integer> single = Maps.of("one", 1);
563
Map<String, Integer> multiple = Maps.of(
564
    "one", 1,
565
    "two", 2, 
566
    "three", 3
567
);
568

569
// Create with entries
570
Map<String, Integer> fromEntries = Maps.ofEntries(
571
    Maps.entry("apple", 5),
572
    Maps.entry("banana", 3),
573
    Maps.entry("orange", 8)
574
);
575

576
// Copy from existing map
577
Map<String, Integer> original = new HashMap<>();
578
original.put("a", 1);
579
original.put("b", 2);
580
Map<String, Integer> immutable = Maps.copyOf(original);
581

582
// Use with streams
583
Map<String, Integer> lengths = Stream.of("hello", "world", "java")
584
    .collect(Collectors.toMap(
585
        s -> s,
586
        String::length,
587
        (a, b) -> a,
588
        () -> new HashMap<>()
589
    ));
590

591
// Create immutable sets
592
Set<String> colors = Sets.of("red", "green", "blue");
593
Set<Integer> numbers = Sets.copyOf(Arrays.asList(1, 2, 3, 2, 1)); // Duplicates removed
594

595
// All collections are truly immutable
596
try {
597
    immutable.put("c", 3); // Throws UnsupportedOperationException
598
} catch (UnsupportedOperationException e) {
599
    System.out.println("Cannot modify immutable map");
600
}
601
```
602

603
## Collection Properties
604

605
All immutable collections provide the following guarantees:
606

607
- **Immutability**: No modification operations are supported; all mutating methods throw `UnsupportedOperationException`
608
- **Thread Safety**: Immutable collections are inherently thread-safe and can be shared across threads without synchronization
609
- **Performance**: Optimized for read operations with minimal memory overhead
610
- **Null Handling**: Collections reject null elements and null keys/values to prevent `NullPointerException`
611
- **Serialization**: All immutable collections are serializable when their elements are serializable
612
- **Iterator Safety**: Iterators never throw `ConcurrentModificationException`
613

614
**Performance Characteristics:**
615

616
- **Memory**: Minimal overhead due to compact internal representation
617
- **Creation**: O(n) for copying operations, O(1) for empty collections
618
- **Access**: O(1) for Maps and Sets, O(1) for List indexed access
619
- **Search**: O(log n) for Sets, O(n) for Lists, O(1) for Map key lookup
620
- **Iteration**: O(n) with no allocation overhead