Module  java.base
软件包  java.util.stream

Interface Collector<T,A,R>

  • 参数类型
    T - 还原操作的输入元素的类型
    A - 缩减操作的可变累积类型（通常作为实现细节隐藏）
    R - 缩小操作的结果类型 

    public interface Collector<T,A,R>
    A mutable reduction operation将输入元素累加到可变结果容器中，可选地将所有输入元素处理后的累加结果转换成最终表示。 还原操作可以顺序还是并行执行。

    可变缩减操作的示例包括：将元素累加到一个Collection ; 使用StringBuilder连接字符串; 计算诸如sum，min，max或average的元素的概要信息; 计算“枢纽表”摘要，如“卖方最大价值交易”等。Collectors类提供了许多常见的可变减少的实现。

    A Collector由四个函数指定，这四个函数一起工作以将条目累加到可变结果容器中，并可选择对结果执行最终转换。 他们是：

    • 创建新的结果容器（ supplier() ）
    • 在结果容器中加入新的数据元素（ accumulator() ）
    • 将两个结果容器组合成一个（ combiner() ）
    • 在容器上执行可选的最终变换（ finisher() ）

    收集者还具有一系列特征，例如Collector.Characteristics.CONCURRENT ，它提供可由减少实现使用以提供更好性能的提示。

    使用收集器的顺序实现减少将使用供应商函数创建单个结果容器，并为每个输入元素调用累加器函数一次。 并行实现将分区输入，为每个分区创建一个结果容器，将每个分区的内容累加到该分区的子结果中，然后使用组合器函数将子结果合并为一个组合结果。

    为了确保顺序和并行执行产生相同的结果，收集器函数必须满足一个身份和一个associativity约束。

    身份约束说，对于任何部分累积的结果，将其与空结果容器组合必须产生等效的结果。 也就是说，部分累加结果a即任何系列累加器和组合器的调用的结果， a必须等于combiner.apply(a, supplier.get()) 。

    关联约束说，分割计算必须产生等效的结果。 也就是说，对于任何输入元件t1和t2 ，下面的计算中的结果r1和r2必须等效： 

       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

    对于不具备收藏UNORDERED特征，二累加结果a1和a2是等价的，如果finisher.apply(a1).equals(finisher.apply(a2)) 。 对于无序的收藏者，放宽等价以允许与秩序的差异相关的不平等。 （例如，如果List元素累积到一个无序的收集器，如果它们包含相同的元素，则会考虑两个列表，忽略顺序。）

    基于Collector实现减少的Collector （如Stream.collect(Collector) ）必须遵守以下约束：

    • 第一个参数传递给累加器函数，两个参数传递给组合函数，传递给完成者函数的参数必须是先前调用结果提供程序，累加器或组合函数的结果。
    • 除了将其再次传递给累加器，组合器或修整器功能之外，实现不应该对任何结果提供者，累加器或组合器功能进行任何操作，也可以将它们返回给还原操作的调用者。
    • 如果结果传递给组合器或整理器函数，并且不从该函数返回相同的对象，则不会再次使用该对象。
    • 一旦结果传递给组合器或整理器函数，它就不会再次传递给累加器函数。
    • 对于非并发收集器，从结果提供者，累加器或组合器函数返回的任何结果必须是串行线程限制的。 这使得集合并行发生，而Collector需要实现任何其他同步。 还原实现必须管理输入被正确分区，分区被隔离处理，并且组合仅在累积完成后才进行。
    • 对于并发收集器，实现可以自由（但不是必须）同时实现还原。 并发减少是使用同一可同时修改的结果容器从多个线程并发调用累加器函数，而不是在累积期间保持结果隔离。 仅当收集器具有Collector.Characteristics.UNORDERED特性或者起始数据无序时，才应用并发减少。

    除了Collectors中的预定义实现之外 ，静态工厂方法of(Supplier, BiConsumer, BinaryOperator, Characteristics...)可用于构建收集器。 例如，您可以创建一个收集器，将小部件累积到TreeSet中： 

       Collector<Widget, ?, TreeSet<Widget>> intoSet = Collector.of(TreeSet::new, TreeSet::add, (left, right) -> { left.addAll(right); return left; });
    （此行为也由预定义的收集器Collectors.toCollection(Supplier)实现 ）。
    API Note:
    使用Collector执行缩减操作时应产生等效于： 
       R container = collector.supplier().get(); for (T t : data) collector.accumulator().accept(container, t); return collector.finisher().apply(container);

    然而，库可以自由分割输入，执行分区的减少，然后使用组合器函数组合部分结果以实现并行还原。 （根据具体的减速操作，这可能会更好或更差，取决于累加器和组合器功能的相对成本。）

    收藏家的目的是组成 ; Collectors中的许多方法是使用收集器并生成新收集器的函数。 例如，给定以下收集器来计算员工流的总和： 

       Collector<Employee, ?, Integer> summingSalaries = Collectors.summingInt(Employee::getSalary))
    如果我们想创建一个收藏家，按部门列出工资总额，我们可以使用Collectors.groupingBy(Function, Collector)重新使用“薪金总额”逻辑： 
       Collector<Employee, ?, Map<Department, Integer>> summingSalariesByDept = Collectors.groupingBy(Employee::getDepartment, summingSalaries);
    从以下版本开始：
    1.8
    另请参见：
    Stream.collect(Collector) ， Collectors

    • 方法详细信息

      • supplier

        Supplier<A> supplier​()
        一个创建并返回一个新的可变结果容器的函数。
        结果
        一个返回一个新的可变结果容器的函数

      • accumulator

        BiConsumer<A,T> accumulator​()
        将值折叠成可变结果容器的函数。
        结果
        将值折叠成可变结果容器的函数

      • combiner

        BinaryOperator<A> combiner​()
        一个接受两个部分结果并将其合并的函数。 组合器功能可以将状态从一个参数折叠到另一个参数，并返回，或者可能返回一个新的结果容器。
        结果
        将两个部分结果组合成一个组合结果的函数

      • finisher

        Function<A,R> finisher​()
        执行从中间累积类型A到最终结果类型R的最终R 。

        如果设置了特征IDENTITY_FINISH则可以将该功能推定为具有从A到R的未经检查的转换的身份变换。

        结果
        将中间结果转换为最终结果的函数

      • characteristics

        Set<Collector.Characteristics> characteristics​()
        返回Set的Collector.Characteristics表明该收藏家的特征。 这一套应该是不变的。
        结果
        一套不可变的收集器特征

      • of

        static <T,R> Collector<T,R,R> of​(Supplier<R> supplier,
                                 BiConsumer<R,T> accumulator,
                                 BinaryOperator<R> combiner,
                                 Collector.Characteristics... characteristics)
        返回一个新Collector由给定的描述supplier ， accumulator ，并combiner功能。 所得到的Collector具有Collector.Characteristics.IDENTITY_FINISH特点。
        参数类型
        T - 新收集器的输入元素的类型
        R - 新收集器的中间累积结果类型和最终结果
        参数
        supplier - 新收藏家的供应商功能
        accumulator - 新收集器的累加器功能
        combiner - 新收集器的组合器功能
        characteristics - 新收集器的收集器特性
        结果
        新的 Collector
        异常
        NullPointerException - 如果任何参数为空

      • of

        static <T,A,R> Collector<T,A,R> of​(Supplier<A> supplier,
                                   BiConsumer<A,T> accumulator,
                                   BinaryOperator<A> combiner,
                                   Function<A,R> finisher,
                                   Collector.Characteristics... characteristics)
        返回一个新 Collector由给定的描述 supplier ， accumulator ， combiner ，并 finisher功能。
        参数类型
        T - 新收集器的输入元素的类型
        A - 新收藏家的中间累积类型
        R - 新收集器的最终结果类型
        参数
        supplier - 新收藏家的供应商功能
        accumulator - 新收集器的累加器功能
        combiner - 新收集器的组合器功能
        finisher - 新收藏家的完成器功能
        characteristics - 新收集器的收集器特性
        结果
        新的 Collector
        异常
        NullPointerException - 如果任何参数为空