Package play.libs.streams

Class Accumulator<E,A>

java.lang.Object
play.libs.streams.Accumulator<E,A>
public abstract class Accumulator<E,A> extends Object
Accumulates inputs asynchronously into an output value.

An accumulator is a view over an Pekko streams Sink that materialises to a future, that is focused on the value of that future, rather than the Stream. This means methods such as map, recover and so on are provided for the eventually redeemed future value.

In order to be in line with the Java ecosystem, the future implementation that this uses for the materialised value of the Sink is java.util.concurrent.CompletionStage, and running this accumulator will yield a CompletionStage. The constructor allows an accumulator to be created from such a sink. Many methods in the Pekko streams API however materialise a scala.concurrent.Future, hence the fromSink method is provided to create an accumulator from a typical Pekko streams Sink.

  • Method Details

    • map

      public abstract <B> Accumulator<E,B> map(Function<? super A,? extends B> f, Executor executor)
      Map the accumulated value.
      Type Parameters:
      B - the mapped value type
      Parameters:
      f - The function to perform the map with.
      executor - The executor to run the function in.
      Returns:
      A new accumulator with the mapped value.

    • mapFuture

      public abstract <B> Accumulator<E,B> mapFuture(Function<? super A,? extends CompletionStage<B>> f, Executor executor)
      Map the accumulated value with a function that returns a future.
      Type Parameters:
      B - the mapped value type
      Parameters:
      f - The function to perform the map with.
      executor - The executor to run the function in.
      Returns:
      A new accumulator with the mapped value.

    • recover

      public abstract Accumulator<E,A> recover(Function<? super Throwable,? extends A> f, Executor executor)
      Recover from any errors encountered by the accumulator.
      Parameters:
      f - The function to use to recover from errors.
      executor - The executor to run the function in.
      Returns:
      A new accumulator that has recovered from errors.

    • recoverWith

      public abstract Accumulator<E,A> recoverWith(Function<? super Throwable,? extends CompletionStage<A>> f, Executor executor)
      Recover from any errors encountered by the accumulator.
      Parameters:
      f - The function to use to recover from errors.
      executor - The executor to run the function in.
      Returns:
      A new accumulator that has recovered from errors.

    • through

      public abstract <D> Accumulator<D,A> through(Flow<D,E,?> flow)
      Pass the stream through the given flow before forwarding it to the accumulator.
      Type Parameters:
      D - the "In" type for the flow parameter.
      Parameters:
      flow - The flow to send the stream through first.
      Returns:
      A new accumulator with the given flow in its graph.

    • run

      public abstract CompletionStage<A> run(Materializer mat)
      Run the accumulator with an empty source.
      Parameters:
      mat - The flow materializer.
      Returns:
      A future that will be redeemed when the accumulator is done.

    • run

      public abstract CompletionStage<A> run(Source<E,?> source, Materializer mat)
      Run the accumulator with the given source.
      Parameters:
      source - The source to feed into the accumulator.
      mat - The flow materializer.
      Returns:
      A future that will be redeemed when the accumulator is done.

    • run

      public abstract CompletionStage<A> run(E element, Materializer mat)
      Run the accumulator with a single element.
      Parameters:
      element - The element to feed into the accumulator.
      mat - The flow materializer.
      Returns:
      A future that will be redeemed when the accumulator is done.

    • toSink

      public abstract Sink<E,CompletionStage<A>> toSink()
      Convert this accumulator to a sink.
      Returns:
      The sink.

    • asScala

      public abstract play.api.libs.streams.Accumulator<E,A> asScala()
      Convert this accumulator to a Scala accumulator.
      Returns:
      The Scala Accumulator.

    • fromSink

      public static <E, A> Accumulator<E,A> fromSink(Sink<E,CompletionStage<A>> sink)
      Create an accumulator from an Pekko streams sink.
      Type Parameters:
      E - the "in" type of the sink parameter.
      A - the materialized result of the accumulator.
      Parameters:
      sink - The sink.
      Returns:
      An accumulator created from the sink.

    • source

      public static <E> Accumulator<E,Source<E,?>> source()
      Create an accumulator that forwards the stream fed into it to the source it produces.

      This is useful for when you want to send the consumed stream to another API that takes a Source as input.

      Extreme care must be taken when using this accumulator - the source *must always* be materialized and consumed. If it isn't, this could lead to resource leaks and deadlocks upstream.

      Type Parameters:
      E - the "in" type of the parameter.
      Returns:
      An accumulator that forwards the stream to the produced source.

    • done

      public static <E, A> Accumulator<E,A> done(A a)
      Create a done accumulator with the given value.
      Type Parameters:
      E - the "in" type of the parameter.
      A - the materialized result of the accumulator.
      Parameters:
      a - The done value for the accumulator.
      Returns:
      The accumulator.

    • done

      public static <E, A> Accumulator<E,A> done(CompletionStage<A> a)
      Create a done accumulator with the given future.
      Type Parameters:
      E - the "in" type of the parameter.
      A - the materialized result of the accumulator.
      Parameters:
      a - A future of the done value.
      Returns:
      The accumulator.

    • strict

      public static <E, A> Accumulator<E,A> strict(Function<Optional<E>,CompletionStage<A>> strictHandler, Sink<E,CompletionStage<A>> toSink)
      Create a done accumulator with the given future.
      Type Parameters:
      E - the "in" type of the parameter.
      A - the materialized result of the accumulator.
      Parameters:
      strictHandler - the handler to handle the stream if it can be expressed as a single element.
      toSink - The sink representation of this accumulator, in case the stream can't be expressed as a single element.
      Returns:
      The accumulator.

    • flatten

      public static <E, A> Accumulator<E,A> flatten(CompletionStage<Accumulator<E,A>> stage, Materializer materializer)
      Flatten a completion stage of an accumulator to an accumulator.
      Type Parameters:
      E - the "in" type of the parameter.
      A - the materialized result of the accumulator.
      Parameters:
      stage - the CompletionStage (asynchronous) accumulator
      materializer - the stream materializer
      Returns:
      The accumulator using the given completion stage