Back to index...

	/*
	* Copyright (c) 2012, 2019, 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.EnumSet;
	import java.util.Objects;
	import java.util.Set;
	import java.util.function.BiConsumer;
	import java.util.function.BinaryOperator;
	import java.util.function.Function;
	import java.util.function.Supplier;

	// A compilation test for the code snippets in this class-level javadoc can be found at:
	// test/jdk/java/util/stream/test/org/openjdk/tests/java/util/stream/CollectorExample.java
	// The test needs to be updated if the examples in this javadoc change or new examples are added.

	/**
	* A <a href="package-summary.html#Reduction">mutable reduction operation</a> that
	* accumulates input elements into a mutable result container, optionally transforming
	* the accumulated result into a final representation after all input elements
	* have been processed. Reduction operations can be performed either sequentially
	* or in parallel.
	*
	* <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. The class {@link Collectors}
	* provides implementations of many common mutable reductions.
	*
	* <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: <ul>
	* <li>creation of a new result container ({@link #supplier()})</li>
	* <li>incorporating a new data element into a result container ({@link #accumulator()})</li>
	* <li>combining two result containers into one ({@link #combiner()})</li>
	* <li>performing an optional final transform on the container ({@link #finisher()})</li>
	* </ul>
	*
	* <p>Collectors also have a set of characteristics, such as
	* {@link Characteristics#CONCURRENT}, that provide hints that can be used by a
	* reduction implementation to provide better performance.
	*
	* <p>A sequential implementation of a reduction using a collector would
	* create a single result container using the supplier function, and invoke the
	* accumulator function once for each input element. A parallel implementation
	* would partition the input, create a result container for each partition,
	* accumulate the contents of each partition into a subresult for that partition,
	* and then use the combiner function to merge the subresults into a combined
	* result.
	*
	* <p>To ensure that sequential and parallel executions produce equivalent
	* results, the collector functions must satisfy an <em>identity</em> and an
	* <a href="package-summary.html#Associativity">associativity</a> constraints.
	*
	* <p>The identity constraint says that for any partially accumulated result,
	* combining it with an empty result container must produce an equivalent
	* result. That is, for a partially accumulated result {@code a} that is the
	* result of any series of accumulator and combiner invocations, {@code a} must
	* be equivalent to {@code combiner.apply(a, supplier.get())}.
	*
	* <p>The associativity constraint says that splitting the computation must
	* produce an equivalent result. That is, for any input elements {@code t1}
	* and {@code t2}, the results {@code r1} and {@code r2} in the computation
	* below must be equivalent:
	* <pre>{@code
	* A a1 = supplier.get();
	* accumulator.accept(a1, t1);
	* accumulator.accept(a1, t2);
	* R r1 = finisher.apply(a1); // result without splitting
	*
	* A a2 = supplier.get();
	* accumulator.accept(a2, t1);
	* A a3 = supplier.get();
	* accumulator.accept(a3, t2);
	* R r2 = finisher.apply(combiner.apply(a2, a3)); // result with splitting
	* } </pre>
	*
	* <p>For collectors that do not have the {@code UNORDERED} characteristic,
	* two accumulated results {@code a1} and {@code a2} are equivalent if
	* {@code finisher.apply(a1).equals(finisher.apply(a2))}. For unordered
	* collectors, equivalence is relaxed to allow for non-equality related to
	* differences in order. (For example, an unordered collector that accumulated
	* elements to a {@code List} would consider two lists equivalent if they
	* contained the same elements, ignoring order.)
	*
	* <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, 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, 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
	* 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>
	*
	* <p>In addition to the predefined implementations in {@link Collectors}, the
	* static factory methods {@link #of(Supplier, BiConsumer, BinaryOperator, Characteristics...)}
	* can be used to construct collectors. For example, you could create a collector
	* that accumulates widgets into a {@code TreeSet} with:
	*
	* <pre>{@code
	* Collector<Widget, ?, TreeSet<Widget>> intoSet =
	* Collector.of(TreeSet::new, TreeSet::add,
	* (left, right) -> { left.addAll(right); return left; });
	* }</pre>
	*
	* (This behavior is also implemented by the predefined collector
	* {@link Collectors#toCollection(Supplier)}).
	*
	* @apiNote
	* Performing a reduction operation with a {@code Collector} should produce a
	* result equivalent to:
	* <pre>{@code
	* A container = collector.supplier().get();
	* for (T t : data)
	* 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
	* operation, this may perform better or worse, depending on the relative cost
	* of the accumulator and combiner functions.)
	*
	* <p>Collectors are designed to be <em>composed</em>; many of the methods
	* in {@link Collectors} are functions that take a collector and produce
	* a new collector. For example, given the following collector that computes
	* the sum of the salaries of a stream of employees:
	*
	* <pre>{@code
	* Collector<Employee, ?, Integer> summingSalaries
	* = Collectors.summingInt(Employee::getSalary))
	* }</pre>
	*
	* If we wanted to create a collector to tabulate the sum of salaries by
	* department, we could reuse the "sum of salaries" logic using
	* {@link Collectors#groupingBy(Function, Collector)}:
	*
	* <pre>{@code
	* Collector<Employee, ?, Map<Department, Integer>> summingSalariesByDept
	* = Collectors.groupingBy(Employee::getDepartment, summingSalaries);
	* }</pre>
	*
	* @see Stream#collect(Collector)
	* @see Collectors
	*
	* @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, A, R> {
	/**
	* A function that creates and returns a new mutable result container.
	*
	* @return a function which returns a new, mutable result container
	*/
	Supplier<A> supplier();

	/**
	* A function that folds a value into a mutable result container.
	*
	* @return a function which folds a value into a mutable result container
	*/
	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 container.
	*
	* @return a function which combines two partial results into a combined
	* result
	*/
	BinaryOperator<A> combiner();

	/**
	* Perform the final transformation from the intermediate accumulation type
	* {@code A} to the final result type {@code R}.
	*
	* <p>If the characteristic {@code IDENTITY_FINISH} 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
	* @throws NullPointerException if any argument is null
	* @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) {
	Objects.requireNonNull(supplier);
	Objects.requireNonNull(accumulator);
	Objects.requireNonNull(combiner);
	Objects.requireNonNull(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
	* @throws NullPointerException if any argument is null
	* @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) {
	Objects.requireNonNull(supplier);
	Objects.requireNonNull(accumulator);
	Objects.requireNonNull(combiner);
	Objects.requireNonNull(finisher);
	Objects.requireNonNull(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.
	*
	* <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 collection operation does not commit to preserving
	* the encounter order of input elements. (This might be true if the
	* result container has no intrinsic order, such as a {@link Set}.)
	*/
	UNORDERED,

	/**
	* 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.
	*/
	IDENTITY_FINISH
	}
	}

Back to index...