Collector.java官方文档翻译

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">可变的reduction（归约/汇聚）操作</a>
* 将元素累加到可变的结果容器中,在所有的输入元素都被处理后，
* 可以选择性的将累加的结果转换为最终的表示。
* 归约操作可以串行或者并行的执行。
*
* 可变reduction操作包括的例子有:
* 将元素累加到一个 {@code Collection}，
* 使用 {@code StringBuilder}连接字符串，
* 计算诸如sum, min, max, 或者 average等元素的汇总信息，
* 计算“数据透视表”的总数，比如“卖方最大值交易”等。
* 这个类 {@link Collectors} 提供了很多常用归约操作的实现。
*
* 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>创建一个新的结果容器 ({@link #supplier()})</li>
* <li>将一个新的数据元素合并到结果容器中({@link #accumulator()})</li>
* <li>将两个结果容器合并为一个 ({@link #combiner()})</li>
* <li>在容器上执行可选的最终转换 ({@link #finisher()})</li>
* </ul>
*
* Collectors 有一系列的特征, 比如
* {@link Characteristics#CONCURRENT},
* 提供了可以使用的归约操作的提示，以提供更好的性能
*
* 使用collector进行的归约操作的串行实现将使用supplier函数式接口
* 创建单个结果容器，并为每个输入元素调用一次累加器函数。
* 并行实现将对输入进行分区，为每个分区创建一个结果容器，
* 将每个分区的内容累加到该分区的子结果中(subresult)，然后使用combiner(合并)
* 函数将每个子结果归并为最终结果。
*
* 为了确保串行执行和并行执行产生等价的结果，collector函数必须满足
*identity 以及<a href="package-summary.html#Associativity">associativity</a> 约束
*
* identity（同一性）约束表示，对于任何部分累积的结果，将其与空的结果容器相结合，
* 就必须产生和最终结果相等的结果。
* 也就是说，对于部分累积的结果 {@code a}，是任何一系列的accumulator和
* combiner调用的结果，{@code a}必须等于{@code combiner.apply(a, supplier.get())}.
*
* associativity（结合性）是说，分割计算必须产生等价的结果。
* 也就是说，对于任何输入元素{@code t1}和 {@code t2}，再下面的
* 计算中，结果{@code t1}和 {@code t2}必须相等。
* <pre>{@code
* A a1 = supplier.get();
* accumulator.accept(a1, t1);
* accumulator.accept(a1, t2);
* R r1 = finisher.apply(a1); // 结果没有分割
*
* A a2 = supplier.get();
* accumulator.accept(a2, t1);
* A a3 = supplier.get();
* accumulator.accept(a3, t2);
* R r2 = finisher.apply(combiner.apply(a2, a3)); // 结果分割
* } </pre>
*
* 对于那么没有{@code UNORDERED} 特性的收集器来说，
* 两个累加的结果 {@code a1} 和 {@code a2}相当于er.apply(a1).equals(finisher.apply(a2))}。
* 对于无序的收集器，等效性是宽松的，允许顺序不同的相等。
* （例如：一个无序的收集器将元素累积到{@code List}，如果它们包含相同的元素，忽略顺序的话
* 将会把它们看作是相同的列表）。
*
* 库基于{@code Collector}实现归约操作，比如： {@link Stream#collect(Collector)},
* 必须坚持以下的约束：
* <ul>
* <li>传递给accumulator函数的第一个参数，传递给combiner函数的参数，
* 以及传递给finisher函数的参数必须是supplier,accumulator,combiner
* 之前调用的结果。
*
* <li>该实现不应该对任何supplier, accumulator, 和 combiner函数的
* 结果进行任何操作，除了再次将它们传递给accumulator, combiner, 或 finisher
* 函数，或者将它们返回给reuction操作的调用方。
*
* <li>如果结果传递给combiner或者finisher函数，
* 并且同一个对象不会从这个函数中返回，则不再次使用它。
*
* <li>一旦一个结果被传递给combiner函数或者finisher 函数,
* 它就决不会再传递给accumulator函数。
*
*
* <li>对于非并发的收集器，从supplier,accumulator,或者combiner函数中
* 返回的任何结果都必须是串行线程限制的。
* 这使得集合可以并发执行，而不需要 {@code Collector} 来实现
* 任何额外的同步。
* reduction实现必须管理好输入将其正确的分区，分区被独立的处理，
* 并且只有在累加之后才进行合并。
*
*
* <li>对于并发的收集器，实现可以是自由的（但不要求）并发实现reduction。
* 并发的reduction是在多个线程中同时调用accumulator函数，使用相同的
* 可并发修改的结果容器，而不是在累积过程中使这个结果隔离。
* 只有当收集器有 {@link Characteristics#UNORDERED} 特性时或者
* 原始数据是无序时，才应该使用并发的reduction.
* </ul>
*
* 除了在 {@link Collectors}中预定义的实现外，静态工厂方法
* {@link #of(Supplier, BiConsumer, BinaryOperator, Characteristics...)}也能够
* 用来构建收集器。例如，你可以创建收集器累加widgets到{@code TreeSet}中：
*
* <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
* 使用 {@code Collector}执行一个reduction操作应该产生和下面等价的结果：
* <pre>{@code
* R container = collector.supplier().get();
* for (T t : data)
* collector.accumulator().accept(container, t);
* return collector.finisher().apply(container);
* }</pre>
*
* 然而，库可以自由的划分输入，在分区上执行reduction操作，
* 然后使用combiner函数合并部分结果实现并行reduction 。
* （取决于特定的reduction操作，可能执行的更好或者更差，依赖于
* 相关的accumulator和combiner函数的开销）
*
* 收集器被设计成 可组合的 ;在 {@link Collectors}
* 的许多方法都是接收一个新的收集器然后生成一个新的收集器。
* 比如，给定如下收集器，计算员工的工资总和。
*
* <pre>{@code
* Collector<Employee, ?, Integer> summingSalaries
* = Collectors.summingInt(Employee::getSalary))
* }</pre>
*
* 如果我们想要创建一个收集器来按部门计算工资的总和，我们可以使用
* {@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> {
 /**
 *创建并返回一个新的可变结果容器的函数。
 * @return a function which returns a new, mutable result container
 */
 Supplier<A> supplier();

 /**
 * 将值汇聚成可变结果的函数
 *
 * @return a function which folds a value into a mutable result container
 */
 BiConsumer<A, T> accumulator();

 /**
 * 一个接收两个部分结果并将其合并的函数。
 * combiner函数可以将状态从一个参数叠加到另一个参数，并将其返回，
 * 或者返回一个新的结果容器。
 *
 * @return a function which combines two partial results into a combined
 * result
 */
 BinaryOperator<A> combiner();

 /**
 *执行从中间结果类型{@code A}到最终结果类型 {@code R}的转换。
 *
 * 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();

 /**
 * 返回 {@code Collector.Characteristics} 的{@code Set}，指出
 * 收集器的特征。这个集合应该是不可变的。
 *
 * @return an immutable set of collector characteristics
 */
 Set<Characteristics> characteristics();

 /**
 * 返回由给定的{@code supplier}, {@code accumulator}, 和 {@code combiner} 函数
 * 描述的新的收集器。此结果{@code Collector}具有{@code Collector.Characteristics.IDENTITY_FINISH}
 * 特征
 *
 * @param supplier 新收集器的supplier函数
 * @param accumulator 新收集器的accumulator函数
 * @param combiner 新收集器的combiner函数
 * @param characteristics 新收集器的特征
 *
 * @param <T> 新收集器输入元素的类型
 * @param <R> 新收集器中间计算结果和最终结果的类型。
 * @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);
 }

 /**
 * 返回一个由给定的 {@code supplier},
 * {@code accumulator}, {@code combiner}, 和 {@code finisher} 函数
 * 描述的收集器。
 *
 * @param supplier 新收集器的supplier函数
 * @param accumulator 新收集器的accumulator函数
 * @param combiner新收集器的combiner函数
 * @param finisher 新收集器的finisher函数
 * @param characteristics 新收集器的characteristics特征。
 *
 * @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);
 }

 /**
 * 特征表明了{@code Collector}的属性，该属性
 * 可用于优化reduction实现。
 */
 enum Characteristics {
 /**
 * Indicates that this collector is concurrent, meaning that
 * the result container can support the accumulator function being
 * called concurrently with the same result container from multiple
 * threads.
 *
 * 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
 }
}

Collector.java官方文档翻译

猜你喜欢