Package org.apache.pekko.stream.javadsl

Class Flow<In,Out,Mat>

java.lang.Object

org.apache.pekko.stream.javadsl.Flow<In,Out,Mat>

All Implemented Interfaces:

Graph<FlowShape<In,Out>,Mat>

public final class Flow<In,Out,Mat>
extends Object
implements Graph<FlowShape<In,Out>,Mat>

A Flow is a set of stream processing steps that has one open input and one open output.

Nested Class Summary

Nested classes/interfaces inherited from interface org.apache.pekko.stream.Graph

Graph.GraphMapMatVal<S extends Shape,M>

Constructor Summary

Constructors

Constructor	Description
Flow(Flow<In,Out,Mat> delegate)

Method Summary

Modifier and Type	Method	Description
Flow<In,Out,Mat>	addAttributes(Attributes attr)	Add the given attributes to this Flow.
<Agg, Emit> Flow<In,Emit,Mat>	aggregateWithBoundary(Creator<Agg> allocate, Function2<Agg,Out,Pair<Agg,Object>> aggregate, Function<Agg,Emit> harvest, Optional<Pair<Predicate<Agg>,Duration>> emitOnTimer)	Aggregate input elements into an arbitrary data structure that can be completed and emitted downstream when custom condition is met which can be triggered by aggregate or timer.
<Agg, Emit> Flow<In,Emit,Mat>	aggregateWithBoundary(Creator<Agg> allocate, Function2<Agg,Out,Pair<Agg,Object>> aggregate, Function<Agg,Emit> harvest, Pair<Predicate<Agg>,Duration> emitOnTimer)	Deprecated. Use the overloaded one which accepts an Optional instead.
Flow<In,Out,Mat>	alsoTo(Graph<SinkShape<Out>,?> that)	Attaches the given Sink to this Flow, meaning that elements that passes through will also be sent to the Sink.
Flow<In,Out,Mat>	alsoToAll(Graph<SinkShape<Out>,?>... those)	Attaches the given Sinks to this Flow, meaning that elements that passes through will also be sent to all those Sinks.
Flow<In,Out,Mat>	alsoToAll(scala.collection.immutable.Seq<Graph<SinkShape<Out>,?>> those)	Attaches the given Sinks to this Flow, meaning that elements that passes through will also be sent to all those Sinks.
<M2, M3> Flow<In,Out,M3>	alsoToMat(Graph<SinkShape<Out>,M2> that, Function2<Mat,M2,M3> matF)	Attaches the given Sink to this Flow, meaning that elements that passes through will also be sent to the Sink.
<U, CtxU, CtxOut> FlowWithContext<U,CtxU,Out,CtxOut,Mat>	asFlowWithContext(Function2<U,CtxU,In> collapseContext, Function<Out,CtxOut> extractContext)	Turns a Flow into a FlowWithContext which manages a context per element along a stream.
<S> Flow<In,S,Mat>	ask(int parallelism, ActorRef ref, Class<S> mapTo, Timeout timeout)	Use the ask pattern to send a request-reply message to the target ref actor.
<S> Flow<In,S,Mat>	ask(ActorRef ref, Class<S> mapTo, Timeout timeout)	Use the ask pattern to send a request-reply message to the target ref actor.
Flow<In,Out,Mat>	asScala()	Converts this Flow to its Scala DSL counterpart
Flow<In,Out,Mat>	async()	Put an asynchronous boundary around this Flow
Flow<In,Out,Mat>	async(String dispatcher)	Put an asynchronous boundary around this Flow
Flow<In,Out,Mat>	async(String dispatcher, int inputBufferSize)	Put an asynchronous boundary around this Flow
Flow<In,Out,Mat>	backpressureTimeout(Duration timeout)	If the time between the emission of an element and the following downstream demand exceeds the provided timeout, the stream is failed with a BackpressureTimeoutException.
<S> Flow<In,S,Mat>	batch(long max, Function<Out,S> seed, Function2<S,Out,S> aggregate)	Allows a faster upstream to progress independently of a slower subscriber by aggregating elements into batches until the subscriber is ready to accept them.
<S> Flow<In,S,Mat>	batchWeighted(long max, Function<Out,Long> costFn, Function<Out,S> seed, Function2<S,Out,S> aggregate)	Allows a faster upstream to progress independently of a slower subscriber by aggregating elements into batches until the subscriber is ready to accept them.
Flow<In,Out,Mat>	buffer(int size, OverflowStrategy overflowStrategy)	Adds a fixed size buffer in the flow that allows to store elements from a faster upstream until it becomes full.
<T> Flow<In,T,Mat>	collect(scala.PartialFunction<Out,T> pf)	Transform this stream by applying the given partial function to each of the elements on which the function is defined as they pass through this processing step.
<T> Flow<In,T,Mat>	collectFirst(scala.PartialFunction<Out,T> pf)	Transform this stream by applying the given partial function to the first element on which the function is defined as it pass through this processing step, and cancel the upstream publisher after the first element is emitted.
<T> Flow<In,T,Mat>	collectType(Class<T> clazz)	Transform this stream by testing the type of each of the elements on which the element is an instance of the provided type as they pass through this processing step.
<T> Flow<In,T,Mat>	collectWhile(scala.PartialFunction<Out,T> pf)	Transform this stream by applying the given partial function to each of the elements on which the function is defined as they pass through this processing step, and cancel the upstream publisher after the partial function is not applied.
static <I, O, M> Flow<I,O,CompletionStage<M>>	completionStageFlow(CompletionStage<Flow<I,O,M>> flow)	Turn a CompletionStage into a flow that will consume the values of the source when the future completes successfully.
Flow<In,Out,Mat>	completionTimeout(Duration timeout)	If the completion of the stream does not happen until the provided timeout, the stream is failed with a CompletionTimeoutException.
<M> Flow<In,Out,Mat>	concat(Graph<SourceShape<Out>,M> that)	Concatenate the given Source to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.
Flow<In,Out,Mat>	concatAllLazy(Graph<SourceShape<Out>,?>... those)	Concatenate the given Sources to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.
Flow<In,Out,Mat>	concatAllLazy(scala.collection.immutable.Seq<Graph<SourceShape<Out>,?>> those)	Concatenate the given Sources to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.
<M> Flow<In,Out,Mat>	concatLazy(Graph<SourceShape<Out>,M> that)	Concatenate the given Source to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.
<M, M2> Flow<In,Out,M2>	concatLazyMat(Graph<SourceShape<Out>,M> that, Function2<Mat,M,M2> matF)	Concatenate the given Source to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.
<M, M2> Flow<In,Out,M2>	concatMat(Graph<SourceShape<Out>,M> that, Function2<Mat,M,M2> matF)	Concatenate the given Source to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.
Flow<In,Out,Mat>	conflate(Function2<Out,Out,Out> aggregate)	Allows a faster upstream to progress independently of a slower subscriber by conflating elements into a summary until the subscriber is ready to accept them.
<S> Flow<In,S,Mat>	conflateWithSeed(Function<Out,S> seed, Function2<S,Out,S> aggregate)	Allows a faster upstream to progress independently of a slower subscriber by conflating elements into a summary until the subscriber is ready to accept them.
<In2> Flow<In2,Out,Mat>	contramap(Function<In2,In> f)	Transform this Flow by applying a function to each *incoming* upstream element before it is passed to the Flow
static <T> Flow<T,T,NotUsed>	create()	Create a `Flow` which can process elements of type `T`.
Flow<In,Out,Mat>	delay(Duration of, DelayOverflowStrategy strategy)	Shifts elements emission in time by a specified amount.
Flow<In,Out,Mat>	delayWith(Creator<DelayStrategy<Out>> delayStrategyCreator, DelayOverflowStrategy overFlowStrategy)	Shifts elements emission in time by an amount individually determined through delay strategy a specified amount.
Flow<In,Out,Mat>	detach()	Detaches upstream demand from downstream demand without detaching the stream rates; in other words acts like a buffer of size 1.
<In2, Out2> Flow<In2,Out2,Mat>	dimap(Function<In2,In> f, Function<Out,Out2> g)	Transform this Flow by applying a function f to each *incoming* upstream element before it is passed to the Flow, and a function g to each *outgoing* downstream element.
Flow<In,Out,Mat>	divertTo(Graph<SinkShape<Out>,?> that, Predicate<Out> when)	Attaches the given Sink to this Flow, meaning that elements will be sent to the Sink instead of being passed through if the predicate when returns true.
<M2, M3> Flow<In,Out,M3>	divertToMat(Graph<SinkShape<Out>,M2> that, Predicate<Out> when, Function2<Mat,M2,M3> matF)	Attaches the given Sink to this Flow, meaning that elements will be sent to the Sink instead of being passed through if the predicate when returns true.
Flow<In,Out,Mat>	doOnCancel(Procedure2<? super Throwable,Boolean> f)	Run the given function when the downstream cancels.
Flow<In,Out,Mat>	doOnFirst(Procedure<Out> f)	Run the given function when the first element is received.
Flow<In,Out,Mat>	drop(long n)	Discard the given number of elements at the beginning of the stream.
Flow<In,Out,Mat>	dropRepeated()	Only pass on those elements that are distinct from the previous element.
Flow<In,Out,Mat>	dropRepeated(Function2<Out,Out,Object> p)	Only pass on those elements that are distinct from the previous element according to the given predicate.
Flow<In,Out,Mat>	dropWhile(Predicate<Out> p)	Discard elements at the beginning of the stream while predicate is true.
Flow<In,Out,Mat>	dropWithin(Duration duration)	Discard the elements received within the given duration at beginning of the stream.
<U> Flow<In,U,Mat>	expand(Function<Out,Iterator<U>> expander)	Allows a faster downstream to progress independently of a slower upstream by extrapolating elements from an older element until new element comes from the upstream.
Flow<In,Out,Mat>	extrapolate(Function<Out,Iterator<Out>> extrapolator)	Allows a faster downstream to progress independent of a slower upstream.
Flow<In,Out,Mat>	extrapolate(Function<Out,Iterator<Out>> extrapolator, Out initial)	Allows a faster downstream to progress independent of a slower upstream.
Flow<In,Out,Mat>	filter(Predicate<Out> p)	Only pass on those elements that satisfy the given predicate.
Flow<In,Out,Mat>	filterNot(Predicate<Out> p)	Only pass on those elements that NOT satisfy the given predicate.
<T, M> Flow<In,T,Mat>	flatMapConcat(int parallelism, Function<Out,? extends Graph<SourceShape<T>,M>> f)	Transform each input element into a Source of output elements that is then flattened into the output stream by concatenation, fully consuming one Source after the other.
<T, M> Flow<In,T,Mat>	flatMapConcat(Function<Out,? extends Graph<SourceShape<T>,M>> f)	Transform each input element into a Source of output elements that is then flattened into the output stream by concatenation, fully consuming one Source after the other.
<T, M> Flow<In,T,Mat>	flatMapMerge(int breadth, Function<Out,? extends Graph<SourceShape<T>,M>> f)	Transform each input element into a Source of output elements that is then flattened into the output stream by merging, where at most breadth substreams are being consumed at any given time.
<Out2, Mat2> Flow<In,Out2,Mat>	flatMapPrefix(int n, Function<List<Out>,Flow<Out,Out2,Mat2>> f)	Takes up to n elements from the stream (less than n only if the upstream completes before emitting n elements), then apply f on these elements in order to obtain a flow, this flow is then materialized and the rest of the input is processed by this flow (similar to via).
<Out2, Mat2, Mat3> Flow<In,Out2,Mat3>	flatMapPrefixMat(int n, Function<List<Out>,Flow<Out,Out2,Mat2>> f, Function2<Mat,CompletionStage<Mat2>,Mat3> matF)	mat version of flatMapPrefix(int, org.apache.pekko.japi.function.Function<java.util.List<Out>, org.apache.pekko.stream.javadsl.Flow<Out, Out2, Mat2>>), this method gives access to a future materialized value of the downstream flow (as a completion stage).
static <Out, In extends Optional<Out>> Flow<In,Out,NotUsed>	flattenOptional()	Collect the value of Optional from the elements passing through this flow, empty Optional is filtered out.
<T> Flow<In,T,Mat>	fold(T zero, Function2<T,Out,T> f)	Similar to scan but only emits its result when the upstream completes, after which it also completes.
<T> Flow<In,T,Mat>	foldAsync(T zero, Function2<T,Out,CompletionStage<T>> f)	Similar to fold but with an asynchronous function.
<T> Flow<In,T,Mat>	foldWhile(T zero, Predicate<T> p, Function2<T,Out,T> f)	Similar to scan but only emits its result when the upstream completes or the predicate p returns false.
static <I, O> Flow<I,O,NotUsed>	fromFunction(Function<I,O> f)	Creates a [Flow] which will use the given function to transform its inputs to outputs.
static <I, O, M> Flow<I,O,M>	fromGraph(Graph<FlowShape<I,O>,M> g)	A graph with the shape of a flow logically is a flow, this method makes it so also in type.
static <I, O, M> Flow<I,O,CompletionStage<M>>	fromMaterializer(Function2<Materializer,Attributes,Flow<I,O,M>> factory)	Defers the creation of a Flow until materialization.
static <I, O> Flow<I,O,NotUsed>	fromProcessor(Creator<org.reactivestreams.Processor<I,O>> processorFactory)
static <I, O, Mat> Flow<I,O,Mat>	fromProcessorMat(Creator<Pair<org.reactivestreams.Processor<I,O>,Mat>> processorFactory)
static <I, O> Flow<I,O,NotUsed>	fromSinkAndSource(Graph<SinkShape<I>,?> sink, Graph<SourceShape<O>,?> source)	Creates a Flow from a Sink and a Source where the Flow's input will be sent to the Sink and the Flow's output will come from the Source.
static <I, O> Flow<I,O,NotUsed>	fromSinkAndSourceCoupled(Graph<SinkShape<I>,?> sink, Graph<SourceShape<O>,?> source)	Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow from them.
static <I, O, M1, M2, M> Flow<I,O,M>	fromSinkAndSourceCoupledMat(Graph<SinkShape<I>,M1> sink, Graph<SourceShape<O>,M2> source, Function2<M1,M2,M> combine)	Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow from them.
static <I, O, M1, M2, M> Flow<I,O,M>	fromSinkAndSourceMat(Graph<SinkShape<I>,M1> sink, Graph<SourceShape<O>,M2> source, Function2<M1,M2,M> combine)	Creates a Flow from a Sink and a Source where the Flow's input will be sent to the Sink and the Flow's output will come from the Source.
Attributes	getAttributes()
<K> SubFlow<In,Out,Mat>	groupBy(int maxSubstreams, Function<Out,K> f)	This operation demultiplexes the incoming stream into separate output streams, one for each element key.
<K> SubFlow<In,Out,Mat>	groupBy(int maxSubstreams, Function<Out,K> f, boolean allowClosedSubstreamRecreation)	This operation demultiplexes the incoming stream into separate output streams, one for each element key.
Flow<In,List<Out>,Mat>	grouped(int n)	Chunk up this stream into groups of the given size, with the last group possibly smaller than requested due to end-of-stream.
<R> Flow<In,List<Out>,Mat>	groupedAdjacentBy(Function<Out,R> f)	Partitions this stream into chunks by a delimiter function, which is applied to each incoming element, when the result of the function is not the same as the previous element's result, a chunk is emitted.
<R> Flow<In,List<Out>,Mat>	groupedAdjacentByWeighted(Function<Out,R> f, long maxWeight, Function<Out,Long> costFn)	Partitions this stream into chunks by a delimiter function, which is applied to each incoming element, when the result of the function is not the same as the previous element's result, or the accumulated weight exceeds the maxWeight, a chunk is emitted.
Flow<In,List<Out>,Mat>	groupedWeighted(long minWeight, Function<Out,Long> costFn)	Chunk up this stream into groups of elements that have a cumulative weight greater than or equal to the minWeight, with the last group possibly smaller than requested minWeight due to end-of-stream.
Flow<In,List<Out>,Mat>	groupedWeightedWithin(long maxWeight, int maxNumber, Function<Out,Long> costFn, Duration duration)	Chunk up this stream into groups of elements received within a time window, or limited by the weight and number of the elements, whatever happens first.
Flow<In,List<Out>,Mat>	groupedWeightedWithin(long maxWeight, Function<Out,Long> costFn, Duration duration)	Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements, whatever happens first.
Flow<In,List<Out>,Mat>	groupedWithin(int maxNumber, Duration duration)	Chunk up this stream into groups of elements received within a time window, or limited by the given number of elements, whatever happens first.
Flow<In,Out,Mat>	idleTimeout(Duration timeout)	If the time between two processed elements exceeds the provided timeout, the stream is failed with a StreamIdleTimeoutException.
Flow<In,Out,Mat>	initialDelay(Duration delay)	Delays the initial element by the specified duration.
Flow<In,Out,Mat>	initialTimeout(Duration timeout)	If the first element has not passed through this operator before the provided timeout, the stream is failed with a InitialTimeoutException.
Flow<In,Out,Mat>	interleave(Graph<SourceShape<Out>,?> that, int segmentSize)	Interleave is a deterministic merge of the given Source with elements of this Flow.
Flow<In,Out,Mat>	interleave(Graph<SourceShape<Out>,?> that, int segmentSize, boolean eagerClose)	Interleave is a deterministic merge of the given Source with elements of this Flow.
Flow<In,Out,Mat>	interleaveAll(List<? extends Graph<SourceShape<Out>,?>> those, int segmentSize, boolean eagerClose)	Interleave is a deterministic merge of the given Sources with elements of this Flow.
<M, M2> Flow<In,Out,M2>	interleaveMat(Graph<SourceShape<Out>,M> that, int segmentSize, boolean eagerClose, Function2<Mat,M,M2> matF)	Interleave is a deterministic merge of the given Source with elements of this Flow.
<M, M2> Flow<In,Out,M2>	interleaveMat(Graph<SourceShape<Out>,M> that, int segmentSize, Function2<Mat,M,M2> matF)	Interleave is a deterministic merge of the given Source with elements of this Flow.
Flow<In,Out,Mat>	intersperse(Out inject)	Intersperses stream with provided element, similar to how scala.collection.immutable.List.mkString injects a separator between a List's elements.
Flow<In,Out,Mat>	intersperse(Out start, Out inject, Out end)	Intersperses stream with provided element, similar to how scala.collection.immutable.List.mkString injects a separator between a List's elements.
<I2, O1, Mat2> Flow<I2,O1,Mat>	join(Graph<BidiShape<Out,O1,I2,In>,Mat2> bidi)	Join this Flow to a BidiFlow to close off the &ldquo;top&rdquo; of the protocol stack:
<M> RunnableGraph<Mat>	join(Graph<FlowShape<Out,In>,M> flow)	Join this Flow to another Flow, by cross connecting the inputs and outputs, creating a RunnableGraph.
<I2, O1, Mat2, M> Flow<I2,O1,M>	joinMat(Graph<BidiShape<Out,O1,I2,In>,Mat2> bidi, Function2<Mat,Mat2,M> combine)	Join this Flow to a BidiFlow to close off the &ldquo;top&rdquo; of the protocol stack:
<M, M2> RunnableGraph<M2>	joinMat(Graph<FlowShape<Out,In>,M> flow, Function2<Mat,M,M2> combine)	Join this Flow to another Flow, by cross connecting the inputs and outputs, creating a RunnableGraph
Flow<In,Out,Mat>	keepAlive(Duration maxIdle, Creator<Out> injectedElem)	Injects additional elements if upstream does not emit for a configured amount of time.
static <I, O, M> Flow<I,O,CompletionStage<M>>	lazyCompletionStageFlow(Creator<CompletionStage<Flow<I,O,M>>> create)	Defers invoking the create function to create a future flow until there downstream demand has caused upstream to send a first element.
static <I, O, M> Flow<I,O,CompletionStage<M>>	lazyFlow(Creator<Flow<I,O,M>> create)	Defers invoking the create function to create a future flow until there is downstream demand and passing that downstream demand upstream triggers the first element.
Flow<In,Out,Mat>	limit(long n)	Ensure stream boundedness by limiting the number of elements from upstream.
Flow<In,Out,Mat>	limitWeighted(long n, Function<Out,Long> costFn)	Ensure stream boundedness by evaluating the cost of incoming elements using a cost function.
Flow<In,Out,Mat>	log(String name)	Logs elements flowing through the stream as well as completion and erroring.
Flow<In,Out,Mat>	log(String name, LoggingAdapter log)	Logs elements flowing through the stream as well as completion and erroring.
Flow<In,Out,Mat>	log(String name, Function<Out,Object> extract)	Logs elements flowing through the stream as well as completion and erroring.
Flow<In,Out,Mat>	log(String name, Function<Out,Object> extract, LoggingAdapter log)	Logs elements flowing through the stream as well as completion and erroring.
Flow<In,Out,Mat>	logWithMarker(String name, Function<Out,LogMarker> marker)	Logs elements flowing through the stream as well as completion and erroring.
Flow<In,Out,Mat>	logWithMarker(String name, Function<Out,LogMarker> marker, MarkerLoggingAdapter log)	Logs elements flowing through the stream as well as completion and erroring.
Flow<In,Out,Mat>	logWithMarker(String name, Function<Out,LogMarker> marker, Function<Out,Object> extract)	Logs elements flowing through the stream as well as completion and erroring.
Flow<In,Out,Mat>	logWithMarker(String name, Function<Out,LogMarker> marker, Function<Out,Object> extract, MarkerLoggingAdapter log)	Logs elements flowing through the stream as well as completion and erroring.
<T> Flow<In,T,Mat>	map(Function<Out,T> f)	Transform this stream by applying the given function to each of the elements as they pass through this processing step.
<T> Flow<In,T,Mat>	mapAsync(int parallelism, Function<Out,CompletionStage<T>> f)	Transform this stream by applying the given function to each of the elements as they pass through this processing step.
<T, P> Flow<In,T,Mat>	mapAsyncPartitioned(int parallelism, Function<Out,P> partitioner, Function2<Out,P,CompletionStage<T>> f)	Transforms this stream.
<T, P> Flow<In,T,Mat>	mapAsyncPartitionedUnordered(int parallelism, Function<Out,P> partitioner, Function2<Out,P,CompletionStage<T>> f)	Transforms this stream.
<T> Flow<In,T,Mat>	mapAsyncUnordered(int parallelism, Function<Out,CompletionStage<T>> f)	Transform this stream by applying the given function to each of the elements as they pass through this processing step.
<T> Flow<In,T,Mat>	mapConcat(Function<Out,Iterable<T>> f)	Transform each input element into an Iterable of output elements that is then flattened into the output stream.
<E extends Throwable> Flow<In,Out,Mat>	mapError(Class<E> clazz, Function<E,Throwable> f)	While similar to recover(scala.PartialFunction<java.lang.Throwable,Out>) this operator can be used to transform an error signal to a different one *without* logging it as an error in the process.
Flow<In,Out,Mat>	mapError(scala.PartialFunction<Throwable,Throwable> pf)	While similar to recover(scala.PartialFunction<java.lang.Throwable,Out>) this operator can be used to transform an error signal to a different one *without* logging it as an error in the process.
<Mat2> Flow<In,Out,Mat2>	mapMaterializedValue(Function<Mat,Mat2> f)	Transform only the materialized value of this Flow, leaving all other properties as they were.
<R extends AutoCloseable, T> Flow<In,T,Mat>	mapWithResource(Creator<R> create, Function2<R,Out,T> f)	Transform each stream element with the help of an AutoCloseable resource and close it when the stream finishes or fails.
<R, T> Flow<In,T,Mat>	mapWithResource(Creator<R> create, Function2<R,Out,T> f, Function<R,Optional<T>> close)	Transform each stream element with the help of a resource.
<Mat1, Mat2> Source<Mat2,CompletionStage<NotUsed>>	materializeIntoSource(Graph<SourceShape<In>,Mat1> source, Graph<SinkShape<Out>,CompletionStage<Mat2>> sink)	Connects the Source to this Flow and materializes it using the Sink, immediately returning the values via the provided Sink as a new Source.
Flow<In,Out,Mat>	merge(Graph<SourceShape<Out>,?> that)	Merge the given Source to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.
Flow<In,Out,Mat>	merge(Graph<SourceShape<Out>,?> that, boolean eagerComplete)	Merge the given Source to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.
Flow<In,Out,Mat>	mergeAll(List<? extends Graph<SourceShape<Out>,?>> those, boolean eagerComplete)	Merge the given Sources to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.
Flow<In,List<Out>,Mat>	mergeLatest(Graph<SourceShape<Out>,?> that, boolean eagerComplete)	MergeLatest joins elements from N input streams into stream of lists of size N.
<Mat2, Mat3> Flow<In,List<Out>,Mat3>	mergeLatestMat(Graph<SourceShape<Out>,Mat2> that, boolean eagerComplete, Function2<Mat,Mat2,Mat3> matF)	MergeLatest joins elements from N input streams into stream of lists of size N.
<M, M2> Flow<In,Out,M2>	mergeMat(Graph<SourceShape<Out>,M> that, Function2<Mat,M,M2> matF)	Merge the given Source to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.
<M, M2> Flow<In,Out,M2>	mergeMat(Graph<SourceShape<Out>,M> that, Function2<Mat,M,M2> matF, boolean eagerComplete)	Merge the given Source to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.
Flow<In,Out,Mat>	mergePreferred(Graph<SourceShape<Out>,?> that, boolean preferred, boolean eagerComplete)	Merge two sources.
<Mat2, Mat3> Flow<In,Out,Mat3>	mergePreferredMat(Graph<SourceShape<Out>,Mat2> that, boolean preferred, boolean eagerComplete, Function2<Mat,Mat2,Mat3> matF)	Merge two sources.
Flow<In,Out,Mat>	mergePrioritized(Graph<SourceShape<Out>,?> that, int leftPriority, int rightPriority, boolean eagerComplete)	Merge two sources.
<Mat2, Mat3> Flow<In,Out,Mat3>	mergePrioritizedMat(Graph<SourceShape<Out>,Mat2> that, int leftPriority, int rightPriority, boolean eagerComplete, Function2<Mat,Mat2,Mat3> matF)	Merge two sources.
<M> Flow<In,Out,Mat>	mergeSorted(Graph<SourceShape<Out>,M> that, Comparator<Out> comp)	Merge the given Source to this Flow, taking elements as they arrive from input streams, picking always the smallest of the available elements (waiting for one element from each side to be available).
<Mat2, Mat3> Flow<In,Out,Mat3>	mergeSortedMat(Graph<SourceShape<Out>,Mat2> that, Comparator<Out> comp, Function2<Mat,Mat2,Mat3> matF)	Merge the given Source to this Flow, taking elements as they arrive from input streams, picking always the smallest of the available elements (waiting for one element from each side to be available).
Flow<In,Out,Pair<Mat,FlowMonitor<Out>>>	monitor()	Materializes to Pair<Mat, FlowMonitor<>, which is unlike most other operators (!), in which usually the default materialized value keeping semantics is to keep the left value (by passing Keep.left() to a *Mat version of a method).
<M> Flow<In,Out,M>	monitorMat(Function2<Mat,FlowMonitor<Out>,M> combine)	Materializes to FlowMonitor[Out] that allows monitoring of the current flow.
Flow<In,Out,Mat>	named(String name)	Add a name attribute to this Flow.
static <T> Flow<T,T,NotUsed>	of(Class<T> clazz)	Create a `Flow` which can process elements of type `T`.
Flow<In,Out,Mat>	onErrorComplete()	onErrorComplete allows to complete the stream when an upstream error occurs.
Flow<In,Out,Mat>	onErrorComplete(Class<? extends Throwable> clazz)	onErrorComplete allows to complete the stream when an upstream error occurs.
Flow<In,Out,Mat>	onErrorComplete(Predicate<? super Throwable> predicate)	onErrorComplete allows to complete the stream when an upstream error occurs.
<T extends Throwable> Flow<In,Out,Mat>	onErrorContinue(Class<T> clazz, Procedure<? super Throwable> errorConsumer)	Continues the stream when an upstream error occurs.
<T extends Throwable> Flow<In,Out,Mat>	onErrorContinue(Predicate<? super Throwable> predicate, Procedure<? super Throwable> errorConsumer)	Continues the stream when an upstream error occurs.
Flow<In,Out,Mat>	onErrorContinue(Procedure<? super Throwable> errorConsumer)	Continues the stream when an upstream error occurs.
<T> Flow<In,T,Mat>	onErrorResume(Class<? extends Throwable> clazz, Function<? super Throwable,? extends Graph<SourceShape<T>,NotUsed>> fallback)	Transform a failure signal into a stream of elements provided by a factory function.
<T> Flow<In,T,Mat>	onErrorResume(Function<? super Throwable,? extends Graph<SourceShape<T>,NotUsed>> fallback)	Transform a failure signal into a stream of elements provided by a factory function.
<T> Flow<In,T,Mat>	onErrorResume(Predicate<? super Throwable> predicate, Function<? super Throwable,? extends Graph<SourceShape<T>,NotUsed>> fallback)	Transform a failure signal into a stream of elements provided by a factory function.
static <FIn, FOut, FViaOut, FMat, FViaMat, Mat> Flow<FIn,Optional<FViaOut>,Mat>	optionalVia(Flow<FIn,Optional<FOut>,FMat> flow, Flow<FOut,FViaOut,FViaMat> viaFlow, Function2<FMat,FViaMat,Mat> combine)	Creates a Flow from an existing base Flow outputting an optional element and applying an additional viaFlow only if the element in the stream is defined.
<M> Flow<In,Out,Mat>	orElse(Graph<SourceShape<Out>,M> secondary)	Provides a secondary source that will be consumed if this source completes without any elements passing by.
<M2, M3> Flow<In,Out,M3>	orElseMat(Graph<SourceShape<Out>,M2> secondary, Function2<Mat,M2,M3> matF)	Provides a secondary source that will be consumed if this source completes without any elements passing by.
Flow<In,Pair<List<Out>,Source<Out,NotUsed>>,Mat>	prefixAndTail(int n)	Takes up to n elements from the stream (less than n if the upstream completes before emitting n elements) and returns a pair containing a strict sequence of the taken element and a stream representing the remaining elements.
Pair<Mat,Flow<In,Out,NotUsed>>	preMaterialize(ClassicActorSystemProvider systemProvider)	Materializes this Flow, immediately returning (1) its materialized value, and (2) a newly materialized Flow.
Pair<Mat,Flow<In,Out,NotUsed>>	preMaterialize(Materializer materializer)	Materializes this Flow, immediately returning (1) its materialized value, and (2) a newly materialized Flow.
<M> Flow<In,Out,Mat>	prepend(Graph<SourceShape<Out>,M> that)	Prepend the given Source to this Flow, meaning that before elements are generated from this Flow, the Source's elements will be produced until it is exhausted, at which point Flow elements will start being produced.
<M> Flow<In,Out,Mat>	prependLazy(Graph<SourceShape<Out>,M> that)	Prepend the given Source to this Flow, meaning that before elements are generated from this Flow, the Source's elements will be produced until it is exhausted, at which point Flow elements will start being produced.
<M, M2> Flow<In,Out,M2>	prependLazyMat(Graph<SourceShape<Out>,M> that, Function2<Mat,M,M2> matF)	Prepend the given Source to this Flow, meaning that before elements are generated from this Flow, the Source's elements will be produced until it is exhausted, at which point Flow elements will start being produced.
<M, M2> Flow<In,Out,M2>	prependMat(Graph<SourceShape<Out>,M> that, Function2<Mat,M,M2> matF)	Prepend the given Source to this Flow, meaning that before elements are generated from this Flow, the Source's elements will be produced until it is exhausted, at which point Flow elements will start being produced.
Flow<In,Out,Mat>	recover(Class<? extends Throwable> clazz, Creator<Out> creator)	Recover allows to send last element on failure and gracefully complete the stream.
Flow<In,Out,Mat>	recover(Class<? extends Throwable> clazz, Out fallbackValue)	Recover allows to send last element on failure and gracefully complete the stream.
Flow<In,Out,Mat>	recover(Predicate<? super Throwable> p, Creator<Out> creator)	Recover allows to send last element on failure and gracefully complete the stream.
Flow<In,Out,Mat>	recover(Predicate<? super Throwable> p, Out fallbackValue)	Recover allows to send last element on failure and gracefully complete the stream.
Flow<In,Out,Mat>	recover(scala.PartialFunction<Throwable,Out> pf)	Recover allows to send last element on failure and gracefully complete the stream
Flow<In,Out,Mat>	recoverWith(Class<? extends Throwable> clazz, Creator<Graph<SourceShape<Out>,NotUsed>> creator)	RecoverWith allows to switch to alternative Source on flow failure.
Flow<In,Out,Mat>	recoverWith(scala.PartialFunction<Throwable,? extends Graph<SourceShape<Out>,NotUsed>> pf)	RecoverWith allows to switch to alternative Source on flow failure.
Flow<In,Out,Mat>	recoverWithRetries(int attempts, Class<? extends Throwable> clazz, Creator<Graph<SourceShape<Out>,NotUsed>> creator)	RecoverWithRetries allows to switch to alternative Source on flow failure.
Flow<In,Out,Mat>	recoverWithRetries(int attempts, scala.PartialFunction<Throwable,Graph<SourceShape<Out>,NotUsed>> pf)	RecoverWithRetries allows to switch to alternative Source on flow failure.
Flow<In,Out,Mat>	reduce(Function2<Out,Out,Out> f)	Similar to fold but uses first element as zero element.
<T, U> Pair<T,U>	runWith(Graph<SourceShape<In>,T> source, Graph<SinkShape<Out>,U> sink, ClassicActorSystemProvider systemProvider)	Connect the Source to this Flow and then connect it to the Sink and run it.
<T, U> Pair<T,U>	runWith(Graph<SourceShape<In>,T> source, Graph<SinkShape<Out>,U> sink, Materializer materializer)	Connect the Source to this Flow and then connect it to the Sink and run it.
<T> Flow<In,T,Mat>	scan(T zero, Function2<T,Out,T> f)	Similar to fold but is not a terminal operation, emits its current value which starts at zero and then applies the current and next value to the given function f, emitting the next current value.
<T> Flow<In,T,Mat>	scanAsync(T zero, Function2<T,Out,CompletionStage<T>> f)	Similar to scan but with an asynchronous function, emits its current value which starts at zero and then applies the current and next value to the given function f, emitting a Future that resolves to the next current value.
FlowShape<In,Out>	shape()	The shape of a graph is all that is externally visible: its inlets and outlets.
Flow<In,List<Out>,Mat>	sliding(int n, int step)	Apply a sliding window over the stream and return the windows as groups of elements, with the last group possibly smaller than requested due to end-of-stream.
int	sliding$default$2()
SubFlow<In,Out,Mat>	splitAfter(Predicate<Out> p)	This operation applies the given predicate to all incoming elements and emits them to a stream of output streams.
SubFlow<In,Out,Mat>	splitAfter(SubstreamCancelStrategy substreamCancelStrategy, Predicate<Out> p)	Deprecated. Use .withAttributes(ActorAttributes.supervisionStrategy(equivalentDecider)) rather than a SubstreamCancelStrategy.
SubFlow<In,Out,Mat>	splitWhen(Predicate<Out> p)	This operation applies the given predicate to all incoming elements and emits them to a stream of output streams, always beginning a new one with the current element if the given predicate returns true for it.
SubFlow<In,Out,Mat>	splitWhen(SubstreamCancelStrategy substreamCancelStrategy, Predicate<Out> p)	Deprecated. Use .withAttributes(ActorAttributes.supervisionStrategy(equivalentDecider)) rather than a SubstreamCancelStrategy.
<S, T> Flow<In,T,Mat>	statefulMap(Creator<S> create, Function2<S,Out,Pair<S,T>> f, Function<S,Optional<T>> onComplete)	Transform each stream element with the help of a state.
<T> Flow<In,T,Mat>	statefulMapConcat(Creator<Function<Out,Iterable<T>>> f)	Transform each input element into an Iterable of output elements that is then flattened into the output stream.
<T, M> Flow<In,T,Mat>	switchMap(Function<Out,? extends Graph<SourceShape<T>,M>> f)	Transforms each input element into a Source of output elements that is then flattened into the output stream until a new input element is received at which point the current (now previous) substream is cancelled (which is why this operator is sometimes also called "flatMapLatest").
Flow<In,Out,Mat>	take(long n)	Terminate processing (and cancel the upstream publisher) after the given number of elements.
Flow<In,Out,Mat>	takeUntil(Predicate<Out> p)	Terminate processing (and cancel the upstream publisher) after predicate returns true for the first time, Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.
Flow<In,Out,Mat>	takeWhile(Predicate<Out> p)	Terminate processing (and cancel the upstream publisher) after predicate returns false for the first time.
Flow<In,Out,Mat>	takeWhile(Predicate<Out> p, boolean inclusive)	Terminate processing (and cancel the upstream publisher) after predicate returns false for the first time.
Flow<In,Out,Mat>	takeWithin(Duration duration)	Terminate processing (and cancel the upstream publisher) after the given duration.
Flow<In,Out,Mat>	throttle(int elements, Duration per)	Sends elements downstream with speed limited to elements/per.
Flow<In,Out,Mat>	throttle(int cost, Duration per, int maximumBurst, Function<Out,Integer> costCalculation, ThrottleMode mode)	Sends elements downstream with speed limited to cost/per.
Flow<In,Out,Mat>	throttle(int elements, Duration per, int maximumBurst, ThrottleMode mode)	Sends elements downstream with speed limited to elements/per.
Flow<In,Out,Mat>	throttle(int cost, Duration per, Function<Out,Integer> costCalculation)	Sends elements downstream with speed limited to cost/per.
Sink<In,Mat>	to(Graph<SinkShape<Out>,?> sink)	Connect this Flow to a Sink, concatenating the processing steps of both.
<M, M2> Sink<In,M2>	toMat(Graph<SinkShape<Out>,M> sink, Function2<Mat,M,M2> combine)	Connect this Flow to a Sink, concatenating the processing steps of both.
RunnableGraph<org.reactivestreams.Processor<In,Out>>	toProcessor()	Converts this Flow to a RunnableGraph that materializes to a Reactive Streams Processor which implements the operations encapsulated by this Flow.
String	toString()
org.apache.pekko.stream.impl.LinearTraversalBuilder	traversalBuilder()	INTERNAL API.
static <In, SuperOut, Out extends SuperOut, M> Flow<In,SuperOut,M>	upcast(Flow<In,Out,M> flow)	Upcast a stream of elements to a stream of supertypes of that element.
<T, M> Flow<In,T,Mat>	via(Graph<FlowShape<Out,T>,M> flow)	Transform this Flow by appending the given processing steps.
<T, M, M2> Flow<In,T,M2>	viaMat(Graph<FlowShape<Out,T>,M> flow, Function2<Mat,M,M2> combine)	Transform this Flow by appending the given processing steps.
Flow<In,Out,Mat>	watch(ActorRef ref)	The operator fails with an pekko.stream.WatchedActorTerminatedException if the target actor is terminated.
<M> Flow<In,Out,M>	watchTermination(Function2<Mat,CompletionStage<Done>,M> matF)	Materializes to CompletionStage that completes on getting termination message.
Flow<In,Out,Mat>	wireTap(Procedure<Out> f)	This is a simplified version of wireTap(Sink) that takes only a simple procedure.
Flow<In,Out,Mat>	wireTap(Graph<SinkShape<Out>,?> that)	Attaches the given Sink to this Flow as a wire tap, meaning that elements that pass through will also be sent to the wire-tap Sink, without the latter affecting the mainline flow.
<M2, M3> Flow<In,Out,M3>	wireTapMat(Graph<SinkShape<Out>,M2> that, Function2<Mat,M2,M3> matF)	Attaches the given Sink to this Flow as a wire tap, meaning that elements that pass through will also be sent to the wire-tap Sink, without the latter affecting the mainline flow.
Flow<In,Out,Mat>	withAttributes(Attributes attr)	Replace the attributes of this Flow with the given ones.
<T> Flow<In,Pair<Out,T>,Mat>	zip(Graph<SourceShape<T>,?> source)	Combine the elements of current Flow and the given Source into a stream of tuples.
<U, A> Flow<In,Pair<A,U>,Mat>	zipAll(Graph<SourceShape<U>,?> that, A thisElem, U thatElem)	Combine the elements of current flow and the given Source into a stream of tuples.
<U, Mat2, Mat3, A> Flow<In,Pair<A,U>,Mat3>	zipAllMat(Graph<SourceShape<U>,Mat2> that, A thisElem, U thatElem, scala.Function2<Mat,Mat2,Mat3> matF)	Combine the elements of current flow and the given Source into a stream of tuples.
<T> Flow<In,Pair<Out,T>,Mat>	zipLatest(Graph<SourceShape<T>,?> source)	Combine the elements of 2 streams into a stream of tuples, picking always the latest element of each.
<T, M, M2> Flow<In,Pair<Out,T>,M2>	zipLatestMat(Graph<SourceShape<T>,M> that, Function2<Mat,M,M2> matF)	Combine the elements of current Flow and the given Source into a stream of tuples, picking always the latest element of each.
<Out2, Out3> Flow<In,Out3,Mat>	zipLatestWith(Graph<SourceShape<Out2>,?> that, boolean eagerComplete, Function2<Out,Out2,Out3> combine)	Combine the elements of multiple streams into a stream of combined elements using a combiner function, picking always the latest of the elements of each source.
<Out2, Out3> Flow<In,Out3,Mat>	zipLatestWith(Graph<SourceShape<Out2>,?> that, Function2<Out,Out2,Out3> combine)	Combine the elements of multiple streams into a stream of combined elements using a combiner function, picking always the latest of the elements of each source.
<Out2, Out3, M, M2> Flow<In,Out3,M2>	zipLatestWithMat(Graph<SourceShape<Out2>,M> that, boolean eagerComplete, Function2<Out,Out2,Out3> combine, Function2<Mat,M,M2> matF)	Put together the elements of current Flow and the given Source into a stream of combined elements using a combiner function, picking always the latest element of each.
<Out2, Out3, M, M2> Flow<In,Out3,M2>	zipLatestWithMat(Graph<SourceShape<Out2>,M> that, Function2<Out,Out2,Out3> combine, Function2<Mat,M,M2> matF)	Put together the elements of current Flow and the given Source into a stream of combined elements using a combiner function, picking always the latest element of each.
<T, M, M2> Flow<In,Pair<Out,T>,M2>	zipMat(Graph<SourceShape<T>,M> that, Function2<Mat,M,M2> matF)	Combine the elements of current Flow and the given Source into a stream of tuples.
<Out2, Out3> Flow<In,Out3,Mat>	zipWith(Graph<SourceShape<Out2>,?> that, Function2<Out,Out2,Out3> combine)	Put together the elements of current Flow and the given Source into a stream of combined elements using a combiner function.
Flow<In,Pair<Out,Long>,Mat>	zipWithIndex()	Combine the elements of current flow into a stream of tuples consisting of all elements paired with their index.
<Out2, Out3, M, M2> Flow<In,Out3,M2>	zipWithMat(Graph<SourceShape<Out2>,M> that, Function2<Out,Out2,Out3> combine, Function2<Mat,M,M2> matF)	Put together the elements of current Flow and the given Source into a stream of combined elements using a combiner function.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

Flow

public Flow(Flow<In,Out,Mat> delegate)

Method Details

create

public static <T> Flow<T,T,NotUsed> create()

Create a `Flow` which can process elements of type `T`.

fromProcessor

public static <I,
O> Flow<I,O,NotUsed> fromProcessor(Creator<org.reactivestreams.Processor<I,O>> processorFactory)

fromProcessorMat

public static <I,
O,
Mat> Flow<I,O,Mat> fromProcessorMat(Creator<Pair<org.reactivestreams.Processor<I,O>,Mat>> processorFactory)

fromFunction

public static <I,
O> Flow<I,O,NotUsed> fromFunction(Function<I,O> f)

Creates a [Flow] which will use the given function to transform its inputs to outputs. It is equivalent to Flow.create[T].map(f)

optionalVia

public static <FIn,
FOut,
FViaOut,
FMat,
FViaMat,
Mat>
Flow<FIn,Optional<FViaOut>,Mat> optionalVia(Flow<FIn,Optional<FOut>,FMat> flow,
 Flow<FOut,FViaOut,FViaMat> viaFlow,
 Function2<FMat,FViaMat,Mat> combine)

Creates a Flow from an existing base Flow outputting an optional element and applying an additional viaFlow only if the element in the stream is defined.

'''Emits when''' the provided viaFlow runs with defined elements

'''Backpressures when''' the viaFlow runs for the defined elements and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

flow - The base flow that outputs an optional element

viaFlow - The flow that gets used if the optional element in is defined.

combine - How to combine the materialized values of flow and viaFlow

Returns:

a Flow with the viaFlow applied onto defined elements of the flow. The output value is contained within an Optional which indicates whether the original flow's element had viaFlow applied.

Since:

1.1.0

of

public static <T> Flow<T,T,NotUsed> of(Class<T> clazz)

Create a `Flow` which can process elements of type `T`.

fromGraph

public static <I,
O,
M> Flow<I,O,M> fromGraph(Graph<FlowShape<I,O>,M> g)

A graph with the shape of a flow logically is a flow, this method makes it so also in type.

fromMaterializer

public static <I,
O,
M> Flow<I,O,CompletionStage<M>> fromMaterializer(Function2<Materializer,Attributes,Flow<I,O,M>> factory)

Defers the creation of a Flow until materialization. The factory function exposes Materializer which is going to be used during materialization and Attributes of the Flow returned by this method.

fromSinkAndSource

public static <I,
O> Flow<I,O,NotUsed> fromSinkAndSource(Graph<SinkShape<I>,?> sink,
 Graph<SourceShape<O>,?> source)

Creates a Flow from a Sink and a Source where the Flow's input will be sent to the Sink and the Flow's output will come from the Source.

The resulting flow can be visualized as:

     +----------------------------------------------+
     | Resulting Flow[I, O, NotUsed]                |
     |                                              |
     |  +---------+                  +-----------+  |
     |  |         |                  |           |  |
 I  ~~> | Sink[I] | [no-connection!] | Source[O] | ~~> O
     |  |         |                  |           |  |
     |  +---------+                  +-----------+  |
     +----------------------------------------------+
 

The completion of the Sink and Source sides of a Flow constructed using this method are independent. So if the Sink receives a completion signal, the Source side will remain unaware of that. If you are looking to couple the termination signals of the two sides use Flow.fromSinkAndSourceCoupled instead.

See also <I,O,M1,M2,M>fromSinkAndSourceMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SinkShape<I>,M1>,org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<O>,M2>,org.apache.pekko.japi.function.Function2<M1,M2,M>) when access to materialized values of the parameters is needed.

fromSinkAndSourceMat

public static <I,
O,
M1,
M2,
M> Flow<I,O,M> fromSinkAndSourceMat(Graph<SinkShape<I>,M1> sink,
 Graph<SourceShape<O>,M2> source,
 Function2<M1,M2,M> combine)

Creates a Flow from a Sink and a Source where the Flow's input will be sent to the Sink and the Flow's output will come from the Source.

The resulting flow can be visualized as:

     +-------------------------------------------------------+
     | Resulting Flow[I, O, M]                              |
     |                                                      |
     |  +-------------+                  +---------------+  |
     |  |             |                  |               |  |
 I  ~~> | Sink[I, M1] | [no-connection!] | Source[O, M2] | ~~> O
     |  |             |                  |               |  |
     |  +-------------+                  +---------------+  |
     +------------------------------------------------------+
 

The completion of the Sink and Source sides of a Flow constructed using this method are independent. So if the Sink receives a completion signal, the Source side will remain unaware of that. If you are looking to couple the termination signals of the two sides use Flow.fromSinkAndSourceCoupledMat instead.

The combine function is used to compose the materialized values of the sink and source into the materialized value of the resulting Flow.

fromSinkAndSourceCoupled

public static <I,
O> Flow<I,O,NotUsed> fromSinkAndSourceCoupled(Graph<SinkShape<I>,?> sink,
 Graph<SourceShape<O>,?> source)

Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow from them. Similar to Flow.fromSinkAndSource however couples the termination of these two operators.

The resulting flow can be visualized as:

     +---------------------------------------------+
     | Resulting Flow[I, O, NotUsed]               |
     |                                             |
     |  +---------+                 +-----------+  |
     |  |         |                 |           |  |
 I  ~~> | Sink[I] | ~~~(coupled)~~~ | Source[O] | ~~> O
     |  |         |                 |           |  |
     |  +---------+                 +-----------+  |
     +---------------------------------------------+
 

E.g. if the emitted Flow gets a cancellation, the Source of course is cancelled, however the Sink will also be completed. The table below illustrates the effects in detail:

Returned Flow	Sink (in)	Source (out)
cause: upstream (sink-side) receives completion	effect: receives completion	effect: receives cancel
cause: upstream (sink-side) receives error	effect: receives error	effect: receives cancel
cause: downstream (source-side) receives cancel	effect: completes	effect: receives cancel
effect: cancels upstream, completes downstream	effect: completes	cause: signals complete
effect: cancels upstream, errors downstream	effect: receives error	cause: signals error or throws
effect: cancels upstream, completes downstream	cause: cancels	effect: receives cancel

See also <I,O,M1,M2,M>fromSinkAndSourceCoupledMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SinkShape<I>,M1>,org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<O>,M2>,org.apache.pekko.japi.function.Function2<M1,M2,M>) when access to materialized values of the parameters is needed.

fromSinkAndSourceCoupledMat

public static <I,
O,
M1,
M2,
M> Flow<I,O,M> fromSinkAndSourceCoupledMat(Graph<SinkShape<I>,M1> sink,
 Graph<SourceShape<O>,M2> source,
 Function2<M1,M2,M> combine)

Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow from them. Similar to Flow.fromSinkAndSource however couples the termination of these two operators.

The resulting flow can be visualized as:

     +-----------------------------------------------------+
     | Resulting Flow[I, O, M]                             |
     |                                                     |
     |  +-------------+                 +---------------+  |
     |  |             |                 |               |  |
 I  ~~> | Sink[I, M1] | ~~~(coupled)~~~ | Source[O, M2] | ~~> O
     |  |             |                 |               |  |
     |  +-------------+                 +---------------+  |
     +-----------------------------------------------------+
 

E.g. if the emitted Flow gets a cancellation, the Source of course is cancelled, however the Sink will also be completed. The table on Flow.fromSinkAndSourceCoupled illustrates the effects in detail.

The combine function is used to compose the materialized values of the sink and source into the materialized value of the resulting Flow.

completionStageFlow

public static <I,
O,
M> Flow<I,O,CompletionStage<M>> completionStageFlow(CompletionStage<Flow<I,O,M>> flow)

Turn a CompletionStage into a flow that will consume the values of the source when the future completes successfully. If the Future is completed with a failure the stream is failed.

The materialized completion stage value is completed with the materialized value of the future flow or failed with a NeverMaterializedException if upstream fails or downstream cancels before the completion stage has completed.

lazyFlow

public static <I,
O,
M> Flow<I,O,CompletionStage<M>> lazyFlow(Creator<Flow<I,O,M>> create)

Defers invoking the create function to create a future flow until there is downstream demand and passing that downstream demand upstream triggers the first element.

Note that asynchronous boundaries (and other operators) in the stream may do pre-fetching which counter acts the laziness and can trigger the factory earlier than expected.

'''Emits when''' the internal flow is successfully created and it emits

'''Backpressures when''' the internal flow is successfully created and it backpressures or downstream backpressures

'''Completes when''' upstream completes and all elements have been emitted from the internal flow

'''Cancels when''' downstream cancels

lazyCompletionStageFlow

public static <I,
O,
M> Flow<I,O,CompletionStage<M>> lazyCompletionStageFlow(Creator<CompletionStage<Flow<I,O,M>>> create)

Defers invoking the create function to create a future flow until there downstream demand has caused upstream to send a first element.

The materialized future value is completed with the materialized value of the created flow when that has successfully been materialized.

If the create function throws or returns a future that fails the stream is failed, in this case the materialized future value is failed with a NeverMaterializedException.

Note that asynchronous boundaries (and other operators) in the stream may do pre-fetching which counter acts the laziness and can trigger the factory earlier than expected.

'''Emits when''' the internal flow is successfully created and it emits

'''Backpressures when''' the internal flow is successfully created and it backpressures or downstream backpressures

'''Completes when''' upstream completes and all elements have been emitted from the internal flow

'''Cancels when''' downstream cancels

upcast

public static <In,
SuperOut,
Out extends SuperOut,
M>
Flow<In,SuperOut,M> upcast(Flow<In,Out,M> flow)

Upcast a stream of elements to a stream of supertypes of that element. Useful in combination with fan-in operators where you do not want to pay the cost of casting each element in a map.

Returns:

A flow that accepts In and outputs elements of the super type

flattenOptional

public static <Out,
In extends Optional<Out>>
Flow<In,Out,NotUsed> flattenOptional()

Collect the value of Optional from the elements passing through this flow, empty Optional is filtered out.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the current Optional's value is present.

'''Backpressures when''' the value of the current Optional is present and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels *

concatAllLazy

public Flow<In,Out,Mat> concatAllLazy(Graph<SourceShape<Out>,?>... those)

Concatenate the given Sources to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.

Note that the Sources are materialized together with this Flow. If lazy materialization is what is needed the operator can be combined with for example Source.lazySource to defer materialization of that until the time when this source completes.

The second source is then kept from producing elements by asserting back-pressure until its time comes.

For a concat operator that is detached, use concat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

If this Flow gets upstream error - no elements from the given Sources will be pulled.

'''Emits when''' element is available from current stream or from the given Sources when current is completed

'''Backpressures when''' downstream backpressures

'''Completes when''' given all those Sources completes

'''Cancels when''' downstream cancels

alsoToAll

public Flow<In,Out,Mat> alsoToAll(Graph<SinkShape<Out>,?>... those)

Attaches the given Sinks to this Flow, meaning that elements that passes through will also be sent to all those Sinks.

It is similar to wireTap(org.apache.pekko.japi.function.Procedure<Out>) but will backpressure instead of dropping elements when the given Sinks is not ready.

'''Emits when''' element is available and demand exists both from the Sinks and the downstream.

'''Backpressures when''' downstream or any of the Sinks backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream or any of the Sinks cancels

shape

public FlowShape<In,Out> shape()

Description copied from interface: Graph

The shape of a graph is all that is externally visible: its inlets and outlets.

Specified by:

shape in interface Graph<In,Out>

traversalBuilder

public org.apache.pekko.stream.impl.LinearTraversalBuilder traversalBuilder()

Description copied from interface: Graph

INTERNAL API.

Every materializable element must be backed by a stream layout module

Specified by:

traversalBuilder in interface Graph<In,Out>

toString

public String toString()

Overrides:

toString in class Object

asScala

public Flow<In,Out,Mat> asScala()

Converts this Flow to its Scala DSL counterpart

mapMaterializedValue

public <Mat2> Flow<In,Out,Mat2> mapMaterializedValue(Function<Mat,Mat2> f)

Transform only the materialized value of this Flow, leaving all other properties as they were.

preMaterialize

public Pair<Mat,Flow<In,Out,NotUsed>> preMaterialize(ClassicActorSystemProvider systemProvider)

Materializes this Flow, immediately returning (1) its materialized value, and (2) a newly materialized Flow.

preMaterialize

public Pair<Mat,Flow<In,Out,NotUsed>> preMaterialize(Materializer materializer)

Materializes this Flow, immediately returning (1) its materialized value, and (2) a newly materialized Flow. The returned flow is partial materialized and do not support multiple times materialization.

via

public <T,
M> Flow<In,T,Mat> via(Graph<FlowShape<Out,T>,M> flow)

Transform this Flow by appending the given processing steps.

     +---------------------------------+
     | Resulting Flow[In, T, Mat]  |
     |                                 |
     |  +------+             +------+  |
     |  |      |             |      |  |
 In ~~> | this |  ~~Out~~>   | flow | ~~> T
     |  |   Mat|             |     M|  |
     |  +------+             +------+  |
     +---------------------------------+
 

The materialized value of the combined Flow will be the materialized value of the current flow (ignoring the other Flow&rsquo;s value), use viaMat if a different strategy is needed.

See also <T,M,M2>viaMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.FlowShape<Out,T>,M>,org.apache.pekko.japi.function.Function2<Mat,M,M2>) when access to materialized values of the parameter is needed.

viaMat

public <T,
M,
M2> Flow<In,T,M2> viaMat(Graph<FlowShape<Out,T>,M> flow,
 Function2<Mat,M,M2> combine)

Transform this Flow by appending the given processing steps.

     +---------------------------------+
     | Resulting Flow[In, T, M2]       |
     |                                 |
     |  +------+            +------+   |
     |  |      |            |      |   |
 In ~~> | this |  ~~Out~~>  | flow |  ~~> T
     |  |   Mat|            |     M|   |
     |  +------+            +------+   |
     +---------------------------------+
 

The combine function is used to compose the materialized values of this flow and that flow into the materialized value of the resulting Flow.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

to

public Sink<In,Mat> to(Graph<SinkShape<Out>,?> sink)

Connect this Flow to a Sink, concatenating the processing steps of both.

     +------------------------------+
     | Resulting Sink[In, Mat]      |
     |                              |
     |  +------+          +------+  |
     |  |      |          |      |  |
 In ~~> | flow | ~~Out~~> | sink |  |
     |  |   Mat|          |     M|  |
     |  +------+          +------+  |
     +------------------------------+
 

The materialized value of the combined Sink will be the materialized value of the current flow (ignoring the given Sink&rsquo;s value), use toMat if a different strategy is needed.

See also <M,M2>toMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SinkShape<Out>,M>,org.apache.pekko.japi.function.Function2<Mat,M,M2>) when access to materialized values of the parameter is needed.

toMat

public <M,
M2> Sink<In,M2> toMat(Graph<SinkShape<Out>,M> sink,
 Function2<Mat,M,M2> combine)

Connect this Flow to a Sink, concatenating the processing steps of both.

     +----------------------------+
     | Resulting Sink[In, M2]     |
     |                            |
     |  +------+        +------+  |
     |  |      |        |      |  |
 In ~~> | flow | ~Out~> | sink |  |
     |  |   Mat|        |     M|  |
     |  +------+        +------+  |
     +----------------------------+
 

The combine function is used to compose the materialized values of this flow and that Sink into the materialized value of the resulting Sink.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

contramap

public <In2> Flow<In2,Out,Mat> contramap(Function<In2,In> f)

Transform this Flow by applying a function to each *incoming* upstream element before it is passed to the Flow

'''Backpressures when''' original Flow backpressures

'''Cancels when''' original Flow cancels

Since:

1.1.0

dimap

public <In2,
Out2> Flow<In2,Out2,Mat> dimap(Function<In2,In> f,
 Function<Out,Out2> g)

Transform this Flow by applying a function f to each *incoming* upstream element before it is passed to the Flow, and a function g to each *outgoing* downstream element.

'''Emits when''' the mapping function g returns an element

'''Backpressures when''' original Flow backpressures

'''Completes when''' original Flow completes

'''Cancels when''' original Flow cancels

Since:

1.1.0

join

public <M> RunnableGraph<Mat> join(Graph<FlowShape<Out,In>,M> flow)

Join this Flow to another Flow, by cross connecting the inputs and outputs, creating a RunnableGraph.

 +------+        +-------+
 |      | ~Out~> |       |
 | this |        | other |
 |      | <~In~  |       |
 +------+        +-------+
 

The materialized value of the combined Flow will be the materialized value of the current flow (ignoring the other Flow&rsquo;s value), use joinMat if a different strategy is needed.

See also <M,M2>joinMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.FlowShape<Out,In>,M>,org.apache.pekko.japi.function.Function2<Mat,M,M2>) when access to materialized values of the parameter is needed.

joinMat

public <M,
M2> RunnableGraph<M2> joinMat(Graph<FlowShape<Out,In>,M> flow,
 Function2<Mat,M,M2> combine)

Join this Flow to another Flow, by cross connecting the inputs and outputs, creating a RunnableGraph

 +------+        +-------+
 |      | ~Out~> |       |
 | this |        | other |
 |      | <~In~  |       |
 +------+        +-------+
 

The combine function is used to compose the materialized values of this flow and that Flow into the materialized value of the resulting Flow.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

join

public <I2,
O1,
Mat2> Flow<I2,O1,Mat> join(Graph<BidiShape<Out,O1,I2,In>,Mat2> bidi)

Join this Flow to a BidiFlow to close off the &ldquo;top&rdquo; of the protocol stack:

 +---------------------------+
 | Resulting Flow            |
 |                           |
 | +------+        +------+  |
 | |      | ~Out~> |      | ~~> O1
 | | flow |        | bidi |  |
 | |      | <~In~  |      | <~~ I2
 | +------+        +------+  |
 +---------------------------+
 

The materialized value of the combined Flow will be the materialized value of the current flow (ignoring the BidiFlow&rsquo;s value), use {@link Flow#joinMat[I2* joinMat} if a different strategy is needed.

joinMat

public <I2,
O1,
Mat2,
M> Flow<I2,O1,M> joinMat(Graph<BidiShape<Out,O1,I2,In>,Mat2> bidi,
 Function2<Mat,Mat2,M> combine)

Join this Flow to a BidiFlow to close off the &ldquo;top&rdquo; of the protocol stack:

 +---------------------------+
 | Resulting Flow            |
 |                           |
 | +------+        +------+  |
 | |      | ~Out~> |      | ~~> O1
 | | flow |        | bidi |  |
 | |      | <~In~  |      | <~~ I2
 | +------+        +------+  |
 +---------------------------+
 

The combine function is used to compose the materialized values of this flow and that BidiFlow into the materialized value of the resulting Flow.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See also <T,M,M2>viaMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.FlowShape<Out,T>,M>,org.apache.pekko.japi.function.Function2<Mat,M,M2>) when access to materialized values of the parameter is needed.

runWith

public <T,
U> Pair<T,U> runWith(Graph<SourceShape<In>,T> source,
 Graph<SinkShape<Out>,U> sink,
 ClassicActorSystemProvider systemProvider)

Connect the Source to this Flow and then connect it to the Sink and run it.

The returned tuple contains the materialized values of the Source and Sink, e.g. the Subscriber of a Source.asSubscriber and Publisher of a Sink.asPublisher.

materializeIntoSource

public <Mat1,
Mat2>
Source<Mat2,CompletionStage<NotUsed>> materializeIntoSource(Graph<SourceShape<In>,Mat1> source,
 Graph<SinkShape<Out>,CompletionStage<Mat2>> sink)

Connects the Source to this Flow and materializes it using the Sink, immediately returning the values via the provided Sink as a new Source.

Parameters:

source - A source that connects to this flow

sink - A sink which needs to materialize into a CompletionStage, typically one that collects values such as Sink.head or Sink.seq

Returns:

A new Source that contains the results of the Flow with the provided Source's elements run with the Sink

Since:

1.2.0

runWith

public <T,
U> Pair<T,U> runWith(Graph<SourceShape<In>,T> source,
 Graph<SinkShape<Out>,U> sink,
 Materializer materializer)

Connect the Source to this Flow and then connect it to the Sink and run it.

The returned tuple contains the materialized values of the Source and Sink, e.g. the Subscriber of a Source.asSubscriber and Publisher of a Sink.asPublisher.

Prefer the method taking an ActorSystem unless you have special requirements.

map

public <T> Flow<In,T,Mat> map(Function<Out,T> f)

Transform this stream by applying the given function to each of the elements as they pass through this processing step.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

wireTap

public Flow<In,Out,Mat> wireTap(Procedure<Out> f)

This is a simplified version of wireTap(Sink) that takes only a simple procedure. Elements will be passed into this "side channel" function, and any of its results will be ignored.

If the wire-tap operation is slow (it backpressures), elements that would've been sent to it will be dropped instead. It is similar to alsoTo(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SinkShape<Out>, ?>) but will not affect (i.e. backpressure) the flow tapped into.

This operation is useful for inspecting the passed through element, usually by means of side-effecting operations (such as println, or emitting metrics), for each element without having to modify it.

For logging signals (elements, completion, error) consider using the log(java.lang.String,org.apache.pekko.japi.function.Function<Out,java.lang.Object>,org.apache.pekko.event.LoggingAdapter) operator instead, along with appropriate ActorAttributes.logLevels.

'''Emits when''' upstream emits an element; the same element will be passed to the attached function, as well as to the downstream operator

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

mapConcat

public <T> Flow<In,T,Mat> mapConcat(Function<Out,Iterable<T>> f)

Transform each input element into an Iterable of output elements that is then flattened into the output stream.

Make sure that the Iterable is immutable or at least not modified after being used as an output sequence. Otherwise the stream may fail with ConcurrentModificationException or other more subtle errors may occur.

The returned Iterable MUST NOT contain null values, as they are illegal as stream elements - according to the Reactive Streams specification.

'''Emits when''' the mapping function returns an element or there are still remaining elements from the previously calculated collection

'''Backpressures when''' downstream backpressures or there are still remaining elements from the previously calculated collection

'''Completes when''' upstream completes and all remaining elements have been emitted

'''Cancels when''' downstream cancels

statefulMap

public <S,
T> Flow<In,T,Mat> statefulMap(Creator<S> create,
 Function2<S,Out,Pair<S,T>> f,
 Function<S,Optional<T>> onComplete)

Transform each stream element with the help of a state.

The state creation function is invoked once when the stream is materialized and the returned state is passed to the mapping function for mapping the first element. The mapping function returns a mapped element to emit downstream and a state to pass to the next mapping function. The state can be the same for each mapping return, be a new immutable state but it is also safe to use a mutable state. The returned T MUST NOT be null as it is illegal as stream element - according to the Reactive Streams specification.

For stateless variant see <T>map(org.apache.pekko.japi.function.Function<Out,T>).

The onComplete function is called only once when the upstream or downstream finished, You can do some clean-up here, and if the returned value is not empty, it will be emitted to the downstream if available, otherwise the value will be dropped.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the mapping function returns an element and downstream is ready to consume it

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

create - a function that creates the initial state

f - a function that transforms the upstream element and the state into a pair of next state and output element

onComplete - a function that transforms the ongoing state into an optional output element

mapWithResource

public <R,
T> Flow<In,T,Mat> mapWithResource(Creator<R> create,
 Function2<R,Out,T> f,
 Function<R,Optional<T>> close)

Transform each stream element with the help of a resource.

The resource creation function is invoked once when the stream is materialized and the returned resource is passed to the mapping function for mapping the first element. The mapping function returns a mapped element to emit downstream. The returned T MUST NOT be null as it is illegal as stream element - according to the Reactive Streams specification.

The close function is called only once when the upstream or downstream finishes or fails. You can do some clean-up here, and if the returned value is not empty, it will be emitted to the downstream if available, otherwise the value will be dropped.

Early completion can be done with combination of the takeWhile(org.apache.pekko.japi.function.Predicate<Out>,boolean) operator.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

You can configure the default dispatcher for this Source by changing the pekko.stream.materializer.blocking-io-dispatcher or set it for a given Source by using ActorAttributes.

'''Emits when''' the mapping function returns an element and downstream is ready to consume it

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

create - function that creates the resource

f - function that transforms the upstream element and the resource to output element

close - function that closes the resource, optionally outputting a last element

Since:

1.1.0

mapWithResource

public <R extends AutoCloseable,
T> Flow<In,T,Mat> mapWithResource(Creator<R> create,
 Function2<R,Out,T> f)

Transform each stream element with the help of an AutoCloseable resource and close it when the stream finishes or fails.

The resource creation function is invoked once when the stream is materialized and the returned resource is passed to the mapping function for mapping the first element. The mapping function returns a mapped element to emit downstream. The returned T MUST NOT be null as it is illegal as stream element - according to the Reactive Streams specification.

The AutoCloseable resource is closed only once when the upstream or downstream finishes or fails.

Early completion can be done with combination of the takeWhile(org.apache.pekko.japi.function.Predicate<Out>,boolean) operator.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

You can configure the default dispatcher for this Source by changing the pekko.stream.materializer.blocking-io-dispatcher or set it for a given Source by using ActorAttributes.

'''Emits when''' the mapping function returns an element and downstream is ready to consume it

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

create - function that creates the resource

f - function that transforms the upstream element and the resource to output element

Since:

1.1.0

statefulMapConcat

public <T> Flow<In,T,Mat> statefulMapConcat(Creator<Function<Out,Iterable<T>>> f)

Transform each input element into an Iterable of output elements that is then flattened into the output stream. The transformation is meant to be stateful, which is enabled by creating the transformation function anew for every materialization — the returned function will typically close over mutable objects to store state between invocations. For the stateless variant see mapConcat(org.apache.pekko.japi.function.Function<Out, java.lang.Iterable<T>>).

Make sure that the Iterable is immutable or at least not modified after being used as an output sequence. Otherwise the stream may fail with ConcurrentModificationException or other more subtle errors may occur.

The returned Iterable MUST NOT contain null values, as they are illegal as stream elements - according to the Reactive Streams specification.

This operator doesn't handle upstream's completion signal since the state kept in the closure can be lost. Use FlowOps.statefulMap, or return an StatefulMapConcatAccumulator instead.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the mapping function returns an element or there are still remaining elements from the previously calculated collection

'''Backpressures when''' downstream backpressures or there are still remaining elements from the previously calculated collection

'''Completes when''' upstream completes and all remaining elements has been emitted

'''Cancels when''' downstream cancels

mapAsync

public <T> Flow<In,T,Mat> mapAsync(int parallelism,
 Function<Out,CompletionStage<T>> f)

Transform this stream by applying the given function to each of the elements as they pass through this processing step. The function returns a CompletionStage and the value of that future will be emitted downstream. The number of CompletionStages that shall run in parallel is given as the first argument to mapAsync. These CompletionStages may complete in any order, but the elements that are emitted downstream are in the same order as received from upstream.

If the function f throws an exception or if the CompletionStage is completed with failure and the supervision decision is pekko.stream.Supervision#stop the stream will be completed with failure.

If the function f throws an exception or if the CompletionStage is completed with failure and the supervision decision is pekko.stream.Supervision#resume or pekko.stream.Supervision#restart or the CompletionStage completed with null, the element is dropped and the stream continues.

The function f is always invoked on the elements in the order they arrive.

'''Emits when''' the CompletionStage returned by the provided function finishes for the next element in sequence

'''Backpressures when''' the number of CompletionStages reaches the configured parallelism and the downstream backpressures or the first future is not completed

'''Completes when''' upstream completes and all CompletionStages have been completed and all elements have been emitted

'''Cancels when''' downstream cancels

See Also:

• mapAsyncUnordered(int, org.apache.pekko.japi.function.Function<Out, java.util.concurrent.CompletionStage<T>>)

mapAsyncPartitioned

public <T,
P> Flow<In,T,Mat> mapAsyncPartitioned(int parallelism,
 Function<Out,P> partitioner,
 Function2<Out,P,CompletionStage<T>> f)

Transforms this stream. Works very similarly to mapAsync(int, org.apache.pekko.japi.function.Function<Out, java.util.concurrent.CompletionStage<T>>) but with an additional partition step before the transform step. The transform function receives the an individual stream entry and the calculated partition value for that entry. The max parallelism of per partition is 1.

The function partitioner is always invoked on the elements in the order they arrive. The function f is always invoked on the elements which in the same partition in the order they arrive.

If the function partitioner or f throws an exception or if the CompletionStage is completed with failure and the supervision decision is pekko.stream.Supervision.Stop the stream will be completed with failure, otherwise the stream continues and the current element is dropped.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the Future returned by the provided function finishes for the next element in sequence

'''Backpressures when''' the number of futures reaches the configured parallelism and the downstream backpressures

'''Completes when''' upstream completes and all futures have been completed and all elements have been emitted

'''Cancels when''' downstream cancels

Since:

1.1.0

See Also:

• mapAsync(int, org.apache.pekko.japi.function.Function<Out, java.util.concurrent.CompletionStage<T>>)
• mapAsyncPartitionedUnordered(int, org.apache.pekko.japi.function.Function<Out, P>, org.apache.pekko.japi.function.Function2<Out, P, java.util.concurrent.CompletionStage<T>>)

mapAsyncPartitionedUnordered

public <T,
P> Flow<In,T,Mat> mapAsyncPartitionedUnordered(int parallelism,
 Function<Out,P> partitioner,
 Function2<Out,P,CompletionStage<T>> f)

Transforms this stream. Works very similarly to mapAsyncUnordered(int, org.apache.pekko.japi.function.Function<Out, java.util.concurrent.CompletionStage<T>>) but with an additional partition step before the transform step. The transform function receives the an individual stream entry and the calculated partition value for that entry.The max parallelism of per partition is 1.

The function partitioner is always invoked on the elements in the order they arrive. The function f is always invoked on the elements which in the same partition in the order they arrive.

If the function partitioner or f throws an exception or if the CompletionStage is completed with failure and the supervision decision is pekko.stream.Supervision.Stop the stream will be completed with failure, otherwise the stream continues and the current element is dropped.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the Future returned by the provided function finishes and downstream available.

'''Backpressures when''' the number of futures reaches the configured parallelism and the downstream backpressures

'''Completes when''' upstream completes and all futures have been completed and all elements have been emitted

'''Cancels when''' downstream cancels

Since:

1.1.0

See Also:

• mapAsyncUnordered(int, org.apache.pekko.japi.function.Function<Out, java.util.concurrent.CompletionStage<T>>)
• mapAsyncPartitioned(int, org.apache.pekko.japi.function.Function<Out, P>, org.apache.pekko.japi.function.Function2<Out, P, java.util.concurrent.CompletionStage<T>>)

mapAsyncUnordered

public <T> Flow<In,T,Mat> mapAsyncUnordered(int parallelism,
 Function<Out,CompletionStage<T>> f)

Transform this stream by applying the given function to each of the elements as they pass through this processing step. The function returns a CompletionStage and the value of that future will be emitted downstream. The number of CompletionStages that shall run in parallel is given as the first argument to mapAsyncUnordered. Each processed element will be emitted downstream as soon as it is ready, i.e. it is possible that the elements are not emitted downstream in the same order as received from upstream.

If the function f throws an exception or if the CompletionStage is completed with failure and the supervision decision is pekko.stream.Supervision#stop the stream will be completed with failure.

If the function f throws an exception or if the CompletionStage is completed with failure and the supervision decision is pekko.stream.Supervision#resume or pekko.stream.Supervision#restart or the CompletionStage completed with null, the element is dropped and the stream continues.

The function f is always invoked on the elements in the order they arrive (even though the result of the futures returned by f might be emitted in a different order).

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' any of the CompletionStages returned by the provided function complete

'''Backpressures when''' the number of CompletionStages reaches the configured parallelism and the downstream backpressures

'''Completes when''' upstream completes and all CompletionStages have been completed and all elements have been emitted

'''Cancels when''' downstream cancels

See Also:

• mapAsync(int, org.apache.pekko.japi.function.Function<Out, java.util.concurrent.CompletionStage<T>>)

ask

public <S> Flow<In,S,Mat> ask(ActorRef ref,
 Class<S> mapTo,
 Timeout timeout)

Use the ask pattern to send a request-reply message to the target ref actor. If any of the asks times out it will fail the stream with a pekko.pattern.AskTimeoutException.

The mapTo class parameter is used to cast the incoming responses to the expected response type.

Similar to the plain ask pattern, the target actor is allowed to reply with org.apache.pekko.util.Status. An org.apache.pekko.util.Status#Failure will cause the operator to fail with the cause carried in the Failure message.

Defaults to parallelism of 2 messages in flight, since while one ask message may be being worked on, the second one still be in the mailbox, so defaulting to sending the second one a bit earlier than when first ask has replied maintains a slightly healthier throughput.

The operator fails with an pekko.stream.WatchedActorTerminatedException if the target actor is terminated.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' any of the CompletionStages returned by the provided function complete

'''Backpressures when''' the number of futures reaches the configured parallelism and the downstream backpressures

'''Completes when''' upstream completes and all futures have been completed and all elements have been emitted

'''Fails when''' the passed in actor terminates, or a timeout is exceeded in any of the asks performed

'''Cancels when''' downstream cancels

ask

public <S> Flow<In,S,Mat> ask(int parallelism,
 ActorRef ref,
 Class<S> mapTo,
 Timeout timeout)

Use the ask pattern to send a request-reply message to the target ref actor. If any of the asks times out it will fail the stream with a pekko.pattern.AskTimeoutException.

The mapTo class parameter is used to cast the incoming responses to the expected response type.

Similar to the plain ask pattern, the target actor is allowed to reply with org.apache.pekko.util.Status. An org.apache.pekko.util.Status#Failure will cause the operator to fail with the cause carried in the Failure message.

Parallelism limits the number of how many asks can be "in flight" at the same time. Please note that the elements emitted by this operator are in-order with regards to the asks being issued (i.e. same behavior as mapAsync).

The operator fails with an pekko.stream.WatchedActorTerminatedException if the target actor is terminated.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' any of the CompletionStages returned by the provided function complete

'''Backpressures when''' the number of futures reaches the configured parallelism and the downstream backpressures

'''Completes when''' upstream completes and all futures have been completed and all elements have been emitted

'''Fails when''' the passed in actor terminates, or a timeout is exceeded in any of the asks performed

'''Cancels when''' downstream cancels

watch

public Flow<In,Out,Mat> watch(ActorRef ref)

The operator fails with an pekko.stream.WatchedActorTerminatedException if the target actor is terminated.

'''Emits when''' upstream emits

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Fails when''' the watched actor terminates

'''Cancels when''' downstream cancels

filter

public Flow<In,Out,Mat> filter(Predicate<Out> p)

Only pass on those elements that satisfy the given predicate.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the given predicate returns true for the element

'''Backpressures when''' the given predicate returns true for the element and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

filterNot

public Flow<In,Out,Mat> filterNot(Predicate<Out> p)

Only pass on those elements that NOT satisfy the given predicate.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the given predicate returns false for the element

'''Backpressures when''' the given predicate returns false for the element and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

doOnFirst

public Flow<In,Out,Mat> doOnFirst(Procedure<Out> f)

Run the given function when the first element is received.

'''Emits when''' upstream emits an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Since:

1.3.0

doOnCancel

public Flow<In,Out,Mat> doOnCancel(Procedure2<? super Throwable,Boolean> f)

Run the given function when the downstream cancels.

The first parameter is the cause of the cancellation, and the second parameter indicates whether the downstream was cancelled normally.

'''Emits when''' upstream emits an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

f - function to be run on cancellation, the first parameter is the cause of the cancellation, and the second parameter indicates whether the downstream was cancelled normally.

Since:

1.3.0

dropRepeated

public Flow<In,Out,Mat> dropRepeated()

Only pass on those elements that are distinct from the previous element.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the element is distinct from the previous element

'''Backpressures when''' the element is distinct from the previous element and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Since:

1.2.0

dropRepeated

public Flow<In,Out,Mat> dropRepeated(Function2<Out,Out,Object> p)

Only pass on those elements that are distinct from the previous element according to the given predicate.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the element is distinct from the previous element

'''Backpressures when''' the element is distinct from the previous element and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Since:

1.2.0

collect

public <T> Flow<In,T,Mat> collect(scala.PartialFunction<Out,T> pf)

Transform this stream by applying the given partial function to each of the elements on which the function is defined as they pass through this processing step. Non-matching elements are filtered out.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the provided partial function is defined for the element

'''Backpressures when''' the partial function is defined for the element and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

collectFirst

public <T> Flow<In,T,Mat> collectFirst(scala.PartialFunction<Out,T> pf)

Transform this stream by applying the given partial function to the first element on which the function is defined as it pass through this processing step, and cancel the upstream publisher after the first element is emitted.

Non-matching elements are filtered out.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the provided partial function is defined for the first element

'''Backpressures when''' the partial function is defined for the element and downstream backpressures

'''Completes when''' upstream completes or the first element is emitted

'''Cancels when''' downstream cancels

collectWhile

public <T> Flow<In,T,Mat> collectWhile(scala.PartialFunction<Out,T> pf)

Transform this stream by applying the given partial function to each of the elements on which the function is defined as they pass through this processing step, and cancel the upstream publisher after the partial function is not applied.

The stream will be completed without producing any elements if the partial function is not applied for the first stream element, eg: there is a downstream buffer.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the provided partial function is defined for the element

'''Backpressures when''' the partial function is defined for the element and downstream backpressures

'''Completes when''' upstream completes or the partial function is not applied.

'''Cancels when''' downstream cancels

Since:

1.1.0

collectType

public <T> Flow<In,T,Mat> collectType(Class<T> clazz)

Transform this stream by testing the type of each of the elements on which the element is an instance of the provided type as they pass through this processing step. Non-matching elements are filtered out.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the element is an instance of the provided type

'''Backpressures when''' the element is an instance of the provided type and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

grouped

public Flow<In,List<Out>,Mat> grouped(int n)

Chunk up this stream into groups of the given size, with the last group possibly smaller than requested due to end-of-stream.

n must be positive, otherwise IllegalArgumentException is thrown.

'''Emits when''' the specified number of elements has been accumulated or upstream completed

'''Backpressures when''' a group has been assembled and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

groupedWeighted

public Flow<In,List<Out>,Mat> groupedWeighted(long minWeight,
 Function<Out,Long> costFn)

Chunk up this stream into groups of elements that have a cumulative weight greater than or equal to the minWeight, with the last group possibly smaller than requested minWeight due to end-of-stream.

minWeight must be positive, otherwise IllegalArgumentException is thrown. costFn must return a non-negative result for all inputs, otherwise the stage will fail with an IllegalArgumentException.

'''Emits when''' the cumulative weight of elements is greater than or equal to the minWeight or upstream completed

'''Backpressures when''' a buffered group weighs more than minWeight and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

groupedAdjacentBy

public <R> Flow<In,List<Out>,Mat> groupedAdjacentBy(Function<Out,R> f)

Partitions this stream into chunks by a delimiter function, which is applied to each incoming element, when the result of the function is not the same as the previous element's result, a chunk is emitted.

The f function must return a non-null value for all elements, otherwise the stage will fail.

'''Emits when''' the delimiter function returns a different value than the previous element's result

'''Backpressures when''' a chunk has been assembled and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Since:

1.2.0

groupedAdjacentByWeighted

public <R> Flow<In,List<Out>,Mat> groupedAdjacentByWeighted(Function<Out,R> f,
 long maxWeight,
 Function<Out,Long> costFn)

Partitions this stream into chunks by a delimiter function, which is applied to each incoming element, when the result of the function is not the same as the previous element's result, or the accumulated weight exceeds the maxWeight, a chunk is emitted.

The f function must return a non-null value , and the costFn must return a non-negative result for all inputs, otherwise the stage will fail.

'''Emits when''' the delimiter function returns a different value than the previous element's result, or exceeds the maxWeight.

'''Backpressures when''' a chunk has been assembled and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Since:

1.2.0

limit

public Flow<In,Out,Mat> limit(long n)

Ensure stream boundedness by limiting the number of elements from upstream. If the number of incoming elements exceeds max, it will signal upstream failure StreamLimitException downstream.

Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.

The stream will be completed without producing any elements if n is zero or negative.

'''Emits when''' the specified number of elements to take has not yet been reached

'''Backpressures when''' downstream backpressures

'''Completes when''' the defined number of elements has been taken or upstream completes

'''Errors when''' the total number of incoming element exceeds max

'''Cancels when''' the defined number of elements has been taken or downstream cancels

See also Flow.take, Flow.takeWithin, Flow.takeWhile

limitWeighted

public Flow<In,Out,Mat> limitWeighted(long n,
 Function<Out,Long> costFn)

Ensure stream boundedness by evaluating the cost of incoming elements using a cost function. Exactly how many elements will be allowed to travel downstream depends on the evaluated cost of each element. If the accumulated cost exceeds max, it will signal upstream failure StreamLimitException downstream.

Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.

The stream will be completed without producing any elements if n is zero or negative.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the specified number of elements to take has not yet been reached

'''Backpressures when''' downstream backpressures

'''Completes when''' the defined number of elements has been taken or upstream completes

'''Errors when''' when the accumulated cost exceeds max

'''Cancels when''' the defined number of elements has been taken or downstream cancels

See also Flow.take, Flow.takeWithin, Flow.takeWhile

sliding

public Flow<In,List<Out>,Mat> sliding(int n,
 int step)

Apply a sliding window over the stream and return the windows as groups of elements, with the last group possibly smaller than requested due to end-of-stream.

n must be positive, otherwise IllegalArgumentException is thrown. step must be positive, otherwise IllegalArgumentException is thrown.

'''Emits when''' enough elements have been collected within the window or upstream completed

'''Backpressures when''' a window has been assembled and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

sliding$default$2

public int sliding$default$2()

scan

public <T> Flow<In,T,Mat> scan(T zero,
 Function2<T,Out,T> f)

Similar to fold but is not a terminal operation, emits its current value which starts at zero and then applies the current and next value to the given function f, emitting the next current value.

If the function f throws an exception and the supervision decision is pekko.stream.Supervision#restart current value starts at zero again the stream will continue.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

Note that the zero value must be immutable.

'''Emits when''' the function scanning the element returns a new element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

scanAsync

public <T> Flow<In,T,Mat> scanAsync(T zero,
 Function2<T,Out,CompletionStage<T>> f)

Similar to scan but with an asynchronous function, emits its current value which starts at zero and then applies the current and next value to the given function f, emitting a Future that resolves to the next current value.

If the function f throws an exception and the supervision decision is pekko.stream.Supervision.Restart current value starts at zero again the stream will continue.

If the function f throws an exception and the supervision decision is pekko.stream.Supervision.Resume current value starts at the previous current value, or zero when it doesn't have one, and the stream will continue.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

Note that the zero value must be immutable.

'''Emits when''' the future returned by f completes

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes and the last future returned by f completes

'''Cancels when''' downstream cancels

See also scan(T, org.apache.pekko.japi.function.Function2<T, Out, T>)

fold

public <T> Flow<In,T,Mat> fold(T zero,
 Function2<T,Out,T> f)

Similar to scan but only emits its result when the upstream completes, after which it also completes. Applies the given function f towards its current and next value, yielding the next current value.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

If the function f throws an exception and the supervision decision is pekko.stream.Supervision#restart current value starts at zero again the stream will continue.

Note that the zero value must be immutable.

'''Emits when''' upstream completes

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

foldWhile

public <T> Flow<In,T,Mat> foldWhile(T zero,
 Predicate<T> p,
 Function2<T,Out,T> f)

Similar to scan but only emits its result when the upstream completes or the predicate p returns false. after which it also completes. Applies the given function towards its current and next value, yielding the next current value.

If the function f throws an exception and the supervision decision is pekko.stream.Supervision.Restart current value starts at zero again the stream will continue.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

Note that the zero value must be immutable.

'''Emits when''' upstream completes or the predicate p returns false

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

See also FlowOps.fold

Since:

1.1.0

foldAsync

public <T> Flow<In,T,Mat> foldAsync(T zero,
 Function2<T,Out,CompletionStage<T>> f)

Similar to fold but with an asynchronous function. Applies the given function towards its current and next value, yielding the next current value.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

If the function f returns a failure and the supervision decision is pekko.stream.Supervision.Restart current value starts at zero again the stream will continue.

Note that the zero value must be immutable.

'''Emits when''' upstream completes

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

reduce

public Flow<In,Out,Mat> reduce(Function2<Out,Out,Out> f)

Similar to fold but uses first element as zero element. Applies the given function towards its current and next value, yielding the next current value.

If the stream is empty (i.e. completes before signalling any elements), the reduce operator will fail its downstream with a NoSuchElementException, which is semantically in-line with that Scala's standard library collections do in such situations.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' upstream completes

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

intersperse

public Flow<In,Out,Mat> intersperse(Out start,
 Out inject,
 Out end)

Intersperses stream with provided element, similar to how scala.collection.immutable.List.mkString injects a separator between a List's elements.

Additionally can inject start and end marker elements to stream.

Examples:

 Source<Integer, ?> nums = Source.from(Arrays.asList(0, 1, 2, 3));
 nums.intersperse(",");            //   1 , 2 , 3
 nums.intersperse("[", ",", "]");  // [ 1 , 2 , 3 ]
 

In case you want to only prepend or only append an element (yet still use the intercept feature to inject a separator between elements, you may want to use the following pattern instead of the 3-argument version of intersperse (See Source.concat for semantics details):

 Source.single(">> ").concat(flow.intersperse(","))
 flow.intersperse(",").concat(Source.single("END"))
 

'''Emits when''' upstream emits (or before with the start element if provided)

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

intersperse

public Flow<In,Out,Mat> intersperse(Out inject)

Intersperses stream with provided element, similar to how scala.collection.immutable.List.mkString injects a separator between a List's elements.

Additionally can inject start and end marker elements to stream.

Examples:

 Source<Integer, ?> nums = Source.from(Arrays.asList(0, 1, 2, 3));
 nums.intersperse(",");            //   1 , 2 , 3
 nums.intersperse("[", ",", "]");  // [ 1 , 2 , 3 ]
 

'''Emits when''' upstream emits (or before with the start element if provided)

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

groupedWithin

public Flow<In,List<Out>,Mat> groupedWithin(int maxNumber,
 Duration duration)

Chunk up this stream into groups of elements received within a time window, or limited by the given number of elements, whatever happens first. Empty groups will not be emitted if no elements are received from upstream. The last group before end-of-stream will contain the buffered elements since the previously emitted group.

'''Emits when''' the configured time elapses since the last group has been emitted or n elements is buffered

'''Backpressures when''' downstream backpressures, and there are n+1 buffered elements

'''Completes when''' upstream completes (emits last group)

'''Cancels when''' downstream completes

maxNumber must be positive, and duration must be greater than 0 seconds, otherwise IllegalArgumentException is thrown.

groupedWeightedWithin

public Flow<In,List<Out>,Mat> groupedWeightedWithin(long maxWeight,
 Function<Out,Long> costFn,
 Duration duration)

Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements, whatever happens first. Empty groups will not be emitted if no elements are received from upstream. The last group before end-of-stream will contain the buffered elements since the previously emitted group.

'''Emits when''' the configured time elapses since the last group has been emitted or weight limit reached

'''Backpressures when''' downstream backpressures, and buffered group (+ pending element) weighs more than maxWeight

'''Completes when''' upstream completes (emits last group)

'''Cancels when''' downstream completes

maxWeight must be positive, and duration must be greater than 0 seconds, otherwise IllegalArgumentException is thrown.

groupedWeightedWithin

public Flow<In,List<Out>,Mat> groupedWeightedWithin(long maxWeight,
 int maxNumber,
 Function<Out,Long> costFn,
 Duration duration)

Chunk up this stream into groups of elements received within a time window, or limited by the weight and number of the elements, whatever happens first. Empty groups will not be emitted if no elements are received from upstream. The last group before end-of-stream will contain the buffered elements since the previously emitted group.

'''Emits when''' the configured time elapses since the last group has been emitted or weight limit reached

'''Backpressures when''' downstream backpressures, and buffered group (+ pending element) weighs more than maxWeight or has more than maxNumber elements

'''Completes when''' upstream completes (emits last group)

'''Cancels when''' downstream completes

maxWeight must be positive, maxNumber must be positive, and duration must be greater than 0 seconds, otherwise IllegalArgumentException is thrown.

delay

public Flow<In,Out,Mat> delay(Duration of,
 DelayOverflowStrategy strategy)

Shifts elements emission in time by a specified amount. It allows to store elements in internal buffer while waiting for next element to be emitted. Depending on the defined pekko.stream.DelayOverflowStrategy it might drop elements or backpressure the upstream if there is no space available in the buffer.

Delay precision is 10ms to avoid unnecessary timer scheduling cycles

Internal buffer has default capacity 16. You can set buffer size by calling addAttributes(inputBuffer)

'''Emits when''' there is a pending element in the buffer and configured time for this element elapsed * EmitEarly - strategy do not wait to emit element if buffer is full

'''Backpressures when''' depending on OverflowStrategy * Backpressure - backpressures when buffer is full * DropHead, DropTail, DropBuffer - never backpressures * Fail - fails the stream if buffer gets full

'''Completes when''' upstream completes and buffered elements have been drained

'''Cancels when''' downstream cancels

Parameters:

of - time to shift all messages

strategy - Strategy that is used when incoming elements cannot fit inside the buffer

delayWith

public Flow<In,Out,Mat> delayWith(Creator<DelayStrategy<Out>> delayStrategyCreator,
 DelayOverflowStrategy overFlowStrategy)

Shifts elements emission in time by an amount individually determined through delay strategy a specified amount. It allows to store elements in internal buffer while waiting for next element to be emitted. Depending on the defined pekko.stream.DelayOverflowStrategy it might drop elements or backpressure the upstream if there is no space available in the buffer.

It determines delay for each ongoing element invoking DelayStrategy.nextDelay(elem: T): FiniteDuration.

Note that elements are not re-ordered: if an element is given a delay much shorter than its predecessor, it will still have to wait for the preceding element before being emitted. It is also important to notice that DelayStrategy can be stateful.

Delay precision is 10ms to avoid unnecessary timer scheduling cycles.

Internal buffer has default capacity 16. You can set buffer size by calling addAttributes(inputBuffer)

'''Emits when''' there is a pending element in the buffer and configured time for this element elapsed * EmitEarly - strategy do not wait to emit element if buffer is full

'''Backpressures when''' depending on OverflowStrategy * Backpressure - backpressures when buffer is full * DropHead, DropTail, DropBuffer - never backpressures * Fail - fails the stream if buffer gets full

'''Completes when''' upstream completes and buffered elements have been drained

'''Cancels when''' downstream cancels

Parameters:

delayStrategyCreator - creates new DelayStrategy object for each materialization

overFlowStrategy - Strategy that is used when incoming elements cannot fit inside the buffer

drop

public Flow<In,Out,Mat> drop(long n)

Discard the given number of elements at the beginning of the stream. No elements will be dropped if n is zero or negative.

'''Emits when''' the specified number of elements has been dropped already

'''Backpressures when''' the specified number of elements has been dropped and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

dropWithin

public Flow<In,Out,Mat> dropWithin(Duration duration)

Discard the elements received within the given duration at beginning of the stream.

'''Emits when''' the specified time elapsed and a new upstream element arrives

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

takeWhile

public Flow<In,Out,Mat> takeWhile(Predicate<Out> p,
 boolean inclusive)

Terminate processing (and cancel the upstream publisher) after predicate returns false for the first time. When inclusive is true, include the element for which the predicate returned false. Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.

The stream will be completed without producing any elements if predicate is false for the first stream element.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the predicate is true

'''Backpressures when''' downstream backpressures

'''Completes when''' predicate returned false (or 1 after predicate returns false if inclusive or upstream completes

'''Cancels when''' predicate returned false or downstream cancels

See also Flow.limit, Flow.limitWeighted

takeWhile

public Flow<In,Out,Mat> takeWhile(Predicate<Out> p)

Terminate processing (and cancel the upstream publisher) after predicate returns false for the first time. When inclusive is true, include the element for which the predicate returned false. Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.

The stream will be completed without producing any elements if predicate is false for the first stream element.

'''Emits when''' the predicate is true

'''Backpressures when''' downstream backpressures

'''Completes when''' predicate returned false (or 1 after predicate returns false if inclusive or upstream completes

'''Cancels when''' predicate returned false or downstream cancels

See also Flow.limit, Flow.limitWeighted

takeUntil

public Flow<In,Out,Mat> takeUntil(Predicate<Out> p)

Terminate processing (and cancel the upstream publisher) after predicate returns true for the first time, Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.

'''Emits when''' the predicate is false or the first time the predicate is true

'''Backpressures when''' downstream backpressures

'''Completes when''' after predicate returned true or upstream completes

'''Cancels when''' after predicate returned true or downstream cancels

See also Flow.limit, Flow.limitWeighted, Flow.takeWhile

Since:

1.2.0

dropWhile

public Flow<In,Out,Mat> dropWhile(Predicate<Out> p)

Discard elements at the beginning of the stream while predicate is true. All elements will be taken after predicate returns false first time.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' predicate returned false and for all following stream elements

'''Backpressures when''' predicate returned false and downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

recover

public Flow<In,Out,Mat> recover(scala.PartialFunction<Throwable,Out> pf)

Recover allows to send last element on failure and gracefully complete the stream

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recover _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and pf returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

recover

public Flow<In,Out,Mat> recover(Class<? extends Throwable> clazz,
 Creator<Out> creator)

Recover allows to send last element on failure and gracefully complete the stream.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recover _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and pf returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

recover

public Flow<In,Out,Mat> recover(Class<? extends Throwable> clazz,
 Out fallbackValue)

Recover allows to send last element on failure and gracefully complete the stream.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recover _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and pf returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

Since:

1.3.0

recover

public Flow<In,Out,Mat> recover(Predicate<? super Throwable> p,
 Creator<Out> creator)

Recover allows to send last element on failure and gracefully complete the stream.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recover _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and pf returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

Since:

1.3.0

recover

public Flow<In,Out,Mat> recover(Predicate<? super Throwable> p,
 Out fallbackValue)

Recover allows to send last element on failure and gracefully complete the stream.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recover _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and pf returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

Since:

1.3.0

mapError

public Flow<In,Out,Mat> mapError(scala.PartialFunction<Throwable,Throwable> pf)

While similar to recover(scala.PartialFunction<java.lang.Throwable,Out>) this operator can be used to transform an error signal to a different one *without* logging it as an error in the process. So in that sense it is NOT exactly equivalent to recover(t => throw t2) since recover would log the t2 error.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Similarly to recover(scala.PartialFunction<java.lang.Throwable,Out>) throwing an exception inside mapError _will_ be logged.

'''Emits when''' element is available from the upstream or upstream is failed and pf returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

mapError

public <E extends Throwable> Flow<In,Out,Mat> mapError(Class<E> clazz,
 Function<E,Throwable> f)

While similar to recover(scala.PartialFunction<java.lang.Throwable,Out>) this operator can be used to transform an error signal to a different one *without* logging it as an error in the process. So in that sense it is NOT exactly equivalent to recover(t => throw t2) since recover would log the t2 error.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Similarly to recover(scala.PartialFunction<java.lang.Throwable,Out>) throwing an exception inside mapError _will_ be logged.

'''Emits when''' element is available from the upstream or upstream is failed and pf returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

recoverWith

public Flow<In,Out,Mat> recoverWith(scala.PartialFunction<Throwable,? extends Graph<SourceShape<Out>,NotUsed>> pf)

RecoverWith allows to switch to alternative Source on flow failure. It will stay in effect after a failure has been recovered so that each time there is a failure it is fed into the pf and a new Source may be materialized.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recoverWith _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and element is available from alternative Source

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

recoverWith

public Flow<In,Out,Mat> recoverWith(Class<? extends Throwable> clazz,
 Creator<Graph<SourceShape<Out>,NotUsed>> creator)

RecoverWith allows to switch to alternative Source on flow failure. It will stay in effect after a failure has been recovered so that each time there is a failure it is fed into the pf and a new Source may be materialized.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recoverWith _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and element is available from alternative Source

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

recoverWithRetries

public Flow<In,Out,Mat> recoverWithRetries(int attempts,
 scala.PartialFunction<Throwable,Graph<SourceShape<Out>,NotUsed>> pf)

RecoverWithRetries allows to switch to alternative Source on flow failure. It will stay in effect after a failure has been recovered up to attempts number of times so that each time there is a failure it is fed into the pf and a new Source may be materialized. Note that if you pass in 0, this won't attempt to recover at all.

A negative attempts number is interpreted as "infinite", which results in the exact same behavior as recoverWith.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recoverWithRetries _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and element is available from alternative Source

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

Parameters:

attempts - Maximum number of retries or -1 to retry indefinitely

pf - Receives the failure cause and returns the new Source to be materialized if any

recoverWithRetries

public Flow<In,Out,Mat> recoverWithRetries(int attempts,
 Class<? extends Throwable> clazz,
 Creator<Graph<SourceShape<Out>,NotUsed>> creator)

RecoverWithRetries allows to switch to alternative Source on flow failure. It will stay in effect after a failure has been recovered up to attempts number of times so that each time there is a failure it is fed into the pf and a new Source may be materialized. Note that if you pass in 0, this won't attempt to recover at all.

A negative attempts number is interpreted as "infinite", which results in the exact same behavior as recoverWith.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

Throwing an exception inside recoverWithRetries _will_ be logged on ERROR level automatically.

'''Emits when''' element is available from the upstream or upstream is failed and element is available from alternative Source

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception pf can handle

'''Cancels when''' downstream cancels

Parameters:

attempts - Maximum number of retries or -1 to retry indefinitely

clazz - the class object of the failure cause

creator - supply the new Source to be materialized

onErrorComplete

public Flow<In,Out,Mat> onErrorComplete()

onErrorComplete allows to complete the stream when an upstream error occurs.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

'''Emits when''' element is available from the upstream

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or failed with exception is an instance of the provided type

'''Cancels when''' downstream cancels

Since:

1.1.0

onErrorComplete

public Flow<In,Out,Mat> onErrorComplete(Class<? extends Throwable> clazz)

onErrorComplete allows to complete the stream when an upstream error occurs.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

'''Emits when''' element is available from the upstream

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or failed with exception is an instance of the provided type

'''Cancels when''' downstream cancels

Since:

1.1.0

onErrorComplete

public Flow<In,Out,Mat> onErrorComplete(Predicate<? super Throwable> predicate)

onErrorComplete allows to complete the stream when an upstream error occurs.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

'''Emits when''' element is available from the upstream

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or failed with predicate return true

'''Cancels when''' downstream cancels

Since:

1.1.0

onErrorContinue

public Flow<In,Out,Mat> onErrorContinue(Procedure<? super Throwable> errorConsumer)

Continues the stream when an upstream error occurs.

When an error is signaled from upstream, the errorConsumer function is invoked with the Throwable, and the stream resumes processing subsequent elements. The element that caused the error is dropped.

'''Note:''' This operator requires stream operators to support supervision. If supervision is not supported, this operator will have no effect.

'''Emits when''' an element is available from upstream

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

errorConsumer - function invoked when an error occurs

Since:

1.3.0

onErrorContinue

public <T extends Throwable> Flow<In,Out,Mat> onErrorContinue(Class<T> clazz,
 Procedure<? super Throwable> errorConsumer)

Continues the stream when an upstream error occurs.

When an error is signaled from upstream, the errorConsumer function is invoked with the Throwable, and the stream resumes processing subsequent elements. The element that caused the error is dropped.

'''Note:''' This operator requires stream operators to support supervision. If supervision is not supported, this operator will have no effect.

'''Emits when''' an element is available from upstream

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

clazz - the class of the failure cause

errorConsumer - function invoked when an error occurs

Since:

1.3.0

onErrorContinue

public <T extends Throwable> Flow<In,Out,Mat> onErrorContinue(Predicate<? super Throwable> predicate,
 Procedure<? super Throwable> errorConsumer)

Continues the stream when an upstream error occurs.

When an error is signaled from upstream, the errorConsumer function is invoked with the Throwable, and the stream resumes processing subsequent elements. The element that caused the error is dropped.

'''Note:''' This operator requires stream operators to support supervision. If supervision is not supported, this operator will have no effect.

'''Emits when''' an element is available from upstream

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

p - predicate which determines if the exception should be handled

errorConsumer - function invoked when an error occurs

Since:

1.3.0

onErrorResume

public <T> Flow<In,T,Mat> onErrorResume(Function<? super Throwable,? extends Graph<SourceShape<T>,NotUsed>> fallback)

Transform a failure signal into a stream of elements provided by a factory function. This allows to continue processing with another stream when a failure occurs.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

'''Emits when''' element is available from the upstream or upstream is failed and fallback Source produces an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception and fallback Source completes

'''Cancels when''' downstream cancels

Parameters:

fallback - Function which produces a Source to continue the stream

Since:

1.3.0

onErrorResume

public <T> Flow<In,T,Mat> onErrorResume(Class<? extends Throwable> clazz,
 Function<? super Throwable,? extends Graph<SourceShape<T>,NotUsed>> fallback)

Transform a failure signal into a stream of elements provided by a factory function. This allows to continue processing with another stream when a failure occurs.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

'''Emits when''' element is available from the upstream or upstream is failed and fallback Source produces an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception and fallback Source completes

'''Cancels when''' downstream cancels

Parameters:

clazz - the class object of the failure cause

fallback - Function which produces a Source to continue the stream

Since:

1.3.0

onErrorResume

public <T> Flow<In,T,Mat> onErrorResume(Predicate<? super Throwable> predicate,
 Function<? super Throwable,? extends Graph<SourceShape<T>,NotUsed>> fallback)

Transform a failure signal into a stream of elements provided by a factory function. This allows to continue processing with another stream when a failure occurs.

Since the underlying failure signal onError arrives out-of-band, it might jump over existing elements. This operator can recover the failure signal, but not the skipped elements, which will be dropped.

'''Emits when''' element is available from the upstream or upstream is failed and fallback Source produces an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or upstream failed with exception and fallback Source completes

'''Cancels when''' downstream cancels

Parameters:

predicate - Predicate which determines if the exception should be handled

fallback - Function which produces a Source to continue the stream

Since:

1.3.0

take

public Flow<In,Out,Mat> take(long n)

Terminate processing (and cancel the upstream publisher) after the given number of elements. Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.

The stream will be completed without producing any elements if n is zero or negative.

'''Emits when''' the specified number of elements to take has not yet been reached

'''Backpressures when''' downstream backpressures

'''Completes when''' the defined number of elements has been taken or upstream completes

'''Cancels when''' the defined number of elements has been taken or downstream cancels

See also Flow.limit, Flow.limitWeighted

takeWithin

public Flow<In,Out,Mat> takeWithin(Duration duration)

Terminate processing (and cancel the upstream publisher) after the given duration. Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.

Note that this can be combined with take(long) to limit the number of elements within the duration.

'''Emits when''' an upstream element arrives

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or timer fires

'''Cancels when''' downstream cancels or timer fires

See also Flow.limit, Flow.limitWeighted

conflateWithSeed

public <S> Flow<In,S,Mat> conflateWithSeed(Function<Out,S> seed,
 Function2<S,Out,S> aggregate)

Allows a faster upstream to progress independently of a slower subscriber by conflating elements into a summary until the subscriber is ready to accept them. For example a conflate step might average incoming numbers if the upstream publisher is faster.

This version of conflate allows to derive a seed from the first element and change the aggregated type to be different than the input type. See Flow.conflate for a simpler version that does not change types.

This element only rolls up elements if the upstream is faster, but if the downstream is faster it will not duplicate elements.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' downstream stops backpressuring and there is a conflated element available

'''Backpressures when''' never

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

see also Flow.conflate Flow.batch Flow.batchWeighted

Parameters:

seed - Provides the first state for a conflated value using the first unconsumed element as a start

aggregate - Takes the currently aggregated value and the current pending element to produce a new aggregate

conflate

public Flow<In,Out,Mat> conflate(Function2<Out,Out,Out> aggregate)

Allows a faster upstream to progress independently of a slower subscriber by conflating elements into a summary until the subscriber is ready to accept them. For example a conflate step might average incoming numbers if the upstream publisher is faster.

This version of conflate does not change the output type of the stream. See Flow.conflateWithSeed for a more flexible version that can take a seed function and transform elements while rolling up.

This element only rolls up elements if the upstream is faster, but if the downstream is faster it will not duplicate elements.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' downstream stops backpressuring and there is a conflated element available

'''Backpressures when''' never

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

see also Flow.conflateWithSeed Flow.batch Flow.batchWeighted

Parameters:

aggregate - Takes the currently aggregated value and the current pending element to produce a new aggregate

batch

public <S> Flow<In,S,Mat> batch(long max,
 Function<Out,S> seed,
 Function2<S,Out,S> aggregate)

Allows a faster upstream to progress independently of a slower subscriber by aggregating elements into batches until the subscriber is ready to accept them. For example a batch step might store received elements in an array up to the allowed max limit if the upstream publisher is faster.

This element only rolls up elements if the upstream is faster, but if the downstream is faster it will not duplicate elements.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' downstream stops backpressuring and there is an aggregated element available

'''Backpressures when''' there are max batched elements and 1 pending element and downstream backpressures

'''Completes when''' upstream completes and there is no batched/pending element waiting

'''Cancels when''' downstream cancels

See also Flow.conflate, Flow.batchWeighted

Parameters:

max - maximum number of elements to batch before backpressuring upstream (must be positive non-zero)

seed - Provides the first state for a batched value using the first unconsumed element as a start

aggregate - Takes the currently batched value and the current pending element to produce a new aggregate

batchWeighted

public <S> Flow<In,S,Mat> batchWeighted(long max,
 Function<Out,Long> costFn,
 Function<Out,S> seed,
 Function2<S,Out,S> aggregate)

Allows a faster upstream to progress independently of a slower subscriber by aggregating elements into batches until the subscriber is ready to accept them. For example a batch step might concatenate ByteString elements up to the allowed max limit if the upstream publisher is faster.

This element only rolls up elements if the upstream is faster, but if the downstream is faster it will not duplicate elements.

Batching will apply for all elements, even if a single element cost is greater than the total allowed limit. In this case, previous batched elements will be emitted, then the "heavy" element will be emitted (after being applied with the seed function) without batching further elements with it, and then the rest of the incoming elements are batched.

'''Emits when''' downstream stops backpressuring and there is a batched element available

'''Backpressures when''' there are max weighted batched elements + 1 pending element and downstream backpressures

'''Completes when''' upstream completes and there is no batched/pending element waiting

'''Cancels when''' downstream cancels

See also Flow.conflate, Flow.batch

Parameters:

max - maximum weight of elements to batch before backpressuring upstream (must be positive non-zero)

costFn - a function to compute a single element weight

seed - Provides the first state for a batched value using the first unconsumed element as a start

aggregate - Takes the currently batched value and the current pending element to produce a new batch

expand

public <U> Flow<In,U,Mat> expand(Function<Out,Iterator<U>> expander)

Allows a faster downstream to progress independently of a slower upstream by extrapolating elements from an older element until new element comes from the upstream. For example an expand step might repeat the last element for the subscriber until it receives an update from upstream.

This element will never "drop" upstream elements as all elements go through at least one extrapolation step. This means that if the upstream is actually faster than the upstream it will be backpressured by the downstream subscriber.

Expand does not support pekko.stream.Supervision#restart and pekko.stream.Supervision#resume. Exceptions from the expander function will complete the stream with failure.

See also extrapolate(org.apache.pekko.japi.function.Function<Out, java.util.Iterator<Out>>) for a version that always preserves the original element and allows for an initial "startup" element.

'''Emits when''' downstream stops backpressuring

'''Backpressures when''' downstream backpressures or iterator runs empty

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

Parameters:

expander - Takes the current extrapolation state to produce an output element and the next extrapolation state.

See Also:

• extrapolate(org.apache.pekko.japi.function.Function<Out, java.util.Iterator<Out>>)

extrapolate

public Flow<In,Out,Mat> extrapolate(Function<Out,Iterator<Out>> extrapolator)

Allows a faster downstream to progress independent of a slower upstream.

This is achieved by introducing "extrapolated" elements - based on those from upstream - whenever downstream signals demand.

Extrapolate does not support pekko.stream.Supervision#restart and pekko.stream.Supervision#resume. Exceptions from the extrapolate function will complete the stream with failure.

See also expand(org.apache.pekko.japi.function.Function<Out, java.util.Iterator<U>>) for a version that can overwrite the original element.

'''Emits when''' downstream stops backpressuring, AND EITHER upstream emits OR initial element is present OR extrapolate is non-empty and applicable

'''Backpressures when''' downstream backpressures or current extrapolate runs empty

'''Completes when''' upstream completes and current extrapolate runs empty

'''Cancels when''' downstream cancels

Parameters:

extrapolator - Takes the current upstream element and provides a sequence of "extrapolated" elements based on the original, to be emitted in case downstream signals demand.

See Also:

• expand(org.apache.pekko.japi.function.Function<Out, java.util.Iterator<U>>)

extrapolate

public Flow<In,Out,Mat> extrapolate(Function<Out,Iterator<Out>> extrapolator,
 Out initial)

Allows a faster downstream to progress independent of a slower upstream.

This is achieved by introducing "extrapolated" elements - based on those from upstream - whenever downstream signals demand.

Extrapolate does not support pekko.stream.Supervision#restart and pekko.stream.Supervision#resume. Exceptions from the extrapolate function will complete the stream with failure.

See also expand(org.apache.pekko.japi.function.Function<Out, java.util.Iterator<U>>) for a version that can overwrite the original element.

'''Emits when''' downstream stops backpressuring, AND EITHER upstream emits OR initial element is present OR extrapolate is non-empty and applicable

'''Backpressures when''' downstream backpressures or current extrapolate runs empty

'''Completes when''' upstream completes and current extrapolate runs empty

'''Cancels when''' downstream cancels

Parameters:

extrapolator - Takes the current upstream element and provides a sequence of "extrapolated" elements based on the original, to be emitted in case downstream signals demand.

initial - The initial element to be emitted, in case upstream is able to stall the entire stream.

See Also:

• expand(org.apache.pekko.japi.function.Function<Out, java.util.Iterator<U>>)

buffer

public Flow<In,Out,Mat> buffer(int size,
 OverflowStrategy overflowStrategy)

Adds a fixed size buffer in the flow that allows to store elements from a faster upstream until it becomes full. Depending on the defined pekko.stream.OverflowStrategy it might drop elements or backpressure the upstream if there is no space available

'''Emits when''' downstream stops backpressuring and there is a pending element in the buffer

'''Backpressures when''' downstream backpressures or depending on OverflowStrategy:

• Backpressure - backpressures when buffer is full
• DropHead, DropTail, DropBuffer - never backpressures
• Fail - fails the stream if buffer gets full

'''Completes when''' upstream completes and buffered elements have been drained

'''Cancels when''' downstream cancels

Parameters:

size - The size of the buffer in element count

overflowStrategy - Strategy that is used when incoming elements cannot fit inside the buffer

prefixAndTail

public Flow<In,Pair<List<Out>,Source<Out,NotUsed>>,Mat> prefixAndTail(int n)

Takes up to n elements from the stream (less than n if the upstream completes before emitting n elements) and returns a pair containing a strict sequence of the taken element and a stream representing the remaining elements. If ''n'' is zero or negative, then this will return a pair of an empty collection and a stream containing the whole upstream unchanged.

In case of an upstream error, depending on the current state - the master stream signals the error if less than n elements have been seen, and therefore the substream has not yet been emitted - the tail substream signals the error after the prefix and tail has been emitted by the main stream (at that point the main stream has already completed)

'''Emits when''' the configured number of prefix elements are available. Emits this prefix, and the rest as a substream

'''Backpressures when''' downstream backpressures or substream backpressures

'''Completes when''' prefix elements have been consumed and substream has been consumed

'''Cancels when''' downstream cancels or substream cancels

flatMapPrefix

public <Out2,
Mat2> Flow<In,Out2,Mat> flatMapPrefix(int n,
 Function<List<Out>,Flow<Out,Out2,Mat2>> f)

Takes up to n elements from the stream (less than n only if the upstream completes before emitting n elements), then apply f on these elements in order to obtain a flow, this flow is then materialized and the rest of the input is processed by this flow (similar to via). This method returns a flow consuming the rest of the stream producing the materialized flow's output.

'''Emits when''' the materialized flow emits. Notice the first n elements are buffered internally before materializing the flow and connecting it to the rest of the upstream - producing elements at its own discretion (might 'swallow' or multiply elements).

'''Backpressures when''' downstream backpressures

'''Completes when''' the materialized flow completes. If upstream completes before producing n elements, f will be applied with the provided elements, the resulting flow will be materialized and signalled for upstream completion, it can then complete or continue to emit elements at its own discretion.

'''Cancels when''' the materialized flow cancels. Notice that when downstream cancels prior to prefix completion, the cancellation cause is stashed until prefix completion (or upstream completion) and then handed to the materialized flow.

Parameters:

n - the number of elements to accumulate before materializing the downstream flow.

f - a function that produces the downstream flow based on the upstream's prefix.

flatMapPrefixMat

public <Out2,
Mat2,
Mat3> Flow<In,Out2,Mat3> flatMapPrefixMat(int n,
 Function<List<Out>,Flow<Out,Out2,Mat2>> f,
 Function2<Mat,CompletionStage<Mat2>,Mat3> matF)

mat version of flatMapPrefix(int, org.apache.pekko.japi.function.Function<java.util.List<Out>, org.apache.pekko.stream.javadsl.Flow<Out, Out2, Mat2>>), this method gives access to a future materialized value of the downstream flow (as a completion stage). see flatMapPrefix(int, org.apache.pekko.japi.function.Function<java.util.List<Out>, org.apache.pekko.stream.javadsl.Flow<Out, Out2, Mat2>>) for details.

groupBy

public <K> SubFlow<In,Out,Mat> groupBy(int maxSubstreams,
 Function<Out,K> f,
 boolean allowClosedSubstreamRecreation)

This operation demultiplexes the incoming stream into separate output streams, one for each element key. The key is computed for each element using the given function. When a new key is encountered for the first time a new substream is opened and subsequently fed with all elements belonging to that key.

WARNING: If allowClosedSubstreamRecreation is set to false (default behavior) the operator keeps track of all keys of streams that have already been closed. If you expect an infinite number of keys this can cause memory issues. Elements belonging to those keys are drained directly and not send to the substream.

Note: If allowClosedSubstreamRecreation is set to true substream completion and incoming elements are subject to race-conditions. If elements arrive for a stream that is in the process of closing these elements might get lost.

The object returned from this method is not a normal Flow, it is a SubFlow. This means that after this operator all transformations are applied to all encountered substreams in the same fashion. Substream mode is exited either by closing the substream (i.e. connecting it to a Sink) or by merging the substreams back together; see the to and mergeBack methods on SubFlow for more information.

It is important to note that the substreams also propagate back-pressure as any other stream, which means that blocking one substream will block the groupBy operator itself—and thereby all substreams—once all internal or explicit buffers are filled.

If the group by function f throws an exception and the supervision decision is pekko.stream.Supervision#stop the stream and substreams will be completed with failure.

If the group by function f throws an exception and the supervision decision is pekko.stream.Supervision#resume or pekko.stream.Supervision#restart the element is dropped and the stream and substreams continue.

Function f MUST NOT return null. This will throw exception and trigger supervision decision mechanism.

'''Emits when''' an element for which the grouping function returns a group that has not yet been created. Emits the new group

'''Backpressures when''' there is an element pending for a group whose substream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels and all substreams cancel

Parameters:

maxSubstreams - configures the maximum number of substreams (keys) that are supported; if more distinct keys are encountered then the stream fails

f - computes the key for each element

allowClosedSubstreamRecreation - enables recreation of already closed substreams if elements with their corresponding keys arrive after completion

groupBy

public <K> SubFlow<In,Out,Mat> groupBy(int maxSubstreams,
 Function<Out,K> f)

This operation demultiplexes the incoming stream into separate output streams, one for each element key. The key is computed for each element using the given function. When a new key is encountered for the first time a new substream is opened and subsequently fed with all elements belonging to that key.

WARNING: The operator keeps track of all keys of streams that have already been closed. If you expect an infinite number of keys this can cause memory issues. Elements belonging to those keys are drained directly and not send to the substream.

See Also:

• groupBy(int, org.apache.pekko.japi.function.Function<Out, K>, boolean)

splitWhen

public SubFlow<In,Out,Mat> splitWhen(Predicate<Out> p)

This operation applies the given predicate to all incoming elements and emits them to a stream of output streams, always beginning a new one with the current element if the given predicate returns true for it. This means that for the following series of predicate values, three substreams will be produced with lengths 1, 2, and 3:

 false,             // element goes into first substream
 true, false,       // elements go into second substream
 true, false, false // elements go into third substream
 

In case the *first* element of the stream matches the predicate, the first substream emitted by splitWhen will start from that element. For example:

 true, false, false // first substream starts from the split-by element
 true, false        // subsequent substreams operate the same way
 

The object returned from this method is not a normal Flow, it is a SubFlow. This means that after this operator all transformations are applied to all encountered substreams in the same fashion. Substream mode is exited either by closing the substream (i.e. connecting it to a Sink) or by merging the substreams back together; see the to and mergeBack methods on SubFlow for more information.

It is important to note that the substreams also propagate back-pressure as any other stream, which means that blocking one substream will block the splitWhen operator itself—and thereby all substreams—once all internal or explicit buffers are filled.

If the split predicate p throws an exception and the supervision decision is pekko.stream.Supervision#stop the stream and substreams will be completed with failure.

If the split predicate p throws an exception and the supervision decision is pekko.stream.Supervision#resume or pekko.stream.Supervision#restart the element is dropped and the stream and substreams continue.

'''Emits when''' an element for which the provided predicate is true, opening and emitting a new substream for subsequent element

'''Backpressures when''' there is an element pending for the next substream, but the previous is not fully consumed yet, or the substream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels and substreams cancel on SubstreamCancelStrategy.drain(), downstream cancels or any substream cancels on SubstreamCancelStrategy.propagate()

See also Flow.splitAfter.

splitWhen

public SubFlow<In,Out,Mat> splitWhen(SubstreamCancelStrategy substreamCancelStrategy,
 Predicate<Out> p)

Deprecated.

Use .withAttributes(ActorAttributes.supervisionStrategy(equivalentDecider)) rather than a SubstreamCancelStrategy. Since 1.1.0.

This operation applies the given predicate to all incoming elements and emits them to a stream of output streams, always beginning a new one with the current element if the given predicate returns true for it.

See Also:

• splitWhen(org.apache.pekko.japi.function.Predicate<Out>)

splitAfter

public SubFlow<In,Out,Mat> splitAfter(Predicate<Out> p)

This operation applies the given predicate to all incoming elements and emits them to a stream of output streams. It *ends* the current substream when the predicate is true. This means that for the following series of predicate values, three substreams will be produced with lengths 2, 2, and 3:

 false, true,        // elements go into first substream
 false, true,        // elements go into second substream
 false, false, true  // elements go into third substream
 

The object returned from this method is not a normal Flow, it is a SubFlow. This means that after this operator all transformations are applied to all encountered substreams in the same fashion. Substream mode is exited either by closing the substream (i.e. connecting it to a Sink) or by merging the substreams back together; see the to and mergeBack methods on SubFlow for more information.

It is important to note that the substreams also propagate back-pressure as any other stream, which means that blocking one substream will block the splitAfter operator itself—and thereby all substreams—once all internal or explicit buffers are filled.

If the split predicate p throws an exception and the supervision decision is pekko.stream.Supervision.Stop the stream and substreams will be completed with failure.

If the split predicate p throws an exception and the supervision decision is pekko.stream.Supervision.Resume or pekko.stream.Supervision.Restart the element is dropped and the stream and substreams continue.

'''Emits when''' an element passes through. When the provided predicate is true it emits the element and opens a new substream for subsequent element

'''Backpressures when''' there is an element pending for the next substream, but the previous is not fully consumed yet, or the substream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels and substreams cancel on SubstreamCancelStrategy.drain, downstream cancels or any substream cancels on SubstreamCancelStrategy.propagate

See also Flow.splitWhen.

splitAfter

public SubFlow<In,Out,Mat> splitAfter(SubstreamCancelStrategy substreamCancelStrategy,
 Predicate<Out> p)

Deprecated.

Use .withAttributes(ActorAttributes.supervisionStrategy(equivalentDecider)) rather than a SubstreamCancelStrategy. Since 1.1.0.

This operation applies the given predicate to all incoming elements and emits them to a stream of output streams. It *ends* the current substream when the predicate is true.

See Also:

• splitAfter(org.apache.pekko.japi.function.Predicate<Out>)

flatMapConcat

public <T,
M> Flow<In,T,Mat> flatMapConcat(Function<Out,? extends Graph<SourceShape<T>,M>> f)

Transform each input element into a Source of output elements that is then flattened into the output stream by concatenation, fully consuming one Source after the other.

'''Emits when''' a currently consumed substream has an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes and all consumed substreams complete

'''Cancels when''' downstream cancels

flatMapConcat

public <T,
M> Flow<In,T,Mat> flatMapConcat(int parallelism,
 Function<Out,? extends Graph<SourceShape<T>,M>> f)

Transform each input element into a Source of output elements that is then flattened into the output stream by concatenation, fully consuming one Source after the other. parallelism can be used to config the max inflight sources, which will be materialized at the same time.

'''Emits when''' a currently consumed substream has an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes and all consumed substreams complete

'''Cancels when''' downstream cancels

Since:

1.2.0

flatMapMerge

public <T,
M> Flow<In,T,Mat> flatMapMerge(int breadth,
 Function<Out,? extends Graph<SourceShape<T>,M>> f)

Transform each input element into a Source of output elements that is then flattened into the output stream by merging, where at most breadth substreams are being consumed at any given time.

'''Emits when''' a currently consumed substream has an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes and all consumed substreams complete

'''Cancels when''' downstream cancels

switchMap

public <T,
M> Flow<In,T,Mat> switchMap(Function<Out,? extends Graph<SourceShape<T>,M>> f)

Transforms each input element into a Source of output elements that is then flattened into the output stream until a new input element is received at which point the current (now previous) substream is cancelled (which is why this operator is sometimes also called "flatMapLatest").

'''Emits when''' the current substream has an element available

'''Backpressures when''' never

'''Completes when''' upstream completes and the current substream completes

'''Cancels when''' downstream cancels

Since:

1.2.0

concat

public <M> Flow<In,Out,Mat> concat(Graph<SourceShape<Out>,M> that)

Concatenate the given Source to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.

Note that the Source is materialized together with this Flow and is "detached" meaning it will in effect behave as a one element buffer in front of both the sources, that eagerly demands an element on start (so it can not be combined with Source.lazy to defer materialization of that).

The second source is then kept from producing elements by asserting back-pressure until its time comes.

When needing a concat operator that is not detached use concatLazy(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

'''Emits when''' element is available from current stream or from the given Source when current is completed

'''Backpressures when''' downstream backpressures

'''Completes when''' given Source completes

'''Cancels when''' downstream cancels

concatLazy

public <M> Flow<In,Out,Mat> concatLazy(Graph<SourceShape<Out>,M> that)

Concatenate the given Source to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.

Note that the Source is materialized together with this Flow. If lazy materialization is what is needed the operator can be combined with for example Source.lazySource to defer materialization of that until the time when this source completes.

The second source is then kept from producing elements by asserting back-pressure until its time comes.

For a concat operator that is detached, use concat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

If this Flow gets upstream error - no elements from the given Source will be pulled.

'''Emits when''' element is available from current stream or from the given Source when current is completed

'''Backpressures when''' downstream backpressures

'''Completes when''' given Source completes

'''Cancels when''' downstream cancels

concatAllLazy

public Flow<In,Out,Mat> concatAllLazy(scala.collection.immutable.Seq<Graph<SourceShape<Out>,?>> those)

Concatenate the given Sources to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.

Note that the Sources are materialized together with this Flow. If lazy materialization is what is needed the operator can be combined with for example Source.lazySource to defer materialization of that until the time when this source completes.

The second source is then kept from producing elements by asserting back-pressure until its time comes.

For a concat operator that is detached, use concat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

If this Flow gets upstream error - no elements from the given Sources will be pulled.

'''Emits when''' element is available from current stream or from the given Sources when current is completed

'''Backpressures when''' downstream backpressures

'''Completes when''' given all those Sources completes

'''Cancels when''' downstream cancels

concatMat

public <M,
M2> Flow<In,Out,M2> concatMat(Graph<SourceShape<Out>,M> that,
 Function2<Mat,M,M2> matF)

Concatenate the given Source to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.

Note that the Source is materialized together with this Flow and is "detached" meaning it will in effect behave as a one element buffer in front of both the sources, that eagerly demands an element on start (so it can not be combined with Source.lazy to defer materialization of that).

The second source is then kept from producing elements by asserting back-pressure until its time comes.

When needing a concat operator that is not detached use concatLazyMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>, org.apache.pekko.japi.function.Function2<Mat, M, M2>)

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• concat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

concatLazyMat

public <M,
M2> Flow<In,Out,M2> concatLazyMat(Graph<SourceShape<Out>,M> that,
 Function2<Mat,M,M2> matF)

Concatenate the given Source to this Flow, meaning that once this Flow&rsquo;s input is exhausted and all result elements have been generated, the Source&rsquo;s elements will be produced.

Note that the Source is materialized together with this Flow, if lazy materialization is what is needed the operator can be combined with Source.lazy to defer materialization of that.

The second source is then kept from producing elements by asserting back-pressure until its time comes.

For a concat operator that is detached, use concatMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>, org.apache.pekko.japi.function.Function2<Mat, M, M2>)

prepend

public <M> Flow<In,Out,Mat> prepend(Graph<SourceShape<Out>,M> that)

Prepend the given Source to this Flow, meaning that before elements are generated from this Flow, the Source's elements will be produced until it is exhausted, at which point Flow elements will start being produced.

Note that the Source is materialized together with this Flow and is "detached" meaning in effect behave as a one element buffer in front of both the sources, that eagerly demands an element on start (so it can not be combined with Source.lazy to defer materialization of that).

This flow will then be kept from producing elements by asserting back-pressure until its time comes.

When needing a prepend operator that is not detached use prependLazy(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

'''Emits when''' element is available from the given Source or from current stream when the Source is completed

'''Backpressures when''' downstream backpressures

'''Completes when''' this Flow completes

'''Cancels when''' downstream cancels

prependLazy

public <M> Flow<In,Out,Mat> prependLazy(Graph<SourceShape<Out>,M> that)

Prepend the given Source to this Flow, meaning that before elements are generated from this Flow, the Source's elements will be produced until it is exhausted, at which point Flow elements will start being produced.

Note that the Source is materialized together with this Flow and will then be kept from producing elements by asserting back-pressure until its time comes.

When needing a prepend operator that is also detached use prepend(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

If the given Source gets upstream error - no elements from this Flow will be pulled.

'''Emits when''' element is available from the given Source or from current stream when the Source is completed

'''Backpressures when''' downstream backpressures

'''Completes when''' this Flow completes

'''Cancels when''' downstream cancels

prependMat

public <M,
M2> Flow<In,Out,M2> prependMat(Graph<SourceShape<Out>,M> that,
 Function2<Mat,M,M2> matF)

Prepend the given Source to this Flow, meaning that before elements are generated from this Flow, the Source's elements will be produced until it is exhausted, at which point Flow elements will start being produced.

Note that this Flow will be materialized together with the Source and just kept from producing elements by asserting back-pressure until its time comes.

When needing a prepend operator that is not detached use prependLazyMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>, org.apache.pekko.japi.function.Function2<Mat, M, M2>)

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• prepend(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

prependLazyMat

public <M,
M2> Flow<In,Out,M2> prependLazyMat(Graph<SourceShape<Out>,M> that,
 Function2<Mat,M,M2> matF)

Prepend the given Source to this Flow, meaning that before elements are generated from this Flow, the Source's elements will be produced until it is exhausted, at which point Flow elements will start being produced.

Note that the Source is materialized together with this Flow.

This flow will then be kept from producing elements by asserting back-pressure until its time comes.

When needing a prepend operator that is detached use prependMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>, org.apache.pekko.japi.function.Function2<Mat, M, M2>)

orElse

public <M> Flow<In,Out,Mat> orElse(Graph<SourceShape<Out>,M> secondary)

Provides a secondary source that will be consumed if this source completes without any elements passing by. As soon as the first element comes through this stream, the alternative will be cancelled.

Note that this Flow will be materialized together with the Source and just kept from producing elements by asserting back-pressure until its time comes or it gets cancelled.

On errors the operator is failed regardless of source of the error.

'''Emits when''' element is available from first stream or first stream closed without emitting any elements and an element is available from the second stream

'''Backpressures when''' downstream backpressures

'''Completes when''' the primary stream completes after emitting at least one element, when the primary stream completes without emitting and the secondary stream already has completed or when the secondary stream completes

'''Cancels when''' downstream cancels and additionally the alternative is cancelled as soon as an element passes by from this stream.

orElseMat

public <M2,
M3> Flow<In,Out,M3> orElseMat(Graph<SourceShape<Out>,M2> secondary,
 Function2<Mat,M2,M3> matF)

Provides a secondary source that will be consumed if this source completes without any elements passing by. As soon as the first element comes through this stream, the alternative will be cancelled.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• orElse(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, M>)

alsoTo

public Flow<In,Out,Mat> alsoTo(Graph<SinkShape<Out>,?> that)

Attaches the given Sink to this Flow, meaning that elements that passes through will also be sent to the Sink.

It is similar to wireTap(org.apache.pekko.japi.function.Procedure<Out>) but will backpressure instead of dropping elements when the given Sink is not ready.

'''Emits when''' element is available and demand exists both from the Sink and the downstream.

'''Backpressures when''' downstream or Sink backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream or Sink cancels

alsoToAll

public Flow<In,Out,Mat> alsoToAll(scala.collection.immutable.Seq<Graph<SinkShape<Out>,?>> those)

Attaches the given Sinks to this Flow, meaning that elements that passes through will also be sent to all those Sinks.

It is similar to wireTap(org.apache.pekko.japi.function.Procedure<Out>) but will backpressure instead of dropping elements when the given Sinks is not ready.

'''Emits when''' element is available and demand exists both from the Sinks and the downstream.

'''Backpressures when''' downstream or any of the Sinks backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream or any of the Sinks cancels

alsoToMat

public <M2,
M3> Flow<In,Out,M3> alsoToMat(Graph<SinkShape<Out>,M2> that,
 Function2<Mat,M2,M3> matF)

Attaches the given Sink to this Flow, meaning that elements that passes through will also be sent to the Sink.

It is similar to wireTapMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SinkShape<Out>, M2>, org.apache.pekko.japi.function.Function2<Mat, M2, M3>) but will backpressure instead of dropping elements when the given Sink is not ready.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• alsoTo(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SinkShape<Out>, ?>)

divertTo

public Flow<In,Out,Mat> divertTo(Graph<SinkShape<Out>,?> that,
 Predicate<Out> when)

Attaches the given Sink to this Flow, meaning that elements will be sent to the Sink instead of being passed through if the predicate when returns true.

'''Emits when''' emits when an element is available from the input and the chosen output has demand

'''Backpressures when''' the currently chosen output back-pressures

'''Completes when''' upstream completes and no output is pending

'''Cancels when''' any of the downstreams cancel

divertToMat

public <M2,
M3> Flow<In,Out,M3> divertToMat(Graph<SinkShape<Out>,M2> that,
 Predicate<Out> when,
 Function2<Mat,M2,M3> matF)

Attaches the given Sink to this Flow, meaning that elements will be sent to the Sink instead of being passed through if the predicate when returns true.

See Also:

• It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

wireTap

public Flow<In,Out,Mat> wireTap(Graph<SinkShape<Out>,?> that)

Attaches the given Sink to this Flow as a wire tap, meaning that elements that pass through will also be sent to the wire-tap Sink, without the latter affecting the mainline flow. If the wire-tap Sink backpressures, elements that would've been sent to it will be dropped instead.

It is similar to alsoTo(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SinkShape<Out>, ?>) which does backpressure instead of dropping elements.

'''Emits when''' element is available and demand exists from the downstream; the element will also be sent to the wire-tap Sink if there is demand.

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

wireTapMat

public <M2,
M3> Flow<In,Out,M3> wireTapMat(Graph<SinkShape<Out>,M2> that,
 Function2<Mat,M2,M3> matF)

Attaches the given Sink to this Flow as a wire tap, meaning that elements that pass through will also be sent to the wire-tap Sink, without the latter affecting the mainline flow. If the wire-tap Sink backpressures, elements that would've been sent to it will be dropped instead.

It is similar to alsoToMat(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SinkShape<Out>, M2>, org.apache.pekko.japi.function.Function2<Mat, M2, M3>) which does backpressure instead of dropping elements.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• wireTap(org.apache.pekko.japi.function.Procedure<Out>)

interleave

public Flow<In,Out,Mat> interleave(Graph<SourceShape<Out>,?> that,
 int segmentSize)

Interleave is a deterministic merge of the given Source with elements of this Flow. It first emits segmentSize number of elements from this flow to downstream, then - same amount for that source, then repeat process.

Example:

 Source<Integer, ?> src = Source.from(Arrays.asList(1, 2, 3))
 Flow<Integer, Integer, ?> flow = flow.interleave(Source.from(Arrays.asList(4, 5, 6, 7)), 2)
 src.via(flow) // 1, 2, 4, 5, 3, 6, 7
 

After one of upstreams is complete than all the rest elements will be emitted from the second one

If this Flow or Source gets upstream error - stream completes with failure.

'''Emits when''' element is available from the currently consumed upstream

'''Backpressures when''' downstream backpressures. Signal to current upstream, switch to next upstream when received segmentSize elements

'''Completes when''' the Flow and given Source completes

'''Cancels when''' downstream cancels

interleave

public Flow<In,Out,Mat> interleave(Graph<SourceShape<Out>,?> that,
 int segmentSize,
 boolean eagerClose)

Interleave is a deterministic merge of the given Source with elements of this Flow. It first emits segmentSize number of elements from this flow to downstream, then - same amount for that source, then repeat process.

If eagerClose is false and one of the upstreams complete the elements from the other upstream will continue passing through the interleave operator. If eagerClose is true and one of the upstream complete interleave will cancel the other upstream and complete itself.

If this Flow or Source gets upstream error - stream completes with failure.

'''Emits when''' element is available from the currently consumed upstream

'''Backpressures when''' downstream backpressures. Signal to current upstream, switch to next upstream when received segmentSize elements

'''Completes when''' the Flow and given Source completes

'''Cancels when''' downstream cancels

interleaveMat

public <M,
M2> Flow<In,Out,M2> interleaveMat(Graph<SourceShape<Out>,M> that,
 int segmentSize,
 Function2<Mat,M,M2> matF)

Interleave is a deterministic merge of the given Source with elements of this Flow. It first emits segmentSize number of elements from this flow to downstream, then - same amount for that source, then repeat process.

After one of upstreams is complete than all the rest elements will be emitted from the second one

If this Flow or Source gets upstream error - stream completes with failure.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• interleave(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, ?>, int)

interleaveMat

public <M,
M2> Flow<In,Out,M2> interleaveMat(Graph<SourceShape<Out>,M> that,
 int segmentSize,
 boolean eagerClose,
 Function2<Mat,M,M2> matF)

Interleave is a deterministic merge of the given Source with elements of this Flow. It first emits segmentSize number of elements from this flow to downstream, then - same amount for that source, then repeat process.

If eagerClose is false and one of the upstreams complete the elements from the other upstream will continue passing through the interleave operator. If eagerClose is true and one of the upstream complete interleave will cancel the other upstream and complete itself.

If this Flow or Source gets upstream error - stream completes with failure.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• interleave(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, ?>, int)

interleaveAll

public Flow<In,Out,Mat> interleaveAll(List<? extends Graph<SourceShape<Out>,?>> those,
 int segmentSize,
 boolean eagerClose)

Interleave is a deterministic merge of the given Sources with elements of this Flow. It first emits segmentSize number of elements from this flow to downstream, then - same amount for that source, then repeat process.

If eagerClose is false and one of the upstreams complete the elements from the other upstream will continue passing through the interleave operator. If eagerClose is true and one of the upstream complete interleave will cancel the other upstream and complete itself.

If this Flow or Source gets upstream error - stream completes with failure.

'''Emits when''' element is available from the currently consumed upstream

'''Backpressures when''' downstream backpressures. Signal to current upstream, switch to next upstream when received segmentSize elements

'''Completes when''' the Flow and given Source completes

'''Cancels when''' downstream cancels

merge

public Flow<In,Out,Mat> merge(Graph<SourceShape<Out>,?> that)

Merge the given Source to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.

'''Emits when''' one of the inputs has an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' all upstreams complete

'''Cancels when''' downstream cancels

merge

public Flow<In,Out,Mat> merge(Graph<SourceShape<Out>,?> that,
 boolean eagerComplete)

Merge the given Source to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.

'''Emits when''' one of the inputs has an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' all upstreams complete (eagerComplete=false) or one upstream completes (eagerComplete=true), default value is false

'''Cancels when''' downstream cancels

mergeMat

public <M,
M2> Flow<In,Out,M2> mergeMat(Graph<SourceShape<Out>,M> that,
 Function2<Mat,M,M2> matF)

Merge the given Source to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• merge(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, ?>)

mergeMat

public <M,
M2> Flow<In,Out,M2> mergeMat(Graph<SourceShape<Out>,M> that,
 Function2<Mat,M,M2> matF,
 boolean eagerComplete)

Merge the given Source to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• merge(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out>, ?>)

mergeAll

public Flow<In,Out,Mat> mergeAll(List<? extends Graph<SourceShape<Out>,?>> those,
 boolean eagerComplete)

Merge the given Sources to this Flow, taking elements as they arrive from input streams, picking randomly when several elements ready.

'''Emits when''' one of the inputs has an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' all upstreams complete (eagerComplete=false) or one upstream completes (eagerComplete=true), default value is false

'''Cancels when''' downstream cancels

mergeLatest

public Flow<In,List<Out>,Mat> mergeLatest(Graph<SourceShape<Out>,?> that,
 boolean eagerComplete)

MergeLatest joins elements from N input streams into stream of lists of size N. i-th element in list is the latest emitted element from i-th input stream. MergeLatest emits list for each element emitted from some input stream, but only after each input stream emitted at least one element.

'''Emits when''' an element is available from some input and each input emits at least one element from stream start

'''Completes when''' all upstreams complete (eagerClose=false) or one upstream completes (eagerClose=true)

mergeLatestMat

public <Mat2,
Mat3> Flow<In,List<Out>,Mat3> mergeLatestMat(Graph<SourceShape<Out>,Mat2> that,
 boolean eagerComplete,
 Function2<Mat,Mat2,Mat3> matF)

MergeLatest joins elements from N input streams into stream of lists of size N. i-th element in list is the latest emitted element from i-th input stream. MergeLatest emits list for each element emitted from some input stream, but only after each input stream emitted at least one element.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

mergePreferred

public Flow<In,Out,Mat> mergePreferred(Graph<SourceShape<Out>,?> that,
 boolean preferred,
 boolean eagerComplete)

Merge two sources. Prefer one source if both sources have elements ready.

'''emits''' when one of the inputs has an element available. If multiple have elements available, prefer the 'right' one when 'preferred' is 'true', or the 'left' one when 'preferred' is 'false'.

'''backpressures''' when downstream backpressures

'''completes''' when all upstreams complete (This behavior is changeable to completing when any upstream completes by setting eagerComplete=true.)

mergePreferredMat

public <Mat2,
Mat3> Flow<In,Out,Mat3> mergePreferredMat(Graph<SourceShape<Out>,Mat2> that,
 boolean preferred,
 boolean eagerComplete,
 Function2<Mat,Mat2,Mat3> matF)

Merge two sources. Prefer one source if both sources have elements ready.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

mergePrioritized

public Flow<In,Out,Mat> mergePrioritized(Graph<SourceShape<Out>,?> that,
 int leftPriority,
 int rightPriority,
 boolean eagerComplete)

Merge two sources. Prefer the sources depending on the 'priority' parameters.

'''emits''' when one of the inputs has an element available, preferring inputs based on the 'priority' parameters if both have elements available

'''backpressures''' when downstream backpressures

'''completes''' when both upstreams complete (This behavior is changeable to completing when any upstream completes by setting eagerComplete=true.)

mergePrioritizedMat

public <Mat2,
Mat3> Flow<In,Out,Mat3> mergePrioritizedMat(Graph<SourceShape<Out>,Mat2> that,
 int leftPriority,
 int rightPriority,
 boolean eagerComplete,
 Function2<Mat,Mat2,Mat3> matF)

Merge two sources. Prefer the sources depending on the 'priority' parameters.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

mergeSorted

public <M> Flow<In,Out,Mat> mergeSorted(Graph<SourceShape<Out>,M> that,
 Comparator<Out> comp)

Merge the given Source to this Flow, taking elements as they arrive from input streams, picking always the smallest of the available elements (waiting for one element from each side to be available). This means that possible contiguity of the input streams is not exploited to avoid waiting for elements, this merge will block when one of the inputs does not have more elements (and does not complete).

'''Emits when''' all of the inputs have an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' all upstreams complete

'''Cancels when''' downstream cancels

mergeSortedMat

public <Mat2,
Mat3> Flow<In,Out,Mat3> mergeSortedMat(Graph<SourceShape<Out>,Mat2> that,
 Comparator<Out> comp,
 Function2<Mat,Mat2,Mat3> matF)

Merge the given Source to this Flow, taking elements as they arrive from input streams, picking always the smallest of the available elements (waiting for one element from each side to be available). This means that possible contiguity of the input streams is not exploited to avoid waiting for elements, this merge will block when one of the inputs does not have more elements (and does not complete).

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

zip

public <T> Flow<In,Pair<Out,T>,Mat> zip(Graph<SourceShape<T>,?> source)

Combine the elements of current Flow and the given Source into a stream of tuples.

'''Emits when''' all of the inputs have an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' any upstream completes

'''Cancels when''' downstream cancels

zipMat

public <T,
M,
M2> Flow<In,Pair<Out,T>,M2> zipMat(Graph<SourceShape<T>,M> that,
 Function2<Mat,M,M2> matF)

Combine the elements of current Flow and the given Source into a stream of tuples.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• zip(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<T>, ?>)

zipAll

public <U,
A> Flow<In,Pair<A,U>,Mat> zipAll(Graph<SourceShape<U>,?> that,
 A thisElem,
 U thatElem)

Combine the elements of current flow and the given Source into a stream of tuples.

'''Emits when''' at first emits when both inputs emit, and then as long as any input emits (coupled to the default value of the completed input).

'''Backpressures when''' downstream backpressures

'''Completes when''' all upstream completes

'''Cancels when''' downstream cancels

zipAllMat

public <U,
Mat2,
Mat3,
A> Flow<In,Pair<A,U>,Mat3> zipAllMat(Graph<SourceShape<U>,Mat2> that,
 A thisElem,
 U thatElem,
 scala.Function2<Mat,Mat2,Mat3> matF)

Combine the elements of current flow and the given Source into a stream of tuples.

See Also:

• '''Emits when''' at first emits when both inputs emit, and then as long as any input emits (coupled to the default value of the completed input).

  '''Backpressures when''' downstream backpressures

  '''Completes when''' all upstream completes

  '''Cancels when''' downstream cancels

zipLatest

public <T> Flow<In,Pair<Out,T>,Mat> zipLatest(Graph<SourceShape<T>,?> source)

Combine the elements of 2 streams into a stream of tuples, picking always the latest element of each.

A ZipLatest has a left and a right input port and one out port.

No element is emitted until at least one element from each Source becomes available.

'''Emits when''' all of the inputs have at least an element available, and then each time an element becomes * available on either of the inputs

'''Backpressures when''' downstream backpressures

'''Completes when''' any upstream completes

'''Cancels when''' downstream cancels

zipLatestMat

public <T,
M,
M2> Flow<In,Pair<Out,T>,M2> zipLatestMat(Graph<SourceShape<T>,M> that,
 Function2<Mat,M,M2> matF)

Combine the elements of current Flow and the given Source into a stream of tuples, picking always the latest element of each.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• zipLatest(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<T>, ?>)

zipWith

public <Out2,
Out3> Flow<In,Out3,Mat> zipWith(Graph<SourceShape<Out2>,?> that,
 Function2<Out,Out2,Out3> combine)

Put together the elements of current Flow and the given Source into a stream of combined elements using a combiner function.

'''Emits when''' all of the inputs have an element available

'''Backpressures when''' downstream backpressures

'''Completes when''' any upstream completes

'''Cancels when''' downstream cancels

zipWithMat

public <Out2,
Out3,
M,
M2> Flow<In,Out3,M2> zipWithMat(Graph<SourceShape<Out2>,M> that,
 Function2<Out,Out2,Out3> combine,
 Function2<Mat,M,M2> matF)

Put together the elements of current Flow and the given Source into a stream of combined elements using a combiner function.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• zipWith(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out2>, ?>, org.apache.pekko.japi.function.Function2<Out, Out2, Out3>)

zipLatestWith

public <Out2,
Out3> Flow<In,Out3,Mat> zipLatestWith(Graph<SourceShape<Out2>,?> that,
 Function2<Out,Out2,Out3> combine)

Combine the elements of multiple streams into a stream of combined elements using a combiner function, picking always the latest of the elements of each source.

No element is emitted until at least one element from each Source becomes available. Whenever a new element appears, the zipping function is invoked with a tuple containing the new element and the other last seen elements.

'''Emits when''' all of the inputs have at least an element available, and then each time an element becomes available on either of the inputs

'''Backpressures when''' downstream backpressures

'''Completes when''' any of the upstreams completes

'''Cancels when''' downstream cancels

zipLatestWith

public <Out2,
Out3> Flow<In,Out3,Mat> zipLatestWith(Graph<SourceShape<Out2>,?> that,
 boolean eagerComplete,
 Function2<Out,Out2,Out3> combine)

Combine the elements of multiple streams into a stream of combined elements using a combiner function, picking always the latest of the elements of each source.

No element is emitted until at least one element from each Source becomes available. Whenever a new element appears, the zipping function is invoked with a tuple containing the new element and the other last seen elements.

'''Emits when''' all of the inputs have at least an element available, and then each time an element becomes available on either of the inputs

'''Backpressures when''' downstream backpressures

'''Completes when''' any upstream completes if eagerComplete is enabled or wait for all upstreams to complete

'''Cancels when''' downstream cancels

zipLatestWithMat

public <Out2,
Out3,
M,
M2> Flow<In,Out3,M2> zipLatestWithMat(Graph<SourceShape<Out2>,M> that,
 boolean eagerComplete,
 Function2<Out,Out2,Out3> combine,
 Function2<Mat,M,M2> matF)

Put together the elements of current Flow and the given Source into a stream of combined elements using a combiner function, picking always the latest element of each.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• zipLatestWith(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out2>, ?>, org.apache.pekko.japi.function.Function2<Out, Out2, Out3>)

zipLatestWithMat

public <Out2,
Out3,
M,
M2> Flow<In,Out3,M2> zipLatestWithMat(Graph<SourceShape<Out2>,M> that,
 Function2<Out,Out2,Out3> combine,
 Function2<Mat,M,M2> matF)

Put together the elements of current Flow and the given Source into a stream of combined elements using a combiner function, picking always the latest element of each.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

See Also:

• zipLatestWith(org.apache.pekko.stream.Graph<org.apache.pekko.stream.SourceShape<Out2>, ?>, org.apache.pekko.japi.function.Function2<Out, Out2, Out3>)

zipWithIndex

public Flow<In,Pair<Out,Long>,Mat> zipWithIndex()

Combine the elements of current flow into a stream of tuples consisting of all elements paired with their index. Indices start at 0.

'''Emits when''' upstream emits an element and is paired with their index

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

initialTimeout

public Flow<In,Out,Mat> initialTimeout(Duration timeout)

If the first element has not passed through this operator before the provided timeout, the stream is failed with a InitialTimeoutException.

'''Emits when''' upstream emits an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or fails if timeout elapses before first element arrives

'''Cancels when''' downstream cancels

completionTimeout

public Flow<In,Out,Mat> completionTimeout(Duration timeout)

If the completion of the stream does not happen until the provided timeout, the stream is failed with a CompletionTimeoutException.

'''Emits when''' upstream emits an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or fails if timeout elapses before upstream completes

'''Cancels when''' downstream cancels

idleTimeout

public Flow<In,Out,Mat> idleTimeout(Duration timeout)

If the time between two processed elements exceeds the provided timeout, the stream is failed with a StreamIdleTimeoutException. The timeout is checked periodically, so the resolution of the check is one period (equals to timeout value).

'''Emits when''' upstream emits an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or fails if timeout elapses between two emitted elements

'''Cancels when''' downstream cancels

backpressureTimeout

public Flow<In,Out,Mat> backpressureTimeout(Duration timeout)

If the time between the emission of an element and the following downstream demand exceeds the provided timeout, the stream is failed with a BackpressureTimeoutException. The timeout is checked periodically, so the resolution of the check is one period (equals to timeout value).

'''Emits when''' upstream emits an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes or fails if timeout elapses between element emission and downstream demand.

'''Cancels when''' downstream cancels

keepAlive

public Flow<In,Out,Mat> keepAlive(Duration maxIdle,
 Creator<Out> injectedElem)

Injects additional elements if upstream does not emit for a configured amount of time. In other words, this operator attempts to maintains a base rate of emitted elements towards the downstream.

If the downstream backpressures then no element is injected until downstream demand arrives. Injected elements do not accumulate during this period.

Upstream elements are always preferred over injected elements.

'''Emits when''' upstream emits an element or if the upstream was idle for the configured period

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

throttle

public Flow<In,Out,Mat> throttle(int elements,
 Duration per)

Sends elements downstream with speed limited to elements/per. In other words, this operator set the maximum rate for emitting messages. This operator works for streams where all elements have the same cost or length.

Throttle implements the token bucket model. There is a bucket with a given token capacity (burst size). Tokens drops into the bucket at a given rate and can be spared for later use up to bucket capacity to allow some burstiness. Whenever stream wants to send an element, it takes as many tokens from the bucket as element costs. If there isn't any, throttle waits until the bucket accumulates enough tokens. Elements that costs more than the allowed burst will be delayed proportionally to their cost minus available tokens, meeting the target rate. Bucket is full when stream just materialized and started.

The burst size is calculated based on the given rate (cost/per) as 0.1 * rate, for example: - rate < 20/second => burst size 1 - rate 20/second => burst size 2 - rate 100/second => burst size 10 - rate 200/second => burst size 20

The throttle mode is pekko.stream.ThrottleMode.Shaping, which makes pauses before emitting messages to meet throttle rate.

'''Emits when''' upstream emits an element and configured time per each element elapsed

'''Backpressures when''' downstream backpressures or the incoming rate is higher than the speed limit

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

throttle

public Flow<In,Out,Mat> throttle(int elements,
 Duration per,
 int maximumBurst,
 ThrottleMode mode)

Sends elements downstream with speed limited to elements/per. In other words, this operator set the maximum rate for emitting messages. This operator works for streams where all elements have the same cost or length.

Throttle implements the token bucket model. There is a bucket with a given token capacity (burst size or maximumBurst). Tokens drops into the bucket at a given rate and can be spared for later use up to bucket capacity to allow some burstiness. Whenever stream wants to send an element, it takes as many tokens from the bucket as element costs. If there isn't any, throttle waits until the bucket accumulates enough tokens. Elements that costs more than the allowed burst will be delayed proportionally to their cost minus available tokens, meeting the target rate. Bucket is full when stream just materialized and started.

Parameter mode manages behavior when upstream is faster than throttle rate: - pekko.stream.ThrottleMode.Shaping makes pauses before emitting messages to meet throttle rate - pekko.stream.ThrottleMode.Enforcing fails with exception when upstream is faster than throttle rate

It is recommended to use non-zero burst sizes as they improve both performance and throttling precision by allowing the implementation to avoid using the scheduler when input rates fall below the enforced limit and to reduce most of the inaccuracy caused by the scheduler resolution (which is in the range of milliseconds).

WARNING: Be aware that throttle is using scheduler to slow down the stream. This scheduler has minimal time of triggering next push. Consequently it will slow down the stream as it has minimal pause for emitting. This can happen in case burst is 0 and speed is higher than 30 events per second. You need to increase the maximumBurst if elements arrive with small interval (30 milliseconds or less). Use the overloaded throttle method without maximumBurst parameter to automatically calculate the maximumBurst based on the given rate (cost/per). In other words the throttler always enforces the rate limit when maximumBurst parameter is given, but in certain cases (mostly due to limited scheduler resolution) it enforces a tighter bound than what was prescribed.

'''Emits when''' upstream emits an element and configured time per each element elapsed

'''Backpressures when''' downstream backpressures or the incoming rate is higher than the speed limit

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

throttle

public Flow<In,Out,Mat> throttle(int cost,
 Duration per,
 Function<Out,Integer> costCalculation)

Sends elements downstream with speed limited to cost/per. Cost is calculating for each element individually by calling calculateCost function. This operator works for streams when elements have different cost(length). Streams of ByteString for example.

Throttle implements the token bucket model. There is a bucket with a given token capacity (burst size). Tokens drops into the bucket at a given rate and can be spared for later use up to bucket capacity to allow some burstiness. Whenever stream wants to send an element, it takes as many tokens from the bucket as element costs. If there isn't any, throttle waits until the bucket accumulates enough tokens. Elements that costs more than the allowed burst will be delayed proportionally to their cost minus available tokens, meeting the target rate. Bucket is full when stream just materialized and started.

The burst size is calculated based on the given rate (cost/per) as 0.1 * rate, for example: - rate < 20/second => burst size 1 - rate 20/second => burst size 2 - rate 100/second => burst size 10 - rate 200/second => burst size 20

The throttle mode is pekko.stream.ThrottleMode.Shaping, which makes pauses before emitting messages to meet throttle rate.

'''Emits when''' upstream emits an element and configured time per each element elapsed

'''Backpressures when''' downstream backpressures or the incoming rate is higher than the speed limit

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

throttle

public Flow<In,Out,Mat> throttle(int cost,
 Duration per,
 int maximumBurst,
 Function<Out,Integer> costCalculation,
 ThrottleMode mode)

Sends elements downstream with speed limited to cost/per. Cost is calculating for each element individually by calling calculateCost function. This operator works for streams when elements have different cost(length). Streams of ByteString for example.

Throttle implements the token bucket model. There is a bucket with a given token capacity (burst size or maximumBurst). Tokens drops into the bucket at a given rate and can be spared for later use up to bucket capacity to allow some burstiness. Whenever stream wants to send an element, it takes as many tokens from the bucket as element costs. If there isn't any, throttle waits until the bucket accumulates enough tokens. Elements that costs more than the allowed burst will be delayed proportionally to their cost minus available tokens, meeting the target rate. Bucket is full when stream just materialized and started.

Parameter mode manages behavior when upstream is faster than throttle rate: - pekko.stream.ThrottleMode.Shaping makes pauses before emitting messages to meet throttle rate - pekko.stream.ThrottleMode.Enforcing fails with exception when upstream is faster than throttle rate. Enforcing cannot emit elements that cost more than the maximumBurst

It is recommended to use non-zero burst sizes as they improve both performance and throttling precision by allowing the implementation to avoid using the scheduler when input rates fall below the enforced limit and to reduce most of the inaccuracy caused by the scheduler resolution (which is in the range of milliseconds).

WARNING: Be aware that throttle is using scheduler to slow down the stream. This scheduler has minimal time of triggering next push. Consequently it will slow down the stream as it has minimal pause for emitting. This can happen in case burst is 0 and speed is higher than 30 events per second. You need to increase the maximumBurst if elements arrive with small interval (30 milliseconds or less). Use the overloaded throttle method without maximumBurst parameter to automatically calculate the maximumBurst based on the given rate (cost/per). In other words the throttler always enforces the rate limit when maximumBurst parameter is given, but in certain cases (mostly due to limited scheduler resolution) it enforces a tighter bound than what was prescribed.

'''Emits when''' upstream emits an element and configured time per each element elapsed

'''Backpressures when''' downstream backpressures or the incoming rate is higher than the speed limit

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

detach

public Flow<In,Out,Mat> detach()

Detaches upstream demand from downstream demand without detaching the stream rates; in other words acts like a buffer of size 1.

'''Emits when''' upstream emits an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

watchTermination

public <M> Flow<In,Out,M> watchTermination(Function2<Mat,CompletionStage<Done>,M> matF)

Materializes to CompletionStage that completes on getting termination message. The future completes with success when received complete message from upstream or cancel from downstream. It fails with the same error when received error message from downstream.

It is recommended to use the internally optimized Keep.left and Keep.right combiners where appropriate instead of manually writing functions that pass through one of the values.

monitorMat

public <M> Flow<In,Out,M> monitorMat(Function2<Mat,FlowMonitor<Out>,M> combine)

Materializes to FlowMonitor[Out] that allows monitoring of the current flow. All events are propagated by the monitor unchanged. Note that the monitor inserts a memory barrier every time it processes an event, and may therefor affect performance.

The combine function is used to combine the FlowMonitor with this flow's materialized value.

monitor

public Flow<In,Out,Pair<Mat,FlowMonitor<Out>>> monitor()

Materializes to Pair<Mat, FlowMonitor<>, which is unlike most other operators (!), in which usually the default materialized value keeping semantics is to keep the left value (by passing Keep.left() to a *Mat version of a method). This operator is an exception from that rule and keeps both values since dropping its sole purpose is to introduce that materialized value.

The FlowMonitor[Out] allows monitoring of the current flow. All events are propagated by the monitor unchanged. Note that the monitor inserts a memory barrier every time it processes an event, and may therefor affect performance.

initialDelay

public Flow<In,Out,Mat> initialDelay(Duration delay)

Delays the initial element by the specified duration.

'''Emits when''' upstream emits an element if the initial delay is already elapsed

'''Backpressures when''' downstream backpressures or initial delay is not yet elapsed

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

withAttributes

public Flow<In,Out,Mat> withAttributes(Attributes attr)

Replace the attributes of this Flow with the given ones. If this Flow is a composite of multiple graphs, new attributes on the composite will be less specific than attributes set directly on the individual graphs of the composite.

Note that this operation has no effect on an empty Flow (because the attributes apply only to the contained processing operators).

Specified by:

withAttributes in interface Graph<In,Out>

addAttributes

public Flow<In,Out,Mat> addAttributes(Attributes attr)

Add the given attributes to this Flow. If the specific attribute was already present on this graph this means the added attribute will be more specific than the existing one. If this Flow is a composite of multiple graphs, new attributes on the composite will be less specific than attributes set directly on the individual graphs of the composite.

Specified by:

addAttributes in interface Graph<In,Out>

named

public Flow<In,Out,Mat> named(String name)

Add a name attribute to this Flow.

Specified by:

named in interface Graph<In,Out>

async

public Flow<In,Out,Mat> async()

Put an asynchronous boundary around this Flow

Specified by:

async in interface Graph<In,Out>

async

public Flow<In,Out,Mat> async(String dispatcher)

Put an asynchronous boundary around this Flow

Specified by:

async in interface Graph<In,Out>

Parameters:

dispatcher - Run the graph on this dispatcher

async

public Flow<In,Out,Mat> async(String dispatcher,
 int inputBufferSize)

Put an asynchronous boundary around this Flow

Specified by:

async in interface Graph<In,Out>

Parameters:

dispatcher - Run the graph on this dispatcher

inputBufferSize - Set the input buffer to this size for the graph

log

public Flow<In,Out,Mat> log(String name,
 Function<Out,Object> extract,
 LoggingAdapter log)

Logs elements flowing through the stream as well as completion and erroring.

By default element and completion signals are logged on debug level, and errors are logged on Error level. This can be adjusted according to your needs by providing a custom Attributes.LogLevels attribute on the given Flow:

The extract function will be applied to each element before logging, so it is possible to log only those fields of a complex object flowing through this element.

Uses the given LoggingAdapter for logging.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

log

public Flow<In,Out,Mat> log(String name,
 Function<Out,Object> extract)

Logs elements flowing through the stream as well as completion and erroring.

By default element and completion signals are logged on debug level, and errors are logged on Error level. This can be adjusted according to your needs by providing a custom Attributes.LogLevels attribute on the given Flow:

The extract function will be applied to each element before logging, so it is possible to log only those fields of a complex object flowing through this element.

Uses an internally created LoggingAdapter which uses org.apache.pekko.stream.Log as it's source (use this class to configure slf4j loggers).

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

log

public Flow<In,Out,Mat> log(String name,
 LoggingAdapter log)

Logs elements flowing through the stream as well as completion and erroring.

By default element and completion signals are logged on debug level, and errors are logged on Error level. This can be adjusted according to your needs by providing a custom Attributes.LogLevels attribute on the given Flow:

Uses the given LoggingAdapter for logging.

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

log

public Flow<In,Out,Mat> log(String name)

Logs elements flowing through the stream as well as completion and erroring.

By default element and completion signals are logged on debug level, and errors are logged on Error level. This can be adjusted according to your needs by providing a custom Attributes.LogLevels attribute on the given Flow.

Uses an internally created LoggingAdapter which uses org.apache.pekko.stream.Log as it's source (use this class to configure slf4j loggers).

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

logWithMarker

public Flow<In,Out,Mat> logWithMarker(String name,
 Function<Out,LogMarker> marker,
 Function<Out,Object> extract,
 MarkerLoggingAdapter log)

Logs elements flowing through the stream as well as completion and erroring.

By default element and completion signals are logged on debug level, and errors are logged on Error level. This can be adjusted according to your needs by providing a custom Attributes.LogLevels attribute on the given Flow:

The extract function will be applied to each element before logging, so it is possible to log only those fields of a complex object flowing through this element.

Uses the given MarkerLoggingAdapter for logging.

Adheres to the ActorAttributes.SupervisionStrategy attribute.

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

logWithMarker

public Flow<In,Out,Mat> logWithMarker(String name,
 Function<Out,LogMarker> marker,
 Function<Out,Object> extract)

Logs elements flowing through the stream as well as completion and erroring.

By default element and completion signals are logged on debug level, and errors are logged on Error level. This can be adjusted according to your needs by providing a custom Attributes.LogLevels attribute on the given Flow:

The extract function will be applied to each element before logging, so it is possible to log only those fields of a complex object flowing through this element.

Uses an internally created MarkerLoggingAdapter which uses org.apache.pekko.stream.Log as it's source (use this class to configure slf4j loggers).

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

logWithMarker

public Flow<In,Out,Mat> logWithMarker(String name,
 Function<Out,LogMarker> marker,
 MarkerLoggingAdapter log)

Logs elements flowing through the stream as well as completion and erroring.

By default element and completion signals are logged on debug level, and errors are logged on Error level. This can be adjusted according to your needs by providing a custom Attributes.LogLevels attribute on the given Flow:

Uses the given MarkerLoggingAdapter for logging.

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

logWithMarker

public Flow<In,Out,Mat> logWithMarker(String name,
 Function<Out,LogMarker> marker)

Logs elements flowing through the stream as well as completion and erroring.

By default element and completion signals are logged on debug level, and errors are logged on Error level. This can be adjusted according to your needs by providing a custom Attributes.LogLevels attribute on the given Flow.

Uses an internally created MarkerLoggingAdapter which uses org.apache.pekko.stream.Log as it's source (use this class to configure slf4j loggers).

'''Emits when''' the mapping function returns an element

'''Backpressures when''' downstream backpressures

'''Completes when''' upstream completes

'''Cancels when''' downstream cancels

toProcessor

public RunnableGraph<org.reactivestreams.Processor<In,Out>> toProcessor()

Converts this Flow to a RunnableGraph that materializes to a Reactive Streams Processor which implements the operations encapsulated by this Flow. Every materialization results in a new Processor instance, i.e. the returned RunnableGraph is reusable.

Returns:

A RunnableGraph that materializes to a Processor when run() is called on it.

asFlowWithContext

public <U,
CtxU,
CtxOut>
FlowWithContext<U,CtxU,Out,CtxOut,Mat> asFlowWithContext(Function2<U,CtxU,In> collapseContext,
 Function<Out,CtxOut> extractContext)

Turns a Flow into a FlowWithContext which manages a context per element along a stream.

Parameters:

collapseContext - turn each incoming pair of element and context value into an element of this Flow

extractContext - turn each outgoing element of this Flow into an outgoing context value

aggregateWithBoundary

public <Agg,
Emit> Flow<In,Emit,Mat> aggregateWithBoundary(Creator<Agg> allocate,
 Function2<Agg,Out,Pair<Agg,Object>> aggregate,
 Function<Agg,Emit> harvest,
 Pair<Predicate<Agg>,Duration> emitOnTimer)

Deprecated.

Use the overloaded one which accepts an Optional instead. Since 1.2.0.

Aggregate input elements into an arbitrary data structure that can be completed and emitted downstream when custom condition is met which can be triggered by aggregate or timer. It can be thought of a more general groupedWeightedWithin(long,org.apache.pekko.japi.function.Function<Out,java.lang.Long>,java.time.Duration).

'''Emits when''' the aggregation function decides the aggregate is complete or the timer function returns true

'''Backpressures when''' downstream backpressures and the aggregate is complete

'''Completes when''' upstream completes and the last aggregate has been emitted downstream

'''Cancels when''' downstream cancels

Parameters:

allocate - allocate the initial data structure for aggregated elements

aggregate - update the aggregated elements, return true if ready to emit after update.

harvest - this is invoked before emit within the current stage/operator

emitOnTimer - decide whether the current aggregated elements can be emitted, the custom function is invoked on every interval

aggregateWithBoundary

public <Agg,
Emit> Flow<In,Emit,Mat> aggregateWithBoundary(Creator<Agg> allocate,
 Function2<Agg,Out,Pair<Agg,Object>> aggregate,
 Function<Agg,Emit> harvest,
 Optional<Pair<Predicate<Agg>,Duration>> emitOnTimer)

Aggregate input elements into an arbitrary data structure that can be completed and emitted downstream when custom condition is met which can be triggered by aggregate or timer. It can be thought of a more general groupedWeightedWithin(long,org.apache.pekko.japi.function.Function<Out,java.lang.Long>,java.time.Duration).

'''Emits when''' the aggregation function decides the aggregate is complete or the timer function returns true

'''Backpressures when''' downstream backpressures and the aggregate is complete

'''Completes when''' upstream completes and the last aggregate has been emitted downstream

'''Cancels when''' downstream cancels

Parameters:

allocate - allocate the initial data structure for aggregated elements

aggregate - update the aggregated elements, return true if ready to emit after update.

harvest - this is invoked before emit within the current stage/operator

emitOnTimer - decide whether the current aggregated elements can be emitted, the custom function is invoked on every interval

getAttributes

public Attributes getAttributes()

Specified by:

getAttributes in interface Graph<In,Out>