Interface Gatherer<T,A,R>

Параметры типа:: T - тип входных элементов для операции сборщика; A - тип потенциально изменяемого состояния операции сборщика (часто скрытый как деталь реализации); R - тип выходных элементов операции сборщика

public interface Gatherer<T,A,R>

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

Операции сборщика могут выполняться последовательно или параллельно — если предоставлена функция-комбайнер.

Существует множество примеров операций сбора, включая, помимо прочего: группировку элементов в пакеты (функции окон); удаление подряд идущих похожих элементов; функции инкрементального накопления (префиксное сканирование); функции инкрементального переупорядочивания и т. д. Класс Gatherers предоставляет реализации распространённых операций сбора.

Примечание API:

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

создание нового, потенциально изменяемого состояния (initializer())
обработка нового входного элемента (integrator())
объединение двух состояний в одно (combiner())
выполнение необязательного завершающего действия (finisher())

Каждый вызов initializer(), integrator(), combiner() и finisher() должен возвращать семантически идентичный результат.

Реализации Gatherer не должны захватывать, сохранять или передавать другим потокам ссылки на экземпляр состояния или нижестоящий Gatherer.Downstream дольше, чем длится вызов метода, которому они переданы.

Операция сбора с помощью Gatherer должна давать результат, эквивалентный следующему:

Gatherer.Downstream<? super R> downstream = ...;
A state = gatherer.initializer().get();
for (T t : data) {
    gatherer.integrator().integrate(state, t, downstream);
}
gatherer.finisher().accept(state, downstream);

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

Помимо предопределённых реализаций в Gatherers, для создания сборщиков можно использовать статические фабричные методы of(...) и ofSequential(...). Например, можно создать сборщик, реализующий эквивалент Stream.map(java.util.function.Function), следующим образом:

public static <T, R> Gatherer<T, ?, R> map(Function<? super T, ? extends R> mapper) {
    return Gatherer.of(
        (unused, element, downstream) -> // integrator
            downstream.push(mapper.apply(element))
    );
}

Сборщики предназначены для композиции; два или более сборщика можно объединить в один с помощью метода andThen(Gatherer).

// using the implementation of `map` as seen above
Gatherer<Integer, ?, Integer> increment = map(i -> i + 1);

Gatherer<Object, ?, String> toString = map(i -> i.toString());

Gatherer<Integer, ?, String> incrementThenToString = increment.andThen(toString);

Например, сборщик, реализующий последовательное префиксное сканирование, можно создать следующим образом:

public static <T, R> Gatherer<T, ?, R> scan(
    Supplier<R> initial,
    BiFunction<? super R, ? super T, ? extends R> scanner) {

    class State {
        R current = initial.get();
    }

    return Gatherer.<T, State, R>ofSequential(
         State::new,
         Gatherer.Integrator.ofGreedy((state, element, downstream) -> {
             state.current = scanner.apply(state.current, element);
             return downstream.push(state.current);
         })
    );
}

Пример использования:

// will contain: ["1", "12", "123", "1234", "12345", "123456", "1234567", "12345678", "123456789"]
List<String> numberStrings =
    Stream.of(1,2,3,4,5,6,7,8,9)
          .gather(
              scan(() -> "", (string, number) -> string + number)
           )
          .toList();

Требования к реализации:

Библиотеки, реализующие преобразования на основе Gatherer, например Stream.gather(Gatherer), должны соблюдать следующие ограничения:

Сборщики, инициализатор которых — это defaultInitializer(), считаются не имеющими состояния; вызов их инициализатора необязателен.
Можно считать, что сборщики, интегратор которых является экземпляром Gatherer.Integrator.Greedy, не выполняют досрочное завершение; проверять возвращаемое значение вызова Gatherer.Integrator.integrate(Object, Object, Downstream) не требуется.
Первый аргумент, передаваемый функции интеграции, оба аргумента, передаваемые функции-комбайнеру, и аргумент, передаваемый функции-завершителю, должны быть результатом предыдущего вызова функции инициализатора или комбайнера.
Реализация не должна использовать результаты функций инициализатора или комбайнера иначе, чем передавая их повторно функциям интегратора, комбайнера или завершителя.
После передачи объекта состояния функции-комбайнеру или функции-завершителю он больше никогда не передаётся функции интегратора.
Если функция интегратора возвращает false, это следует интерпретировать так же, как если бы для передачи ей больше не было элементов.
При параллельном вычислении реализация операции сбора должна обеспечить правильное разбиение входных данных на части, изолированную обработку частей и выполнение объединения только после завершения интеграции обеих частей.
Сборщики с defaultCombiner() в качестве комбайнера могут вычисляться только последовательно. Все остальные комбайнеры позволяют выполнять операцию параллельно: каждую часть инициализируют отдельно, вызывают интегратор до тех пор, пока он не вернёт false, затем объединяют состояния частей с помощью комбайнера и вызывают завершитель для объединённого состояния. Выходные данные и состояние, относящиеся к более поздним элементам входной последовательности, будут отброшены, если обработка более ранней части завершится досрочно.
Сборщики, у которых завершителем является defaultFinisher(), считаются не имеющими обработчика конца потока; вызов их завершителя необязателен.

С версии:

См. также:

Краткое описание вложенных классов

Модификатор и тип	Интерфейс	Описание
`static interface`	`Gatherer.Downstream<T>`	Объект Downstream — это следующий этап конвейера операций, которому можно передавать элементы.
`static interface`	`Gatherer.Integrator<A,T,R>`	Интегратор получает и обрабатывает элементы, при необходимости используя предоставленное состояние, и, при необходимости, передаёт инкрементальные результаты нижестоящему этапу.

Краткое описание методов

Модификатор и тип	Метод	Описание
`default <RR> Gatherer<T,?,RR>`	`andThen(Gatherer<? super R, ?, ? extends RR> that)`	Возвращает составной сборщик, соединяющий выход этого сборщика со входом того сборщика.
`default BinaryOperator<A>`	`combiner()`	Функция, принимающая два промежуточных состояния и объединяющая их в одно.
`static <A> BinaryOperator<A>`	`defaultCombiner()`	Возвращает комбайнер, являющийся комбайнером по умолчанию для сборщика.
`static <A,R> BiConsumer<A, Gatherer.Downstream<? super R>>`	`defaultFinisher()`	Возвращает `finisher`, являющийся завершителем по умолчанию для `Gatherer`.
`static <A> Supplier<A>`	`defaultInitializer()`	Возвращает инициализатор, являющийся инициализатором по умолчанию для сборщика.
`default BiConsumer<A, Gatherer.Downstream<? super R>>`	`finisher()`	Функция, принимающая конечное промежуточное состояние и объект `Gatherer.Downstream`, что позволяет выполнить завершающее действие в конце входных элементов.
`default Supplier<A>`	`initializer()`	Функция, создающая экземпляр промежуточного состояния, используемого для этой операции сбора.
`Gatherer.Integrator<A,T,R>`	`integrator()`	Функция, интегрирующая предоставленные элементы, при необходимости используя предоставленное промежуточное состояние и, при необходимости, выдавая результат в предоставленный объект `Gatherer.Downstream`.
`static <T,A,R> Gatherer<T,A,R>`	`of(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator, BinaryOperator<A> combiner, BiConsumer<A, Gatherer.Downstream<? super R>> finisher)`	Возвращает новый параллелизуемый `Gatherer`, заданный предоставленными `initializer`, `integrator`, `combiner` и `finisher`.
`static <T,R> Gatherer<T,Void,R>`	`of(Gatherer.Integrator<Void,T,R> integrator)`	Возвращает новый параллелизуемый сборщик без состояния `Gatherer`, заданный предоставленным `integrator`.
`static <T,R> Gatherer<T,Void,R>`	`of(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)`	Возвращает новый параллелизуемый сборщик без состояния `Gatherer`, заданный предоставленными `integrator` и `finisher`.
`static <T,A,R> Gatherer<T,A,R>`	`ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator)`	Возвращает новый последовательный `Gatherer`, заданный предоставленными `initializer` и `integrator`.
`static <T,A,R> Gatherer<T,A,R>`	`ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator, BiConsumer<A, Gatherer.Downstream<? super R>> finisher)`	Возвращает новый последовательный `Gatherer`, заданный предоставленными `initializer`, `integrator` и `finisher`.
`static <T,R> Gatherer<T,Void,R>`	`ofSequential(Gatherer.Integrator<Void,T,R> integrator)`	Возвращает новый последовательный сборщик без состояния `Gatherer`, заданный предоставленным `integrator`.
`static <T,R> Gatherer<T,Void,R>`	`ofSequential(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)`	Возвращает новый последовательный сборщик без состояния `Gatherer`, заданный предоставленными `integrator` и `finisher`.

Подробное описание методов

initializer

default Supplier<A> initializer()

Функция, создающая экземпляр промежуточного состояния, используемого для этой операции сбора.

Требования к реализации:: Реализация в этом интерфейсе возвращает defaultInitializer().
Возвращает:: функцию, создающую экземпляр промежуточного состояния, используемого для этой операции сбора

integrator

Gatherer.Integrator<A,T,R> integrator()

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

Возвращает:: функцию, интегрирующую предоставленные элементы, при необходимости используя предоставленное состояние и, при необходимости, выдавая результат в предоставленный объект Downstream

combiner

default BinaryOperator<A> combiner()

Функция, принимающая два промежуточных состояния и объединяющая их в одно.

Требования к реализации:: Реализация в этом интерфейсе возвращает defaultCombiner().
Возвращает:: функцию, принимающую два промежуточных состояния и объединяющую их в одно

finisher

default BiConsumer<A, Gatherer.Downstream<? super R>> finisher()

Функция, принимающая конечное промежуточное состояние и объект Gatherer.Downstream, что позволяет выполнить завершающее действие в конце входных элементов.

Требования к реализации:: Реализация в этом интерфейсе возвращает defaultFinisher().
Возвращает:: функцию, преобразующую промежуточный результат в конечный результат или результаты, которые затем передаются предоставленному объекту Downstream

andThen

default <RR> Gatherer<T,?,RR> andThen(Gatherer<? super R, ?, ? extends RR> that)

Возвращает составной сборщик, соединяющий выход этого сборщика со входом того сборщика.

Требования к реализации:: Реализация в этом интерфейсе возвращает новый сборщик, семантически эквивалентный комбинации сборщиков this и that.
Параметры типа:: RR - тип выходных данных того сборщика
Параметры:: that - другой сборщик
Возвращает:: возвращает составной сборщик, соединяющий выход этого сборщика со входом того сборщика
Выбрасывает:: NullPointerException - если аргумент равен null

defaultInitializer

static <A> Supplier<A> defaultInitializer()

Возвращает инициализатор, являющийся инициализатором по умолчанию для сборщика. Возвращённый инициализатор указывает, что содержащий его сборщик не имеет состояния.

Требования к реализации:

Этот метод всегда возвращает один и тот же экземпляр.

Параметры типа:

A - тип состояния возвращённого инициализатора

Возвращает:

экземпляр инициализатора по умолчанию

См. также:

defaultCombiner

static <A> BinaryOperator<A> defaultCombiner()

Возвращает комбайнер, являющийся комбайнером по умолчанию для сборщика. Возвращённый комбайнер указывает, что содержащий его сборщик должен вычисляться только последовательно.

Требования к реализации:

Этот метод всегда возвращает один и тот же экземпляр.

Параметры типа:

A - тип состояния возвращённого комбайнера

Возвращает:

экземпляр комбайнера по умолчанию

См. также:

defaultFinisher

static <A,R> BiConsumer<A, Gatherer.Downstream<? super R>> defaultFinisher()

Возвращает finisher, являющийся завершителем по умолчанию для Gatherer. Возвращённый завершитель указывает, что содержащий его сборщик не выполняет никаких дополнительных действий в конце входных данных.

Требования к реализации:

Этот метод всегда возвращает один и тот же экземпляр.

Параметры типа:

A - тип состояния возвращённого завершителя

R - тип Downstream возвращённого завершителя

Возвращает:

экземпляр завершителя по умолчанию

См. также:

ofSequential

static <T,R> Gatherer<T,Void,R> ofSequential(Gatherer.Integrator<Void,T,R> integrator)

Возвращает новый последовательный сборщик без состояния Gatherer, заданный предоставленным integrator.

Параметры типа:: T - тип входных элементов для нового сборщика; R - тип результатов нового сборщика
Параметры:: integrator - функция интегратора для нового сборщика
Возвращает:: новый Gatherer
Выбрасывает:: NullPointerException - если аргумент равен null

ofSequential

static <T,R> Gatherer<T,Void,R> ofSequential(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)

Возвращает новый последовательный сборщик без состояния Gatherer, заданный предоставленными integrator и finisher.

Параметры типа:: T - тип входных элементов для нового сборщика; R - тип результатов нового сборщика
Параметры:: integrator - функция интегратора для нового сборщика; finisher - функция завершителя для нового сборщика
Возвращает:: новый Gatherer
Выбрасывает:: NullPointerException - если какой-либо аргумент равен null

ofSequential

static <T,A,R> Gatherer<T,A,R> ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator)

Возвращает новый последовательный Gatherer, заданный предоставленными initializer и integrator.

Параметры типа:: T - тип входных элементов для нового сборщика; A - тип состояния нового сборщика; R - тип результатов нового сборщика
Параметры:: initializer - функция инициализатора для нового сборщика; integrator - функция интегратора для нового сборщика
Возвращает:: новый Gatherer
Выбрасывает:: NullPointerException - если какой-либо аргумент равен null

ofSequential

static <T,A,R> Gatherer<T,A,R> ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator, BiConsumer<A, Gatherer.Downstream<? super R>> finisher)

Возвращает новый последовательный Gatherer, заданный предоставленными initializer, integrator и finisher.

Параметры типа:: T - тип входных элементов для нового сборщика; A - тип состояния нового сборщика; R - тип результатов нового сборщика
Параметры:: initializer - функция инициализатора для нового сборщика; integrator - функция интегратора для нового сборщика; finisher - функция завершителя для нового сборщика
Возвращает:: новый Gatherer
Выбрасывает:: NullPointerException - если какой-либо аргумент равен null

of

static <T,R> Gatherer<T,Void,R> of(Gatherer.Integrator<Void,T,R> integrator)

Возвращает новый параллелизуемый сборщик без состояния Gatherer, заданный предоставленным integrator.

Параметры типа:: T - тип входных элементов для нового сборщика; R - тип результатов нового сборщика
Параметры:: integrator - функция интегратора для нового сборщика
Возвращает:: новый Gatherer
Выбрасывает:: NullPointerException - если какой-либо аргумент равен null

of

static <T,R> Gatherer<T,Void,R> of(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)

Возвращает новый параллелизуемый сборщик без состояния Gatherer, заданный предоставленными integrator и finisher.

Параметры типа:: T - тип входных элементов для нового сборщика; R - тип результатов нового сборщика
Параметры:: integrator - функция интегратора для нового сборщика; finisher - функция завершителя для нового сборщика
Возвращает:: новый Gatherer
Выбрасывает:: NullPointerException - если какой-либо аргумент равен null

of

static <T,A,R> Gatherer<T,A,R> of(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator, BinaryOperator<A> combiner, BiConsumer<A, Gatherer.Downstream<? super R>> finisher)

Возвращает новый параллелизуемый Gatherer, заданный предоставленными initializer, integrator, combiner и finisher.

Параметры типа:: T - тип входных элементов для нового сборщика; A - тип состояния нового сборщика; R - тип результатов нового сборщика
Параметры:: initializer - функция инициализатора для нового сборщика; integrator - функция интегратора для нового сборщика; combiner - функция-комбайнер для нового сборщика; finisher - функция завершителя для нового сборщика
Возвращает:: новый Gatherer
Выбрасывает:: NullPointerException - если какой-либо аргумент равен null

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/stream/Gatherer.html