src/share/classes/java/util/stream/Collector.java
Print this page
rev 7597 : 8015318: Extend Collector with 'finish' operation
Reviewed-by:
Contributed-by: brian.goetz@oracle.com
@@ -23,96 +23,100 @@
* questions.
*/
package java.util.stream;
import java.util.Collections;
+import java.util.EnumSet;
import java.util.Set;
-import java.util.function.BiFunction;
+import java.util.function.BiConsumer;
import java.util.function.BinaryOperator;
+import java.util.function.Function;
import java.util.function.Supplier;
/**
* A <a href="package-summary.html#Reduction">reduction operation</a> that
- * supports folding input elements into a cumulative result. The result may be
- * a value or may be a mutable result container. Examples of operations
- * accumulating results into a mutable result container include: accumulating
- * input elements into a {@code Collection}; concatenating strings into a
- * {@code StringBuilder}; computing summary information about elements such as
- * sum, min, max, or average; computing "pivot table" summaries such as "maximum
- * valued transaction by seller", etc. Reduction operations can be performed
- * either sequentially or in parallel.
+ * folds input elements into a mutable result container, optionally transforming
+ * the accumulated result into a final representation after all input elements
+ * have been processed.
+ *
+ * <p>Examples of mutable reduction operations include:
+ * accumulating elements into a {@code Collection}; concatenating
+ * strings using a {@code StringBuilder}; computing summary information about
+ * elements such as sum, min, max, or average; computing "pivot table" summaries
+ * such as "maximum valued transaction by seller", etc. Reduction operations
+ * can be performed either sequentially or in parallel.
*
* <p>The following are examples of using the predefined {@code Collector}
* implementations in {@link Collectors} with the {@code Stream} API to perform
* mutable reduction tasks:
* <pre>{@code
- * // Accumulate elements into a List
- * List<String> list = stream.collect(Collectors.toList());
+ * // Accumulate names into a List
+ * List<String> list = people.stream().map(Person::getName).collect(Collectors.toList());
*
- * // Accumulate elements into a TreeSet
- * Set<String> list = stream.collect(Collectors.toCollection(TreeSet::new));
+ * // Accumulate names into a TreeSet
+ * Set<String> list = people.stream().map(Person::getName).collect(Collectors.toCollection(TreeSet::new));
*
* // Convert elements to strings and concatenate them, separated by commas
- * String joined = stream.map(Object::toString)
- * .collect(Collectors.toStringJoiner(", "))
- * .toString();
+ * String joined = things.stream()
+ * .map(Object::toString)
+ * .collect(Collectors.joining(", "));
*
* // Find highest-paid employee
* Employee highestPaid = employees.stream()
- * .collect(Collectors.maxBy(Comparators.comparing(Employee::getSalary)));
+ * .collect(Collectors.maxBy(Comparators.comparing(Employee::getSalary)))
+ * .get();
*
* // Group employees by department
* Map<Department, List<Employee>> byDept
* = employees.stream()
* .collect(Collectors.groupingBy(Employee::getDepartment));
*
* // Find highest-paid employee by department
- * Map<Department, Employee> highestPaidByDept
+ * Map<Department, Optional<Employee>> highestPaidByDept
* = employees.stream()
* .collect(Collectors.groupingBy(Employee::getDepartment,
* Collectors.maxBy(Comparators.comparing(Employee::getSalary))));
*
* // Partition students into passing and failing
* Map<Boolean, List<Student>> passingFailing =
* students.stream()
- * .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD);
+ * .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD));
*
* }</pre>
*
- * <p>A {@code Collector} is specified by three functions that work together to
- * manage a result or result container. They are: creation of an initial
- * result, incorporating a new data element into a result, and combining two
- * results into one. The last function -- combining two results into one -- is
- * used during parallel operations, where subsets of the input are accumulated
- * in parallel, and then the subresults merged into a combined result. The
- * result may be a mutable container or a value. If the result is mutable, the
- * accumulation and combination functions may either mutate their left argument
- * and return that (such as adding elements to a collection), or return a new
- * result, in which case it should not perform any mutation.
- *
- * <p>Collectors also have a set of characteristics, including
- * {@link Characteristics#CONCURRENT} and
- * {@link Characteristics#STRICTLY_MUTATIVE}. These characteristics provide
+ * <p>A {@code Collector} is specified by four functions that work together to
+ * accumulate entries into a mutable result container, and optionally perform
+ * a final transform on the result. They are: creation of a new result container,
+ * incorporating a new data element into a result container, combining two
+ * result containers into one, and performing a final transform on the container.
+ * The combiner function is used during parallel operations, where
+ * subsets of the input are accumulated into separate result
+ * containers, and then the subresults merged into a combined result. The
+ * combiner function may merge one set of subresults into the other and return
+ * that, or it may return a new object to describe the combined results.
+ *
+ * <p>Collectors also have a set of characteristics, such as
+ * {@link Characteristics#CONCURRENT}. These characteristics provide
* hints that can be used by a reduction implementation to provide better
* performance.
*
* <p>Libraries that implement reduction based on {@code Collector}, such as
* {@link Stream#collect(Collector)}, must adhere to the following constraints:
* <ul>
- * <li>The first argument passed to the accumulator function, and both
- * arguments passed to the combiner function, must be the result of a
- * previous invocation of {@link #resultSupplier()}, {@link #accumulator()},
- * or {@link #combiner()}.</li>
+ * <li>The first argument passed to the accumulator function, both
+ * arguments passed to the combiner function, and the argument passed to the
+ * finisher function must be the result of a previous invocation of the
+ * result supplier, accumulator, or combiner functions.</li>
* <li>The implementation should not do anything with the result of any of
* the result supplier, accumulator, or combiner functions other than to
- * pass them again to the accumulator or combiner functions, or return them
- * to the caller of the reduction operation.</li>
- * <li>If a result is passed to the accumulator or combiner function, and
- * the same object is not returned from that function, it is never used
- * again.</li>
- * <li>Once a result is passed to the combiner function, it is never passed
- * to the accumulator function again.</li>
+ * pass them again to the accumulator, combiner, or finisher functions,
+ * or return them to the caller of the reduction operation.</li>
+ * <li>If a result is passed to the combiner or finisher
+ * function, and the same object is not returned from that function, it is
+ * never used again.</li>
+ * <li>Once a result is passed to the combiner or finisher function, it
+ * is never passed to the accumulator function again.</li>
* <li>For non-concurrent collectors, any result returned from the result
* supplier, accumulator, or combiner functions must be serially
* thread-confined. This enables collection to occur in parallel without
* the {@code Collector} needing to implement any additional synchronization.
* The reduction implementation must manage that the input is properly
@@ -130,15 +134,14 @@
*
* @apiNote
* Performing a reduction operation with a {@code Collector} should produce a
* result equivalent to:
* <pre>{@code
- * BiFunction<R,T,R> accumulator = collector.accumulator();
- * R result = collector.resultSupplier().get();
+ * R container = collector.supplier().get();
* for (T t : data)
- * result = accumulator.apply(result, t);
- * return result;
+ * collector.accumulator().accept(container, t);
+ * return collector.finisher().apply(container);
* }</pre>
*
* <p>However, the library is free to partition the input, perform the reduction
* on the partitions, and then use the combiner function to combine the partial
* results to achieve a parallel reduction. Depending on the specific reduction
@@ -147,85 +150,138 @@
*
* <p>An example of an operation that can be easily modeled by {@code Collector}
* is accumulating elements into a {@code TreeSet}. In this case, the {@code
* resultSupplier()} function is {@code () -> new Treeset<T>()}, the
* {@code accumulator} function is
- * {@code (set, element) -> { set.add(element); return set; }}, and the combiner
+ * {@code (set, element) -> set.add(element) }, and the combiner
* function is {@code (left, right) -> { left.addAll(right); return left; }}.
* (This behavior is implemented by
* {@code Collectors.toCollection(TreeSet::new)}).
*
* TODO Associativity and commutativity
*
* @see Stream#collect(Collector)
* @see Collectors
*
- * @param <T> the type of input element to the collect operation
- * @param <R> the result type of the collect operation
+ * @param <T> the type of input elements to the reduction operation
+ * @param <A> the mutable accumulation type of the reduction operation (often
+ * hidden as an implementation detail)
+ * @param <R> the result type of the reduction operation
* @since 1.8
*/
-public interface Collector<T, R> {
+public interface Collector<T, A, R> {
/**
- * A function that creates and returns a new result that represents
- * "no values". If the accumulator or combiner functions may mutate their
- * arguments, this must be a new, empty result container.
+ * A function that creates and returns a new mutable result container.
*
- * @return a function which, when invoked, returns a result representing
- * "no values"
+ * @return a function which returns a new, mutable result container
*/
- Supplier<R> resultSupplier();
+ Supplier<A> supplier();
/**
- * A function that folds a new value into a cumulative result. The result
- * may be a mutable result container or a value. The accumulator function
- * may modify a mutable container and return it, or create a new result and
- * return that, but if it returns a new result object, it must not modify
- * any of its arguments.
- *
- * <p>If the collector has the {@link Characteristics#STRICTLY_MUTATIVE}
- * characteristic, then the accumulator function <em>must</em> always return
- * its first argument, after possibly mutating its state.
+ * A function that folds a new value into a mutable result container.
*
- * @return a function which folds a new value into a cumulative result
+ * @return a function which folds a new value into a mutable result container
*/
- BiFunction<R, T, R> accumulator();
+ BiConsumer<A, T> accumulator();
/**
* A function that accepts two partial results and merges them. The
* combiner function may fold state from one argument into the other and
- * return that, or may return a new result object, but if it returns
- * a new result object, it must not modify the state of either of its
- * arguments.
- *
- * <p>If the collector has the {@link Characteristics#STRICTLY_MUTATIVE}
- * characteristic, then the combiner function <em>must</em> always return
- * its first argument, after possibly mutating its state.
+ * return that, or may return a new result object.
*
* @return a function which combines two partial results into a cumulative
* result
*/
- BinaryOperator<R> combiner();
+ BinaryOperator<A> combiner();
+
+ /**
+ * Perform the final transformation from the intermediate accumulation type
+ * {@code A} to the final result representation {@code R}.
+ *
+ * <p>If the characteristic {@code IDENTITY_TRANSFORM} is
+ * set, this function may be presumed to be an identity transform with an
+ * unchecked cast from {@code A} to {@code R}.
+ *
+ * @return a function which transforms the intermediate result to the final
+ * result
+ */
+ Function<A, R> finisher();
/**
* Returns a {@code Set} of {@code Collector.Characteristics} indicating
* the characteristics of this Collector. This set should be immutable.
*
* @return an immutable set of collector characteristics
*/
Set<Characteristics> characteristics();
/**
+ * Returns a new {@code Collector} described by the given {@code supplier},
+ * {@code accumulator}, and {@code combiner} functions. The resulting
+ * {@code Collector} has the {@code Collector.Characteristics.IDENTITY_FINISH}
+ * characteristic.
+ *
+ * @param supplier The supplier function for the new collector
+ * @param accumulator The accumulator function for the new collector
+ * @param combiner The combiner function for the new collector
+ * @param characteristics The collector characteristics for the new
+ * collector
+ * @param <T> The type of input elements for the new collector
+ * @param <R> The type of intermediate accumulation result, and final result,
+ * for the new collector
+ * @return the new {@code Collector}
+ */
+ public static<T, R> Collector<T, R, R> of(Supplier<R> supplier,
+ BiConsumer<R, T> accumulator,
+ BinaryOperator<R> combiner,
+ Characteristics... characteristics) {
+ Set<Characteristics> cs = (characteristics.length == 0)
+ ? Collectors.CH_ID
+ : Collections.unmodifiableSet(EnumSet.of(Collector.Characteristics.IDENTITY_FINISH,
+ characteristics));
+ return new Collectors.CollectorImpl<>(supplier, accumulator, combiner, cs);
+ }
+
+ /**
+ * Returns a new {@code Collector} described by the given {@code supplier},
+ * {@code accumulator}, {@code combiner}, and {@code finisher} functions.
+ *
+ * @param supplier The supplier function for the new collector
+ * @param accumulator The accumulator function for the new collector
+ * @param combiner The combiner function for the new collector
+ * @param finisher The finisher function for the new collector
+ * @param characteristics The collector characteristics for the new
+ * collector
+ * @param <T> The type of input elements for the new collector
+ * @param <A> The intermediate accumulation type of the new collector
+ * @param <R> The final result type of the new collector
+ * @return the new {@code Collector}
+ */
+ public static<T, A, R> Collector<T, A, R> of(Supplier<A> supplier,
+ BiConsumer<A, T> accumulator,
+ BinaryOperator<A> combiner,
+ Function<A, R> finisher,
+ Characteristics... characteristics) {
+ Set<Characteristics> cs = Collectors.CH_NOID;
+ if (characteristics.length > 0) {
+ cs = EnumSet.noneOf(Characteristics.class);
+ Collections.addAll(cs, characteristics);
+ cs = Collections.unmodifiableSet(cs);
+ }
+ return new Collectors.CollectorImpl<>(supplier, accumulator, combiner, finisher, cs);
+ }
+
+ /**
* Characteristics indicating properties of a {@code Collector}, which can
* be used to optimize reduction implementations.
*/
enum Characteristics {
/**
* Indicates that this collector is <em>concurrent</em>, meaning that
* the result container can support the accumulator function being
* called concurrently with the same result container from multiple
- * threads. Concurrent collectors must also always have the
- * {@code STRICTLY_MUTATIVE} characteristic.
+ * threads.
*
* <p>If a {@code CONCURRENT} collector is not also {@code UNORDERED},
* then it should only be evaluated concurrently if applied to an
* unordered data source.
*/
@@ -236,14 +292,12 @@
* a {@link Set}.
*/
UNORDERED,
/**
- * Indicates that this collector operates by strict mutation of its
- * result container. This means that the {@link #accumulator()} and
- * {@link #combiner()} functions will always modify the state of and
- * return their first argument, rather than returning a different result
- * container.
+ * Indicates that the finisher function is the identity function and
+ * can be elided. If set, it must be the case that an unchecked cast
+ * from A to R will succeed.
*/
- STRICTLY_MUTATIVE
+ IDENTITY_FINISH
}
}