Interface Gatherer<T,A,R>

Type Parameters:

T - the type of input elements to the gatherer operation

A - the potentially mutable state type of the gatherer operation (often hidden as an implementation detail)

R - the type of output elements from the gatherer operation

public interface Gatherer<T,A,R>

An intermediate operation that transforms a stream of input elements into a stream of output elements, optionally applying a final action when the end of the upstream is reached. The transformation may be stateless or stateful, and may buffer input before producing any output.

Gatherer operations can be performed either sequentially, or be parallelized -- if a combiner function is supplied.

There are many examples of gathering operations, including but not limited to: grouping elements into batches (windowing functions); de-duplicating consecutively similar elements; incremental accumulation functions (prefix scan); incremental reordering functions, etc. The class Gatherers provides implementations of common gathering operations.

Since:

24

See Also:

• Stream.gather(Gatherer)
• Gatherers

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	Gatherer.Downstream<T>	A Downstream object is the next stage in a pipeline of operations, to which elements can be sent.
static interface	Gatherer.Integrator<A,T,R>	An Integrator receives elements and processes them, optionally using the supplied state, and optionally sends incremental results downstream.

Method Summary

Modifier and Type	Method	Description
default <RR> Gatherer<T,?,RR>	andThen(Gatherer<? super R, ?, ? extends RR> that)	Returns a composed Gatherer which connects the output of this Gatherer to the input of that Gatherer.
default BinaryOperator<A>	combiner()	A function which accepts two intermediate states and combines them into one.
static <A> BinaryOperator<A>	defaultCombiner()	Returns a combiner which is the default combiner of a Gatherer.
static <A,R> BiConsumer<A, Gatherer.Downstream<? super R>>	defaultFinisher()	Returns a finisher which is the default finisher of a Gatherer.
static <A> Supplier<A>	defaultInitializer()	Returns an initializer which is the default initializer of a Gatherer.
default BiConsumer<A, Gatherer.Downstream<? super R>>	finisher()	A function which accepts the final intermediate state and a Gatherer.Downstream object, allowing to perform a final action at the end of input elements.
default Supplier<A>	initializer()	A function that produces an instance of the intermediate state used for this gathering operation.
Gatherer.Integrator<A,T,R>	integrator()	A function which integrates provided elements, potentially using the provided intermediate state, optionally producing output to the provided 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)	Returns a new, parallelizable, Gatherer described by the given initializer, integrator, combiner and finisher.
static <T,R> Gatherer<T,Void,R>	of(Gatherer.Integrator<Void,T,R> integrator)	Returns a new, parallelizable, and stateless Gatherer described by the given integrator.
static <T,R> Gatherer<T,Void,R>	of(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)	Returns a new, parallelizable, and stateless Gatherer described by the given integrator and finisher.
static <T,A,R> Gatherer<T,A,R>	ofSequential(Supplier<A> initializer, Gatherer.Integrator<A,T,R> integrator)	Returns a new, sequential, Gatherer described by the given initializer and 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)	Returns a new, sequential, Gatherer described by the given initializer, integrator, and finisher.
static <T,R> Gatherer<T,Void,R>	ofSequential(Gatherer.Integrator<Void,T,R> integrator)	Returns a new, sequential, and stateless Gatherer described by the given integrator.
static <T,R> Gatherer<T,Void,R>	ofSequential(Gatherer.Integrator<Void,T,R> integrator, BiConsumer<Void, Gatherer.Downstream<? super R>> finisher)	Returns a new, sequential, and stateless Gatherer described by the given integrator and finisher.

Method Details

initializer

default Supplier<A> initializer()

A function that produces an instance of the intermediate state used for this gathering operation.

Returns:

A function that produces an instance of the intermediate state used for this gathering operation

integrator

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

A function which integrates provided elements, potentially using the provided intermediate state, optionally producing output to the provided Gatherer.Downstream.

Returns:

a function which integrates provided elements, potentially using the provided state, optionally producing output to the provided Downstream

combiner

default BinaryOperator<A> combiner()

A function which accepts two intermediate states and combines them into one.

Returns:

a function which accepts two intermediate states and combines them into one

finisher

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

A function which accepts the final intermediate state and a Gatherer.Downstream object, allowing to perform a final action at the end of input elements.

Returns:

a function which transforms the intermediate result to the final result(s) which are then passed on to the provided Downstream

andThen

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

Returns a composed Gatherer which connects the output of this Gatherer to the input of that Gatherer.

Type Parameters:

RR - The type of output of that Gatherer

Parameters:

that - the other gatherer

Returns:

returns a composed Gatherer which connects the output of this Gatherer as input that Gatherer

Throws:

NullPointerException - if the argument is null

defaultInitializer

static <A> Supplier<A> defaultInitializer()

Returns an initializer which is the default initializer of a Gatherer. The returned initializer identifies that the owner Gatherer is stateless.

Type Parameters:

A - the type of the state of the returned initializer

Returns:

the instance of the default initializer

See Also:

• initializer()

defaultCombiner

static <A> BinaryOperator<A> defaultCombiner()

Returns a combiner which is the default combiner of a Gatherer. The returned combiner identifies that the owning Gatherer must only be evaluated sequentially.

Type Parameters:

A - the type of the state of the returned combiner

Returns:

the instance of the default combiner

See Also:

• combiner()

defaultFinisher

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

Returns a finisher which is the default finisher of a Gatherer. The returned finisher identifies that the owning Gatherer performs no additional actions at the end of input.

Type Parameters:

A - the type of the state of the returned finisher

R - the type of the Downstream of the returned finisher

Returns:

the instance of the default finisher

See Also:

• finisher()

ofSequential

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

Returns a new, sequential, and stateless Gatherer described by the given integrator.

Type Parameters:

T - the type of input elements for the new gatherer

R - the type of results for the new gatherer

Parameters:

integrator - the integrator function for the new gatherer

Returns:

the new Gatherer

Throws:

NullPointerException - if the argument is null

ofSequential

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

Returns a new, sequential, and stateless Gatherer described by the given integrator and finisher.

Type Parameters:

T - the type of input elements for the new gatherer

R - the type of results for the new gatherer

Parameters:

integrator - the integrator function for the new gatherer

finisher - the finisher function for the new gatherer

Returns:

the new Gatherer

Throws:

NullPointerException - if any argument is null

ofSequential

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

Returns a new, sequential, Gatherer described by the given initializer and integrator.

Type Parameters:

T - the type of input elements for the new gatherer

A - the type of state for the new gatherer

R - the type of results for the new gatherer

Parameters:

initializer - the initializer function for the new gatherer

integrator - the integrator function for the new gatherer

Returns:

the new Gatherer

Throws:

NullPointerException - if any argument is 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)

Returns a new, sequential, Gatherer described by the given initializer, integrator, and finisher.

Type Parameters:

T - the type of input elements for the new gatherer

A - the type of state for the new gatherer

R - the type of results for the new gatherer

Parameters:

initializer - the initializer function for the new gatherer

integrator - the integrator function for the new gatherer

finisher - the finisher function for the new gatherer

Returns:

the new Gatherer

Throws:

NullPointerException - if any argument is null

of

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

Returns a new, parallelizable, and stateless Gatherer described by the given integrator.

Type Parameters:

T - the type of input elements for the new gatherer

R - the type of results for the new gatherer

Parameters:

integrator - the integrator function for the new gatherer

Returns:

the new Gatherer

Throws:

NullPointerException - if any argument is null

of

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

Returns a new, parallelizable, and stateless Gatherer described by the given integrator and finisher.

Type Parameters:

T - the type of input elements for the new gatherer

R - the type of results for the new gatherer

Parameters:

integrator - the integrator function for the new gatherer

finisher - the finisher function for the new gatherer

Returns:

the new Gatherer

Throws:

NullPointerException - if any argument is 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)

Returns a new, parallelizable, Gatherer described by the given initializer, integrator, combiner and finisher.

Type Parameters:

T - the type of input elements for the new gatherer

A - the type of state for the new gatherer

R - the type of results for the new gatherer

Parameters:

initializer - the initializer function for the new gatherer

integrator - the integrator function for the new gatherer

combiner - the combiner function for the new gatherer

finisher - the finisher function for the new gatherer

Returns:

the new Gatherer

Throws:

NullPointerException - if any argument is null