Интерфейс Collector<T,A,R>

public interface Collector<T,A,R>

Изменяемая операция редукции, которая накапливает входные элементы в изменяемом контейнере результата и, при необходимости, преобразует накопленный результат в итоговое представление после обработки всех входных элементов. Операции редукции могут выполняться последовательно или параллельно.

Примеры изменяемых операций редукции: накопление элементов в Collection; объединение строк с помощью StringBuilder; вычисление сводной информации об элементах, например суммы, минимума, максимума или среднего значения; вычисление сводных данных в виде «сводной таблицы», например «транзакция с наибольшей стоимостью по продавцу» и т. д. Класс Collectors предоставляет реализации многих распространённых изменяемых редукций.

Collector задаётся четырьмя функциями, которые совместно накапливают элементы в изменяемом контейнере результата и, при необходимости, выполняют итоговое преобразование результата. Это:

• создание нового контейнера результата (supplier())
• добавление нового элемента данных в контейнер результата (accumulator())
• объединение двух контейнеров результата в один (combiner())
• выполнение необязательного итогового преобразования контейнера (finisher())

У коллекторов также есть набор характеристик, например Collector.Characteristics.CONCURRENT, которые предоставляют подсказки, позволяющие реализации редукции повысить производительность.

Последовательная реализация редукции с помощью коллектора создаёт один контейнер результата с помощью функции-поставщика и вызывает функцию-аккумулятор один раз для каждого входного элемента. Параллельная реализация разбивает входные данные на части, создаёт контейнер результата для каждой части, накапливает содержимое каждой части в промежуточном результате для этой части, а затем использует функцию-комбайнер для объединения промежуточных результатов.

Чтобы последовательное и параллельное выполнение давали эквивалентные результаты, функции коллектора должны удовлетворять ограничениям идентичности и ассоциативности.

Ограничение идентичности означает, что для любого частично накопленного результата его объединение с пустым контейнером результата должно давать эквивалентный результат. То есть для частично накопленного результата 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, например 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)).