Interface 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)).