Gatherer

public interface Gatherer

java.util.stream.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.

Summary

Nested classes

interface Gatherer.Downstream<T>

A Downstream object is the next stage in a pipeline of operations, to which elements can be sent. 

interface Gatherer.Integrator<A, T, R>

An Integrator receives elements and processes them, optionally using the supplied state, and optionally sends incremental results downstream. 

Public methods

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, 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, Downstream<? super R>> finisher()

A function which accepts the final intermediate state and a 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.

abstract Integrator<A, T, R> integrator()

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

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

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

static <T, A, R> Gatherer<T, A, R> of(Supplier<A> initializer, Integrator<A, T, R> integrator, BinaryOperator<A> combiner, BiConsumer<A, 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(Integrator<Void, T, R> integrator, BiConsumer<Void, 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, 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, Integrator<A, T, R> integrator, BiConsumer<A, 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(Integrator<Void, T, R> integrator, BiConsumer<Void, Downstream<? super R>> finisher)

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

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

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

Public methods

andThen

public 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.

Implementation Requirements:
  • The implementation in this interface returns a new Gatherer which is semantically equivalent to the combination of this and that gatherer.
Parameters
that Gatherer: the other gatherer
Returns
Gatherer<T, ?, RR> returns a composed Gatherer which connects the output of this Gatherer as input that Gatherer
Throws
NullPointerException if the argument is null

combiner

public BinaryOperator<A> combiner ()

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

Implementation Requirements:
Returns
BinaryOperator<A> a function which accepts two intermediate states and combines them into one

defaultCombiner

public static 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.

Implementation Requirements:
  • This method always returns the same instance.
Returns
BinaryOperator<A> the instance of the default combiner

See also:

defaultFinisher

public static BiConsumer<A, 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.

Implementation Requirements:
  • This method always returns the same instance.
Returns
BiConsumer<A, Downstream<? super R>> the instance of the default finisher

See also:

defaultInitializer

public static Supplier<A> defaultInitializer ()

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

Implementation Requirements:
  • This method always returns the same instance.
Returns
Supplier<A> the instance of the default initializer

See also:

finisher

public BiConsumer<A, Downstream<? super R>> finisher ()

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

Implementation Requirements:
Returns
BiConsumer<A, Downstream<? super R>> a function which transforms the intermediate result to the final result(s) which are then passed on to the provided Downstream

initializer

public Supplier<A> initializer ()

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

Implementation Requirements:
Returns
Supplier<A> A function that produces an instance of the intermediate state used for this gathering operation

integrator

public abstract Integrator<A, T, R> integrator ()

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

Returns
Integrator<A, T, R> a function which integrates provided elements, potentially using the provided state, optionally producing output to the provided Downstream

of

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

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

Parameters
integrator Integrator: the integrator function for the new gatherer
Returns
Gatherer<T, Void, R> the new Gatherer
Throws
NullPointerException if any argument is null

of

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

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

Parameters
initializer Supplier: the initializer function for the new gatherer
integrator Integrator: the integrator function for the new gatherer
combiner BinaryOperator: the combiner function for the new gatherer
finisher BiConsumer: the finisher function for the new gatherer
Returns
Gatherer<T, A, R> the new Gatherer
Throws
NullPointerException if any argument is null

of

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

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

Parameters
integrator Integrator: the integrator function for the new gatherer
finisher BiConsumer: the finisher function for the new gatherer
Returns
Gatherer<T, Void, R> the new Gatherer
Throws
NullPointerException if any argument is null

ofSequential

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

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

Parameters
initializer Supplier: the initializer function for the new gatherer
integrator Integrator: the integrator function for the new gatherer
Returns
Gatherer<T, A, R> the new Gatherer
Throws
NullPointerException if any argument is null

ofSequential

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

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

Parameters
initializer Supplier: the initializer function for the new gatherer
integrator Integrator: the integrator function for the new gatherer
finisher BiConsumer: the finisher function for the new gatherer
Returns
Gatherer<T, A, R> the new Gatherer
Throws
NullPointerException if any argument is null

ofSequential

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

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

Parameters
integrator Integrator: the integrator function for the new gatherer
finisher BiConsumer: the finisher function for the new gatherer
Returns
Gatherer<T, Void, R> the new Gatherer
Throws
NullPointerException if any argument is null

ofSequential

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

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

Parameters
integrator Integrator: the integrator function for the new gatherer
Returns
Gatherer<T, Void, R> the new Gatherer
Throws
NullPointerException if the argument is null