Interface Streamer<T>

Type Parameters:

T - the element type.

public interface Streamer<@NonNull T>

A realized stream which can then be consumed asynchronously in steps. Think of it as the IAsyncEnumerator from C# ported to the clumsy Java world.

The Streamer methods must be invoked sequentially and non-overlappingly, similar to the Reactive Streams rule §1.3.

For an optimized synchronous operation, please consider using the NEXT_TRUE, NEXT_FALSE and FINISHED constant CompletionStages.

Since:

4.0.0

Field Summary

Fields

Modifier and Type	Field	Description
static final CompletableFuture<Void>	FINISHED	Use this constant in finish() to indicate the cleanup was done synchronously.
static final CompletableFuture<Boolean>	NEXT_FALSE	Use this constant in next() to indicate no more values will be available, synchronously.
static final CompletableFuture<Boolean>	NEXT_TRUE	Use this constant in next() to indicate the next value is available, synchronously.

Method Summary

Modifier and Type	Method	Description
static boolean	awaitBoolean(CompletionStage<Boolean> stage)	Convenience method to await the completion of a boolean stage, optimized for handling NEXT_TRUE and NEXT_FALSE directly.
default void	awaitFinish()	Convenience method to blockingly await the CompletionStage returned by the finish() method.
default boolean	awaitNext()	Convenience method to blockingly await the CompletionStage returned by the next() method.
static void	awaitVoid(CompletionStage<Void> stage)	Convenience method to await the completion of a stage, optimized for handling FINISHED directly.
T	current()	Returns the currently available item synchronously if the previous call to [#next()] yielded `true`.
@NonNull CompletionStage<Void>	finish()	Finish the sequence once all processing has been done to it either via exhaustion or via cancellation.
@NonNull CompletionStage<Boolean>	next()	Determine if there are more elements available from the source.

Field Details

NEXT_TRUE

static final CompletableFuture<Boolean> NEXT_TRUE

Use this constant in next() to indicate the next value is available, synchronously.

NEXT_FALSE

static final CompletableFuture<Boolean> NEXT_FALSE

Use this constant in next() to indicate no more values will be available, synchronously.

FINISHED

static final CompletableFuture<Void> FINISHED

Use this constant in finish() to indicate the cleanup was done synchronously.

Method Details

next

@NonNull
@NonNull CompletionStage<Boolean> next()

Determine if there are more elements available from the source.

Returns:

a `CompletionStage` with 3 outcomes

• `true` indicates there is an item available for consumption via current()
• `false` indicates there are no more items available
• `Throwable` indicates there was an upstream error

current

@NonNull
T current()

Returns the currently available item synchronously if the previous call to [#next()] yielded `true`. Calling it during an ongoing [#next()] or [#finish()] call, or beyond the lifecycle of the `Streamer` is an undefined behavior. It may yield `null` or throw.

Returns:

the current item

Throws:

NoSuchElementException - if there are no items to return

finish

@NonNull
@NonNull CompletionStage<Void> finish()

Finish the sequence once all processing has been done to it either via exhaustion or via cancellation.

Usually involves resource cleanup, so this method must be always called.

If the cleanup crashes and the [#next()] crashed too, the cleanup `Throwable` will be added as suppressed to the main crash `Throwable` from `next`.

Returns:

a `CompletionStage` that completes when the resource cleanup completes normally or exceptionally

awaitNext

default boolean awaitNext()

Convenience method to blockingly await the CompletionStage returned by the next() method.

Returns:

true if there are more items, false if no more items are coming, or crashes

awaitFinish

default void awaitFinish()

Convenience method to blockingly await the CompletionStage returned by the finish() method.

awaitBoolean

static boolean awaitBoolean(CompletionStage<Boolean> stage)

Convenience method to await the completion of a boolean stage, optimized for handling NEXT_TRUE and NEXT_FALSE directly.

Parameters:

stage - the stage to await

Returns:

the result of the stage

awaitVoid

static void awaitVoid(CompletionStage<Void> stage)

Convenience method to await the completion of a stage, optimized for handling FINISHED directly.

Parameters:

stage - the stage to await