{"id":2114,"date":"2026-02-07T02:25:58","date_gmt":"2026-02-06T13:25:58","guid":{"rendered":"https:\/\/www.ronella.xyz\/?p=2114"},"modified":"2026-02-07T02:25:58","modified_gmt":"2026-02-06T13:25:58","slug":"java-stream-collectors","status":"publish","type":"post","link":"https:\/\/www.ronella.xyz\/?p=2114","title":{"rendered":"Java Stream Collectors"},"content":{"rendered":"

Collectors are the strategies<\/strong> that tell a Stream how to turn a flow of elements into a concrete result such as a List<\/code>, Map<\/code>, number, or custom DTO. Conceptually, a collector answers the question: \u201cGiven a stream of T<\/code>, how do I build a result R<\/code> in a single reduction step?\u201d<\/p>\n

\n

1. What is a Collector?<\/h2>\n

A Collector<\/code> is a mutable reduction<\/em> that accumulates stream elements into a container and optionally transforms that container into a final result. This is the formal definition of the Collector<\/code> interface:<\/p>\n

public interface Collector<T, A, R> {\n    Supplier<A> supplier();\n    BiConsumer<A, T> accumulator();\n    BinaryOperator<A> combiner();\n    Function<A, R> finisher();\n    Set<Characteristics> characteristics();\n}<\/code><\/pre>\n
Where:<\/p>\n
    \n
  • T<\/code> \u2013 input element type coming from the stream.  <\/li>\n
  • A<\/code> \u2013 mutable accumulator type used during collection (e.g. ArrayList<T><\/code>, Map<K,V><\/code>, statistics object).  <\/li>\n
  • R<\/code> \u2013 final result type (may be the same as A<\/code>).<\/li>\n<\/ul>\n
    The functions have clear responsibilities:<\/p>\n
      \n
    • supplier<\/code> \u2013 creates a new accumulator instance A<\/code>.  <\/li>\n
    • accumulator<\/code> \u2013 folds each element T<\/code> into the accumulator A<\/code>.  <\/li>\n
    • combiner<\/code> \u2013 merges two accumulators (essential for parallel streams).  <\/li>\n
    • finisher<\/code> \u2013 converts A<\/code> to R<\/code> (often identity, sometimes a transformation like making the result unmodifiable).  <\/li>\n
    • characteristics<\/code> \u2013 hints like CONCURRENT<\/code>, UNORDERED<\/code>, IDENTITY_FINISH<\/code> that allow stream implementations to optimize.<\/li>\n<\/ul>\n
      The Collectors<\/code> utility class provides dozens of ready\u2011made collectors so you rarely need to implement Collector<\/code> yourself. You use them via the Stream.collect(...)<\/code> terminal operation:<\/p>\n
      <R> R collect(Collector<? super T, ?, R> collector)<\/code><\/pre>\n
      You can think of this as: collector = recipe<\/strong>, and collect(recipe)<\/code> = \u201cexecute this aggregation recipe on the stream.\u201d<\/p>\n
      \n
      2. Collectors vs Collector<\/h2>\n
      Two related but distinct concepts:<\/p>\n
        \n
      • Collector<\/code> (interface)\n
          \n
        • Describes what<\/em> a mutable reduction looks like in terms of supplier<\/code>, accumulator<\/code>, combiner<\/code>, finisher<\/code>, characteristics<\/code>.<\/li>\n<\/ul>\n<\/li>\n
        • Collectors<\/code> (utility class)\n
            \n
          • Provides static factory methods that create Collector<\/code> instances: toList()<\/code>, toMap(...)<\/code>, groupingBy(...)<\/code>, mapping(...)<\/code>, teeing(...)<\/code>, etc.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
            As an engineer, you almost always use the factory methods<\/em> on Collectors<\/code>, and only occasionally need to implement a custom Collector<\/code> directly.<\/p>\n
            \n
            3. Collectors.toMap \u2013 building maps with unique keys<\/h2>\n
            Collectors.toMap<\/code> builds a Map<\/code> by turning each stream element into exactly one key\u2013value pair. It is appropriate when you conceptually want one aggregate value per key<\/strong>.<\/p>\n
            3.1 Overloads and semantics<\/h3>\n
            Key overloads:<\/p>\n
              \n
            • toMap(keyMapper, valueMapper)<\/code>\n
                \n
              • Requires keys to be unique; on duplicates, throws IllegalStateException<\/code>.  <\/li>\n<\/ul>\n<\/li>\n
              • toMap(keyMapper, valueMapper, mergeFunction)<\/code>\n
                  \n
                • Uses mergeFunction<\/code> to decide what to do with duplicate keys (e.g. pick first, pick max, sum).  <\/li>\n<\/ul>\n<\/li>\n
                • toMap(keyMapper, valueMapper, mergeFunction, mapSupplier)<\/code>\n
                    \n
                  • Also allows specifying the Map<\/code> implementation (e.g. LinkedHashMap<\/code>, TreeMap<\/code>).<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
                    The explicit mergeFunction<\/code> parameter is a deliberate design: the JDK authors wanted to prevent silent data loss, forcing you to define your collision semantics.<\/p>\n
                    3.2 Example<\/h3>\n
                    import java.util.LinkedHashMap;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.stream.Collectors;\n\npublic record City(String name, String country, int population) {}\n\nvoid main() {\n    List<City> cities = List.of(\n            new City("Paris", "France", 2_140_000),\n            new City("Nice", "France", 340_000),\n            new City("Berlin", "Germany", 3_600_000),\n            new City("Hamburg", "Germany", 1_800_000)\n    );\n\n    \/\/ Country -> largest city by population, preserve insertion order\n    Map<String, City> largestCityByCountry = cities.stream()\n            .collect(Collectors.toMap(\n                    City::country,\n                    city -> city,\n                    (c1, c2) -> c1.population() >= c2.population() ? c1 : c2,\n                    LinkedHashMap::new\n            ));\n\n    System.out.println(largestCityByCountry);\n}<\/code><\/pre>\n
                    Rationale:<\/strong>  <\/p>\n
                      \n
                    • We express domain logic (\u201ckeep the most populous city per country\u201d) with a merge function instead of an extra grouping pass.<\/li>\n
                    • LinkedHashMap<\/code> documents that iteration order matters (e.g. for responses or serialization) and keeps output deterministic.<\/li>\n<\/ul>\n
                      \n
                      4. Collectors.groupingBy \u2013 grouping and aggregating<\/h2>\n
                      Collectors.groupingBy<\/code> is the collector analogue of SQL GROUP BY<\/code>: it classifies elements into buckets and aggregates each bucket with a downstream collector. You use it when keys are not unique<\/strong> and you want collections or metrics per key.<\/p>\n
                      4.1 Overloads and default shapes<\/h3>\n
                      Representative overloads:<\/p>\n
                        \n
                      • groupingBy(classifier)<\/code>\n
                          \n
                        • Map<K, List<T>><\/code>, using toList<\/code> downstream.  <\/li>\n<\/ul>\n<\/li>\n
                        • groupingBy(classifier, downstream)<\/code>\n
                            \n
                          • Map<K, D><\/code> where D<\/code> is the downstream result (sum, count, set, custom type).  <\/li>\n<\/ul>\n<\/li>\n
                          • groupingBy(classifier, mapFactory, downstream)<\/code>\n
                              \n
                            • Adds control over the map implementation.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n
                              This design splits the problem into classification<\/strong> (classifier<\/code>) and aggregation<\/strong> (downstream), which makes collectors highly composable.<\/p>\n
                              4.2 Example<\/h3>\n
                              import java.util.List;\nimport java.util.Map;\nimport java.util.stream.Collectors;\n\npublic record Order(String city, String status, double amount) {}\n\nvoid main() {\n    List<Order> orders = List.of(\n            new Order("Auckland", "NEW", 100),\n            new Order("Auckland", "NEW", 200),\n            new Order("Auckland", "SHIPPED", 150),\n            new Order("Wellington", "NEW", 300)\n    );\n\n    \/\/ City -> list of orders\n    Map<String, List<Order>> ordersByCity = orders.stream()\n            .collect(Collectors.groupingBy(Order::city));\n\n    \/\/ City -> total amount\n    Map<String, Double> totalByCity = orders.stream()\n            .collect(Collectors.groupingBy(\n                    Order::city,\n                    Collectors.summingDouble(Order::amount)\n            ));\n\n    \/\/ Status -> number of orders\n    Map<String, Long> countByStatus = orders.stream()\n            .collect(Collectors.groupingBy(\n                    Order::status,\n                    Collectors.counting()\n            ));\n\n    System.out.println("Orders by city: " + ordersByCity);\n    System.out.println("Total by city: " + totalByCity);\n    System.out.println("Count by status: " + countByStatus);\n}<\/code><\/pre>\n
                              Rationale:<\/strong>  <\/p>\n
                                \n
                              • We avoid explicit Map<\/code> mutation and nested conditionals; aggregation logic is declarative and parallel\u2011safe by construction.  <\/li>\n
                              • Downstream collectors like summingDouble<\/code> and counting<\/code> can be reused for other groupings.<\/li>\n<\/ul>\n
                                \n
                                5. Composing collectors \u2013 mapping, filtering, flatMapping, collectingAndThen<\/h2>\n
                                Collectors are designed to be nested, especially as downstreams of groupingBy<\/code> or partitioningBy<\/code>. This composability is what turns them into a mini DSL for aggregation.<\/p>\n
                                5.1 mapping \u2013 transform before collecting<\/h3>\n
                                mapping(mapper, downstream)<\/code> applies a mapping to each element, then forwards the result to a downstream collector. Use it when you don\u2019t want to store the full original element in the group. <\/p>\n
                                Example: department \u2192 distinct employee names.<\/p>\n
                                import java.util.List;\nimport java.util.Map;\nimport java.util.Set;\nimport java.util.stream.Collectors;\n\npublic record Employee(String department, String name) {}\n\nvoid main() {\n    List<Employee> employees = List.of(\n            new Employee("Engineering", "Alice"),\n            new Employee("Engineering", "Alice"),\n            new Employee("Engineering", "Bob"),\n            new Employee("Sales", "Carol")\n    );\n\n    Map<String, Set<String>> namesByDept = employees.stream()\n            .collect(Collectors.groupingBy(\n                    Employee::department,\n                    Collectors.mapping(Employee::name, Collectors.toSet())\n            ));\n\n    System.out.println(namesByDept);\n}<\/code><\/pre>\n
                                Rationale:<\/strong>  <\/p>\n
                                  \n
                                • We avoid storing full Employee<\/code> objects when we only need names, reducing memory and making the intent explicit.<\/li>\n<\/ul>\n
                                  5.2 filtering \u2013 per-group filtering<\/h3>\n
                                  filtering(predicate, downstream)<\/code> (Java 9+) filters elements at the collector level. Unlike stream.filter<\/code>, it keeps the outer grouping key even if the filtered collection becomes empty. <\/p>\n
                                  Example: city \u2192 list of large orders (\u2265 150), but preserve all cities as keys.<\/p>\n
                                  import java.util.List;\nimport java.util.Map;\nimport java.util.stream.Collectors;\n\npublic record Order(String city, double amount) {}\n\nvoid main() {\n    List<Order> orders = List.of(\n            new Order("Auckland", 100),\n            new Order("Auckland", 200),\n            new Order("Wellington", 50),\n            new Order("Wellington", 300)\n    );\n\n    Map<String, List<Order>> largeOrdersByCity = orders.stream()\n            .collect(Collectors.groupingBy(\n                    Order::city,\n                    Collectors.filtering(\n                            o -> o.amount() >= 150,\n                            Collectors.toList()\n                    )\n            ));\n\n    System.out.println(largeOrdersByCity);\n}<\/code><\/pre>\n
                                  Rationale:<\/strong>  <\/p>\n
                                    \n
                                  • This approach preserves the full key space (e.g. all cities), which can be important for UI or reporting, while still applying a per-group filter.<\/li>\n<\/ul>\n
                                    5.3 flatMapping \u2013 flatten nested collections<\/h3>\n
                                    flatMapping(mapperToStream, downstream)<\/code> (Java 9+) flattens nested collections or streams before collecting.<\/p>\n
                                    Example: department \u2192 set of all courses taught there.<\/p>\n
                                    import java.util.List;\nimport java.util.Map;\nimport java.util.Set;\nimport java.util.stream.Collectors;\n\npublic record Staff(String department, List<String> courses) {}\n\nvoid main() {\n    List<Staff> staff = List.of(\n            new Staff("CS", List.of("Algorithms", "DS")),\n            new Staff("CS", List.of("Computer Architecture")),\n            new Staff("Math", List.of("Discrete Maths", "Probability"))\n    );\n\n    Map<String, Set<String>> coursesByDept = staff.stream()\n            .collect(Collectors.groupingBy(\n                    Staff::department,\n                    Collectors.flatMapping(\n                            s -> s.courses().stream(),\n                            Collectors.toSet()\n                    )\n            ));\n\n    System.out.println(coursesByDept);\n}<\/code><\/pre>\n
                                    Rationale:<\/strong>  <\/p>\n
                                      \n
                                    • Without flatMapping<\/code>, you\u2019d get Set<Set<String>><\/code> or need an extra pass to flatten; this keeps it one-pass and semantically clear.<\/li>\n<\/ul>\n
                                      5.4 collectingAndThen \u2013 post-process a collected result<\/h3>\n
                                      collectingAndThen(downstream, finisher)<\/code> applies a finisher function to the result of the downstream collector.<\/p>\n
                                      Example: collect to an unmodifiable list.<\/p>\n
                                      import java.util.List;\nimport java.util.stream.Collectors;\n\nvoid main() {\n    List<String> names = List.of("Alice", "Bob", "Carol");\n\n    List<String> unmodifiableNames = names.stream()\n            .collect(Collectors.collectingAndThen(\n                    Collectors.toList(),\n                    List::copyOf\n            ));\n\n    System.out.println(unmodifiableNames);\n}<\/code><\/pre>\n
                                      Rationale:<\/strong>  <\/p>\n
                                        \n
                                      • It encapsulates the \u201ccollect then wrap\u201d pattern into a single collector, improving readability and signaling immutability explicitly.<\/li>\n<\/ul>\n
                                        5.5 Nested composition example<\/h3>\n
                                        Now combine several of these ideas:<\/p>\n
                                        import java.util.List;\nimport java.util.Map;\nimport java.util.Set;\nimport java.util.stream.Collectors;\n\npublic record Employee(String department, String city, String name, int age) {}\n\nvoid main() {\n    List<Employee> employees = List.of(\n            new Employee("Engineering", "Auckland", "Alice", 30),\n            new Employee("Engineering", "Auckland", "Bob", 26),\n            new Employee("Engineering", "Wellington", "Carol", 35),\n            new Employee("Sales", "Auckland", "Dave", 40)\n    );\n\n    \/\/ Department -> City -> unmodifiable set of names for employees age >= 30\n    Map<String, Map<String, Set<String>>> result = employees.stream()\n            .collect(Collectors.groupingBy(\n                    Employee::department,\n                    Collectors.groupingBy(\n                            Employee::city,\n                            Collectors.collectingAndThen(\n                                    Collectors.filtering(\n                                            e -> e.age() >= 30,\n                                            Collectors.mapping(Employee::name, Collectors.toSet())\n                                    ),\n                                    Set::copyOf\n                            )\n                    )\n            ));\n\n    System.out.println(result);\n}<\/code><\/pre>\n
                                        Rationale:<\/strong>  <\/p>\n
                                          \n
                                        • We express a fairly involved requirement in a single declarative pipeline and single pass, instead of multiple nested maps and loops.<\/li>\n
                                        • Each collector in the composition captures a small, local concern (grouping, filtering, mapping, immutability).<\/li>\n<\/ul>\n
                                          \n
                                          6. Collectors.teeing \u2013 two collectors, one pass<\/h2>\n
                                          Collectors.teeing<\/code> (Java 12+) runs two collectors over the same stream in one pass and merges their results with a BiFunction<\/code>.<\/p>\n
                                          Signature:<\/p>\n
                                          public static <T, R1, R2, R> Collector<T, ?, R>\nteeing(Collector<? super T, ?, R1> downstream1,\n       Collector<? super T, ?, R2> downstream2,\n       java.util.function.BiFunction<? super R1, ? super R2, R> merger)<\/code><\/pre>\n
                                          Use teeing<\/code> when you want multiple aggregates (min and max, count and average, etc.) from the same data in one traversal.<\/p>\n
                                          6.1 Example: Stats in one pass<\/h3>\n
                                          import java.util.List;\nimport java.util.stream.Collectors;\n\npublic record Stats(long count, int min, int max, double average) {}\n\nvoid main() {\n    List<Integer> numbers = List.of(5, 12, 19, 21);\n\n    Stats stats = numbers.stream()\n            .collect(Collectors.teeing(\n                    Collectors.summarizingInt(Integer::intValue),\n                    Collectors.teeing(\n                            Collectors.minBy(Integer::compareTo),\n                            Collectors.maxBy(Integer::compareTo),\n                            (minOpt, maxOpt) -> new int[] {\n                                    minOpt.orElseThrow(),\n                                    maxOpt.orElseThrow()\n                            }\n                    ),\n                    (summary, minMax) -> new Stats(\n                            summary.getCount(),\n                            minMax[0],\n                            minMax[1],\n                            summary.getAverage()\n                    )\n            ));\n\n    System.out.println(stats);\n}<\/code><\/pre>\n
                                          Rationale:<\/strong>  <\/p>\n
                                            \n
                                          • We avoid traversing numbers<\/code> multiple times or managing manual mutable state (counters, min\/max variables).<\/li>\n
                                          • We can reuse existing collectors (summarizingInt<\/code>, minBy<\/code>, maxBy<\/code>) and compose them via teeing<\/code> for a single-pass, parallelizable aggregation.<\/li>\n<\/ul>\n
                                            \n
                                            7. When to choose which collector<\/h2>\n
                                            For design decisions, the following mental model works well:<\/p>\n\n\n\n\n\n\n\n\n\n
                                            Scenario<\/th>\nCollector pattern<\/th>\n<\/tr>\n<\/thead>\n
                                            One value per key, need explicit handling of collisions<\/td>\ntoMap<\/code> (with merge & mapSupplier as needed)<\/td>\n<\/tr>\n
                                            Many values per key (lists, sets, or metrics)<\/td>\ngroupingBy<\/code> + downstream (toList<\/code>, counting<\/code>, etc.)<\/td>\n<\/tr>\n
                                            Need per-group transformation\/filtering\/flattening<\/td>\ngroupingBy<\/code> with mapping<\/code>, filtering<\/code>, flatMapping<\/code><\/td>\n<\/tr>\n
                                            Need post-processing of collected result<\/td>\ncollectingAndThen(...)<\/code><\/td>\n<\/tr>\n
                                            Two independent aggregates, one traversal<\/td>\nteeing(collector1, collector2, merger)<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
                                            Viewed as a whole, collectors<\/strong> form a high-level, composable DSL for aggregation, while the Stream<\/code> interface stays relatively small and general. Treating collectors as \u201caggregation policies\u201d lets you reason about what<\/em> result you want, while delegating how<\/em> to accumulate, combine, and finish to the carefully designed mechanisms of the Collectors API.<\/p>\n","protected":false},"excerpt":{"rendered":"
                                            Collectors are the strategies that tell a Stream how to turn a flow of elements into a concrete result such as a List, Map, number, or custom DTO. Conceptually, a collector answers the question: \u201cGiven a stream of T, how do I build a result R in a single reduction step?\u201d 1. What is a […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":[],"categories":[17],"tags":[],"_links":{"self":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2114"}],"collection":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=2114"}],"version-history":[{"count":1,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2114\/revisions"}],"predecessor-version":[{"id":2115,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=\/wp\/v2\/posts\/2114\/revisions\/2115"}],"wp:attachment":[{"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=2114"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=2114"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.ronella.xyz\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=2114"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}