java.util.stream

Interface Collector<T,R>

Type Parameters:

T - The type of input element to the collect operation

R - The result type of the collect operation

public interface Collector<T,R>

A reduction operation 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 Collection; concatenating strings into a 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.

The following are examples of using the predefined Collector implementations in Collectors with the Stream API to perform mutable reduction tasks:

// Accumulate elements into a List
     List list = stream.collect(Collectors.toList());

     // Accumulate elements into a TreeSet
     List 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);

 

A 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.

Collectors also have a set of characteristics, including Collector.Characteristics.CONCURRENT and Collector.Characteristics.STRICTLY_MUTATIVE. These characteristics provide hints that can be used by a reduction implementation to provide better performance.

Libraries that implement reduction based on Collector, such as Stream.collect(Collector), must adhere to the following constraints:

• 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 resultSupplier(), accumulator(), or combiner().
• 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.
• 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.
• Once a result is passed to the combiner function, it is never passed to the accumulator function again.
• 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 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.
• 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 Collector.Characteristics.UNORDERED characteristics or if the originating data is unordered.

Since:

1.8

See Also:

Stream.collect(Collector), Collectors

API Note:

Performing a reduction operation with a Collector should produce a result equivalent to:

BiFunction<R,T,R> accumulator = collector.accumulator();
     R result = collector.resultSupplier().get();
     for (T t : data)
         result = accumulator.apply(result, t);
     return result;
 

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.

An example of an operation that can be easily modeled by Collector is accumulating elements into a TreeSet. In this case, the resultSupplier() function is () -> new Treeset<T>(), the accumulator function is (set, element) -> { set.add(element); return set; }, and the combiner function is (left, right) -> { left.addAll(right); return left; }. (This behavior is implemented by Collectors.toCollection(TreeSet::new)). TODO Associativity and commutativity

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Collector.Characteristics Characteristics indicating properties of a Collector, which can be used to optimize reduction implementations.

Method Summary

Modifier and Type	Method and Description
java.util.function.BiFunction<R,T,R>	accumulator() A function that folds a new value into a cumulative result.
default java.util.Set<Collector.Characteristics>	characteristics() Returns a Set of Collector.Characteristics indicating the characteristics of this Collector.
java.util.function.BinaryOperator<R>	combiner() A function that accepts two partial results and merges them.
java.util.function.Supplier<R>	resultSupplier() A function that creates and returns a new result that represents "no values".

Method Detail

resultSupplier

java.util.function.Supplier<R> resultSupplier()

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.

Returns:

A function which, when invoked, returns a result representing "no values"

accumulator

java.util.function.BiFunction<R,T,R> accumulator()

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.

If the collector has the Collector.Characteristics.STRICTLY_MUTATIVE characteristic, then the accumulator function must always return its first argument, after possibly mutating its state.

Returns:

A function which folds a new value into a cumulative result

combiner

java.util.function.BinaryOperator<R> combiner()

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.

If the collector has the Collector.Characteristics.STRICTLY_MUTATIVE characteristic, then the combiner function must always return its first argument, after possibly mutating its state.

Returns:

A function which combines two partial results into a cumulative result

characteristics

default java.util.Set<Collector.Characteristics> characteristics()

Returns a Set of Collector.Characteristics indicating the characteristics of this Collector. This set should be immutable.

Returns:

An immutable set of collector characteristics