Package play.libs.streams

Class 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 Detail

      • 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