1ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin/* 2ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved. 3ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 5ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * This code is free software; you can redistribute it and/or modify it 6ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * under the terms of the GNU General Public License version 2 only, as 7ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * published by the Free Software Foundation. Oracle designates this 8ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * particular file as subject to the "Classpath" exception as provided 9ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * by Oracle in the LICENSE file that accompanied this code. 10ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 11ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * This code is distributed in the hope that it will be useful, but WITHOUT 12ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * version 2 for more details (a copy is included in the LICENSE file that 15ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accompanied this code). 16ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 17ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * You should have received a copy of the GNU General Public License version 18ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 2 along with this work; if not, write to the Free Software Foundation, 19ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 21ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * or visit www.oracle.com if you need additional information or have any 23ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * questions. 24ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 25ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinpackage java.util.stream; 26ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 27ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinimport java.util.Collections; 28ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinimport java.util.EnumSet; 29ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinimport java.util.Objects; 30ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinimport java.util.Set; 31ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinimport java.util.function.BiConsumer; 32ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinimport java.util.function.BinaryOperator; 33ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinimport java.util.function.Function; 34ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinimport java.util.function.Supplier; 35ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 36ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin/** 37ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * A <a href="package-summary.html#Reduction">mutable reduction operation</a> that 38ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulates input elements into a mutable result container, optionally transforming 39ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * the accumulated result into a final representation after all input elements 40ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * have been processed. Reduction operations can be performed either sequentially 41ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * or in parallel. 42ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 43ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>Examples of mutable reduction operations include: 44ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulating elements into a {@code Collection}; concatenating 45ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * strings using a {@code StringBuilder}; computing summary information about 46ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * elements such as sum, min, max, or average; computing "pivot table" summaries 47ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * such as "maximum valued transaction by seller", etc. The class {@link Collectors} 48ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * provides implementations of many common mutable reductions. 49ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 50ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>A {@code Collector} is specified by four functions that work together to 51ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulate entries into a mutable result container, and optionally perform 52ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * a final transform on the result. They are: <ul> 53ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>creation of a new result container ({@link #supplier()})</li> 54ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>incorporating a new data element into a result container ({@link #accumulator()})</li> 55ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>combining two result containers into one ({@link #combiner()})</li> 56ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>performing an optional final transform on the container ({@link #finisher()})</li> 57ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * </ul> 58ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 59ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>Collectors also have a set of characteristics, such as 60ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@link Characteristics#CONCURRENT}, that provide hints that can be used by a 61ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * reduction implementation to provide better performance. 62ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 63ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>A sequential implementation of a reduction using a collector would 64ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * create a single result container using the supplier function, and invoke the 65ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulator function once for each input element. A parallel implementation 66ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * would partition the input, create a result container for each partition, 67ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulate the contents of each partition into a subresult for that partition, 68ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * and then use the combiner function to merge the subresults into a combined 69ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * result. 70ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 71ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>To ensure that sequential and parallel executions produce equivalent 72ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * results, the collector functions must satisfy an <em>identity</em> and an 73ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <a href="package-summary.html#Associativity">associativity</a> constraints. 74ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 75ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>The identity constraint says that for any partially accumulated result, 76ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * combining it with an empty result container must produce an equivalent 77ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * result. That is, for a partially accumulated result {@code a} that is the 78ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * result of any series of accumulator and combiner invocations, {@code a} must 79ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * be equivalent to {@code combiner.apply(a, supplier.get())}. 80ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 81ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>The associativity constraint says that splitting the computation must 82ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * produce an equivalent result. That is, for any input elements {@code t1} 83ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * and {@code t2}, the results {@code r1} and {@code r2} in the computation 84ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * below must be equivalent: 85ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <pre>{@code 86ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * A a1 = supplier.get(); 87ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulator.accept(a1, t1); 88ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulator.accept(a1, t2); 89ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * R r1 = finisher.apply(a1); // result without splitting 90ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 91ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * A a2 = supplier.get(); 92ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulator.accept(a2, t1); 93ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * A a3 = supplier.get(); 94ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * accumulator.accept(a3, t2); 95ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * R r2 = finisher.apply(combiner.apply(a2, a3)); // result with splitting 96ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * } </pre> 97ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 98ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>For collectors that do not have the {@code UNORDERED} characteristic, 99ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * two accumulated results {@code a1} and {@code a2} are equivalent if 100ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@code finisher.apply(a1).equals(finisher.apply(a2))}. For unordered 101ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * collectors, equivalence is relaxed to allow for non-equality related to 102ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * differences in order. (For example, an unordered collector that accumulated 103ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * elements to a {@code List} would consider two lists equivalent if they 104ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * contained the same elements, ignoring order.) 105ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 106ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>Libraries that implement reduction based on {@code Collector}, such as 107ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@link Stream#collect(Collector)}, must adhere to the following constraints: 108ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <ul> 109ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>The first argument passed to the accumulator function, both 110ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * arguments passed to the combiner function, and the argument passed to the 111ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * finisher function must be the result of a previous invocation of the 112ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * result supplier, accumulator, or combiner functions.</li> 113ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>The implementation should not do anything with the result of any of 114ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * the result supplier, accumulator, or combiner functions other than to 115ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * pass them again to the accumulator, combiner, or finisher functions, 116ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * or return them to the caller of the reduction operation.</li> 117ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>If a result is passed to the combiner or finisher 118ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * function, and the same object is not returned from that function, it is 119ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * never used again.</li> 120ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>Once a result is passed to the combiner or finisher function, it 121ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * is never passed to the accumulator function again.</li> 122ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>For non-concurrent collectors, any result returned from the result 123ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * supplier, accumulator, or combiner functions must be serially 124ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * thread-confined. This enables collection to occur in parallel without 125ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * the {@code Collector} needing to implement any additional synchronization. 126ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * The reduction implementation must manage that the input is properly 127ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * partitioned, that partitions are processed in isolation, and combining 128ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * happens only after accumulation is complete.</li> 129ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <li>For concurrent collectors, an implementation is free to (but not 130ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * required to) implement reduction concurrently. A concurrent reduction 131ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * is one where the accumulator function is called concurrently from 132ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * multiple threads, using the same concurrently-modifiable result container, 133ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * rather than keeping the result isolated during accumulation. 134ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * A concurrent reduction should only be applied if the collector has the 135ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@link Characteristics#UNORDERED} characteristics or if the 136ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * originating data is unordered.</li> 137ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * </ul> 138ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 139ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>In addition to the predefined implementations in {@link Collectors}, the 140ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * static factory methods {@link #of(Supplier, BiConsumer, BinaryOperator, Characteristics...)} 141ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * can be used to construct collectors. For example, you could create a collector 142ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * that accumulates widgets into a {@code TreeSet} with: 143ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 144ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <pre>{@code 145ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Collector<Widget, ?, TreeSet<Widget>> intoSet = 146ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Collector.of(TreeSet::new, TreeSet::add, 147ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * (left, right) -> { left.addAll(right); return left; }); 148ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * }</pre> 149ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 150ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * (This behavior is also implemented by the predefined collector 151ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@link Collectors#toCollection(Supplier)}). 152ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 153ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @apiNote 154ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Performing a reduction operation with a {@code Collector} should produce a 155ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * result equivalent to: 156ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <pre>{@code 157ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * R container = collector.supplier().get(); 158ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * for (T t : data) 159ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * collector.accumulator().accept(container, t); 160ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * return collector.finisher().apply(container); 161ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * }</pre> 162ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 163ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>However, the library is free to partition the input, perform the reduction 164ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * on the partitions, and then use the combiner function to combine the partial 165ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * results to achieve a parallel reduction. (Depending on the specific reduction 166ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * operation, this may perform better or worse, depending on the relative cost 167ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * of the accumulator and combiner functions.) 168ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 169ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>Collectors are designed to be <em>composed</em>; many of the methods 170ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * in {@link Collectors} are functions that take a collector and produce 171ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * a new collector. For example, given the following collector that computes 172ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * the sum of the salaries of a stream of employees: 173ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 174ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <pre>{@code 175ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Collector<Employee, ?, Integer> summingSalaries 176ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * = Collectors.summingInt(Employee::getSalary)) 177ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * }</pre> 178ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 179ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * If we wanted to create a collector to tabulate the sum of salaries by 180ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * department, we could reuse the "sum of salaries" logic using 181ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@link Collectors#groupingBy(Function, Collector)}: 182ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 183ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <pre>{@code 184ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Collector<Employee, ?, Map<Department, Integer>> summingSalariesByDept 185ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * = Collectors.groupingBy(Employee::getDepartment, summingSalaries); 186ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * }</pre> 187ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 188ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @see Stream#collect(Collector) 189ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @see Collectors 190ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 191ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param <T> the type of input elements to the reduction operation 192ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param <A> the mutable accumulation type of the reduction operation (often 193ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * hidden as an implementation detail) 194ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param <R> the result type of the reduction operation 195ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @since 1.8 196ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 197ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkinpublic interface Collector<T, A, R> { 198ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 199ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * A function that creates and returns a new mutable result container. 200ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 201ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @return a function which returns a new, mutable result container 202ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 203ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Supplier<A> supplier(); 204ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 205ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 206ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * A function that folds a value into a mutable result container. 207ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 208ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @return a function which folds a value into a mutable result container 209ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 210ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin BiConsumer<A, T> accumulator(); 211ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 212ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 213ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * A function that accepts two partial results and merges them. The 214ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * combiner function may fold state from one argument into the other and 215ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * return that, or may return a new result container. 216ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 217ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @return a function which combines two partial results into a combined 218ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * result 219ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 220ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin BinaryOperator<A> combiner(); 221ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 222ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 223ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Perform the final transformation from the intermediate accumulation type 224ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@code A} to the final result type {@code R}. 225ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 226ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>If the characteristic {@code IDENTITY_TRANSFORM} is 227ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * set, this function may be presumed to be an identity transform with an 228ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * unchecked cast from {@code A} to {@code R}. 229ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 230ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @return a function which transforms the intermediate result to the final 231ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * result 232ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 233ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Function<A, R> finisher(); 234ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 235ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 236ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Returns a {@code Set} of {@code Collector.Characteristics} indicating 237ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * the characteristics of this Collector. This set should be immutable. 238ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 239ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @return an immutable set of collector characteristics 240ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 241ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Set<Characteristics> characteristics(); 242ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 243ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 244ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Returns a new {@code Collector} described by the given {@code supplier}, 245ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@code accumulator}, and {@code combiner} functions. The resulting 246ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@code Collector} has the {@code Collector.Characteristics.IDENTITY_FINISH} 247ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * characteristic. 248ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 249ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param supplier The supplier function for the new collector 250ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param accumulator The accumulator function for the new collector 251ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param combiner The combiner function for the new collector 252ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param characteristics The collector characteristics for the new 253ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * collector 254ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param <T> The type of input elements for the new collector 255ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param <R> The type of intermediate accumulation result, and final result, 256ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * for the new collector 257ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @throws NullPointerException if any argument is null 258ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @return the new {@code Collector} 259ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 260ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin public static<T, R> Collector<T, R, R> of(Supplier<R> supplier, 261ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin BiConsumer<R, T> accumulator, 262ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin BinaryOperator<R> combiner, 263ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Characteristics... characteristics) { 264ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(supplier); 265ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(accumulator); 266ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(combiner); 267ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(characteristics); 268ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Set<Characteristics> cs = (characteristics.length == 0) 269ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin ? Collectors.CH_ID 270ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin : Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.IDENTITY_FINISH, 271ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin characteristics)); 272ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin return new Collectors.CollectorImpl<>(supplier, accumulator, combiner, cs); 273ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin } 274ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 275ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 276ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Returns a new {@code Collector} described by the given {@code supplier}, 277ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * {@code accumulator}, {@code combiner}, and {@code finisher} functions. 278ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 279ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param supplier The supplier function for the new collector 280ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param accumulator The accumulator function for the new collector 281ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param combiner The combiner function for the new collector 282ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param finisher The finisher function for the new collector 283ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param characteristics The collector characteristics for the new 284ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * collector 285ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param <T> The type of input elements for the new collector 286ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param <A> The intermediate accumulation type of the new collector 287ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @param <R> The final result type of the new collector 288ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @throws NullPointerException if any argument is null 289ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * @return the new {@code Collector} 290ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 291ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin public static<T, A, R> Collector<T, A, R> of(Supplier<A> supplier, 292ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin BiConsumer<A, T> accumulator, 293ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin BinaryOperator<A> combiner, 294ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Function<A, R> finisher, 295ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Characteristics... characteristics) { 296ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(supplier); 297ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(accumulator); 298ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(combiner); 299ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(finisher); 300ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Objects.requireNonNull(characteristics); 301ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Set<Characteristics> cs = Collectors.CH_NOID; 302ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin if (characteristics.length > 0) { 303ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin cs = EnumSet.noneOf(Characteristics.class); 304ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin Collections.addAll(cs, characteristics); 305ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin cs = Collections.unmodifiableSet(cs); 306ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin } 307ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin return new Collectors.CollectorImpl<>(supplier, accumulator, combiner, finisher, cs); 308ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin } 309ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 310ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 311ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Characteristics indicating properties of a {@code Collector}, which can 312ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * be used to optimize reduction implementations. 313ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 314ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin enum Characteristics { 315ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 316ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Indicates that this collector is <em>concurrent</em>, meaning that 317ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * the result container can support the accumulator function being 318ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * called concurrently with the same result container from multiple 319ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * threads. 320ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * 321ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * <p>If a {@code CONCURRENT} collector is not also {@code UNORDERED}, 322ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * then it should only be evaluated concurrently if applied to an 323ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * unordered data source. 324ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 325ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin CONCURRENT, 326ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 327ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 328ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Indicates that the collection operation does not commit to preserving 329ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * the encounter order of input elements. (This might be true if the 330ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * result container has no intrinsic order, such as a {@link Set}.) 331ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 332ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin UNORDERED, 333ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin 334ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin /** 335ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * Indicates that the finisher function is the identity function and 336ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * can be elided. If set, it must be the case that an unchecked cast 337ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin * from A to R will succeed. 338ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin */ 339ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin IDENTITY_FINISH 340ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin } 341ff18b5f136f92154f2e05217e3953d10f459e561Igor Murashkin} 342