250 lines
12 KiB
Java
250 lines
12 KiB
Java
|
/*
|
||
|
* Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
|
||
|
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
||
|
*
|
||
|
* This code is free software; you can redistribute it and/or modify it
|
||
|
* under the terms of the GNU General Public License version 2 only, as
|
||
|
* published by the Free Software Foundation. Oracle designates this
|
||
|
* particular file as subject to the "Classpath" exception as provided
|
||
|
* by Oracle in the LICENSE file that accompanied this code.
|
||
|
*
|
||
|
* This code is distributed in the hope that it will be useful, but WITHOUT
|
||
|
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
||
|
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
||
|
* version 2 for more details (a copy is included in the LICENSE file that
|
||
|
* accompanied this code).
|
||
|
*
|
||
|
* You should have received a copy of the GNU General Public License version
|
||
|
* 2 along with this work; if not, write to the Free Software Foundation,
|
||
|
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
||
|
*
|
||
|
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
||
|
* or visit www.oracle.com if you need additional information or have any
|
||
|
* questions.
|
||
|
*/
|
||
|
package java.util.stream;
|
||
|
|
||
|
import java.util.Collections;
|
||
|
import java.util.Set;
|
||
|
import java.util.function.BiFunction;
|
||
|
import java.util.function.BinaryOperator;
|
||
|
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.
|
||
|
*
|
||
|
* <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 elements into a TreeSet
|
||
|
* Set<String> list = stream.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();
|
||
|
*
|
||
|
* // Find highest-paid employee
|
||
|
* Employee highestPaid = employees.stream()
|
||
|
* .collect(Collectors.maxBy(Comparators.comparing(Employee::getSalary)));
|
||
|
*
|
||
|
* // 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
|
||
|
* = 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);
|
||
|
*
|
||
|
* }</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
|
||
|
* 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 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>
|
||
|
* <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
|
||
|
* partitioned, that partitions are processed in isolation, and combining
|
||
|
* happens only after accumulation is complete.</li>
|
||
|
* <li>For concurrent collectors, an implementation is free to (but not
|
||
|
* required to) implement reduction concurrently. A concurrent reduction
|
||
|
* is one where the accumulator function is called concurrently from
|
||
|
* multiple threads, using the same concurrently-modifiable result container,
|
||
|
* rather than keeping the result isolated during accumulation.
|
||
|
* A concurrent reduction should only be applied if the collector has the
|
||
|
* {@link Characteristics#UNORDERED} characteristics or if the
|
||
|
* originating data is unordered.</li>
|
||
|
* </ul>
|
||
|
*
|
||
|
* @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();
|
||
|
* for (T t : data)
|
||
|
* result = accumulator.apply(result, t);
|
||
|
* return result;
|
||
|
* }</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
|
||
|
* operation, this may perform better or worse, depending on the relative cost
|
||
|
* of the accumulator and combiner functions.
|
||
|
*
|
||
|
* <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
|
||
|
* 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
|
||
|
* @since 1.8
|
||
|
*/
|
||
|
public interface Collector<T, 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.
|
||
|
*
|
||
|
* @return a function which, when invoked, returns a result representing
|
||
|
* "no values"
|
||
|
*/
|
||
|
Supplier<R> resultSupplier();
|
||
|
|
||
|
/**
|
||
|
* 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.
|
||
|
*
|
||
|
* @return a function which folds a new value into a cumulative result
|
||
|
*/
|
||
|
BiFunction<R, T, R> 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 a function which combines two partial results into a cumulative
|
||
|
* result
|
||
|
*/
|
||
|
BinaryOperator<R> combiner();
|
||
|
|
||
|
/**
|
||
|
* 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();
|
||
|
|
||
|
/**
|
||
|
* 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.
|
||
|
*
|
||
|
* <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.
|
||
|
*/
|
||
|
CONCURRENT,
|
||
|
|
||
|
/**
|
||
|
* Indicates that the result container has no intrinsic order, such as
|
||
|
* 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.
|
||
|
*/
|
||
|
STRICTLY_MUTATIVE
|
||
|
}
|
||
|
}
|