[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/blog-tag",{"_7":8,"_9":10},"tag",{"_31":95,"_73":34,"_35":96},"articles",{"_11":12,"_13":14,"_15":16,"_17":16,"_18":19,"_20":21,"_22":23,"_24":23,"_25":16,"_26":27},"content",[30],"pageable",{"_28":21,"_29":19},"totalElements",1,"totalPages","size",10,"number",0,"first",true,"last","numberOfElements","empty",false,"page_number","page_size",{"_31":32,"_33":34,"_35":36,"_37":38,"_11":39,"_40":-5,"_41":23,"_42":27,"_43":44,"_45":46,"_47":48,"_49":50,"_51":52,"_53":52,"_54":55,"_56":57,"_58":59,"_60":52,"_61":62,"_63":64,"_65":66,"_67":68,"_69":70,"_71":72},"id",118,"title","Immutable Collections","slug","java-collections-part-22-immutable-collections","excerpt","Evolution from Collections.unmodifiableXxx() to Java 9+ List.of()/Set.of()/Map.of() factories, structural vs deep immutability, and null handling differences.","# Java Collections Compendium Part 22: Immutable Collections - From Unmodifiable to List.of()\n\nMaster immutability in Java collections. Learn the evolution from Collections.unmodifiableXxx() wrappers to Java 9+ factory methods, understand structural vs deep immutability, and build bulletproof APIs.\n\n## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| **Topic** | List.of(), Set.of(), Map.of(), Collections.unmodifiableXxx(), copyOf() |\n| **Complexity** | Intermediate |\n| **Prerequisites** | Part 1 (Collection Framework Architecture) |\n| **Time to Master** | 2-3 hours |\n| **Interview Frequency** | High (defensive programming, API design) |\n\n## 🎯 What You'll Learn\n\nAfter completing this article, you will be able to:\n\n1. Choose between unmodifiable wrappers and immutable factory methods\n2. Understand structural vs deep immutability\n3. Design APIs that return safe, immutable collections\n4. Handle null elements correctly in different collection types\n5. Use copyOf() for defensive copies efficiently\n\n---\n\n## Production Story: The Mutant Configuration\n\n### The Incident\n\nOur configuration service was returning cached settings to multiple threads. One team \"optimized\" their code by modifying the returned list directly:\n\n```java\n// ConfigurationService.java - The problematic code\n@Service\npublic class ConfigurationService {\n private final Map> configCache = new ConcurrentHashMap<>();\n\n public List getFeatureFlags(String tenant) {\n return configCache.computeIfAbsent(tenant, this::loadFromDatabase);\n }\n}\n\n// SomeOtherService.java - The innocent-looking caller\npublic void processRequest(String tenant) {\n List flags = configService.getFeatureFlags(tenant);\n\n // \"Let me just add this temporary flag...\"\n flags.add(\"TEMP_DEBUG_MODE\"); // Modifies the cached list!\n\n // Process with flags...\n}\n```\n\n### The Problem\n\n```text\nTimeline of Chaos:\n├─ 10:00: Service starts, cache empty\n├─ 10:01: Tenant A calls getFeatureFlags → [\"FEATURE_X\", \"FEATURE_Y\"]\n├─ 10:02: Request handler adds \"TEMP_DEBUG_MODE\" to returned list\n├─ 10:03: Tenant A calls again → [\"FEATURE_X\", \"FEATURE_Y\", \"TEMP_DEBUG_MODE\"]\n├─ 10:04: Debug mode enabled for ALL tenant A requests!\n├─ 10:05: More requests add more debug flags...\n├─ 10:30: Cache contains: [\"FEATURE_X\", \"FEATURE_Y\", \"TEMP_DEBUG_MODE\" x 100]\n├─ 11:00: OutOfMemoryError from list growing infinitely!\n\nBusiness Impact:\n- Debug data exposed to production users\n- Performance degradation from huge lists\n- 2 hours of downtime\n- Data leak investigation required\n```\n\n### The Immutable Solution\n\n```java\n// ConfigurationService.java - The safe version\n@Service\npublic class ConfigurationService {\n private final Map> configCache = new ConcurrentHashMap<>();\n\n public List getFeatureFlags(String tenant) {\n return configCache.computeIfAbsent(tenant, t ->\n List.copyOf(loadFromDatabase(t)) // Immutable copy!\n );\n }\n\n // Alternative: Return unmodifiable view\n public List getFeatureFlagsView(String tenant) {\n List flags = configCache.computeIfAbsent(tenant, this::loadFromDatabase);\n return Collections.unmodifiableList(flags); // Wrapper\n }\n}\n\n// Now callers can't modify:\nList flags = configService.getFeatureFlags(tenant);\nflags.add(\"TEMP_DEBUG_MODE\"); // UnsupportedOperationException!\n```\n\n### The Difference\n\n```text\nMutable return (dangerous):\n├─ Caller receives reference to internal list\n├─ Modifications affect cached data\n├─ Other callers see the mutations\n├─ Cache becomes corrupted\n\nImmutable return (safe):\n├─ Caller receives independent immutable copy\n├─ UnsupportedOperationException on modification\n├─ Cache remains pristine\n├─ Each caller isolated from others\n```\n\n---\n\n## Mental Model: The Museum vs The Gift Shop\n\n```text\n┌─────────────────────────────────────────────────────────────────────┐\n│ IMMUTABILITY MENTAL MODEL │\n├─────────────────────────────────────────────────────────────────────┤\n│ │\n│ MUTABLE COLLECTION = Loaning Out The Original Painting │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ Museum gives you the actual Mona Lisa │ │\n│ │ You can paint a mustache on it │ │\n│ │ Return it - everyone sees the mustache! │ │\n│ │ Museum ruined forever 💥 │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n│ UNMODIFIABLE WRAPPER = Painting Behind Glass │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ Collections.unmodifiableList(original) │ │\n│ │ ┌────────────────────────────────────────────┐ │ │\n│ │ │ Glass barrier prevents touching │ │ │\n│ │ │ [═══════════════════════════════════] │ │ │\n│ │ │ MONA LISA (real) │ │ │\n│ │ └────────────────────────────────────────────┘ │ │\n│ │ But: Someone with key (original reference) │ │\n│ │ can still modify it from behind! │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n│ IMMUTABLE FACTORY = High-Quality Reproduction │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ List.of(\"a\", \"b\", \"c\") │ │\n│ │ ┌────────────────────────────────────────────┐ │ │\n│ │ │ Perfect copy, built read-only │ │ │\n│ │ │ No way to modify - no original exists! │ │ │\n│ │ │ [REPRODUCTION - DO NOT TOUCH] │ │ │\n│ │ └────────────────────────────────────────────┘ │ │\n│ │ No mustaches possible. Safe forever. │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n│ KEY INSIGHT: │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ unmodifiableList = \"You can't modify through THIS view\" │ │\n│ │ List.of() = \"Nobody can modify, PERIOD\" │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n### Interactive Visualization\n\nSee what happens when you try to modify immutable collections:\n\n```visualizer-immutable\ncontrols: true\n```\n\n---\n\n## Deep Dive: Collections.unmodifiableXxx() Wrappers\n\n### How Wrappers Work\n\n```java\n// Creating unmodifiable wrappers (Java 1.2+)\nList original = new ArrayList<>(Arrays.asList(\"a\", \"b\", \"c\"));\nList unmodifiable = Collections.unmodifiableList(original);\n\n// The wrapper delegates reads, blocks writes:\nunmodifiable.get(0); // OK → \"a\"\nunmodifiable.size(); // OK → 3\nunmodifiable.add(\"d\"); // UnsupportedOperationException!\nunmodifiable.set(0, \"x\"); // UnsupportedOperationException!\nunmodifiable.clear(); // UnsupportedOperationException!\n\n// BUT: Original reference can still modify!\noriginal.add(\"d\"); // OK!\nunmodifiable.size(); // Now returns 4!\n```\n\n### Internal Implementation\n\n```java\n// Simplified view of Collections.unmodifiableList()\npublic class Collections {\n\n public static List unmodifiableList(List list) {\n return (list instanceof RandomAccess ?\n new UnmodifiableRandomAccessList<>(list) :\n new UnmodifiableList<>(list));\n }\n\n static class UnmodifiableList extends UnmodifiableCollection\n implements List {\n\n final List list;\n\n UnmodifiableList(List list) {\n super(list);\n this.list = list;\n }\n\n public E get(int index) {\n return list.get(index); // Delegate to wrapped list\n }\n\n public E set(int index, E element) {\n throw new UnsupportedOperationException(); // Block modification\n }\n\n public void add(int index, E element) {\n throw new UnsupportedOperationException();\n }\n\n public E remove(int index) {\n throw new UnsupportedOperationException();\n }\n\n // Iterator also wrapped to prevent remove()\n public Iterator iterator() {\n return new Iterator() {\n private final Iterator i = list.iterator();\n\n public boolean hasNext() { return i.hasNext(); }\n public E next() { return i.next(); }\n public void remove() {\n throw new UnsupportedOperationException();\n }\n };\n }\n }\n}\n```\n\n### Available Wrappers\n\n```java\n// All available wrapper methods:\nCollections.unmodifiableList(list);\nCollections.unmodifiableSet(set);\nCollections.unmodifiableSortedSet(sortedSet);\nCollections.unmodifiableNavigableSet(navigableSet);\nCollections.unmodifiableMap(map);\nCollections.unmodifiableSortedMap(sortedMap);\nCollections.unmodifiableNavigableMap(navigableMap);\nCollections.unmodifiableCollection(collection);\n```\n\n### The Wrapper Problem\n\n```java\n// The fundamental issue: wrapper shares underlying collection\nList original = new ArrayList<>();\noriginal.add(\"safe\");\n\nList wrapped = Collections.unmodifiableList(original);\nSystem.out.println(wrapped); // [safe]\n\n// Later, someone with original reference:\noriginal.add(\"sneaky\");\nSystem.out.println(wrapped); // [safe, sneaky] - Changed!\n\n// Wrapper provides view immutability, NOT data immutability\n```\n\n---\n\n## Deep Dive: Java 9+ Immutable Factory Methods\n\n### List.of(), Set.of(), Map.of()\n\n```java\n// Java 9+ immutable factories - truly immutable!\nList list = List.of(\"a\", \"b\", \"c\");\nSet set = Set.of(\"x\", \"y\", \"z\");\nMap map = Map.of(\"one\", 1, \"two\", 2);\n\n// Key properties:\n// 1. Truly immutable - no way to modify\n// 2. No null elements/keys/values allowed\n// 3. Compact internal representation\n// 4. Optimized for small collections\n```\n\n### Null Handling Differences\n\n```java\n// Wrappers: Allow nulls (if underlying collection does)\nList withNull = new ArrayList<>();\nwithNull.add(null);\nList wrapped = Collections.unmodifiableList(withNull); // OK\n\n// Factory methods: NO nulls allowed\nList.of(\"a\", null, \"c\"); // NullPointerException!\nSet.of(\"a\", null); // NullPointerException!\nMap.of(\"key\", null); // NullPointerException!\nMap.of(null, \"value\"); // NullPointerException!\n\n// Why no nulls?\n// 1. Null is ambiguous (absent vs present-but-null)\n// 2. Prevents bugs (NPE at creation, not later)\n// 3. Allows internal optimizations\n// 4. Cleaner API semantics\n```\n\n### Internal Optimizations\n\n```java\n// List.of() uses specialized implementations based on size:\nList.of() // → ImmutableCollections.EMPTY_LIST (singleton)\nList.of(\"a\") // → ImmutableCollections.List12 (1-2 elements)\nList.of(\"a\", \"b\") // → ImmutableCollections.List12 (1-2 elements)\nList.of(\"a\", \"b\", \"c\") // → ImmutableCollections.ListN (array-based)\n\n// Memory efficiency compared to ArrayList:\n// ArrayList: Object[] array + int size + int modCount + header\n// List12: Just 1-2 Object fields + header (no array!)\n// ListN: Object[] array + header (no size tracking needed)\n\n// Set.of() similarly optimized:\nSet.of() // → ImmutableCollections.EMPTY_SET\nSet.of(\"a\") // → ImmutableCollections.Set12\nSet.of(\"a\", \"b\") // → ImmutableCollections.Set12\nSet.of(\"a\", \"b\", \"c\", ...) // → ImmutableCollections.SetN (hash table)\n```\n\n### Map.of() and Map.ofEntries()\n\n```java\n// Map.of() for small maps (up to 10 entries)\nMap small = Map.of(\n \"one\", 1,\n \"two\", 2,\n \"three\", 3\n);\n\n// Map.ofEntries() for larger maps or dynamic construction\nMap larger = Map.ofEntries(\n Map.entry(\"one\", 1),\n Map.entry(\"two\", 2),\n Map.entry(\"three\", 3),\n Map.entry(\"four\", 4),\n // ... can have any number of entries\n Map.entry(\"hundred\", 100)\n);\n\n// Map.entry() creates immutable entry\nMap.Entry entry = Map.entry(\"key\", 42);\nentry.setValue(0); // UnsupportedOperationException!\n```\n\n---\n\n## Deep Dive: copyOf() Methods (Java 10+)\n\n### Creating Immutable Copies\n\n```java\n// Java 10+ copyOf() - creates immutable copy from any collection\nList mutable = new ArrayList<>(Arrays.asList(\"a\", \"b\", \"c\"));\nList immutable = List.copyOf(mutable);\n\n// Properties:\n// 1. Returns immutable collection\n// 2. No null elements allowed\n// 3. May return same instance if input already immutable!\n// 4. Creates defensive copy if input is mutable\n\nSet mutableSet = new HashSet<>(Set.of(1, 2, 3));\nSet immutableSet = Set.copyOf(mutableSet);\n\nMap mutableMap = new HashMap<>(Map.of(\"a\", 1));\nMap immutableMap = Map.copyOf(mutableMap);\n```\n\n### Optimization: No Copy When Already Immutable\n\n```java\n// If input is already immutable, same instance returned:\nList original = List.of(\"a\", \"b\", \"c\");\nList copy = List.copyOf(original);\n\nSystem.out.println(original == copy); // true! No new object created\n\n// This is safe because:\n// 1. Original is immutable, can't change\n// 2. Copy is immutable, can't change\n// 3. Why waste memory on identical copy?\n\n// But mutable input creates new instance:\nList mutable = new ArrayList<>(List.of(\"a\", \"b\"));\nList copy2 = List.copyOf(mutable);\n\nSystem.out.println(mutable == copy2); // false - new instance\n```\n\n### Null Rejection\n\n```java\n// copyOf() rejects nulls even if source allows them\nList withNull = Arrays.asList(\"a\", null, \"c\");\nList.copyOf(withNull); // NullPointerException!\n\n// If you need nulls, use unmodifiable wrapper instead:\nList safe = Collections.unmodifiableList(new ArrayList<>(withNull));\n```\n\n---\n\n## Deep Dive: Structural vs Deep Immutability\n\n### The Critical Distinction\n\n```java\n// Structural immutability: Can't add/remove elements\n// Deep immutability: Elements themselves are immutable\n\n// Example: List of mutable objects\nclass MutablePerson {\n private String name;\n public void setName(String name) { this.name = name; }\n public String getName() { return name; }\n}\n\nMutablePerson alice = new MutablePerson();\nalice.setName(\"Alice\");\n\nList people = List.of(alice); // Structurally immutable\n\n// Can't modify structure:\npeople.add(new MutablePerson()); // UnsupportedOperationException!\n\n// BUT can modify elements:\npeople.get(0).setName(\"Eve\"); // Works! Alice is now Eve!\n\n// List didn't change, but the Person inside did!\n```\n\n### Achieving True Immutability\n\n```java\n// Option 1: Use immutable elements\nrecord ImmutablePerson(String name) {} // Records are immutable\n\nList trulyImmutable = List.of(\n new ImmutablePerson(\"Alice\"),\n new ImmutablePerson(\"Bob\")\n);\n\n// Option 2: Defensive copies of mutable elements\npublic List getImportantDates() {\n return dates.stream()\n .map(d -> new Date(d.getTime())) // Copy each Date\n .collect(Collectors.toUnmodifiableList()); // Immutable list of copies\n}\n\n// Option 3: Use immutable types throughout\n// Instead of Date, use java.time.LocalDate (immutable)\nList dates = List.of(\n LocalDate.of(2024, 1, 1),\n LocalDate.of(2024, 12, 31)\n);\n```\n\n### Immutability Hierarchy\n\n```text\n┌─────────────────────────────────────────────────────────────────────┐\n│ IMMUTABILITY LEVELS │\n├─────────────────────────────────────────────────────────────────────┤\n│ │\n│ Level 0: Fully Mutable │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ List list = new ArrayList<>(); │ │\n│ │ - Can add/remove elements │ │\n│ │ - Can modify elements │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n│ Level 1: Unmodifiable View (Wrapper) │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ Collections.unmodifiableList(mutableList) │ │\n│ │ - Can't add/remove through this reference │ │\n│ │ - Original can still modify │ │\n│ │ - Elements still mutable │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n│ Level 2: Structurally Immutable │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ List.of(mutableObj1, mutableObj2) │ │\n│ │ - Can't add/remove elements, period │ │\n│ │ - No backing collection to modify │ │\n│ │ - Elements still mutable! │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n│ Level 3: Deeply Immutable (Goal!) │\n│ ┌─────────────────────────────────────────────────────────────┐ │\n│ │ List.of(record1, record2) // Records, Strings, etc. │ │\n│ │ - Can't add/remove elements │ │\n│ │ - Elements are also immutable │ │\n│ │ - Truly safe to share across threads │ │\n│ └─────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Deep Dive: API Design with Immutable Collections\n\n### Returning Collections from Methods\n\n```java\npublic class UserRepository {\n private final List users = new ArrayList<>();\n\n // ❌ WRONG: Returns mutable internal list\n public List getUsers_Bad() {\n return users; // Caller can modify our internal state!\n }\n\n // ⚠️ BETTER: Unmodifiable wrapper\n public List getUsers_Wrapper() {\n return Collections.unmodifiableList(users);\n // Caller can't modify through this reference\n // But if we modify 'users', caller sees changes\n }\n\n // ✅ GOOD: Defensive copy\n public List getUsers_Copy() {\n return new ArrayList<>(users);\n // Caller gets their own copy\n // Our internal state protected\n }\n\n // ✅✅ BEST: Immutable copy (Java 10+)\n public List getUsers_Immutable() {\n return List.copyOf(users);\n // Immutable + defensive copy\n // Clearly signals \"don't try to modify\"\n }\n}\n```\n\n### Accepting Collections as Parameters\n\n```java\npublic class OrderService {\n\n // ❌ WRONG: Stores reference to caller's list\n public void setItems_Bad(List items) {\n this.items = items; // Caller can modify our state!\n }\n\n // ✅ GOOD: Defensive copy on input\n public void setItems_Good(List items) {\n this.items = List.copyOf(items); // Our own immutable copy\n }\n\n // ✅ ALSO GOOD: Copy to mutable if we need to modify later\n public void setItems_Mutable(List items) {\n this.items = new ArrayList<>(items); // Our own mutable copy\n }\n}\n```\n\n### Builder Pattern with Immutable Result\n\n```java\npublic class Order {\n private final List items;\n private final String customerId;\n\n private Order(Builder builder) {\n this.items = List.copyOf(builder.items); // Immutable\n this.customerId = builder.customerId;\n }\n\n public List getItems() {\n return items; // Already immutable, safe to return directly\n }\n\n public static class Builder {\n private final List items = new ArrayList<>();\n private String customerId;\n\n public Builder addItem(Item item) {\n items.add(item);\n return this;\n }\n\n public Builder customerId(String id) {\n this.customerId = id;\n return this;\n }\n\n public Order build() {\n return new Order(this);\n }\n }\n}\n\n// Usage:\nOrder order = new Order.Builder()\n .customerId(\"C123\")\n .addItem(new Item(\"Widget\"))\n .addItem(new Item(\"Gadget\"))\n .build();\n\norder.getItems().add(new Item(\"Hack\")); // UnsupportedOperationException!\n```\n\n---\n\n## Deep Dive: Records and Immutable Collections\n\n### Records with Collections\n\n```java\n// Records provide immutability for the record itself,\n// but collection fields need special handling\n\n// ❌ WRONG: Record with mutable collection\nrecord OrderBad(String id, List items) {}\n\nList mutableItems = new ArrayList<>();\nmutableItems.add(new Item(\"A\"));\n\nOrderBad order = new OrderBad(\"1\", mutableItems);\nmutableItems.add(new Item(\"B\")); // Modifies order's items!\n\n// ✅ CORRECT: Defensive copy in compact constructor\nrecord OrderGood(String id, List items) {\n public OrderGood { // Compact constructor\n items = List.copyOf(items); // Defensive copy\n }\n}\n\nList mutableItems2 = new ArrayList<>();\nmutableItems2.add(new Item(\"A\"));\n\nOrderGood order2 = new OrderGood(\"1\", mutableItems2);\nmutableItems2.add(new Item(\"B\")); // Doesn't affect order2!\norder2.items().add(new Item(\"C\")); // UnsupportedOperationException!\n```\n\n### Complete Immutable Record Pattern\n\n```java\n// Fully defensive record\npublic record ImmutableOrder(\n String orderId,\n String customerId,\n List lines,\n Map metadata\n) {\n // Compact constructor for validation and defensive copying\n public ImmutableOrder {\n Objects.requireNonNull(orderId, \"orderId required\");\n Objects.requireNonNull(customerId, \"customerId required\");\n\n // Defensive copies - ensure immutability\n lines = lines == null ? List.of() : List.copyOf(lines);\n metadata = metadata == null ? Map.of() : Map.copyOf(metadata);\n }\n\n // Static factory for convenience\n public static ImmutableOrder of(String orderId, String customerId) {\n return new ImmutableOrder(orderId, customerId, List.of(), Map.of());\n }\n\n // \"Wither\" methods for updates (return new instance)\n public ImmutableOrder withLine(OrderLine line) {\n List newLines = new ArrayList<>(lines);\n newLines.add(line);\n return new ImmutableOrder(orderId, customerId, newLines, metadata);\n }\n\n public ImmutableOrder withMetadata(String key, String value) {\n Map newMeta = new HashMap<>(metadata);\n newMeta.put(key, value);\n return new ImmutableOrder(orderId, customerId, lines, newMeta);\n }\n}\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: Assuming Wrapper Provides Full Immutability\n\n```java\n// ❌ WRONG: Thinking wrapper is fully immutable\nList original = new ArrayList<>();\noriginal.add(\"a\");\n\nList \"immutable\" = Collections.unmodifiableList(original);\n\n// Later in another thread:\noriginal.add(\"b\"); // Oops! Both lists now have \"b\"\n\n// ✅ CORRECT: Use copyOf() or create copy before wrapping\nList trulyImmutable = List.copyOf(original);\n// or\nList wrapped = Collections.unmodifiableList(new ArrayList<>(original));\n```\n\n### Mistake 2: Null Elements with Factory Methods\n\n```java\n// ❌ WRONG: Trying to include null\nList list = List.of(\"a\", null, \"c\"); // NullPointerException!\n\n// ✅ CORRECT: Use Optional or filter nulls\nList list = Stream.of(\"a\", null, \"c\")\n .filter(Objects::nonNull)\n .collect(Collectors.toUnmodifiableList());\n\n// Or if nulls are valid, use wrapper approach:\nList withNulls = Collections.unmodifiableList(\n new ArrayList<>(Arrays.asList(\"a\", null, \"c\"))\n);\n```\n\n### Mistake 3: Forgetting Element Mutability\n\n```java\n// ❌ WRONG: Immutable list of mutable objects\nList builders = List.of(\n new StringBuilder(\"hello\"),\n new StringBuilder(\"world\")\n);\n\nbuilders.get(0).append(\"!\"); // \"hello\" is now \"hello!\"\n// List structure unchanged, but content modified!\n\n// ✅ CORRECT: Use immutable elements\nList strings = List.of(\"hello\", \"world\"); // Strings are immutable\n// or\nrecord Message(String text) {} // Records are immutable\nList messages = List.of(new Message(\"hello\"), new Message(\"world\"));\n```\n\n### Mistake 4: Expensive Repeated Copies\n\n```java\n// ❌ WRONG: Creating copies in hot path\npublic List getItems() {\n return List.copyOf(this.items); // New copy every call!\n}\n\n// Called 1000x per second = 1000 copies per second!\n\n// ✅ CORRECT: Cache immutable version\nprivate List itemsImmutable;\n\npublic void setItems(List items) {\n this.items = new ArrayList<>(items);\n this.itemsImmutable = null; // Invalidate cache\n}\n\npublic List getItems() {\n if (itemsImmutable == null) {\n itemsImmutable = List.copyOf(items);\n }\n return itemsImmutable; // Return cached immutable\n}\n```\n\n### Mistake 5: Using List.of() for Large Collections\n\n```java\n// ❌ WRONG: List.of() with many elements\nList numbers = List.of(\n 1, 2, 3, 4, 5, 6, 7, 8, 9, 10,\n // ... hundreds more ...\n);\n// Performance: O(n) varargs array copy, then another copy\n\n// ✅ CORRECT: Build then copyOf() for large collections\nList numbers = IntStream.rangeClosed(1, 1000)\n .boxed()\n .collect(Collectors.toUnmodifiableList());\n\n// Or build ArrayList then convert:\nList mutable = new ArrayList<>(1000);\nfor (int i = 1; i <= 1000; i++) {\n mutable.add(i);\n}\nList immutable = List.copyOf(mutable);\n```\n\n---\n\n## 🐛 Debug This\n\n### Challenge 1: The Mystery Mutation\n\n```java\nSet tags = Set.of(\"java\", \"collections\");\nMap> articleTags = new HashMap<>();\narticleTags.put(\"article1\", tags);\n\n// Later...\nSet moreTags = articleTags.get(\"article1\");\nmoreTags.add(\"tutorial\"); // What happens?\n```\n\n**✅ Answer:**\n\n`UnsupportedOperationException`! The Set from `Set.of()` is immutable. You cannot add elements to it.\n\n**Fix:**\n```java\n// If you need mutable sets in the map:\narticleTags.put(\"article1\", new HashSet<>(tags));\n\n// Or use computeIfAbsent for modification:\narticleTags.computeIfAbsent(\"article1\", k -> new HashSet<>()).add(\"tutorial\");\n```\n\n### Challenge 2: The Inconsistent Equality\n\n```java\nList list1 = List.of(\"a\", \"b\", \"c\");\nList list2 = Arrays.asList(\"a\", \"b\", \"c\");\nList list3 = new ArrayList<>(List.of(\"a\", \"b\", \"c\"));\n\nSystem.out.println(list1.equals(list2)); // ?\nSystem.out.println(list1.equals(list3)); // ?\nSystem.out.println(list1.getClass() == list2.getClass()); // ?\n```\n\n**✅ Answer:**\n\n```java\nlist1.equals(list2) // true - same contents\nlist1.equals(list3) // true - same contents\nlist1.getClass() == list2.getClass() // false - different implementations\n```\n\nList equality is based on contents (same elements in same order), not implementation type. This is by design - you can compare ArrayList to LinkedList to ImmutableList.\n\n### Challenge 3: The Missing Element\n\n```java\nList source = Arrays.asList(\"a\", null, \"c\");\nList copy = List.copyOf(source); // What happens?\n```\n\n**✅ Answer:**\n\n`NullPointerException`! `List.copyOf()` does not allow null elements.\n\n**Fix:**\n```java\n// Filter nulls first:\nList copy = source.stream()\n .filter(Objects::nonNull)\n .toList(); // Java 16+ - returns immutable list\n\n// Or if nulls are valid, use different approach:\nList copy = Collections.unmodifiableList(new ArrayList<>(source));\n```\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Immutable Configuration\n\nCreate a configuration holder that is fully immutable:\n\n```java\npublic class AppConfig {\n // Store: database URL, feature flags (Set), properties (Map)\n // All must be immutable\n // No nulls allowed\n}\n```\n\n**✅ Solution:**\n\n```java\npublic record AppConfig(\n String databaseUrl,\n Set featureFlags,\n Map properties\n) {\n public AppConfig {\n Objects.requireNonNull(databaseUrl, \"databaseUrl required\");\n featureFlags = featureFlags == null ? Set.of() : Set.copyOf(featureFlags);\n properties = properties == null ? Map.of() : Map.copyOf(properties);\n }\n\n public static AppConfig load(Properties props) {\n return new AppConfig(\n props.getProperty(\"db.url\"),\n Set.of(props.getProperty(\"features\", \"\").split(\",\")),\n props.stringPropertyNames().stream()\n .filter(k -> k.startsWith(\"app.\"))\n .collect(Collectors.toUnmodifiableMap(\n k -> k,\n props::getProperty\n ))\n );\n }\n\n public boolean hasFeature(String feature) {\n return featureFlags.contains(feature);\n }\n\n public String getProperty(String key) {\n return properties.get(key);\n }\n}\n```\n\n### Exercise 2: Safe Collection Return\n\nRefactor this class to be safe:\n\n```java\npublic class ShoppingCart {\n private List items = new ArrayList<>();\n\n public void addItem(Item item) { items.add(item); }\n public List getItems() { return items; } // Unsafe!\n public void setItems(List items) { this.items = items; } // Unsafe!\n}\n```\n\n**✅ Solution:**\n\n```java\npublic class ShoppingCart {\n private final List items = new ArrayList<>();\n\n public void addItem(Item item) {\n Objects.requireNonNull(item, \"item required\");\n items.add(item);\n }\n\n public void addItems(Collection newItems) {\n Objects.requireNonNull(newItems, \"items required\");\n newItems.forEach(this::addItem); // Validates each\n }\n\n public List getItems() {\n return List.copyOf(items); // Immutable copy\n }\n\n public void setItems(List newItems) {\n items.clear();\n if (newItems != null) {\n addItems(newItems); // Defensive copy through addItems\n }\n }\n\n public void clear() {\n items.clear();\n }\n\n public int size() {\n return items.size();\n }\n}\n```\n\n### Exercise 3: Collection Factory Methods\n\nImplement a utility class that creates immutable collections from various sources:\n\n```java\npublic class ImmutableCollections {\n public static List listOf(T... elements); // Skip nulls\n public static Set setOf(Collection source); // Skip nulls\n public static Map mapOf(Map source); // Skip null keys/values\n}\n```\n\n**✅ Solution:**\n\n```java\npublic final class ImmutableCollections {\n\n private ImmutableCollections() {} // Utility class\n\n @SafeVarargs\n public static List listOf(T... elements) {\n if (elements == null || elements.length == 0) {\n return List.of();\n }\n return Arrays.stream(elements)\n .filter(Objects::nonNull)\n .collect(Collectors.toUnmodifiableList());\n }\n\n public static Set setOf(Collection source) {\n if (source == null || source.isEmpty()) {\n return Set.of();\n }\n return source.stream()\n .filter(Objects::nonNull)\n .collect(Collectors.toUnmodifiableSet());\n }\n\n public static Map mapOf(Map source) {\n if (source == null || source.isEmpty()) {\n return Map.of();\n }\n return source.entrySet().stream()\n .filter(e -> e.getKey() != null && e.getValue() != null)\n .collect(Collectors.toUnmodifiableMap(\n Map.Entry::getKey,\n Map.Entry::getValue\n ));\n }\n\n // Bonus: Create from entries with null handling\n @SafeVarargs\n public static Map mapOfEntries(Map.Entry... entries) {\n if (entries == null || entries.length == 0) {\n return Map.of();\n }\n return Arrays.stream(entries)\n .filter(Objects::nonNull)\n .filter(e -> e.getKey() != null && e.getValue() != null)\n .collect(Collectors.toUnmodifiableMap(\n Map.Entry::getKey,\n Map.Entry::getValue\n ));\n }\n}\n```\n\n---\n\n## 🎤 Senior-Level Interview Questions\n\n### Question 1: Wrapper vs Factory\n\n**Q: What's the difference between `Collections.unmodifiableList()` and `List.of()`?**\n\n**A:**\n\n| Aspect | unmodifiableList() | List.of() |\n|--------|-------------------|-----------|\n| **Type** | Wrapper/view | True immutable |\n| **Backing collection** | Yes, can be modified | No backing collection |\n| **Nulls** | Allowed (if source allows) | Not allowed |\n| **Memory** | Extra wrapper object | Optimized for size |\n| **Use case** | Temporary immutability | Permanent immutability |\n\n```java\n// unmodifiableList: View over original\nList original = new ArrayList<>();\nList view = Collections.unmodifiableList(original);\noriginal.add(\"x\"); // view also changes!\n\n// List.of: Independent immutable\nList immutable = List.of(\"a\", \"b\");\n// No way to modify - no original exists\n```\n\n### Question 2: Null Handling\n\n**Q: Why don't Java 9+ immutable collections allow null elements?**\n\n**A:**\n\nDesign decision for clarity and safety:\n\n1. **Ambiguity**: `null` can mean \"absent\" or \"present but null\"\n2. **Bug prevention**: NPE at creation time, not later in code\n3. **Optimization**: No null checks needed in internal iteration\n4. **API clarity**: Forces explicit handling of absence (Optional, empty collection)\n\n```java\n// If nulls were allowed:\nList list = List.of(\"a\", null, \"c\");\nfor (String s : list) {\n s.length(); // NPE somewhere in iteration\n}\n\n// Without nulls - fail fast:\nList.of(\"a\", null, \"c\"); // NPE immediately at creation\n// Clear stack trace pointing to the problem\n```\n\n### Question 3: copyOf() Optimization\n\n**Q: When does `List.copyOf()` return the same instance instead of creating a copy?**\n\n**A:**\n\nWhen the input is already an immutable list from the same family:\n\n```java\nList a = List.of(\"x\", \"y\");\nList b = List.copyOf(a);\nSystem.out.println(a == b); // true - same instance!\n\nList c = new ArrayList<>(List.of(\"x\", \"y\"));\nList d = List.copyOf(c);\nSystem.out.println(c == d); // false - new instance\n\n// Implementation checks:\n// if (input instanceof ImmutableCollections.AbstractImmutableList)\n// return input; // Already immutable, reuse!\n```\n\n### Question 4: Structural vs Deep Immutability\n\n**Q: Is `List.of(mutableObject)` truly immutable? Explain.**\n\n**A:**\n\nIt provides **structural immutability**, not **deep immutability**:\n\n```java\nclass MutableData {\n int value = 0;\n}\n\nMutableData data = new MutableData();\nList list = List.of(data);\n\n// Structurally immutable:\nlist.add(new MutableData()); // UnsupportedOperationException!\nlist.set(0, new MutableData()); // UnsupportedOperationException!\n\n// But NOT deeply immutable:\nlist.get(0).value = 42; // Works! Content modified\n\n// For true immutability:\n// - Use immutable element types (records, String, Integer)\n// - Or make defensive copies of mutable elements\n```\n\n### Question 5: Performance Considerations\n\n**Q: In a hot path called millions of times, which is better: caching an unmodifiable view or returning List.copyOf() each time?**\n\n**A:**\n\nCache the immutable copy, not create on each call:\n\n```java\n// ❌ Bad: Creating copy on every call\npublic List getData() {\n return List.copyOf(this.data); // New object each time!\n}\n// 1M calls = 1M objects = GC pressure\n\n// ✅ Good: Cache the immutable version\nprivate List dataImmutable;\n\npublic void setData(List data) {\n this.data = new ArrayList<>(data);\n this.dataImmutable = null; // Invalidate\n}\n\npublic List getData() {\n List result = dataImmutable;\n if (result == null) {\n result = List.copyOf(data);\n dataImmutable = result; // Cache\n }\n return result; // Same object on repeated calls\n}\n```\n\n---\n\n## 📝 Summary & Key Takeaways\n\n### Immutability Approaches\n\n| Method | Mutability | Nulls | Use Case |\n|--------|------------|-------|----------|\n| `Collections.unmodifiableXxx()` | View only | Yes | Temporary protection |\n| `List.of()` / `Set.of()` / `Map.of()` | True immutable | No | Small known collections |\n| `List.copyOf()` | True immutable | No | Defensive copies |\n| `Collectors.toUnmodifiableList()` | True immutable | No | Stream results |\n\n### Best Practices\n\n1. **Return immutable collections from APIs** - prevents caller corruption\n2. **Make defensive copies on input** - protect internal state\n3. **Use records with copyOf()** - truly immutable data classes\n4. **Cache immutable versions** - avoid repeated copy creation\n5. **Prefer List.of() for literals** - compact, optimized, clear intent\n\n### Production Checklist\n\n- [ ] API methods return immutable or defensive copies\n- [ ] Constructors make defensive copies of collection parameters\n- [ ] Records use copyOf() in compact constructors\n- [ ] Null handling is explicit (reject or filter)\n- [ ] Mutable elements are documented or avoided\n- [ ] Hot paths cache immutable versions\n- [ ] Tests verify immutability (modification attempts throw)\n\n---\n\n## 🏁 Conclusion\n\nImmutable collections are fundamental to safe, predictable Java applications. The evolution from Collections.unmodifiableXxx() wrappers to Java 9+ factory methods represents a significant improvement in both safety and expressiveness. Remember:\n\n1. **Wrappers provide view immutability** - the underlying collection can still change\n2. **Factory methods provide structural immutability** - but elements may still be mutable\n3. **True immutability requires immutable elements** - use records, strings, or primitives\n4. **Defensive copying protects both input and output** - use copyOf() liberally\n5. **Null rejection is a feature** - it catches bugs early\n\nIn the next article, we'll explore Java 21+ Sequenced Collections - a major evolution in the Collections Framework that finally gives us consistent \"first\" and \"last\" operations across collection types.\n\n---\n\n## 📅 Review Schedule\n\nTo solidify your understanding, review this material:\n- **Tomorrow**: Practice converting mutable collections to immutable\n- **In 3 days**: Implement a fully immutable domain class with collections\n- **In 1 week**: Review wrapper vs factory method trade-offs\n- **In 2 weeks**: Audit existing code for immutability opportunities\n\n---\n\n**Next in Series**: [Part 23: Java 21+ Sequenced Collections](/articles/java-collections-part-23-java21-sequenced-collections)\n\n**Series Navigation**: [Part 0: How to Use This Series](/articles/java-collections-part-0-how-to-use-this-series) | [Full Index](/articles/java-collections-compendium)\n","featuredImage","isPublished","isFeatured","subscriptionType","BASIC","publishedAt","2026-06-10T07:19:26.127127Z","createdAt","2026-06-10T07:19:26.127859Z","updatedAt","2026-06-16T21:26:56.086200Z","readingTimeMinutes",20,"estimatedReadingTime","authorId",3,"authorUsername","tomasz_main","categoryName","Java","readingTime","seriesId",5,"seriesOrder",22,"author",{"_31":55,"_99":57,"_100":101,"_102":103,"_104":-5,"_105":-5,"_106":-5,"_107":-5,"_108":-5},"category",{"_31":62,"_73":59,"_35":94,"_76":97,"_98":-5},"tags",[79,80,81,82,83],"series",{"_31":62,"_73":74,"_35":75,"_76":77,"_78":23},"name","Java Collections Compendium: From Fundamentals to Production Mastery","java-collections-compendium","description","A comprehensive 30-part series covering everything about Java Collections Framework. From foundational concepts like generics and equals/hashCode contract, through deep dives into ArrayList, LinkedList, HashMap, TreeMap, ConcurrentHashMap, to modern features like immutable collections, Java 21 sequenced collections, streams & collectors, and production patterns with JPA, Jackson & Spring. Includes real production stories, mental models, exercises, and 50+ interview questions.","isActive",{"_31":95,"_73":34,"_35":96},{"_31":93,"_73":59,"_35":94},{"_31":90,"_73":91,"_35":92},{"_31":87,"_73":88,"_35":89},{"_31":84,"_73":85,"_35":86},363,"Set.of","set.of",364,"Map.of","map.of",362,"List.of","list.of",14,"java",361,"immutable-collections","Category for Java","colorHex","username","firstName","Tomasz","lastName","Jarosz","profilePicture","bio","website","githubUrl","linkedinUrl"]