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 and 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 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

  • 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 and 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 directly.
      Parameters:
      stage - the stage to await