[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6},"actionData","errors","routes/blog-tag",{"_7":8,"_9":10},"tag",{"_31":95,"_73":96,"_35":97},"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",120,"title","Streams and Collectors","slug","java-collections-part-24-streams-collectors","excerpt","Master Stream API transformations, Collectors for complex aggregations, toMap()/groupingBy() pitfalls, and when parallel streams help versus hurt performance.","# Java Collections Compendium Part 24: Streams & Collectors - Collection Transformation\n\nMaster the Stream API for powerful collection transformations. Learn Collector internals, avoid toMap() pitfalls, write custom collectors, and understand when parallel streams help versus hurt performance.\n\n## 📋 At a Glance\n\n| Aspect | Details |\n|--------|---------|\n| **Topic** | Stream API, Collectors, groupingBy, toMap, parallel streams |\n| **Complexity** | Intermediate to Advanced |\n| **Prerequisites** | Part 1 (Collection Architecture), Part 2 (Generics) |\n| **Time to Master** | 4-5 hours |\n| **Interview Frequency** | Very High (functional programming, data transformation) |\n\n## 🎯 What You'll Learn\n\nAfter completing this article, you will be able to:\n\n1. Transform collections efficiently with Stream operations\n2. Use Collectors for complex aggregations\n3. Avoid common toMap() and groupingBy() pitfalls\n4. Write custom Collectors for specialized needs\n5. Decide when parallel streams improve performance\n\n---\n\n## Production Story: The toMap() Crash\n\n### The Incident\n\nOur data import service crashed during the nightly batch job. The culprit was a simple-looking stream operation:\n\n```java\n// DataImportService.java - The problematic code\npublic Map importCustomers(List dtos) {\n return dtos.stream()\n .map(this::convertToCustomer)\n .collect(Collectors.toMap(\n Customer::getEmail,\n Function.identity()\n ));\n // IllegalStateException: Duplicate key john@email.com\n}\n```\n\n### The Problem\n\n```text\nError: IllegalStateException: Duplicate key john@email.com\n\nRoot cause analysis:\n├─ Source data: 50,000 customer records\n├─ Expected: All unique emails\n├─ Reality: 3 duplicate emails in source data\n├─ toMap() behavior: Throws on duplicate keys by default!\n\nTimeline:\n├─ 02:00 AM: Batch job starts\n├─ 02:15 AM: Import reaches customer with duplicate email\n├─ 02:15 AM: IllegalStateException thrown\n├─ 02:15 AM: Entire import rolled back\n├─ 02:16 AM: On-call engineer woken up\n├─ 04:00 AM: Manual data cleanup completed\n├─ 04:30 AM: Import restarted\n├─ 06:00 AM: Finally complete - 4 hours late!\n```\n\n### The Stream Solution\n\n```java\n// DataImportService.java - The robust version\npublic Map importCustomers(List dtos) {\n return dtos.stream()\n .map(this::convertToCustomer)\n .collect(Collectors.toMap(\n Customer::getEmail,\n Function.identity(),\n (existing, replacement) -> {\n // Merge strategy: keep existing, log duplicate\n log.warn(\"Duplicate email found: {}\", replacement.getEmail());\n return existing;\n }\n ));\n}\n\n// Alternative: Collect duplicates for reporting\npublic record ImportResult(\n Map customers,\n List duplicates\n) {}\n\npublic ImportResult importCustomersWithReport(List dtos) {\n Map customers = new HashMap<>();\n List duplicates = new ArrayList<>();\n\n dtos.stream()\n .map(this::convertToCustomer)\n .forEach(c -> {\n Customer existing = customers.putIfAbsent(c.getEmail(), c);\n if (existing != null) {\n duplicates.add(c);\n }\n });\n\n return new ImportResult(\n Map.copyOf(customers),\n List.copyOf(duplicates)\n );\n}\n```\n\n### The Difference\n\n```text\nDefault toMap() behavior:\n├─ Duplicate key → IllegalStateException\n├─ No recovery possible\n├─ All previous work lost\n\nWith merge function:\n├─ Duplicate key → Merge function decides\n├─ Options: keep first, keep last, combine, or reject\n├─ Processing continues\n├─ Duplicates can be logged/reported\n```\n\n---\n\n## Mental Model: The Assembly Line\n\n```text\n┌─────────────────────────────────────────────────────────────────────┐\n│ STREAM AS ASSEMBLY LINE │\n├─────────────────────────────────────────────────────────────────────┤\n│ │\n│ SOURCE → INTERMEDIATE OPERATIONS → TERMINAL OPERATION → RESULT │\n│ │\n│ Collection Stateless: Reductions: │\n│ Array map(), filter() collect() │\n│ Generator flatMap() reduce() │\n│ I/O peek() forEach() │\n│ │\n│ Stateful: Short-circuit: │\n│ sorted() findFirst() │\n│ distinct() anyMatch() │\n│ limit(), skip() allMatch() │\n│ │\n│ ┌──────────────────────────────────────────────────────────────┐ │\n│ │ │ │\n│ │ [📦]→[📦]→[📦] → filter → map → collect → [📊] │ │\n│ │ ↓ ↓ ↓ │ │\n│ │ Keep? Transform Aggregate │ │ \n│ │ │ │\n│ └──────────────────────────────────────────────────────────────┘ │\n│ │\n│ KEY INSIGHTS: │\n│ ┌──────────────────────────────────────────────────────────────┐ │\n│ │ 1. Lazy: Nothing happens until terminal operation │ │\n│ │ 2. Once: Stream can only be consumed once │ │\n│ │ 3. Non-interfering: Don't modify source during stream │ │\n│ │ 4. Order: Intermediate ops form pipeline, order matters │ │\n│ └──────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────┘\n\n┌─────────────────────────────────────────────────────────────────────┐\n│ COLLECTOR AS BOX FACTORY │\n├─────────────────────────────────────────────────────────────────────┤\n│ │\n│ Collector │\n│ ├─ T = Input type (what goes in) │\n│ ├─ A = Accumulator type (the box being filled) │\n│ └─ R = Result type (what comes out) │\n│ │\n│ Four methods: │\n│ ┌──────────────────────────────────────────────────────────────┐ │\n│ │ │ │\n│ │ supplier() → Creates empty box │ │\n│ │ () -> new ArrayList<>() │ │\n│ │ │ │\n│ │ accumulator() → Adds item to box │ │\n│ │ (list, item) -> list.add(item) │ │\n│ │ │ │\n│ │ combiner() → Merges two boxes (for parallel) │ │\n│ │ (list1, list2) -> { list1.addAll(list2); │ │\n│ │ return list1; } │ │\n│ │ │ │\n│ │ finisher() → Final transformation │ │\n│ │ list -> List.copyOf(list) │ │\n│ │ │ │\n│ └──────────────────────────────────────────────────────────────┘ │\n│ │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## Deep Dive: Collection to Stream and Back\n\n### Creating Streams from Collections\n\n```java\n// From Collection\nList list = List.of(\"a\", \"b\", \"c\");\nStream stream1 = list.stream();\nStream parallelStream1 = list.parallelStream();\n\n// From array\nString[] array = {\"a\", \"b\", \"c\"};\nStream stream2 = Arrays.stream(array);\nStream stream3 = Stream.of(\"a\", \"b\", \"c\");\n\n// From Map\nMap map = Map.of(\"a\", 1, \"b\", 2);\nStream keys = map.keySet().stream();\nStream values = map.values().stream();\nStream> entries = map.entrySet().stream();\n\n// Generated streams\nStream infinite = Stream.iterate(0, n -> n + 1);\nStream randoms = Stream.generate(Math::random);\nIntStream range = IntStream.range(0, 100); // 0 to 99\nIntStream rangeClosed = IntStream.rangeClosed(1, 100); // 1 to 100\n```\n\n### Collecting Back to Collections\n\n```java\n// To List (mutable)\nList mutableList = stream.collect(Collectors.toList());\n\n// To List (immutable, Java 16+)\nList immutableList = stream.toList();\n\n// To Set\nSet set = stream.collect(Collectors.toSet());\n\n// To specific collection type\nLinkedList linkedList = stream\n .collect(Collectors.toCollection(LinkedList::new));\n\nTreeSet treeSet = stream\n .collect(Collectors.toCollection(TreeSet::new));\n\n// To array\nString[] array = stream.toArray(String[]::new);\n```\n\n---\n\n## Deep Dive: Collectors.toMap()\n\n### Basic toMap Usage\n\n```java\n// Key and value extraction\nMap nameLengths = names.stream()\n .collect(Collectors.toMap(\n name -> name, // Key mapper\n String::length // Value mapper\n ));\n\n// Using identity\nMap productsById = products.stream()\n .collect(Collectors.toMap(\n Product::getId,\n Function.identity() // Value is the product itself\n ));\n```\n\n### Handling Duplicates (The Critical Part!)\n\n```java\n// ❌ DANGEROUS: Throws on duplicate\nMap byDept = employees.stream()\n .collect(Collectors.toMap(\n Employee::getDepartment,\n Function.identity()\n )); // IllegalStateException if multiple employees in same dept!\n\n// ✅ SAFE: Merge function handles duplicates\nMap byDept = employees.stream()\n .collect(Collectors.toMap(\n Employee::getDepartment,\n Function.identity(),\n (existing, replacement) -> existing // Keep first\n ));\n\n// Common merge strategies:\n// Keep first:\n(e, r) -> e\n\n// Keep last:\n(e, r) -> r\n\n// Throw explicit error with context:\n(e, r) -> {\n throw new IllegalStateException(\n \"Duplicate department: \" + e.getDepartment());\n}\n\n// Combine values (for numeric):\n(e, r) -> e + r\n\n// Keep max/min:\n(e, r) -> e.getSalary() > r.getSalary() ? e : r\n```\n\n### Specifying Map Implementation\n\n```java\n// Default is HashMap, but you can specify:\n\n// LinkedHashMap (maintains insertion order)\nMap ordered = stream.collect(Collectors.toMap(\n keyMapper,\n valueMapper,\n (e, r) -> e,\n LinkedHashMap::new\n));\n\n// TreeMap (sorted by key)\nMap sorted = stream.collect(Collectors.toMap(\n keyMapper,\n valueMapper,\n (e, r) -> e,\n TreeMap::new\n));\n\n// ConcurrentHashMap (thread-safe)\nMap concurrent = stream.collect(Collectors.toMap(\n keyMapper,\n valueMapper,\n (e, r) -> e,\n ConcurrentHashMap::new\n));\n```\n\n---\n\n## Deep Dive: groupingBy and partitioningBy\n\n### Basic Grouping\n\n```java\n// Group employees by department\nMap> byDepartment = employees.stream()\n .collect(Collectors.groupingBy(Employee::getDepartment));\n// {\"Engineering\": [emp1, emp2], \"Sales\": [emp3, emp4]}\n\n// Group by computed key\nMap> byLength = words.stream()\n .collect(Collectors.groupingBy(String::length));\n// {3: [\"cat\", \"dog\"], 4: [\"fish\", \"bird\"]}\n```\n\n### Downstream Collectors\n\n```java\n// Count per group\nMap countByDept = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.counting()\n ));\n// {\"Engineering\": 15, \"Sales\": 8}\n\n// Sum per group\nMap salaryByDept = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.summingDouble(Employee::getSalary)\n ));\n\n// Average per group\nMap avgSalaryByDept = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.averagingDouble(Employee::getSalary)\n ));\n\n// Collect to different collection type\nMap> byDeptSet = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.toSet()\n ));\n\n// Max/Min per group\nMap> highestPaid = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.maxBy(Comparator.comparing(Employee::getSalary))\n ));\n\n// Map values in each group\nMap> namesByDept = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.mapping(Employee::getName, Collectors.toList())\n ));\n```\n\n### Nested Grouping\n\n```java\n// Two-level grouping\nMap>> byDeptAndRole = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.groupingBy(Employee::getRole)\n ));\n// {\"Engineering\": {\"Senior\": [emp1], \"Junior\": [emp2, emp3]}}\n\n// Three-level\nMap>>> threeLevels = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getCountry,\n Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.groupingBy(Employee::getRole)\n )\n ));\n```\n\n### partitioningBy (Binary Split)\n\n```java\n// Split into two groups by predicate\nMap> partitioned = employees.stream()\n .collect(Collectors.partitioningBy(\n e -> e.getSalary() > 100000\n ));\n// {true: [highPaid], false: [others]}\n\n// With downstream collector\nMap countPartitioned = employees.stream()\n .collect(Collectors.partitioningBy(\n e -> e.getSalary() > 100000,\n Collectors.counting()\n ));\n// {true: 25, false: 75}\n```\n\n---\n\n## Deep Dive: Advanced Collectors\n\n### joining()\n\n```java\n// Simple join\nString names = employees.stream()\n .map(Employee::getName)\n .collect(Collectors.joining());\n// \"AliceBobCharlie\"\n\n// With delimiter\nString csv = employees.stream()\n .map(Employee::getName)\n .collect(Collectors.joining(\", \"));\n// \"Alice, Bob, Charlie\"\n\n// With delimiter, prefix, and suffix\nString json = employees.stream()\n .map(Employee::getName)\n .map(n -> \"\\\"\" + n + \"\\\"\")\n .collect(Collectors.joining(\", \", \"[\", \"]\"));\n// \"[\\\"Alice\\\", \\\"Bob\\\", \\\"Charlie\\\"]\"\n```\n\n### collectingAndThen()\n\n```java\n// Post-process the collected result\nList immutableNames = employees.stream()\n .map(Employee::getName)\n .collect(Collectors.collectingAndThen(\n Collectors.toList(),\n Collections::unmodifiableList\n ));\n\n// Get size after collecting\nint count = employees.stream()\n .collect(Collectors.collectingAndThen(\n Collectors.toSet(),\n Set::size\n ));\n\n// Find single element or throw\nEmployee single = employees.stream()\n .filter(e -> e.getId() == 123)\n .collect(Collectors.collectingAndThen(\n Collectors.toList(),\n list -> {\n if (list.size() != 1) {\n throw new IllegalStateException(\n \"Expected exactly one, got \" + list.size());\n }\n return list.get(0);\n }\n ));\n```\n\n### reducing()\n\n```java\n// Sum with identity\nInteger total = numbers.stream()\n .collect(Collectors.reducing(0, Integer::sum));\n\n// With mapping\nInteger totalSalary = employees.stream()\n .collect(Collectors.reducing(\n 0,\n Employee::getSalary,\n Integer::sum\n ));\n\n// Equivalent to stream().reduce() but as Collector\n// Useful as downstream collector in groupingBy\nMap salaryByDept = employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.reducing(0, Employee::getSalary, Integer::sum)\n ));\n```\n\n### teeing() (Java 12+)\n\n```java\n// Collect using two collectors simultaneously\nrecord MinMax(Integer min, Integer max) {}\n\nMinMax result = numbers.stream()\n .collect(Collectors.teeing(\n Collectors.minBy(Comparator.naturalOrder()),\n Collectors.maxBy(Comparator.naturalOrder()),\n (min, max) -> new MinMax(\n min.orElse(null),\n max.orElse(null)\n )\n ));\n\n// Statistics example\nrecord Stats(long count, double average) {}\n\nStats stats = numbers.stream()\n .collect(Collectors.teeing(\n Collectors.counting(),\n Collectors.averagingDouble(n -> n),\n Stats::new\n ));\n```\n\n---\n\n## Deep Dive: Writing Custom Collectors\n\n### Collector Interface\n\n```java\npublic interface Collector {\n Supplier supplier(); // Create mutable result container\n BiConsumer accumulator(); // Add element to container\n BinaryOperator combiner(); // Merge two containers (parallel)\n Function finisher(); // Final transformation\n Set characteristics(); // Hints for optimization\n}\n\n// Characteristics:\n// CONCURRENT - accumulator can be called concurrently\n// UNORDERED - collection doesn't depend on encounter order\n// IDENTITY_FINISH - finisher is identity function, can be skipped\n```\n\n### Custom Collector: ImmutableList\n\n```java\npublic static Collector> toImmutableList() {\n return Collector.of(\n ArrayList::new, // supplier\n ArrayList::add, // accumulator\n (left, right) -> { // combiner\n left.addAll(right);\n return left;\n },\n Collections::unmodifiableList, // finisher\n Collector.Characteristics.UNORDERED // characteristics\n );\n}\n\n// Usage\nList immutable = stream.collect(toImmutableList());\n```\n\n### Custom Collector: Running Statistics\n\n```java\npublic class RunningStats {\n private int count = 0;\n private double sum = 0;\n private double min = Double.MAX_VALUE;\n private double max = Double.MIN_VALUE;\n\n public void accept(double value) {\n count++;\n sum += value;\n min = Math.min(min, value);\n max = Math.max(max, value);\n }\n\n public RunningStats combine(RunningStats other) {\n count += other.count;\n sum += other.sum;\n min = Math.min(min, other.min);\n max = Math.max(max, other.max);\n return this;\n }\n\n public double getAverage() { return count > 0 ? sum / count : 0; }\n public double getMin() { return min; }\n public double getMax() { return max; }\n public int getCount() { return count; }\n}\n\npublic static Collector toRunningStats() {\n return Collector.of(\n RunningStats::new,\n RunningStats::accept,\n RunningStats::combine,\n Function.identity(),\n Collector.Characteristics.UNORDERED,\n Collector.Characteristics.IDENTITY_FINISH\n );\n}\n\n// Usage\nRunningStats stats = prices.stream().collect(toRunningStats());\nSystem.out.println(\"Average: \" + stats.getAverage());\nSystem.out.println(\"Range: \" + stats.getMin() + \" - \" + stats.getMax());\n```\n\n### Custom Collector: Top N\n\n```java\npublic static Collector> topN(\n int n, Comparator comparator) {\n\n return Collector.of(\n () -> new PriorityQueue<>(comparator.reversed()),\n (queue, item) -> {\n queue.offer(item);\n if (queue.size() > n) {\n queue.poll(); // Remove smallest\n }\n },\n (q1, q2) -> {\n q1.addAll(q2);\n while (q1.size() > n) {\n q1.poll();\n }\n return q1;\n },\n queue -> {\n List result = new ArrayList<>(queue);\n result.sort(comparator.reversed());\n return result;\n }\n );\n}\n\n// Usage: Get top 5 highest salaries\nList top5 = employees.stream()\n .collect(topN(5, Comparator.comparing(Employee::getSalary)));\n```\n\n---\n\n## Deep Dive: Parallel Streams\n\n### When to Use Parallel Streams\n\n```java\n// Parallel stream processing\nList results = data.parallelStream()\n .filter(this::isValid)\n .map(this::transform)\n .collect(Collectors.toList());\n\n// Factors that favor parallel streams:\n// 1. Large data (10,000+ elements typically)\n// 2. Expensive per-element operations\n// 3. Splitable source (ArrayList > LinkedList)\n// 4. Stateless operations\n// 5. No ordering requirements\n\n// Factors that hurt parallel streams:\n// 1. Small data (overhead > benefit)\n// 2. Cheap operations (bounded by splitting overhead)\n// 3. LinkedList, Stream.iterate() (hard to split)\n// 4. Stateful operations (distinct, sorted, limit)\n// 5. Ordered terminal operations\n```\n\n### Parallel Stream Pitfalls\n\n```java\n// ❌ WRONG: Shared mutable state\nList results = new ArrayList<>(); // NOT thread-safe!\nnumbers.parallelStream()\n .filter(n -> n > 0)\n .forEach(results::add); // Race condition!\n\n// ✅ CORRECT: Use thread-safe collector\nList results = numbers.parallelStream()\n .filter(n -> n > 0)\n .collect(Collectors.toList()); // Collector handles synchronization\n\n// ❌ WRONG: Order-dependent with parallel\nList first5 = numbers.parallelStream()\n .filter(n -> n > 0)\n .limit(5) // Which 5? Non-deterministic in parallel!\n .collect(Collectors.toList());\n\n// ✅ CORRECT: Use sequential for order-dependent\nList first5 = numbers.stream() // sequential\n .filter(n -> n > 0)\n .limit(5)\n .collect(Collectors.toList());\n\n// ❌ WRONG: Blocking operations in parallel stream\nresults.parallelStream()\n .forEach(item -> {\n httpClient.post(item); // Blocks ForkJoinPool threads!\n });\n\n// ✅ CORRECT: Use dedicated executor for I/O\nresults.stream()\n .forEach(item -> {\n executor.submit(() -> httpClient.post(item));\n });\n```\n\n### Measuring Parallel Performance\n\n```java\n// Simple benchmark pattern\nlong sequential = measureTime(() ->\n data.stream()\n .map(this::expensiveOperation)\n .collect(Collectors.toList())\n);\n\nlong parallel = measureTime(() ->\n data.parallelStream()\n .map(this::expensiveOperation)\n .collect(Collectors.toList())\n);\n\nSystem.out.printf(\"Sequential: %d ms, Parallel: %d ms, Speedup: %.2fx%n\",\n sequential, parallel, (double) sequential / parallel);\n\n// Rule of thumb thresholds:\n// - Less than 1000 elements: sequential usually wins\n// - 1000-10000 elements: depends on operation cost\n// - More than 10000 elements: parallel often helps\n// - Always measure for your specific case!\n```\n\n---\n\n## ⚠️ Common Mistakes\n\n### Mistake 1: toMap() Without Merge Function\n\n```java\n// ❌ WRONG: Will throw on duplicate keys\nMap ordersByCustomer = orders.stream()\n .collect(Collectors.toMap(Order::getCustomerId, o -> o));\n\n// ✅ CORRECT: Always specify merge strategy\nMap ordersByCustomer = orders.stream()\n .collect(Collectors.toMap(\n Order::getCustomerId,\n o -> o,\n (existing, replacement) -> replacement // Keep latest\n ));\n\n// Or use groupingBy if duplicates expected\nMap> ordersByCustomer = orders.stream()\n .collect(Collectors.groupingBy(Order::getCustomerId));\n```\n\n### Mistake 2: Modifying Source During Stream\n\n```java\n// ❌ WRONG: ConcurrentModificationException (or worse, silent bug)\nList list = new ArrayList<>(List.of(\"a\", \"b\", \"c\"));\nlist.stream()\n .filter(s -> s.equals(\"b\"))\n .forEach(s -> list.remove(s)); // Modifying source!\n\n// ✅ CORRECT: Collect then modify, or use removeIf\nList toRemove = list.stream()\n .filter(s -> s.equals(\"b\"))\n .toList();\nlist.removeAll(toRemove);\n\n// Even better:\nlist.removeIf(s -> s.equals(\"b\"));\n```\n\n### Mistake 3: Assuming Parallel is Faster\n\n```java\n// ❌ WRONG: Parallel for small data\nList small = List.of(1, 2, 3, 4, 5);\nsmall.parallelStream()\n .map(n -> n * 2)\n .toList(); // Overhead > benefit!\n\n// ❌ WRONG: Parallel for cheap operations\nlargeList.parallelStream()\n .filter(Objects::nonNull) // Very cheap\n .toList(); // Splitting overhead dominates\n\n// ✅ CORRECT: Parallel for expensive operations on large data\nlargeList.parallelStream()\n .map(this::complexCalculation) // Expensive\n .toList(); // Now parallelism helps\n```\n\n### Mistake 4: Using peek() for Side Effects\n\n```java\n// ❌ WRONG: peek() not guaranteed to execute for all elements\nList collected = stream\n .peek(item -> database.save(item)) // May not run!\n .filter(item -> item.length() > 5)\n .limit(10)\n .toList();\n// Short-circuiting means not all items processed\n\n// ✅ CORRECT: Use forEach for side effects, or process all first\nstream.forEach(item -> database.save(item));\n\n// Or collect first, then side-effect\nList all = stream.toList();\nall.forEach(item -> database.save(item));\n```\n\n### Mistake 5: Ignoring Optional in Collectors\n\n```java\n// ❌ WRONG: Not handling empty case\nOptional highest = employees.stream()\n .collect(Collectors.maxBy(Comparator.comparing(Employee::getSalary)));\nEmployee emp = highest.get(); // NoSuchElementException if empty!\n\n// ✅ CORRECT: Handle Optional properly\nEmployee emp = employees.stream()\n .collect(Collectors.maxBy(Comparator.comparing(Employee::getSalary)))\n .orElseThrow(() -> new IllegalStateException(\"No employees\"));\n\n// Or with default\nEmployee emp = employees.stream()\n .collect(Collectors.maxBy(Comparator.comparing(Employee::getSalary)))\n .orElse(DEFAULT_EMPLOYEE);\n```\n\n---\n\n## 🐛 Debug This\n\n### Challenge 1: The Empty Map\n\n```java\nList words = List.of(\"cat\", \"dog\", \"cat\", \"bird\");\n\nMap wordCounts = words.stream()\n .collect(Collectors.toMap(\n word -> word,\n word -> 1,\n Integer::sum\n ));\n\nSystem.out.println(wordCounts);\n// Expected: {cat=2, dog=1, bird=1}\n// What do you actually get?\n```\n\n**✅ Answer:**\n\nYou get `{cat=2, dog=1, bird=1}` - it works correctly! The merge function `Integer::sum` adds up values for duplicate keys.\n\nThis is actually the RIGHT way to count occurrences with `toMap()`.\n\nHowever, a simpler approach:\n```java\nMap wordCounts = words.stream()\n .collect(Collectors.groupingBy(\n Function.identity(),\n Collectors.counting()\n ));\n```\n\n### Challenge 2: The Lost Elements\n\n```java\nList numbers = List.of(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);\n\nList result = numbers.parallelStream()\n .filter(n -> n > 5)\n .limit(3)\n .toList();\n\nSystem.out.println(result); // What's in result?\n```\n\n**✅ Answer:**\n\nResult is non-deterministic! Could be `[6, 7, 8]` or `[8, 9, 10]` or `[6, 9, 10]`, etc.\n\n`limit()` with parallel streams doesn't guarantee which elements are kept - just that 3 are kept.\n\n**Fix:**\n```java\n// Use sequential for deterministic limit\nList result = numbers.stream() // sequential!\n .filter(n -> n > 5)\n .limit(3)\n .toList();\n// Always [6, 7, 8]\n```\n\n### Challenge 3: The Mysterious Null\n\n```java\nMap> byDept = employees.stream()\n .collect(Collectors.groupingBy(e -> e.getDepartment()));\n\n// Some employees have null department\nEmployee emp = new Employee(\"John\", null); // null department\n\n// What happens?\n```\n\n**✅ Answer:**\n\n`NullPointerException`! groupingBy doesn't allow null keys.\n\n**Fix:**\n```java\n// Option 1: Filter nulls\nMap> byDept = employees.stream()\n .filter(e -> e.getDepartment() != null)\n .collect(Collectors.groupingBy(Employee::getDepartment));\n\n// Option 2: Replace null with sentinel\nMap> byDept = employees.stream()\n .collect(Collectors.groupingBy(\n e -> e.getDepartment() == null ? \"UNASSIGNED\" : e.getDepartment()\n ));\n```\n\n---\n\n## 💻 Exercises\n\n### Exercise 1: Multi-level Aggregation\n\nCreate a report showing average salary by department and seniority level:\n\n```java\npublic Map> avgSalaryByDeptAndLevel(\n List employees\n);\n// Output: {\"Engineering\": {\"Senior\": 150000.0, \"Junior\": 80000.0}, ...}\n```\n\n**✅ Solution:**\n\n```java\npublic Map> avgSalaryByDeptAndLevel(\n List employees) {\n return employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n Collectors.groupingBy(\n Employee::getSeniorityLevel,\n Collectors.averagingDouble(Employee::getSalary)\n )\n ));\n}\n\n// With sorted output:\npublic Map> avgSalaryByDeptAndLevelSorted(\n List employees) {\n return employees.stream()\n .collect(Collectors.groupingBy(\n Employee::getDepartment,\n TreeMap::new, // Sorted by department\n Collectors.groupingBy(\n Employee::getSeniorityLevel,\n TreeMap::new, // Sorted by level\n Collectors.averagingDouble(Employee::getSalary)\n )\n ));\n}\n```\n\n### Exercise 2: Custom Collector - Distinct Count Per Group\n\nWrite a collector that counts distinct values per group:\n\n```java\npublic static Collector> distinctCountingBy(\n Function keyMapper,\n Function valueMapper\n);\n\n// Usage:\nMap uniqueProductsPerCategory = products.stream()\n .collect(distinctCountingBy(\n Product::getCategory,\n Product::getName // Count distinct names per category\n ));\n```\n\n**✅ Solution:**\n\n```java\npublic static Collector> distinctCountingBy(\n Function keyMapper,\n Function valueMapper) {\n\n return Collectors.groupingBy(\n keyMapper,\n Collectors.mapping(\n valueMapper,\n Collectors.collectingAndThen(\n Collectors.toSet(),\n set -> (long) set.size()\n )\n )\n );\n}\n\n// Alternative using custom accumulator:\npublic static Collector> distinctCountingByCustom(\n Function keyMapper,\n Function valueMapper) {\n\n return Collector.of(\n () -> new HashMap>(),\n (map, item) -> {\n K key = keyMapper.apply(item);\n V value = valueMapper.apply(item);\n map.computeIfAbsent(key, k -> new HashSet<>()).add(value);\n },\n (map1, map2) -> {\n map2.forEach((k, v) ->\n map1.merge(k, v, (s1, s2) -> { s1.addAll(s2); return s1; }));\n return map1;\n },\n map -> map.entrySet().stream()\n .collect(Collectors.toMap(\n Map.Entry::getKey,\n e -> (long) e.getValue().size()\n ))\n );\n}\n```\n\n### Exercise 3: Pagination Collector\n\nCreate a collector that paginates results:\n\n```java\npublic static Collector>> paginate(int pageSize);\n\n// Usage:\nList> pages = products.stream()\n .collect(paginate(10)); // 10 items per page\n```\n\n**✅ Solution:**\n\n```java\npublic static Collector>> paginate(int pageSize) {\n if (pageSize <= 0) {\n throw new IllegalArgumentException(\"Page size must be positive\");\n }\n\n return Collector.of(\n ArrayList::new,\n (pages, item) -> {\n if (pages.isEmpty() || pages.get(pages.size() - 1).size() >= pageSize) {\n pages.add(new ArrayList<>());\n }\n pages.get(pages.size() - 1).add(item);\n },\n (left, right) -> {\n if (left.isEmpty()) return right;\n if (right.isEmpty()) return left;\n\n // Merge last page of left with first page of right if not full\n List lastLeft = left.get(left.size() - 1);\n if (lastLeft.size() < pageSize) {\n Iterator> rightIter = right.iterator();\n while (rightIter.hasNext() && lastLeft.size() < pageSize) {\n List rightPage = rightIter.next();\n int space = pageSize - lastLeft.size();\n lastLeft.addAll(rightPage.subList(0, Math.min(space, rightPage.size())));\n if (rightPage.size() > space) {\n // Remaining items form new page\n left.add(new ArrayList<>(rightPage.subList(space, rightPage.size())));\n }\n rightIter.remove();\n }\n }\n left.addAll(right);\n return left;\n },\n pages -> pages.stream()\n .map(List::copyOf)\n .collect(Collectors.toUnmodifiableList())\n );\n}\n```\n\n---\n\n## 🎤 Senior-Level Interview Questions\n\n### Question 1: toMap vs groupingBy\n\n**Q: When would you use toMap() vs groupingBy()? What's the key difference?**\n\n**A:**\n\n| Aspect | toMap() | groupingBy() |\n|--------|---------|--------------|\n| Result | `Map` | `Map>` |\n| Duplicates | Must handle explicitly | Naturally groups duplicates |\n| Use case | Unique key per element | Multiple elements per key |\n\n```java\n// toMap: When you expect one value per key\nMap productsById = products.stream()\n .collect(Collectors.toMap(Product::getId, Function.identity()));\n\n// groupingBy: When you expect multiple values per key\nMap> productsByCategory = products.stream()\n .collect(Collectors.groupingBy(Product::getCategory));\n```\n\n### Question 2: Collector Components\n\n**Q: Explain the four methods of the Collector interface and when each is called.**\n\n**A:**\n\n```java\nCollector:\n// T = input type, A = accumulator type, R = result type\n\nsupplier() // Called once to create empty accumulator\n // Example: ArrayList::new\n\naccumulator() // Called for each element to add to accumulator\n // Example: List::add\n\ncombiner() // Called in parallel to merge two accumulators\n // Only used if stream is parallel\n // Example: (list1, list2) -> { list1.addAll(list2); return list1; }\n\nfinisher() // Called once at end to transform accumulator to result\n // Example: List::copyOf for immutable result\n```\n\n### Question 3: Parallel Stream Overhead\n\n**Q: Why can parallel streams be slower than sequential for small collections?**\n\n**A:**\n\nParallel streams have overhead:\n\n1. **Splitting**: Source must be split into chunks\n2. **Thread management**: ForkJoinPool coordination\n3. **Combining**: Results from threads must be merged\n4. **Memory**: Each thread needs its own accumulator\n\n```java\n// For small collection:\n// Overhead: 1ms (split) + 0.5ms (thread) + 0.5ms (combine) = 2ms\n// Work: 0.1ms\n// Total parallel: 2.1ms\n\n// Sequential:\n// Work: 0.1ms\n// Total: 0.1ms\n\n// Parallel is 20x SLOWER!\n\n// For large collection with expensive work:\n// Overhead: 2ms\n// Work: 1000ms → 250ms (4 cores)\n// Total parallel: 252ms vs sequential 1000ms = 4x faster\n```\n\n### Question 4: Stream Reuse\n\n**Q: Can you reuse a stream? What happens if you try?**\n\n**A:**\n\nNo, streams can only be consumed once:\n\n```java\nStream stream = list.stream();\nstream.forEach(System.out::println);\nstream.forEach(System.out::println); // IllegalStateException!\n// \"stream has already been operated upon or closed\"\n\n// Why? Stream maintains pipeline state that's consumed:\n// - Terminal operation triggers execution\n// - Source iterator is exhausted\n// - Intermediate state is discarded\n\n// Solution: Create new stream each time\nlist.stream().forEach(System.out::println);\nlist.stream().forEach(System.out::println); // OK\n\n// Or use Supplier\nSupplier> streamSupplier = () -> list.stream();\nstreamSupplier.get().forEach(System.out::println); // OK\nstreamSupplier.get().forEach(System.out::println); // OK\n```\n\n### Question 5: flatMap vs map\n\n**Q: What's the difference between map() and flatMap()? Give an example.**\n\n**A:**\n\n```java\n// map: One-to-one transformation\n// T -> R\n\n// flatMap: One-to-many transformation (flattens nested structure)\n// T -> Stream\n\nList> nested = List.of(\n List.of(1, 2),\n List.of(3, 4),\n List.of(5)\n);\n\n// map produces Stream> - still nested!\nnested.stream()\n .map(list -> list) // Stream>\n .toList(); // [[1, 2], [3, 4], [5]]\n\n// flatMap produces Stream - flattened!\nnested.stream()\n .flatMap(List::stream) // Stream\n .toList(); // [1, 2, 3, 4, 5]\n\n// Common use: Processing one-to-many relationships\norders.stream()\n .flatMap(order -> order.getItems().stream()) // All items from all orders\n .filter(item -> item.getPrice() > 100)\n .toList();\n```\n\n---\n\n## 📝 Summary & Key Takeaways\n\n### Essential Collectors\n\n| Collector | Purpose | Example |\n|-----------|---------|---------|\n| `toList()` | Collect to List | `stream.collect(toList())` |\n| `toSet()` | Collect to Set | `stream.collect(toSet())` |\n| `toMap()` | Collect to Map | `stream.collect(toMap(k, v, merge))` |\n| `groupingBy()` | Group by key | `stream.collect(groupingBy(classifier))` |\n| `partitioningBy()` | Binary split | `stream.collect(partitioningBy(predicate))` |\n| `joining()` | Concatenate strings | `stream.collect(joining(\", \"))` |\n| `counting()` | Count elements | `groupingBy(x, counting())` |\n| `summingInt()` | Sum values | `groupingBy(x, summingInt(fn))` |\n| `mapping()` | Transform in group | `groupingBy(x, mapping(fn, toList()))` |\n\n### Key Rules\n\n1. **Always use merge function with toMap()** - duplicate keys are common\n2. **groupingBy doesn't allow null keys** - filter or transform nulls\n3. **Parallel streams need stateless operations** - avoid shared mutable state\n4. **Measure before parallelizing** - overhead can exceed benefit\n5. **Streams are single-use** - create new stream for each operation\n\n---\n\n## 🏁 Conclusion\n\nStreams and Collectors provide powerful tools for collection transformation, but their complexity can lead to subtle bugs. The key insights are:\n\n1. **toMap() is dangerous without merge function** - always specify one\n2. **groupingBy with downstream collectors** enables complex aggregations\n3. **Parallel streams have overhead** - measure before assuming they're faster\n4. **Custom collectors** solve specialized needs elegantly\n5. **Stream pipeline order matters** - filter early, transform late\n\nIn the next article, we'll explore Views, Wrappers, and Defensive Patterns - techniques for protecting your collections from unintended modification.\n\n---\n\n## 📅 Review Schedule\n\nTo solidify your understanding, review this material:\n- **Tomorrow**: Practice toMap() with merge functions\n- **In 3 days**: Write a groupingBy with nested downstream collectors\n- **In 1 week**: Implement a custom Collector\n- **In 2 weeks**: Benchmark sequential vs parallel for your use case\n\n---\n\n**Next in Series**: [Part 25: Views, Wrappers & Defensive Patterns](/articles/java-collections-part-25-views-wrappers-defensive)\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.155902Z","createdAt","2026-06-10T07:19:26.156743Z","updatedAt","2026-06-16T21:26:56.086200Z","readingTimeMinutes",18,"estimatedReadingTime","authorId",3,"authorUsername","tomasz_main","categoryName","Java","readingTime","seriesId",5,"seriesOrder",24,"author",{"_31":55,"_100":57,"_101":102,"_103":104,"_105":-5,"_106":-5,"_107":-5,"_108":-5,"_109":-5},"category",{"_31":62,"_73":59,"_35":91,"_76":98,"_99":-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":96,"_35":97},{"_31":92,"_73":93,"_35":94},{"_31":90,"_73":59,"_35":91},{"_31":87,"_73":88,"_35":89},{"_31":84,"_73":85,"_35":86},58,"Streams","streams",369,"Pipeline","pipeline",14,"java",56,"Functional Programming","functional-programming",368,"Collectors","collectors","Category for Java","colorHex","username","firstName","Tomasz","lastName","Jarosz","profilePicture","bio","website","githubUrl","linkedinUrl"]