/*

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

 *     R 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_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();

    /**

     * 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

    }

}