2013-04-17 14:39:04 -04:00
|
|
|
/*
|
|
|
|
* 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;
|
2013-06-28 16:26:54 -04:00
|
|
|
import java.util.EnumSet;
|
2013-04-17 14:39:04 -04:00
|
|
|
import java.util.Set;
|
2013-06-28 16:26:54 -04:00
|
|
|
import java.util.function.BiConsumer;
|
2013-04-17 14:39:04 -04:00
|
|
|
import java.util.function.BinaryOperator;
|
2013-06-28 16:26:54 -04:00
|
|
|
import java.util.function.Function;
|
2013-04-17 14:39:04 -04:00
|
|
|
import java.util.function.Supplier;
|
|
|
|
|
|
|
|
/**
|
|
|
|
* A <a href="package-summary.html#Reduction">reduction operation</a> that
|
2013-06-28 16:26:54 -04:00
|
|
|
* 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.
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* <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
|
2013-06-28 16:26:54 -04:00
|
|
|
* // Accumulate names into a List
|
|
|
|
* List<String> list = people.stream().map(Person::getName).collect(Collectors.toList());
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
2013-06-28 16:26:54 -04:00
|
|
|
* // Accumulate names into a TreeSet
|
|
|
|
* Set<String> list = people.stream().map(Person::getName).collect(Collectors.toCollection(TreeSet::new));
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* // Convert elements to strings and concatenate them, separated by commas
|
2013-06-28 16:26:54 -04:00
|
|
|
* String joined = things.stream()
|
|
|
|
* .map(Object::toString)
|
|
|
|
* .collect(Collectors.joining(", "));
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* // Find highest-paid employee
|
|
|
|
* Employee highestPaid = employees.stream()
|
2013-06-28 16:26:54 -04:00
|
|
|
* .collect(Collectors.maxBy(Comparators.comparing(Employee::getSalary)))
|
|
|
|
* .get();
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* // Group employees by department
|
|
|
|
* Map<Department, List<Employee>> byDept
|
|
|
|
* = employees.stream()
|
|
|
|
* .collect(Collectors.groupingBy(Employee::getDepartment));
|
|
|
|
*
|
|
|
|
* // Find highest-paid employee by department
|
2013-06-28 16:26:54 -04:00
|
|
|
* Map<Department, Optional<Employee>> highestPaidByDept
|
2013-04-17 14:39:04 -04:00
|
|
|
* = 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()
|
2013-06-28 16:26:54 -04:00
|
|
|
* .collect(Collectors.partitioningBy(s -> s.getGrade() >= PASS_THRESHOLD));
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* }</pre>
|
|
|
|
*
|
2013-06-28 16:26:54 -04:00
|
|
|
* <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
|
2013-04-17 14:39:04 -04:00
|
|
|
* 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>
|
2013-06-28 16:26:54 -04:00
|
|
|
* <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>
|
2013-04-17 14:39:04 -04:00
|
|
|
* <li>The implementation should not do anything with the result of any of
|
|
|
|
* the result supplier, accumulator, or combiner functions other than to
|
2013-06-28 16:26:54 -04:00
|
|
|
* 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>
|
2013-04-17 14:39:04 -04:00
|
|
|
* <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
|
2013-06-28 16:26:54 -04:00
|
|
|
* R container = collector.supplier().get();
|
2013-04-17 14:39:04 -04:00
|
|
|
* for (T t : data)
|
2013-06-28 16:26:54 -04:00
|
|
|
* collector.accumulator().accept(container, t);
|
|
|
|
* return collector.finisher().apply(container);
|
2013-04-17 14:39:04 -04:00
|
|
|
* }</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
|
2013-06-28 16:26:54 -04:00
|
|
|
* {@code (set, element) -> set.add(element) }, and the combiner
|
2013-04-17 14:39:04 -04:00
|
|
|
* 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
|
|
|
|
*
|
2013-06-28 16:26:54 -04:00
|
|
|
* @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
|
2013-04-17 14:39:04 -04:00
|
|
|
* @since 1.8
|
|
|
|
*/
|
2013-06-28 16:26:54 -04:00
|
|
|
public interface Collector<T, A, R> {
|
2013-04-17 14:39:04 -04:00
|
|
|
/**
|
2013-06-28 16:26:54 -04:00
|
|
|
* A function that creates and returns a new mutable result container.
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
2013-06-28 16:26:54 -04:00
|
|
|
* @return a function which returns a new, mutable result container
|
2013-04-17 14:39:04 -04:00
|
|
|
*/
|
2013-06-28 16:26:54 -04:00
|
|
|
Supplier<A> supplier();
|
2013-04-17 14:39:04 -04:00
|
|
|
|
|
|
|
/**
|
2013-06-28 16:26:54 -04:00
|
|
|
* A function that folds a new value into a mutable result container.
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
2013-06-28 16:26:54 -04:00
|
|
|
* @return a function which folds a new value into a mutable result container
|
2013-04-17 14:39:04 -04:00
|
|
|
*/
|
2013-06-28 16:26:54 -04:00
|
|
|
BiConsumer<A, T> accumulator();
|
2013-04-17 14:39:04 -04:00
|
|
|
|
|
|
|
/**
|
|
|
|
* A function that accepts two partial results and merges them. The
|
|
|
|
* combiner function may fold state from one argument into the other and
|
2013-06-28 16:26:54 -04:00
|
|
|
* return that, or may return a new result object.
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* @return a function which combines two partial results into a cumulative
|
|
|
|
* result
|
|
|
|
*/
|
2013-06-28 16:26:54 -04:00
|
|
|
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();
|
2013-04-17 14:39:04 -04:00
|
|
|
|
|
|
|
/**
|
|
|
|
* 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();
|
|
|
|
|
2013-06-28 16:26:54 -04:00
|
|
|
/**
|
|
|
|
* 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);
|
|
|
|
}
|
|
|
|
|
2013-04-17 14:39:04 -04:00
|
|
|
/**
|
|
|
|
* 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
|
2013-06-28 16:26:54 -04:00
|
|
|
* threads.
|
2013-04-17 14:39:04 -04:00
|
|
|
*
|
|
|
|
* <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,
|
|
|
|
|
|
|
|
/**
|
2013-06-28 16:26:54 -04:00
|
|
|
* 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.
|
2013-04-17 14:39:04 -04:00
|
|
|
*/
|
2013-06-28 16:26:54 -04:00
|
|
|
IDENTITY_FINISH
|
2013-04-17 14:39:04 -04:00
|
|
|
}
|
|
|
|
}
|