/*

 * 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

    }

}