Class Source<Out,​Mat>

  • All Implemented Interfaces:
    Graph<SourceShape<Out>,​Mat>

    public final class Source<Out,​Mat>
    extends java.lang.Object
    implements Graph<SourceShape<Out>,​Mat>
    Java API

    A Source is a set of stream processing steps that has one open output and an attached input. Can be used as a Publisher

    • Constructor Summary

      Constructors 
      Constructor Description
      Source​(Source<Out,​Mat> delegate)  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static <T> Source<T,​ActorRef> actorPublisher​(Props props)
      Deprecated.
      Use akka.stream.stage.GraphStage and fromGraph instead, it allows for all operations an Actor would and is more type-safe as well as guaranteed to be ReactiveStreams compliant.
      static <T> Source<T,​ActorRef> actorRef​(int bufferSize, OverflowStrategy overflowStrategy)
      Creates a Source that is materialized as an ActorRef.
      Source<Out,​Mat> addAttributes​(Attributes attr)
      Add the given attributes to this Source.
      Source<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.
      <M2,​M3>
      Source<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.
      <S> Source<S,​Mat> ask​(int parallelism, ActorRef ref, java.lang.Class<S> mapTo, Timeout timeout)
      Use the ask pattern to send a request-reply message to the target ref actor.
      <S> Source<S,​Mat> ask​(ActorRef ref, java.lang.Class<S> mapTo, Timeout timeout)
      Use the ask pattern to send a request-reply message to the target ref actor.
      Source<Out,​Mat> asScala()
      Converts this Java DSL element to its Scala DSL counterpart.
      static <T> Source<T,​org.reactivestreams.Subscriber<T>> asSubscriber()
      Creates a Source that is materialized as a Subscriber
      Source<Out,​Mat> async()
      Put an asynchronous boundary around this Source
      Source<Out,​Mat> async​(java.lang.String dispatcher)
      Put an asynchronous boundary around this Source
      Source<Out,​Mat> async​(java.lang.String dispatcher, int inputBufferSize)
      Put an asynchronous boundary around this Source
      Source<Out,​Mat> backpressureTimeout​(java.time.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 TimeoutException.
      Source<Out,​Mat> backpressureTimeout​(scala.concurrent.duration.FiniteDuration timeout)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      <S> Source<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> Source<S,​Mat> batchWeighted​(long max, Function<Out,​java.lang.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.
      Source<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> Source<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> Source<T,​Mat> collectType​(java.lang.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.
      static <T,​U>
      Source<U,​NotUsed>
      combine​(Source<T,​?> first, Source<T,​?> second, java.util.List<Source<T,​?>> rest, Function<java.lang.Integer,​? extends Graph<UniformFanInShape<T,​U>,​NotUsed>> strategy)
      Combines several sources with fan-in strategy like Merge or Concat and returns Source.
      static <T,​U,​M1,​M2,​M>
      Source<U,​M>
      combineMat​(Source<T,​M1> first, Source<T,​M2> second, Function<java.lang.Integer,​? extends Graph<UniformFanInShape<T,​U>,​NotUsed>> strategy, Function2<M1,​M2,​M> combine)
      Combines two sources with fan-in strategy like Merge or Concat and returns Source with a materialized value.
      Source<Out,​Mat> completionTimeout​(java.time.Duration timeout)
      If the completion of the stream does not happen until the provided timeout, the stream is failed with a TimeoutException.
      Source<Out,​Mat> completionTimeout​(scala.concurrent.duration.FiniteDuration timeout)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      <M> Source<Out,​Mat> concat​(Graph<SourceShape<Out>,​M> that)
      Concatenate this Source with the given one, meaning that once current is exhausted and all result elements have been generated, the given source elements will be produced.
      <M,​M2>
      Source<Out,​M2>
      concatMat​(Graph<SourceShape<Out>,​M> that, Function2<Mat,​M,​M2> matF)
      Concatenate this Source with the given one, meaning that once current is exhausted and all result elements have been generated, the given source elements will be produced.
      Source<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> Source<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.
      static <O> Source<O,​NotUsed> cycle​(Creator<java.util.Iterator<O>> f)
      Helper to create 'cycled' Source from iterator provider.
      Source<Out,​Mat> delay​(java.time.Duration of, DelayOverflowStrategy strategy)
      Shifts elements emission in time by a specified amount.
      Source<Out,​Mat> delay​(scala.concurrent.duration.FiniteDuration of, DelayOverflowStrategy strategy)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<Out,​Mat> detach()
      Detaches upstream demand from downstream demand without detaching the stream rates; in other words acts like a buffer of size 1.
      Source<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>
      Source<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.
      Source<Out,​Mat> drop​(long n)
      Discard the given number of elements at the beginning of the stream.
      Source<Out,​Mat> dropWhile​(Predicate<Out> p)
      Discard elements at the beginning of the stream while predicate is true.
      Source<Out,​Mat> dropWithin​(java.time.Duration d)
      Discard the elements received within the given duration at beginning of the stream.
      Source<Out,​Mat> dropWithin​(scala.concurrent.duration.FiniteDuration d)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      static <O> Source<O,​NotUsed> empty()
      Create a Source with no elements, i.e.
      static <T> Source<T,​NotUsed> empty​(java.lang.Class<T> clazz)
      Create a Source with no elements.
      <U> Source<U,​Mat> expand​(Function<Out,​java.util.Iterator<U>> expander)
      Allows a faster downstream to progress independently of a slower publisher by extrapolating elements from an older element until new element comes from the upstream.
      Source<Out,​Mat> extrapolate​(Function<Out,​java.util.Iterator<Out>> extrapolator)
      Allows a faster downstream to progress independent of a slower upstream.
      Source<Out,​Mat> extrapolate​(Function<Out,​java.util.Iterator<Out>> extrapolator, Out initial)
      Allows a faster downstream to progress independent of a slower upstream.
      static <T> Source<T,​NotUsed> failed​(java.lang.Throwable cause)
      Create a Source that immediately ends the stream with the cause failure to every connected Sink.
      Source<Out,​Mat> filter​(Predicate<Out> p)
      Only pass on those elements that satisfy the given predicate.
      Source<Out,​Mat> filterNot​(Predicate<Out> p)
      Only pass on those elements that NOT satisfy the given predicate.
      <T,​M>
      Source<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>
      Source<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.
      <T> Source<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> Source<T,​Mat> foldAsync​(T zero, Function2<T,​Out,​java.util.concurrent.CompletionStage<T>> f)
      Similar to fold but with an asynchronous function.
      static <O> Source<O,​NotUsed> from​(java.lang.Iterable<O> iterable)
      Helper to create Source from Iterable.
      static <O> Source<O,​NotUsed> fromCompletionStage​(java.util.concurrent.CompletionStage<O> future)
      Starts a new Source from the given CompletionStage.
      static <O> Source<O,​NotUsed> fromFuture​(scala.concurrent.Future<O> future)
      Start a new Source from the given Future.
      static <T,​M>
      Source<T,​scala.concurrent.Future<M>>
      fromFutureSource​(scala.concurrent.Future<? extends Graph<SourceShape<T>,​M>> future)
      Streams the elements of the given future source once it successfully completes.
      static <T,​M>
      Source<T,​M>
      fromGraph​(Graph<SourceShape<T>,​M> g)
      A graph with the shape of a source logically is a source, this method makes it so also in type.
      static <O> Source<O,​NotUsed> fromIterator​(Creator<java.util.Iterator<O>> f)
      Helper to create Source from Iterator.
      static <O> Source<O,​NotUsed> fromPublisher​(org.reactivestreams.Publisher<O> publisher)
      Helper to create Source from Publisher.
      static <T,​M>
      Source<T,​java.util.concurrent.CompletionStage<M>>
      fromSourceCompletionStage​(java.util.concurrent.CompletionStage<? extends Graph<SourceShape<T>,​M>> completion)
      Streams the elements of an asynchronous source once its given CompletionStage completes.
      <K> SubSource<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> SubSource<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.
      Source<java.util.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.
      Source<java.util.List<Out>,​Mat> groupedWeightedWithin​(long maxWeight, Function<Out,​java.lang.Long> costFn, java.time.Duration d)
      Chunk up this stream into groups of elements received within a time window, or limited by the weight of the elements, whatever happens first.
      Source<java.util.List<Out>,​Mat> groupedWeightedWithin​(long maxWeight, Function<Out,​java.lang.Long> costFn, scala.concurrent.duration.FiniteDuration d)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<java.util.List<Out>,​Mat> groupedWithin​(int n, java.time.Duration d)
      Chunk up this stream into groups of elements received within a time window, or limited by the given number of elements, whatever happens first.
      Source<java.util.List<Out>,​Mat> groupedWithin​(int n, scala.concurrent.duration.FiniteDuration d)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<Out,​Mat> idleTimeout​(java.time.Duration timeout)
      If the time between two processed elements exceeds the provided timeout, the stream is failed with a TimeoutException.
      Source<Out,​Mat> idleTimeout​(scala.concurrent.duration.FiniteDuration timeout)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<Out,​Mat> initialDelay​(java.time.Duration delay)
      Delays the initial element by the specified duration.
      Source<Out,​Mat> initialDelay​(scala.concurrent.duration.FiniteDuration delay)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<Out,​Mat> initialTimeout​(java.time.Duration timeout)
      If the first element has not passed through this operator before the provided timeout, the stream is failed with a TimeoutException.
      Source<Out,​Mat> initialTimeout​(scala.concurrent.duration.FiniteDuration timeout)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<Out,​Mat> interleave​(Graph<SourceShape<Out>,​?> that, int segmentSize)
      Interleave is a deterministic merge of the given Source with elements of this Source.
      Source<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.
      <M,​M2>
      Source<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 Source.
      <M,​M2>
      Source<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 Source.
      Source<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.
      Source<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.
      Source<Out,​Mat> keepAlive​(java.time.Duration maxIdle, Creator<Out> injectedElem)
      Injects additional elements if upstream does not emit for a configured amount of time.
      Source<Out,​Mat> keepAlive​(scala.concurrent.duration.FiniteDuration maxIdle, Creator<Out> injectedElem)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      static <T,​M>
      Source<T,​java.util.concurrent.CompletionStage<M>>
      lazily​(Creator<Source<T,​M>> create)
      Creates a Source that is not materialized until there is downstream demand, when the source gets materialized the materialized future is completed with its value, if downstream cancels or fails without any demand the create factory is never called and the materialized CompletionStage is failed.
      static <T> Source<T,​scala.concurrent.Future<NotUsed>> lazilyAsync​(Creator<java.util.concurrent.CompletionStage<T>> create)
      Creates a Source from supplied future factory that is not called until downstream demand.
      Source<Out,​Mat> limit​(int n)
      Ensure stream boundedness by limiting the number of elements from upstream.
      Source<Out,​Mat> limitWeighted​(long n, Function<Out,​java.lang.Long> costFn)
      Ensure stream boundedness by evaluating the cost of incoming elements using a cost function.
      Source<Out,​Mat> log​(java.lang.String name)
      Logs elements flowing through the stream as well as completion and erroring.
      Source<Out,​Mat> log​(java.lang.String name, LoggingAdapter log)
      Logs elements flowing through the stream as well as completion and erroring.
      Source<Out,​Mat> log​(java.lang.String name, Function<Out,​java.lang.Object> extract)
      Logs elements flowing through the stream as well as completion and erroring.
      Source<Out,​Mat> log​(java.lang.String name, Function<Out,​java.lang.Object> extract, LoggingAdapter log)
      Logs elements flowing through the stream as well as completion and erroring.
      <T> Source<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> Source<T,​Mat> mapAsync​(int parallelism, Function<Out,​java.util.concurrent.CompletionStage<T>> f)
      Transform this stream by applying the given function to each of the elements as they pass through this processing step.
      <T> Source<T,​Mat> mapAsyncUnordered​(int parallelism, Function<Out,​java.util.concurrent.CompletionStage<T>> f)
      Transform this stream by applying the given function to each of the elements as they pass through this processing step.
      <T> Source<T,​Mat> mapConcat​(Function<Out,​? extends java.lang.Iterable<T>> f)
      Transform each input element into an Iterable of output elements that is then flattened into the output stream.
      Source<Out,​Mat> mapError​(scala.PartialFunction<java.lang.Throwable,​java.lang.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> Source<Out,​Mat2> mapMaterializedValue​(Function<Mat,​Mat2> f)
      Transform only the materialized value of this Source, leaving all other properties as they were.
      static <T> Source<T,​java.util.concurrent.CompletableFuture<java.util.Optional<T>>> maybe()
      Create a Source which materializes a CompletableFuture which controls what element will be emitted by the Source.
      Source<Out,​Mat> merge​(Graph<SourceShape<Out>,​?> that)
      Merge the given Source to the current one, taking elements as they arrive from input streams, picking randomly when several elements ready.
      Source<Out,​Mat> merge​(Graph<SourceShape<Out>,​?> that, boolean eagerComplete)
      Merge the given Source to the current one, taking elements as they arrive from input streams, picking randomly when several elements ready.
      <M,​M2>
      Source<Out,​M2>
      mergeMat​(Graph<SourceShape<Out>,​M> that, Function2<Mat,​M,​M2> matF)
      Merge the given Source to the current one, taking elements as they arrive from input streams, picking randomly when several elements ready.
      <M,​M2>
      Source<Out,​M2>
      mergeMat​(Graph<SourceShape<Out>,​M> that, Function2<Mat,​M,​M2> matF, boolean eagerComplete)
      Merge the given Source to the current one, taking elements as they arrive from input streams, picking randomly when several elements ready.
      <M> Source<Out,​Mat> mergeSorted​(Graph<SourceShape<Out>,​M> that, java.util.Comparator<Out> comp)
      Merge the given Source to this Source, 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>
      Source<Out,​Mat3>
      mergeSortedMat​(Graph<SourceShape<Out>,​Mat2> that, java.util.Comparator<Out> comp, Function2<Mat,​Mat2,​Mat3> matF)
      Merge the given Source to this Source, 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).
      Source<Out,​Pair<Mat,​FlowMonitor<Out>>> monitor()
      Materializes to Pair>, 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> Source<Out,​M> monitor​(Function2<Mat,​FlowMonitor<Out>,​M> combine)
      Deprecated.
      Use monitor() or monitorMat(combine) instead.
      <M> Source<Out,​M> monitorMat​(Function2<Mat,​FlowMonitor<Out>,​M> combine)
      Materializes to FlowMonitor[Out] that allows monitoring of the current flow.
      Source<Out,​Mat> named​(java.lang.String name)
      Add a name attribute to this Source.
      <M> Source<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.
      <M,​M2>
      Source<Out,​M2>
      orElseMat​(Graph<SourceShape<Out>,​M> secondary, Function2<Mat,​M,​M2> matF)
      Provides a secondary source that will be consumed if this source completes without any elements passing by.
      Source<Pair<java.util.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,​Source<Out,​NotUsed>> preMaterialize​(Materializer materializer)
      Materializes this Source, immediately returning (1) its materialized value, and (2) a new Source that can be used to consume elements from the newly materialized Source.
      <M> Source<Out,​Mat> prepend​(Graph<SourceShape<Out>,​M> that)
      Prepend the given Source to this one, meaning that once the given source is exhausted and all result elements have been generated, the current source's elements will be produced.
      <M,​M2>
      Source<Out,​M2>
      prependMat​(Graph<SourceShape<Out>,​M> that, Function2<Mat,​M,​M2> matF)
      Prepend the given Source to this one, meaning that once the given source is exhausted and all result elements have been generated, the current source's elements will be produced.
      static <T> Source<T,​SourceQueueWithComplete<T>> queue​(int bufferSize, OverflowStrategy overflowStrategy)
      Creates a Source that is materialized as an SourceQueue.
      static Source<java.lang.Integer,​NotUsed> range​(int start, int end)
      Creates Source that represents integer values in range ''[start;end]'', step equals to 1.
      static Source<java.lang.Integer,​NotUsed> range​(int start, int end, int step)
      Creates Source that represents integer values in range ''[start;end]'', with the given step.
      Source<Out,​Mat> recover​(java.lang.Class<? extends java.lang.Throwable> clazz, java.util.function.Supplier<Out> supplier)
      Deprecated.
      Use recoverWithRetries instead.
      Source<Out,​Mat> recover​(scala.PartialFunction<java.lang.Throwable,​Out> pf)
      Deprecated.
      Use recoverWithRetries instead.
      Source<Out,​Mat> recoverWith​(java.lang.Class<? extends java.lang.Throwable> clazz, java.util.function.Supplier<Graph<SourceShape<Out>,​NotUsed>> supplier)
      RecoverWith allows to switch to alternative Source on flow failure.
      Source<Out,​Mat> recoverWith​(scala.PartialFunction<java.lang.Throwable,​? extends Graph<SourceShape<Out>,​NotUsed>> pf)
      RecoverWith allows to switch to alternative Source on flow failure.
      Source<Out,​Mat> recoverWithRetries​(int attempts, java.lang.Class<? extends java.lang.Throwable> clazz, java.util.function.Supplier<Graph<SourceShape<Out>,​NotUsed>> supplier)
      RecoverWithRetries allows to switch to alternative Source on flow failure.
      Source<Out,​Mat> recoverWithRetries​(int attempts, scala.PartialFunction<java.lang.Throwable,​? extends Graph<SourceShape<Out>,​NotUsed>> pf)
      RecoverWithRetries allows to switch to alternative Source on flow failure.
      Source<Out,​Mat> reduce​(Function2<Out,​Out,​Out> f)
      Similar to fold but uses first element as zero element.
      static <T> Source<T,​NotUsed> repeat​(T element)
      Create a Source that will continually emit the given element.
      <U> java.util.concurrent.CompletionStage<U> runFold​(U zero, Function2<U,​Out,​U> f, Materializer materializer)
      Shortcut for running this Source with a fold function.
      <U> java.util.concurrent.CompletionStage<U> runFoldAsync​(U zero, Function2<U,​Out,​java.util.concurrent.CompletionStage<U>> f, Materializer materializer)
      Shortcut for running this Source with an asynchronous fold function.
      java.util.concurrent.CompletionStage<Done> runForeach​(Procedure<Out> f, Materializer materializer)
      Shortcut for running this Source with a foreach procedure.
      java.util.concurrent.CompletionStage<Out> runReduce​(Function2<Out,​Out,​Out> f, Materializer materializer)
      Shortcut for running this Source with a reduce function.
      <M> M runWith​(Graph<SinkShape<Out>,​M> sink, Materializer materializer)
      Connect this Source to a Sink and run it.
      <T> Source<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> Source<T,​Mat> scanAsync​(T zero, Function2<T,​Out,​java.util.concurrent.CompletionStage<T>> f)
      Similar to scan but with a 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.
      SourceShape<Out> shape()
      The shape of a graph is all that is externally visible: its inlets and outlets.
      static <T> Source<T,​NotUsed> single​(T element)
      Create a Source with one element.
      Source<java.util.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.
      SubSource<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.
      SubSource<Out,​Mat> splitAfter​(SubstreamCancelStrategy substreamCancelStrategy, Predicate<Out> p)
      This operation applies the given predicate to all incoming elements and emits them to a stream of output streams.
      SubSource<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.
      SubSource<Out,​Mat> splitWhen​(SubstreamCancelStrategy substreamCancelStrategy, 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.
      <Ctx> SourceWithContext<Ctx,​Out,​Mat> startContextPropagation​(Function<Out,​Ctx> extractContext)
      API MAY CHANGE
      <T> Source<T,​Mat> statefulMapConcat​(Creator<Function<Out,​java.lang.Iterable<T>>> f)
      Transform each input element into an Iterable of output elements that is then flattened into the output stream.
      Source<Out,​Mat> take​(long n)
      Terminate processing (and cancel the upstream publisher) after the given number of elements.
      Source<Out,​Mat> takeWhile​(Predicate<Out> p)
      Terminate processing (and cancel the upstream publisher) after predicate returns false for the first time.
      Source<Out,​Mat> takeWhile​(Predicate<Out> p, boolean inclusive)
      Terminate processing (and cancel the upstream publisher) after predicate returns false for the first time, including the first failed element if inclusive is true Due to input buffering some elements may have been requested from upstream publishers that will then not be processed downstream of this step.
      Source<Out,​Mat> takeWithin​(java.time.Duration d)
      Terminate processing (and cancel the upstream publisher) after the given duration.
      Source<Out,​Mat> takeWithin​(scala.concurrent.duration.FiniteDuration d)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<Out,​Mat> throttle​(int elements, java.time.Duration per)
      Sends elements downstream with speed limited to elements/per.
      Source<Out,​Mat> throttle​(int cost, java.time.Duration per, int maximumBurst, Function<Out,​java.lang.Integer> costCalculation, ThrottleMode mode)
      Sends elements downstream with speed limited to cost/per.
      Source<Out,​Mat> throttle​(int elements, java.time.Duration per, int maximumBurst, ThrottleMode mode)
      Sends elements downstream with speed limited to elements/per.
      Source<Out,​Mat> throttle​(int cost, java.time.Duration per, Function<Out,​java.lang.Integer> costCalculation)
      Sends elements downstream with speed limited to cost/per.
      Source<Out,​Mat> throttle​(int cost, scala.concurrent.duration.FiniteDuration per, int maximumBurst, Function<Out,​java.lang.Integer> costCalculation, ThrottleMode mode)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<Out,​Mat> throttle​(int elements, scala.concurrent.duration.FiniteDuration per, int maximumBurst, ThrottleMode mode)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      Source<Out,​Mat> throttleEven​(int elements, java.time.Duration per, ThrottleMode mode)
      Deprecated.
      Use throttle without `maximumBurst` parameter instead.
      Source<Out,​Mat> throttleEven​(int cost, java.time.Duration per, scala.Function1<Out,​java.lang.Object> costCalculation, ThrottleMode mode)
      Deprecated.
      Use throttle without `maximumBurst` parameter instead.
      Source<Out,​Mat> throttleEven​(int elements, scala.concurrent.duration.FiniteDuration per, ThrottleMode mode)
      Deprecated.
      Use throttle without `maximumBurst` parameter instead.
      Source<Out,​Mat> throttleEven​(int cost, scala.concurrent.duration.FiniteDuration per, scala.Function1<Out,​java.lang.Object> costCalculation, ThrottleMode mode)
      Deprecated.
      Use throttle without `maximumBurst` parameter instead.
      static <O> Source<O,​Cancellable> tick​(java.time.Duration initialDelay, java.time.Duration interval, O tick)
      Elements are emitted periodically with the specified interval.
      static <O> Source<O,​Cancellable> tick​(scala.concurrent.duration.FiniteDuration initialDelay, scala.concurrent.duration.FiniteDuration interval, O tick)
      Deprecated.
      Use the overloaded one which accepts java.time.Duration instead.
      <M> RunnableGraph<Mat> to​(Graph<SinkShape<Out>,​M> sink)
      Connect this Source to a Sink, concatenating the processing steps of both.
      <M,​M2>
      RunnableGraph<M2>
      toMat​(Graph<SinkShape<Out>,​M> sink, Function2<Mat,​M,​M2> combine)
      Connect this Source to a Sink, concatenating the processing steps of both.
      java.lang.String toString()  
      LinearTraversalBuilder traversalBuilder()
      INTERNAL API.
      static <S,​E>
      Source<E,​NotUsed>
      unfold​(S s, Function<S,​java.util.Optional<Pair<S,​E>>> f)
      Create a Source that will unfold a value of type S into a pair of the next state S and output elements of type E.
      static <S,​E>
      Source<E,​NotUsed>
      unfoldAsync​(S s, Function<S,​java.util.concurrent.CompletionStage<java.util.Optional<Pair<S,​E>>>> f)
      Same as <S,E>unfold(S,akka.japi.function.Function<S,java.util.Optional<akka.japi.Pair<S,E>>>), but uses an async function to generate the next state-element tuple.
      static <T,​S>
      Source<T,​NotUsed>
      unfoldResource​(Creator<S> create, Function<S,​java.util.Optional<T>> read, Procedure<S> close)
      Start a new Source from some resource which can be opened, read and closed.
      static <T,​S>
      Source<T,​NotUsed>
      unfoldResourceAsync​(Creator<java.util.concurrent.CompletionStage<S>> create, Function<S,​java.util.concurrent.CompletionStage<java.util.Optional<T>>> read, Function<S,​java.util.concurrent.CompletionStage<Done>> close)
      Start a new Source from some resource which can be opened, read and closed.
      static <SuperOut,​Out extends SuperOut,​Mat>
      Source<SuperOut,​Mat>
      upcast​(Source<Out,​Mat> source)
      Upcast a stream of elements to a stream of supertypes of that element.
      <T,​M>
      Source<T,​Mat>
      via​(Graph<FlowShape<Out,​T>,​M> flow)
      Transform this Source by appending the given processing operators.
      <T,​M,​M2>
      Source<T,​M2>
      viaMat​(Graph<FlowShape<Out,​T>,​M> flow, Function2<Mat,​M,​M2> combine)
      Transform this Source by appending the given processing operators.
      Source<Out,​Mat> watch​(ActorRef ref)
      The operator fails with an WatchedActorTerminatedException if the target actor is terminated.
      <M> Source<Out,​M> watchTermination​(Function2<Mat,​java.util.concurrent.CompletionStage<Done>,​M> matF)
      Materializes to Future[Done] that completes on getting termination message.
      Source<Out,​Mat> wireTap​(Procedure<Out> f)
      This is a simplified version of wireTap(Sink) that takes only a simple procedure.
      Source<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>
      Source<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.
      Source<Out,​Mat> withAttributes​(Attributes attr)
      Replace the attributes of this Source with the given ones.
      <T> Source<Pair<Out,​T>,​Mat> zip​(Graph<SourceShape<T>,​?> that)
      Combine the elements of current Source and the given one into a stream of tuples.
      <T> Source<Pair<Out,​T>,​Mat> zipLatest​(Graph<SourceShape<T>,​?> that)
      Combine the elements of 2 streams into a stream of tuples, picking always the latest element of each.
      <T,​M,​M2>
      Source<Pair<Out,​T>,​M2>
      zipLatestMat​(Graph<SourceShape<T>,​M> that, Function2<Mat,​M,​M2> matF)
      Combine the elements of current Source and the given one into a stream of tuples, picking always the latest element of each.
      <Out2,​Out3>
      Source<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>
      Source<Out3,​M2>
      zipLatestWithMat​(Graph<SourceShape<Out2>,​M> that, Function2<Out,​Out2,​Out3> combine, Function2<Mat,​M,​M2> matF)
      Put together the elements of current Source and the given one into a stream of combined elements using a combiner function, picking always the latest of the elements of each source.
      <T,​M,​M2>
      Source<Pair<Out,​T>,​M2>
      zipMat​(Graph<SourceShape<T>,​M> that, Function2<Mat,​M,​M2> matF)
      Combine the elements of current Source and the given one into a stream of tuples.
      static <T> Source<java.util.List<T>,​NotUsed> zipN​(java.util.List<Source<T,​?>> sources)
      Combine the elements of multiple streams into a stream of lists.
      <Out2,​Out3>
      Source<Out3,​Mat>
      zipWith​(Graph<SourceShape<Out2>,​?> that, Function2<Out,​Out2,​Out3> combine)
      Put together the elements of current Source and the given one into a stream of combined elements using a combiner function.
      Source<Pair<Out,​java.lang.Long>,​Mat> zipWithIndex()
      Combine the elements of current Source into a stream of tuples consisting of all elements paired with their index.
      <Out2,​Out3,​M,​M2>
      Source<Out3,​M2>
      zipWithMat​(Graph<SourceShape<Out2>,​M> that, Function2<Out,​Out2,​Out3> combine, Function2<Mat,​M,​M2> matF)
      Put together the elements of current Source and the given one into a stream of combined elements using a combiner function.
      static <T,​O>
      Source<O,​NotUsed>
      zipWithN​(Function<java.util.List<T>,​O> zipper, java.util.List<Source<T,​?>> sources)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

    • Method Detail

      • empty

        public static <O> Source<O,​NotUsed> empty()
        Create a Source with no elements, i.e. an empty stream that is completed immediately for every connected Sink.
        Returns:
        (undocumented)
      • empty

        public static <T> Source<T,​NotUsed> empty​(java.lang.Class<T> clazz)
        Create a Source with no elements. The result is the same as calling Source.empty()
        Parameters:
        clazz - (undocumented)
        Returns:
        (undocumented)
      • maybe

        public static <T> Source<T,​java.util.concurrent.CompletableFuture<java.util.Optional<T>>> maybe()
        Create a Source which materializes a CompletableFuture which controls what element will be emitted by the Source. If the materialized promise is completed with a filled Optional, that value will be produced downstream, followed by completion. If the materialized promise is completed with an empty Optional, no value will be produced downstream and completion will be signalled immediately. If the materialized promise is completed with a failure, then the returned source will terminate with that error. If the downstream of this source cancels before the promise has been completed, then the promise will be completed with an empty Optional.
        Returns:
        (undocumented)
      • fromPublisher

        public static <O> Source<O,​NotUsed> fromPublisher​(org.reactivestreams.Publisher<O> publisher)
        Helper to create Source from Publisher.

        Construct a transformation starting with given publisher. The transformation steps are executed by a series of Processor instances that mediate the flow of elements downstream and the propagation of back-pressure upstream.

        Parameters:
        publisher - (undocumented)
        Returns:
        (undocumented)
      • fromIterator

        public static <O> Source<O,​NotUsed> fromIterator​(Creator<java.util.Iterator<O>> f)
        Helper to create Source from Iterator. Example usage:

        
         List<Integer> data = new ArrayList<Integer>();
         data.add(1);
         data.add(2);
         data.add(3);
         Source.from(() -> data.iterator());
         

        Start a new Source from the given Iterator. The produced stream of elements will continue until the iterator runs empty or fails during evaluation of the next() method. Elements are pulled out of the iterator in accordance with the demand coming from the downstream transformation steps.

        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • cycle

        public static <O> Source<O,​NotUsed> cycle​(Creator<java.util.Iterator<O>> f)
        Helper to create 'cycled' Source from iterator provider. Example usage:

        
         Source.cycle(() -> Arrays.asList(1, 2, 3).iterator());
         

        Start a new 'cycled' Source from the given elements. The producer stream of elements will continue infinitely by repeating the sequence of elements provided by function parameter.

        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • from

        public static <O> Source<O,​NotUsed> from​(java.lang.Iterable<O> iterable)
        Helper to create Source from Iterable. Example usage:
        
         List<Integer> data = new ArrayList<Integer>();
         data.add(1);
         data.add(2);
         data.add(3);
         Source.from(data);
         

        Starts a new Source from the given Iterable. This is like starting from an Iterator, but every Subscriber directly attached to the Publisher of this stream will see an individual flow of elements (always starting from the beginning) regardless of when they subscribed.

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

        Parameters:
        iterable - (undocumented)
        Returns:
        (undocumented)
      • range

        public static Source<java.lang.Integer,​NotUsed> range​(int start,
                                                                    int end)
        Creates Source that represents integer values in range ''[start;end]'', step equals to 1. It allows to create Source out of range as simply as on Scala Source(1 to N)

        Uses {@link scala.collection.immutable.Range.inclusive(Int, Int)} internally

        Parameters:
        start - (undocumented)
        end - (undocumented)
        Returns:
        (undocumented)
      • range

        public static Source<java.lang.Integer,​NotUsed> range​(int start,
                                                                    int end,
                                                                    int step)
        Creates Source that represents integer values in range ''[start;end]'', with the given step. It allows to create Source out of range as simply as on Scala Source(1 to N)

        Uses {@link scala.collection.immutable.Range.inclusive(Int, Int, Int)} internally

        Parameters:
        start - (undocumented)
        end - (undocumented)
        step - (undocumented)
        Returns:
        (undocumented)
      • fromFuture

        public static <O> Source<O,​NotUsed> fromFuture​(scala.concurrent.Future<O> future)
        Start a new Source from the given Future. The stream will consist of one element when the Future is completed with a successful value, which may happen before or after materializing the Flow. The stream terminates with a failure if the Future is completed with a failure.
        Parameters:
        future - (undocumented)
        Returns:
        (undocumented)
      • fromCompletionStage

        public static <O> Source<O,​NotUsed> fromCompletionStage​(java.util.concurrent.CompletionStage<O> future)
        Starts a new Source from the given CompletionStage. The stream will consist of one element when the CompletionStage is completed with a successful value, which may happen before or after materializing the Flow. The stream terminates with a failure if the CompletionStage is completed with a failure.
        Parameters:
        future - (undocumented)
        Returns:
        (undocumented)
      • fromFutureSource

        public static <T,​M> Source<T,​scala.concurrent.Future<M>> fromFutureSource​(scala.concurrent.Future<? extends Graph<SourceShape<T>,​M>> future)
        Streams the elements of the given future source once it successfully completes. If the Future fails the stream is failed with the exception from the future. If downstream cancels before the stream completes the materialized Future will be failed with a StreamDetachedException.
        Parameters:
        future - (undocumented)
        Returns:
        (undocumented)
      • fromSourceCompletionStage

        public static <T,​M> Source<T,​java.util.concurrent.CompletionStage<M>> fromSourceCompletionStage​(java.util.concurrent.CompletionStage<? extends Graph<SourceShape<T>,​M>> completion)
        Streams the elements of an asynchronous source once its given CompletionStage completes. If the CompletionStage fails the stream is failed with the exception from the future. If downstream cancels before the stream completes the materialized CompletionStage will be failed with a StreamDetachedException
        Parameters:
        completion - (undocumented)
        Returns:
        (undocumented)
      • tick

        public static <O> Source<O,​Cancellable> tick​(scala.concurrent.duration.FiniteDuration initialDelay,
                                                           scala.concurrent.duration.FiniteDuration interval,
                                                           O tick)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        Elements are emitted periodically with the specified interval. The tick element will be delivered to downstream consumers that has requested any elements. If a consumer has not requested any elements at the point in time when the tick element is produced it will not receive that tick element later. It will receive new tick elements as soon as it has requested more elements.
        Parameters:
        initialDelay - (undocumented)
        interval - (undocumented)
        tick - (undocumented)
        Returns:
        (undocumented)
      • tick

        public static <O> Source<O,​Cancellable> tick​(java.time.Duration initialDelay,
                                                           java.time.Duration interval,
                                                           O tick)
        Elements are emitted periodically with the specified interval. The tick element will be delivered to downstream consumers that has requested any elements. If a consumer has not requested any elements at the point in time when the tick element is produced it will not receive that tick element later. It will receive new tick elements as soon as it has requested more elements.
        Parameters:
        initialDelay - (undocumented)
        interval - (undocumented)
        tick - (undocumented)
        Returns:
        (undocumented)
      • single

        public static <T> Source<T,​NotUsed> single​(T element)
        Create a Source with one element. Every connected Sink of this stream will see an individual stream consisting of one element.
        Parameters:
        element - (undocumented)
        Returns:
        (undocumented)
      • repeat

        public static <T> Source<T,​NotUsed> repeat​(T element)
        Create a Source that will continually emit the given element.
        Parameters:
        element - (undocumented)
        Returns:
        (undocumented)
      • unfold

        public static <S,​E> Source<E,​NotUsed> unfold​(S s,
                                                                 Function<S,​java.util.Optional<Pair<S,​E>>> f)
        Create a Source that will unfold a value of type S into a pair of the next state S and output elements of type E.
        Parameters:
        s - (undocumented)
        f - (undocumented)
        Returns:
        (undocumented)
      • failed

        public static <T> Source<T,​NotUsed> failed​(java.lang.Throwable cause)
        Create a Source that immediately ends the stream with the cause failure to every connected Sink.
        Parameters:
        cause - (undocumented)
        Returns:
        (undocumented)
      • lazily

        public static <T,​M> Source<T,​java.util.concurrent.CompletionStage<M>> lazily​(Creator<Source<T,​M>> create)
        Creates a Source that is not materialized until there is downstream demand, when the source gets materialized the materialized future is completed with its value, if downstream cancels or fails without any demand the create factory is never called and the materialized CompletionStage is failed.
        Parameters:
        create - (undocumented)
        Returns:
        (undocumented)
      • lazilyAsync

        public static <T> Source<T,​scala.concurrent.Future<NotUsed>> lazilyAsync​(Creator<java.util.concurrent.CompletionStage<T>> create)
        Creates a Source from supplied future factory that is not called until downstream demand. When source gets materialized the materialized future is completed with the value from the factory. If downstream cancels or fails without any demand the create factory is never called and the materialized Future is failed.

        Parameters:
        create - (undocumented)
        Returns:
        (undocumented)
        See Also:
        Source.lazily
      • asSubscriber

        public static <T> Source<T,​org.reactivestreams.Subscriber<T>> asSubscriber()
        Creates a Source that is materialized as a Subscriber
        Returns:
        (undocumented)
      • actorPublisher

        public static <T> Source<T,​ActorRef> actorPublisher​(Props props)
        Deprecated.
        Use akka.stream.stage.GraphStage and fromGraph instead, it allows for all operations an Actor would and is more type-safe as well as guaranteed to be ReactiveStreams compliant.
        Creates a Source that is materialized to an ActorRef which points to an Actor created according to the passed in Props. Actor created by the props should be ActorPublisher.

        Parameters:
        props - (undocumented)
        Returns:
        (undocumented)
      • actorRef

        public static <T> Source<T,​ActorRef> actorRef​(int bufferSize,
                                                            OverflowStrategy overflowStrategy)
        Creates a Source that is materialized as an ActorRef. Messages sent to this actor will be emitted to the stream if there is demand from downstream, otherwise they will be buffered until request for demand is received.

        Depending on the defined OverflowStrategy it might drop elements if there is no space available in the buffer.

        The strategy akka.stream.OverflowStrategy.backpressure is not supported, and an IllegalArgument("Backpressure overflowStrategy not supported") will be thrown if it is passed as argument.

        The buffer can be disabled by using bufferSize of 0 and then received messages are dropped if there is no demand from downstream. When bufferSize is 0 the overflowStrategy does not matter. An async boundary is added after this Source; as such, it is never safe to assume the downstream will always generate demand.

        The stream can be completed successfully by sending the actor reference a Status.Success (whose content will be ignored) in which case already buffered elements will be signaled before signaling completion.

        The stream can be completed with failure by sending a Status.Failure to the actor reference. In case the Actor is still draining its internal buffer (after having received a Status.Success) before signaling completion and it receives a Status.Failure, the failure will be signaled downstream immediately (instead of the completion signal).

        Note that terminating the actor without first completing it, either with a success or a failure, will prevent the actor triggering downstream completion and the stream will continue to run even though the source actor is dead. Therefore you should **not** attempt to manually terminate the actor such as with a PoisonPill.

        The actor will be stopped when the stream is completed, failed or canceled from downstream, i.e. you can watch it to get notified when that happens.

        See also akka.stream.javadsl.Source.queue.

        Parameters:
        bufferSize - The size of the buffer in element count
        overflowStrategy - Strategy that is used when incoming elements cannot fit inside the buffer
        Returns:
        (undocumented)
      • fromGraph

        public static <T,​M> Source<T,​M> fromGraph​(Graph<SourceShape<T>,​M> g)
        A graph with the shape of a source logically is a source, this method makes it so also in type.
        Parameters:
        g - (undocumented)
        Returns:
        (undocumented)
      • combine

        public static <T,​U> Source<U,​NotUsed> combine​(Source<T,​?> first,
                                                                  Source<T,​?> second,
                                                                  java.util.List<Source<T,​?>> rest,
                                                                  Function<java.lang.Integer,​? extends Graph<UniformFanInShape<T,​U>,​NotUsed>> strategy)
        Combines several sources with fan-in strategy like Merge or Concat and returns Source.
        Parameters:
        first - (undocumented)
        second - (undocumented)
        rest - (undocumented)
        strategy - (undocumented)
        Returns:
        (undocumented)
      • combineMat

        public static <T,​U,​M1,​M2,​M> Source<U,​M> combineMat​(Source<T,​M1> first,
                                                                                         Source<T,​M2> second,
                                                                                         Function<java.lang.Integer,​? extends Graph<UniformFanInShape<T,​U>,​NotUsed>> strategy,
                                                                                         Function2<M1,​M2,​M> combine)
        Combines two sources with fan-in strategy like Merge or Concat and returns Source with a materialized value.
        Parameters:
        first - (undocumented)
        second - (undocumented)
        strategy - (undocumented)
        combine - (undocumented)
        Returns:
        (undocumented)
      • zipN

        public static <T> Source<java.util.List<T>,​NotUsed> zipN​(java.util.List<Source<T,​?>> sources)
        Combine the elements of multiple streams into a stream of lists.
        Parameters:
        sources - (undocumented)
        Returns:
        (undocumented)
      • zipWithN

        public static <T,​O> Source<O,​NotUsed> zipWithN​(Function<java.util.List<T>,​O> zipper,
                                                                   java.util.List<Source<T,​?>> sources)
      • queue

        public static <T> Source<T,​SourceQueueWithComplete<T>> queue​(int bufferSize,
                                                                           OverflowStrategy overflowStrategy)
        Creates a Source that is materialized as an SourceQueue. You can push elements to the queue and they will be emitted to the stream if there is demand from downstream, otherwise they will be buffered until request for demand is received. Elements in the buffer will be discarded if downstream is terminated.

        Depending on the defined OverflowStrategy it might drop elements if there is no space available in the buffer.

        Acknowledgement mechanism is available. akka.stream.javadsl.SourceQueue.offer returns CompletionStage which completes with QueueOfferResult.enqueued if element was added to buffer or sent downstream. It completes with QueueOfferResult.dropped if element was dropped. Can also complete with QueueOfferResult.Failure - when stream failed or QueueOfferResult.QueueClosed when downstream is completed.

        The strategy akka.stream.OverflowStrategy.backpressure will not complete last offer():CompletionStage call when buffer is full.

        You can watch accessibility of stream with akka.stream.javadsl.SourceQueue.watchCompletion. It returns a future that completes with success when this operator is completed or fails when stream is failed.

        The buffer can be disabled by using bufferSize of 0 and then received message will wait for downstream demand unless there is another message waiting for downstream demand, in that case offer result will be completed according to the overflow strategy.

        SourceQueue that current source is materialized to is for single thread usage only.

        Parameters:
        bufferSize - size of buffer in element count
        overflowStrategy - Strategy that is used when incoming elements cannot fit inside the buffer
        Returns:
        (undocumented)
      • unfoldResource

        public static <T,​S> Source<T,​NotUsed> unfoldResource​(Creator<S> create,
                                                                         Function<S,​java.util.Optional<T>> read,
                                                                         Procedure<S> close)
        Start a new Source from some resource which can be opened, read and closed. Interaction with resource happens in a blocking way.

        Example:

        
         Source.unfoldResource(
           () -> new BufferedReader(new FileReader("...")),
           reader -> reader.readLine(),
           reader -> reader.close())
         

        You can use the supervision strategy to handle exceptions for read function. All exceptions thrown by create or close will fail the stream.

        Restart supervision strategy will close and create blocking IO again. Default strategy is Stop which means that stream will be terminated on error in read function by default.

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

        Adheres to the ActorAttributes.SupervisionStrategy attribute.

        Parameters:
        create - - function that is called on stream start and creates/opens resource.
        read - - function that reads data from opened resource. It is called each time backpressure signal is received. Stream calls close and completes when read returns None.
        close - - function that closes resource
        Returns:
        (undocumented)
      • unfoldResourceAsync

        public static <T,​S> Source<T,​NotUsed> unfoldResourceAsync​(Creator<java.util.concurrent.CompletionStage<S>> create,
                                                                              Function<S,​java.util.concurrent.CompletionStage<java.util.Optional<T>>> read,
                                                                              Function<S,​java.util.concurrent.CompletionStage<Done>> close)
        Start a new Source from some resource which can be opened, read and closed. It's similar to unfoldResource but takes functions that return CompletionStage instead of plain values.

        You can use the supervision strategy to handle exceptions for read function or failures of produced Futures. All exceptions thrown by create or close as well as fails of returned futures will fail the stream.

        Restart supervision strategy will close and create resource. Default strategy is Stop which means that stream will be terminated on error in read function (or future) by default.

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

        Adheres to the ActorAttributes.SupervisionStrategy attribute.

        Parameters:
        create - - function that is called on stream start and creates/opens resource.
        read - - function that reads data from opened resource. It is called each time backpressure signal is received. Stream calls close and completes when CompletionStage from read function returns None.
        close - - function that closes resource
        Returns:
        (undocumented)
      • upcast

        public static <SuperOut,​Out extends SuperOut,​Mat> Source<SuperOut,​Mat> upcast​(Source<Out,​Mat> source)
        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.

        Example:

        
         Source<Apple, NotUsed> apples = Source.single(new Apple());
         Source<Orange, NotUsed> oranges = Source.single(new Orange());
         Source<Fruit, NotUsed> appleFruits = Source.upcast(apples);
         Source<Fruit, NotUsed> orangeFruits = Source.upcast(oranges);
        
         Source<Fruit, NotUsed> fruits = appleFruits.merge(orangeFruits);
         

        Parameters:
        source - (undocumented)
        Returns:
        A source with the supertype as elements
      • shape

        public SourceShape<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<Out,​Mat>
        Returns:
        (undocumented)
      • traversalBuilder

        public 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<Out,​Mat>
        Returns:
        (undocumented)
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • asScala

        public Source<Out,​Mat> asScala()
        Converts this Java DSL element to its Scala DSL counterpart.
        Returns:
        (undocumented)
      • mapMaterializedValue

        public <Mat2> Source<Out,​Mat2> mapMaterializedValue​(Function<Mat,​Mat2> f)
        Transform only the materialized value of this Source, leaving all other properties as they were.
        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • preMaterialize

        public Pair<Mat,​Source<Out,​NotUsed>> preMaterialize​(Materializer materializer)
        Materializes this Source, immediately returning (1) its materialized value, and (2) a new Source that can be used to consume elements from the newly materialized Source.
        Parameters:
        materializer - (undocumented)
        Returns:
        (undocumented)
      • via

        public <T,​M> Source<T,​Mat> via​(Graph<FlowShape<Out,​T>,​M> flow)
        Transform this Source by appending the given processing operators.
        
             +----------------------------+
             | Resulting Source           |
             |                            |
             |  +------+        +------+  |
             |  |      |        |      |  |
             |  | this | ~Out~> | flow | ~~> T
             |  |      |        |      |  |
             |  +------+        +------+  |
             +----------------------------+
         
        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.
        Parameters:
        flow - (undocumented)
        Returns:
        (undocumented)
      • viaMat

        public <T,​M,​M2> Source<T,​M2> viaMat​(Graph<FlowShape<Out,​T>,​M> flow,
                                                              Function2<Mat,​M,​M2> combine)
        Transform this Source by appending the given processing operators.
        
             +----------------------------+
             | Resulting Source           |
             |                            |
             |  +------+        +------+  |
             |  |      |        |      |  |
             |  | this | ~Out~> | flow | ~~> T
             |  |      |        |      |  |
             |  +------+        +------+  |
             +----------------------------+
         
        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.

        Parameters:
        flow - (undocumented)
        combine - (undocumented)
        Returns:
        (undocumented)
      • to

        public <M> RunnableGraph<Mat> to​(Graph<SinkShape<Out>,​M> sink)
        Connect this Source to a Sink, concatenating the processing steps of both.
        
             +----------------------------+
             | Resulting RunnableGraph    |
             |                            |
             |  +------+        +------+  |
             |  |      |        |      |  |
             |  | this | ~Out~> | sink |  |
             |  |      |        |      |  |
             |  +------+        +------+  |
             +----------------------------+
         
        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.
        Parameters:
        sink - (undocumented)
        Returns:
        (undocumented)
      • toMat

        public <M,​M2> RunnableGraph<M2> toMat​(Graph<SinkShape<Out>,​M> sink,
                                                    Function2<Mat,​M,​M2> combine)
        Connect this Source to a Sink, concatenating the processing steps of both.
        
             +----------------------------+
             | Resulting RunnableGraph    |
             |                            |
             |  +------+        +------+  |
             |  |      |        |      |  |
             |  | this | ~Out~> | sink |  |
             |  |      |        |      |  |
             |  +------+        +------+  |
             +----------------------------+
         
        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.

        Parameters:
        sink - (undocumented)
        combine - (undocumented)
        Returns:
        (undocumented)
      • runWith

        public <M> M runWith​(Graph<SinkShape<Out>,​M> sink,
                             Materializer materializer)
        Connect this Source to a Sink and run it. The returned value is the materialized value of the Sink, e.g. the Publisher of a Sink.asPublisher.
        Parameters:
        sink - (undocumented)
        materializer - (undocumented)
        Returns:
        (undocumented)
      • runFold

        public <U> java.util.concurrent.CompletionStage<U> runFold​(U zero,
                                                                   Function2<U,​Out,​U> f,
                                                                   Materializer materializer)
        Shortcut for running this Source with a fold function. The given function is invoked for every received element, giving it its previous output (or the given zero value) and the element as input. The returned CompletionStage will be completed with value of the final function evaluation when the input stream ends, or completed with Failure if there is a failure is signaled in the stream.
        Parameters:
        zero - (undocumented)
        f - (undocumented)
        materializer - (undocumented)
        Returns:
        (undocumented)
      • runFoldAsync

        public <U> java.util.concurrent.CompletionStage<U> runFoldAsync​(U zero,
                                                                        Function2<U,​Out,​java.util.concurrent.CompletionStage<U>> f,
                                                                        Materializer materializer)
        Shortcut for running this Source with an asynchronous fold function. The given function is invoked for every received element, giving it its previous output (or the given zero value) and the element as input. The returned CompletionStage will be completed with value of the final function evaluation when the input stream ends, or completed with Failure if there is a failure is signaled in the stream.
        Parameters:
        zero - (undocumented)
        f - (undocumented)
        materializer - (undocumented)
        Returns:
        (undocumented)
      • runReduce

        public java.util.concurrent.CompletionStage<Out> runReduce​(Function2<Out,​Out,​Out> f,
                                                                   Materializer materializer)
        Shortcut for running this Source with a reduce function. The given function is invoked for every received element, giving it its previous output (from the second ones) an the element as input. The returned CompletionStage will be completed with value of the final function evaluation when the input stream ends, or completed with Failure if there is a failure is signaled in the stream.

        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.

        Parameters:
        f - (undocumented)
        materializer - (undocumented)
        Returns:
        (undocumented)
      • concat

        public <M> Source<Out,​Mat> concat​(Graph<SourceShape<Out>,​M> that)
        Concatenate this Source with the given one, meaning that once current is exhausted and all result elements have been generated, the given source elements will be produced.

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

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

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

        '''Backpressures when''' downstream backpressures

        '''Completes when''' given Source completes

        '''Cancels when''' downstream cancels

        Parameters:
        that - (undocumented)
        Returns:
        (undocumented)
      • concatMat

        public <M,​M2> Source<Out,​M2> concatMat​(Graph<SourceShape<Out>,​M> that,
                                                           Function2<Mat,​M,​M2> matF)
        Concatenate this Source with the given one, meaning that once current is exhausted and all result elements have been generated, the given source elements will be produced.

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

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

        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.

        Parameters:
        that - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • prepend

        public <M> Source<Out,​Mat> prepend​(Graph<SourceShape<Out>,​M> that)
        Prepend the given Source to this one, meaning that once the given source is exhausted and all result elements have been generated, the current source's elements will be produced.

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

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

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

        '''Backpressures when''' downstream backpressures

        '''Completes when''' given Source completes

        '''Cancels when''' downstream cancels

        Parameters:
        that - (undocumented)
        Returns:
        (undocumented)
      • prependMat

        public <M,​M2> Source<Out,​M2> prependMat​(Graph<SourceShape<Out>,​M> that,
                                                            Function2<Mat,​M,​M2> matF)
        Prepend the given Source to this one, meaning that once the given source is exhausted and all result elements have been generated, the current source's elements will be produced.

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

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

        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.

        Parameters:
        that - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • orElse

        public <M> Source<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.

        Parameters:
        secondary - (undocumented)
        Returns:
        (undocumented)
      • orElseMat

        public <M,​M2> Source<Out,​M2> orElseMat​(Graph<SourceShape<Out>,​M> secondary,
                                                           Function2<Mat,​M,​M2> 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.

        Parameters:
        secondary - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
        See Also:
        orElse(akka.stream.Graph<akka.stream.SourceShape<Out>, M>)
      • alsoTo

        public Source<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(akka.stream.Graph<akka.stream.SinkShape<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

        Parameters:
        that - (undocumented)
        Returns:
        (undocumented)
      • divertTo

        public Source<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

        Parameters:
        that - (undocumented)
        when - (undocumented)
        Returns:
        (undocumented)
      • wireTap

        public Source<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(akka.stream.Graph<akka.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

        Parameters:
        that - (undocumented)
        Returns:
        (undocumented)
      • interleave

        public Source<Out,​Mat> interleave​(Graph<SourceShape<Out>,​?> that,
                                                int segmentSize)
        Interleave is a deterministic merge of the given Source with elements of this Source. It first emits segmentSize number of elements from this flow to downstream, then - same amount for that source, then repeat process.

        Example:

        
         Source.from(Arrays.asList(1, 2, 3)).interleave(Source.from(Arrays.asList(4, 5, 6, 7), 2)
         // 1, 2, 4, 5, 3, 6, 7
         

        After one of sources is complete than all the rest elements will be emitted from the second one

        If one of sources 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''' this Source and given one completes

        '''Cancels when''' downstream cancels

        Parameters:
        that - (undocumented)
        segmentSize - (undocumented)
        Returns:
        (undocumented)
      • interleave

        public Source<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

        Parameters:
        that - (undocumented)
        segmentSize - (undocumented)
        eagerClose - (undocumented)
        Returns:
        (undocumented)
      • interleaveMat

        public <M,​M2> Source<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 Source. It first emits segmentSize number of elements from this flow to downstream, then - same amount for that source, then repeat process.

        After one of sources is complete than all the rest elements will be emitted from the second one

        If one of sources 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.

        Parameters:
        that - (undocumented)
        segmentSize - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • interleaveMat

        public <M,​M2> Source<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 Source. 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.

        Parameters:
        that - (undocumented)
        segmentSize - (undocumented)
        eagerClose - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
        See Also:
        interleave(akka.stream.Graph<akka.stream.SourceShape<Out>, ?>, int)
      • merge

        public Source<Out,​Mat> merge​(Graph<SourceShape<Out>,​?> that)
        Merge the given Source to the current one, 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

        Parameters:
        that - (undocumented)
        Returns:
        (undocumented)
      • merge

        public Source<Out,​Mat> merge​(Graph<SourceShape<Out>,​?> that,
                                           boolean eagerComplete)
        Merge the given Source to the current one, 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

        Parameters:
        that - (undocumented)
        eagerComplete - (undocumented)
        Returns:
        (undocumented)
      • mergeMat

        public <M,​M2> Source<Out,​M2> mergeMat​(Graph<SourceShape<Out>,​M> that,
                                                          Function2<Mat,​M,​M2> matF)
        Merge the given Source to the current one, 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.

        Parameters:
        that - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • mergeMat

        public <M,​M2> Source<Out,​M2> mergeMat​(Graph<SourceShape<Out>,​M> that,
                                                          Function2<Mat,​M,​M2> matF,
                                                          boolean eagerComplete)
        Merge the given Source to the current one, 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.

        Parameters:
        that - (undocumented)
        matF - (undocumented)
        eagerComplete - (undocumented)
        Returns:
        (undocumented)
        See Also:
        merge(akka.stream.Graph<akka.stream.SourceShape<Out>, ?>)
      • mergeSorted

        public <M> Source<Out,​Mat> mergeSorted​(Graph<SourceShape<Out>,​M> that,
                                                     java.util.Comparator<Out> comp)
        Merge the given Source to this Source, 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

        Parameters:
        that - (undocumented)
        comp - (undocumented)
        Returns:
        (undocumented)
      • mergeSortedMat

        public <Mat2,​Mat3> Source<Out,​Mat3> mergeSortedMat​(Graph<SourceShape<Out>,​Mat2> that,
                                                                       java.util.Comparator<Out> comp,
                                                                       Function2<Mat,​Mat2,​Mat3> matF)
        Merge the given Source to this Source, 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.

        Parameters:
        that - (undocumented)
        comp - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • zip

        public <T> Source<Pair<Out,​T>,​Mat> zip​(Graph<SourceShape<T>,​?> that)
        Combine the elements of current Source and the given one into a stream of tuples.

        '''Emits when''' all of the inputs has an element available

        '''Backpressures when''' downstream backpressures

        '''Completes when''' any upstream completes

        '''Cancels when''' downstream cancels

        Parameters:
        that - (undocumented)
        Returns:
        (undocumented)
      • zipMat

        public <T,​M,​M2> Source<Pair<Out,​T>,​M2> zipMat​(Graph<SourceShape<T>,​M> that,
                                                                              Function2<Mat,​M,​M2> matF)
        Combine the elements of current Source and the given one 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.

        Parameters:
        that - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • zipLatest

        public <T> Source<Pair<Out,​T>,​Mat> zipLatest​(Graph<SourceShape<T>,​?> that)
        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

        Parameters:
        that - (undocumented)
        Returns:
        (undocumented)
      • zipLatestMat

        public <T,​M,​M2> Source<Pair<Out,​T>,​M2> zipLatestMat​(Graph<SourceShape<T>,​M> that,
                                                                                    Function2<Mat,​M,​M2> matF)
        Combine the elements of current Source and the given one 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.

        Parameters:
        that - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • zipWith

        public <Out2,​Out3> Source<Out3,​Mat> zipWith​(Graph<SourceShape<Out2>,​?> that,
                                                                Function2<Out,​Out2,​Out3> combine)
        Put together the elements of current Source and the given one into a stream of combined elements using a combiner function.

        '''Emits when''' all of the inputs has an element available

        '''Backpressures when''' downstream backpressures

        '''Completes when''' any upstream completes

        '''Cancels when''' downstream cancels

        Parameters:
        that - (undocumented)
        combine - (undocumented)
        Returns:
        (undocumented)
      • zipWithMat

        public <Out2,​Out3,​M,​M2> Source<Out3,​M2> zipWithMat​(Graph<SourceShape<Out2>,​M> that,
                                                                                   Function2<Out,​Out2,​Out3> combine,
                                                                                   Function2<Mat,​M,​M2> matF)
        Put together the elements of current Source and the given one 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.

        Parameters:
        that - (undocumented)
        combine - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • zipLatestWith

        public <Out2,​Out3> Source<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

        Parameters:
        that - (undocumented)
        combine - (undocumented)
        Returns:
        (undocumented)
      • zipLatestWithMat

        public <Out2,​Out3,​M,​M2> Source<Out3,​M2> zipLatestWithMat​(Graph<SourceShape<Out2>,​M> that,
                                                                                         Function2<Out,​Out2,​Out3> combine,
                                                                                         Function2<Mat,​M,​M2> matF)
        Put together the elements of current Source and the given one into a stream of combined elements using a combiner function, picking always the latest of the elements of each source.

        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.

        Parameters:
        that - (undocumented)
        combine - (undocumented)
        matF - (undocumented)
        Returns:
        (undocumented)
      • zipWithIndex

        public Source<Pair<Out,​java.lang.Long>,​Mat> zipWithIndex()
        Combine the elements of current Source 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

        Returns:
        (undocumented)
      • runForeach

        public java.util.concurrent.CompletionStage<Done> runForeach​(Procedure<Out> f,
                                                                     Materializer materializer)
        Shortcut for running this Source with a foreach procedure. The given procedure is invoked for each received element. The returned CompletionStage will be completed normally when reaching the normal end of the stream, or completed exceptionally if there is a failure is signaled in the stream.
        Parameters:
        f - (undocumented)
        materializer - (undocumented)
        Returns:
        (undocumented)
      • map

        public <T> Source<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.

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

        '''Backpressures when''' downstream backpressures

        '''Completes when''' upstream completes

        '''Cancels when''' downstream cancels

        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • wireTap

        public Source<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(akka.stream.Graph<akka.stream.SinkShape<Out>, ?>) which does backpressure instead of dropping elements.

        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,akka.japi.function.Function<Out,java.lang.Object>,akka.event.LoggingAdapter) operator instead, along with appropriate ActorAttributes.createLogLevels.

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

        '''Backpressures when''' downstream backpressures

        '''Completes when''' upstream completes

        '''Cancels when''' downstream cancels; Note that failures of the f function will not cause cancellation

        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • recover

        public Source<Out,​Mat> recover​(scala.PartialFunction<java.lang.Throwable,​Out> pf)
        Deprecated.
        Use recoverWithRetries instead. Since 2.4.4.
        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

        Parameters:
        pf - (undocumented)
        Returns:
        (undocumented)
      • recover

        public Source<Out,​Mat> recover​(java.lang.Class<? extends java.lang.Throwable> clazz,
                                             java.util.function.Supplier<Out> supplier)
        Deprecated.
        Use recoverWithRetries instead. Since 2.4.4.
        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

        Parameters:
        clazz - (undocumented)
        supplier - (undocumented)
        Returns:
        (undocumented)
      • mapError

        public Source<Out,​Mat> mapError​(scala.PartialFunction<java.lang.Throwable,​java.lang.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

        Parameters:
        pf - (undocumented)
        Returns:
        (undocumented)
      • recoverWith

        public Source<Out,​Mat> recoverWith​(scala.PartialFunction<java.lang.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

        Parameters:
        pf - (undocumented)
        Returns:
        (undocumented)
      • recoverWith

        public Source<Out,​Mat> recoverWith​(java.lang.Class<? extends java.lang.Throwable> clazz,
                                                 java.util.function.Supplier<Graph<SourceShape<Out>,​NotUsed>> supplier)
        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

        Parameters:
        clazz - (undocumented)
        supplier - (undocumented)
        Returns:
        (undocumented)
      • recoverWithRetries

        public Source<Out,​Mat> recoverWithRetries​(int attempts,
                                                        scala.PartialFunction<java.lang.Throwable,​? extends 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 - (undocumented)
        pf - (undocumented)
        Returns:
        (undocumented)
      • recoverWithRetries

        public Source<Out,​Mat> recoverWithRetries​(int attempts,
                                                        java.lang.Class<? extends java.lang.Throwable> clazz,
                                                        java.util.function.Supplier<Graph<SourceShape<Out>,​NotUsed>> supplier)
        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
        supplier - supply the new Source to be materialized
        Returns:
        (undocumented)
      • mapConcat

        public <T> Source<T,​Mat> mapConcat​(Function<Out,​? extends java.lang.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 has been emitted

        '''Cancels when''' downstream cancels

        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • statefulMapConcat

        public <T> Source<T,​Mat> statefulMapConcat​(Creator<Function<Out,​java.lang.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(akka.japi.function.Function<Out, ? extends 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.

        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

        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • mapAsync

        public <T> Source<T,​Mat> mapAsync​(int parallelism,
                                                Function<Out,​java.util.concurrent.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 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 Supervision.resume() or Supervision.restart() the element is dropped and the stream continues.

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

        Adheres to the ActorAttributes.SupervisionStrategy attribute.

        '''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 CompletionStage is not completed

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

        '''Cancels when''' downstream cancels

        Parameters:
        parallelism - (undocumented)
        f - (undocumented)
        Returns:
        (undocumented)
        See Also:
        mapAsyncUnordered(int, akka.japi.function.Function<Out, java.util.concurrent.CompletionStage<T>>)
      • mapAsyncUnordered

        public <T> Source<T,​Mat> mapAsyncUnordered​(int parallelism,
                                                         Function<Out,​java.util.concurrent.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 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 Supervision.resume() or Supervision.restart() 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 CompletionStages 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 has been completed and all elements has been emitted

        '''Cancels when''' downstream cancels

        Parameters:
        parallelism - (undocumented)
        f - (undocumented)
        Returns:
        (undocumented)
        See Also:
        mapAsync(int, akka.japi.function.Function<Out, java.util.concurrent.CompletionStage<T>>)
      • ask

        public <S> Source<S,​Mat> ask​(ActorRef ref,
                                           java.lang.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 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 akka.util.Status. An akka.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 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

        Parameters:
        ref - (undocumented)
        mapTo - (undocumented)
        timeout - (undocumented)
        Returns:
        (undocumented)
      • ask

        public <S> Source<S,​Mat> ask​(int parallelism,
                                           ActorRef ref,
                                           java.lang.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 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 akka.util.Status. An akka.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 behaviour as mapAsync).

        The operator fails with an 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

        Parameters:
        parallelism - (undocumented)
        ref - (undocumented)
        mapTo - (undocumented)
        timeout - (undocumented)
        Returns:
        (undocumented)
      • watch

        public Source<Out,​Mat> watch​(ActorRef ref)
        The operator fails with an 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

        Parameters:
        ref - (undocumented)
        Returns:
        (undocumented)
      • filter

        public Source<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

        Parameters:
        p - (undocumented)
        Returns:
        (undocumented)
      • filterNot

        public Source<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

        Parameters:
        p - (undocumented)
        Returns:
        (undocumented)
      • collect

        public <T> Source<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

        Parameters:
        pf - (undocumented)
        Returns:
        (undocumented)
      • collectType

        public <T> Source<T,​Mat> collectType​(java.lang.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

        Parameters:
        clazz - (undocumented)
        Returns:
        (undocumented)
      • grouped

        public Source<java.util.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

        Parameters:
        n - (undocumented)
        Returns:
        (undocumented)
      • limit

        public Source<Out,​Mat> limit​(int 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

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

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

        Parameters:
        n - (undocumented)
        Returns:
        (undocumented)
      • limitWeighted

        public Source<Out,​Mat> limitWeighted​(long n,
                                                   Function<Out,​java.lang.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

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

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

        Parameters:
        n - (undocumented)
        costFn - (undocumented)
        Returns:
        (undocumented)
      • sliding

        public Source<java.util.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

        Parameters:
        n - (undocumented)
        step - (undocumented)
        Returns:
        (undocumented)
      • scan

        public <T> Source<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 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

        Parameters:
        zero - (undocumented)
        f - (undocumented)
        Returns:
        (undocumented)
      • scanAsync

        public <T> Source<T,​Mat> scanAsync​(T zero,
                                                 Function2<T,​Out,​java.util.concurrent.CompletionStage<T>> f)
        Similar to scan but with a 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 akka.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 akka.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 FlowOps.scan

        Parameters:
        zero - (undocumented)
        f - (undocumented)
        Returns:
        (undocumented)
      • fold

        public <T> Source<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 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

        Parameters:
        zero - (undocumented)
        f - (undocumented)
        Returns:
        (undocumented)
      • foldAsync

        public <T> Source<T,​Mat> foldAsync​(T zero,
                                                 Function2<T,​Out,​java.util.concurrent.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 akka.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

        Parameters:
        zero - (undocumented)
        f - (undocumented)
        Returns:
        (undocumented)
      • reduce

        public Source<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.

        Adheres to the ActorAttributes.SupervisionStrategy attribute.

        '''Emits when''' upstream completes

        '''Backpressures when''' downstream backpressures

        '''Completes when''' upstream completes

        '''Cancels when''' downstream cancels

        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • intersperse

        public Source<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(list.intersperse(","))
         list.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

        Parameters:
        start - (undocumented)
        inject - (undocumented)
        end - (undocumented)
        Returns:
        (undocumented)
      • intersperse

        public Source<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

        Parameters:
        inject - (undocumented)
        Returns:
        (undocumented)
      • groupedWithin

        public Source<java.util.List<Out>,​Mat> groupedWithin​(int n,
                                                                   scala.concurrent.duration.FiniteDuration d)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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

        n must be positive, and d must be greater than 0 seconds, otherwise IllegalArgumentException is thrown.

        Parameters:
        n - (undocumented)
        d - (undocumented)
        Returns:
        (undocumented)
      • groupedWithin

        public Source<java.util.List<Out>,​Mat> groupedWithin​(int n,
                                                                   java.time.Duration d)
        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

        n must be positive, and d must be greater than 0 seconds, otherwise IllegalArgumentException is thrown.

        Parameters:
        n - (undocumented)
        d - (undocumented)
        Returns:
        (undocumented)
      • groupedWeightedWithin

        public Source<java.util.List<Out>,​Mat> groupedWeightedWithin​(long maxWeight,
                                                                           Function<Out,​java.lang.Long> costFn,
                                                                           scala.concurrent.duration.FiniteDuration d)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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 d must be greater than 0 seconds, otherwise IllegalArgumentException is thrown.

        Parameters:
        maxWeight - (undocumented)
        costFn - (undocumented)
        d - (undocumented)
        Returns:
        (undocumented)
      • groupedWeightedWithin

        public Source<java.util.List<Out>,​Mat> groupedWeightedWithin​(long maxWeight,
                                                                           Function<Out,​java.lang.Long> costFn,
                                                                           java.time.Duration d)
        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 d must be greater than 0 seconds, otherwise IllegalArgumentException is thrown.

        Parameters:
        maxWeight - (undocumented)
        costFn - (undocumented)
        d - (undocumented)
        Returns:
        (undocumented)
      • delay

        public Source<Out,​Mat> delay​(scala.concurrent.duration.FiniteDuration of,
                                           DelayOverflowStrategy strategy)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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 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 withAttributes(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 has 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
        Returns:
        (undocumented)
      • delay

        public Source<Out,​Mat> delay​(java.time.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 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 withAttributes(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 has 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
        Returns:
        (undocumented)
      • drop

        public Source<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

        Parameters:
        n - (undocumented)
        Returns:
        (undocumented)
      • dropWithin

        public Source<Out,​Mat> dropWithin​(scala.concurrent.duration.FiniteDuration d)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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

        Parameters:
        d - (undocumented)
        Returns:
        (undocumented)
      • dropWithin

        public Source<Out,​Mat> dropWithin​(java.time.Duration d)
        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

        Parameters:
        d - (undocumented)
        Returns:
        (undocumented)
      • takeWhile

        public Source<Out,​Mat> takeWhile​(Predicate<Out> p,
                                               boolean inclusive)
        Terminate processing (and cancel the upstream publisher) after predicate returns false for the first time, including the first failed element if inclusive is true 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 Source.limit, Source.limitWeighted

        Parameters:
        p - (undocumented)
        inclusive - (undocumented)
        Returns:
        (undocumented)
      • takeWhile

        public Source<Out,​Mat> takeWhile​(Predicate<Out> p)
        Terminate processing (and cancel the upstream publisher) after predicate returns false 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.

        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 upstream completes

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

        See also Source.limit, Source.limitWeighted

        Parameters:
        p - (undocumented)
        Returns:
        (undocumented)
      • dropWhile

        public Source<Out,​Mat> dropWhile​(Predicate<Out> p)
        Discard elements at the beginning of the stream while predicate is true. No elements will be dropped after predicate first time returned false.

        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

        Parameters:
        p - predicate is evaluated for each new element until first time returns false
        Returns:
        (undocumented)
      • take

        public Source<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

        Parameters:
        n - (undocumented)
        Returns:
        (undocumented)
      • takeWithin

        public Source<Out,​Mat> takeWithin​(scala.concurrent.duration.FiniteDuration d)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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

        Parameters:
        d - (undocumented)
        Returns:
        (undocumented)
      • takeWithin

        public Source<Out,​Mat> takeWithin​(java.time.Duration d)
        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

        Parameters:
        d - (undocumented)
        Returns:
        (undocumented)
      • conflateWithSeed

        public <S> Source<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 Source.conflate Source.batch Source.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
        Returns:
        (undocumented)
      • conflate

        public Source<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 Source.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 Source.conflateWithSeed Source.batch Source.batchWeighted

        Parameters:
        aggregate - Takes the currently aggregated value and the current pending element to produce a new aggregate
        Returns:
        (undocumented)
      • batch

        public <S> Source<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 Source.conflate, Source.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
        Returns:
        (undocumented)
      • batchWeighted

        public <S> Source<S,​Mat> batchWeighted​(long max,
                                                     Function<Out,​java.lang.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 Source.conflate, Source.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
        Returns:
        (undocumented)
      • expand

        public <U> Source<U,​Mat> expand​(Function<Out,​java.util.Iterator<U>> expander)
        Allows a faster downstream to progress independently of a slower publisher 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 Supervision.restart() and Supervision.resume(). Exceptions from the expander function will complete the stream with failure.

        See also extrapolate(akka.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.
        Returns:
        (undocumented)
        See Also:
        extrapolate(akka.japi.function.Function<Out, java.util.Iterator<Out>>)
      • extrapolate

        public Source<Out,​Mat> extrapolate​(Function<Out,​java.util.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 Supervision.restart() and Supervision.resume(). Exceptions from the extrapolate function will complete the stream with failure.

        See also expand(akka.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.
        Returns:
        (undocumented)
        See Also:
        expand(akka.japi.function.Function<Out, java.util.Iterator<U>>)
      • extrapolate

        public Source<Out,​Mat> extrapolate​(Function<Out,​java.util.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 Supervision.restart() and Supervision.resume(). Exceptions from the extrapolate function will complete the stream with failure.

        See also expand(akka.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.
        Returns:
        (undocumented)
        See Also:
        expand(akka.japi.function.Function<Out, java.util.Iterator<U>>)
      • buffer

        public Source<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 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 has 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
        Returns:
        (undocumented)
      • prefixAndTail

        public Source<Pair<java.util.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 has 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 has been consumed and substream has been consumed

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

        Parameters:
        n - (undocumented)
        Returns:
        (undocumented)
      • groupBy

        public <K> SubSource<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 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 Supervision.resume() or 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
        Returns:
        (undocumented)
      • groupBy

        public <K> SubSource<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.

        The object returned from this method is not a normal Flow, it is a SubSource. 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 SubSource 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 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 Supervision.resume() or Supervision.restart() the element is dropped and the stream and substreams continue.

        Adheres to the ActorAttributes.SupervisionStrategy attribute.

        '''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 - (undocumented)
        Returns:
        (undocumented)
      • splitWhen

        public SubSource<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 SubSource. 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 SubSource 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 akka.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 akka.stream.Supervision.Resume or akka.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

        See also Source.splitAfter.

        Parameters:
        p - (undocumented)
        Returns:
        (undocumented)
      • splitWhen

        public SubSource<Out,​Mat> splitWhen​(SubstreamCancelStrategy substreamCancelStrategy,
                                                  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.

        Parameters:
        substreamCancelStrategy - (undocumented)
        p - (undocumented)
        Returns:
        (undocumented)
        See Also:
        splitWhen(akka.japi.function.Predicate<Out>)
      • splitAfter

        public SubSource<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 SubSource. 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 SubSource 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 akka.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 akka.stream.Supervision.Resume or akka.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

        See also Source.splitWhen.

        Parameters:
        p - (undocumented)
        Returns:
        (undocumented)
      • flatMapConcat

        public <T,​M> Source<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

        Parameters:
        f - (undocumented)
        Returns:
        (undocumented)
      • flatMapMerge

        public <T,​M> Source<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

        Parameters:
        breadth - (undocumented)
        f - (undocumented)
        Returns:
        (undocumented)
      • initialTimeout

        public Source<Out,​Mat> initialTimeout​(scala.concurrent.duration.FiniteDuration timeout)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        If the first element has not passed through this operator before the provided timeout, the stream is failed with a TimeoutException.

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

        Parameters:
        timeout - (undocumented)
        Returns:
        (undocumented)
      • initialTimeout

        public Source<Out,​Mat> initialTimeout​(java.time.Duration timeout)
        If the first element has not passed through this operator before the provided timeout, the stream is failed with a TimeoutException.

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

        Parameters:
        timeout - (undocumented)
        Returns:
        (undocumented)
      • completionTimeout

        public Source<Out,​Mat> completionTimeout​(scala.concurrent.duration.FiniteDuration timeout)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        If the completion of the stream does not happen until the provided timeout, the stream is failed with a TimeoutException.

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

        Parameters:
        timeout - (undocumented)
        Returns:
        (undocumented)
      • completionTimeout

        public Source<Out,​Mat> completionTimeout​(java.time.Duration timeout)
        If the completion of the stream does not happen until the provided timeout, the stream is failed with a TimeoutException.

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

        Parameters:
        timeout - (undocumented)
        Returns:
        (undocumented)
      • idleTimeout

        public Source<Out,​Mat> idleTimeout​(scala.concurrent.duration.FiniteDuration timeout)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        If the time between two processed elements exceeds the provided timeout, the stream is failed with a TimeoutException. 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

        Parameters:
        timeout - (undocumented)
        Returns:
        (undocumented)
      • idleTimeout

        public Source<Out,​Mat> idleTimeout​(java.time.Duration timeout)
        If the time between two processed elements exceeds the provided timeout, the stream is failed with a TimeoutException. 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

        Parameters:
        timeout - (undocumented)
        Returns:
        (undocumented)
      • backpressureTimeout

        public Source<Out,​Mat> backpressureTimeout​(scala.concurrent.duration.FiniteDuration timeout)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        If the time between the emission of an element and the following downstream demand exceeds the provided timeout, the stream is failed with a TimeoutException. 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

        Parameters:
        timeout - (undocumented)
        Returns:
        (undocumented)
      • backpressureTimeout

        public Source<Out,​Mat> backpressureTimeout​(java.time.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 TimeoutException. 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

        Parameters:
        timeout - (undocumented)
        Returns:
        (undocumented)
      • keepAlive

        public Source<Out,​Mat> keepAlive​(scala.concurrent.duration.FiniteDuration maxIdle,
                                               Creator<Out> injectedElem)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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

        Parameters:
        maxIdle - (undocumented)
        injectedElem - (undocumented)
        Returns:
        (undocumented)
      • keepAlive

        public Source<Out,​Mat> keepAlive​(java.time.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

        Parameters:
        maxIdle - (undocumented)
        injectedElem - (undocumented)
        Returns:
        (undocumented)
      • throttle

        public Source<Out,​Mat> throttle​(int elements,
                                              java.time.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 akka.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

        Parameters:
        elements - (undocumented)
        per - (undocumented)
        Returns:
        (undocumented)
      • throttle

        public Source<Out,​Mat> throttle​(int elements,
                                              scala.concurrent.duration.FiniteDuration per,
                                              int maximumBurst,
                                              ThrottleMode mode)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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: - akka.stream.ThrottleMode.Shaping makes pauses before emitting messages to meet throttle rate - akka.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

        Parameters:
        elements - (undocumented)
        per - (undocumented)
        maximumBurst - (undocumented)
        mode - (undocumented)
        Returns:
        (undocumented)
      • throttle

        public Source<Out,​Mat> throttle​(int elements,
                                              java.time.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: - akka.stream.ThrottleMode.Shaping makes pauses before emitting messages to meet throttle rate - akka.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

        Parameters:
        elements - (undocumented)
        per - (undocumented)
        maximumBurst - (undocumented)
        mode - (undocumented)
        Returns:
        (undocumented)
      • throttle

        public Source<Out,​Mat> throttle​(int cost,
                                              java.time.Duration per,
                                              Function<Out,​java.lang.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 akka.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

        Parameters:
        cost - (undocumented)
        per - (undocumented)
        costCalculation - (undocumented)
        Returns:
        (undocumented)
      • throttle

        public Source<Out,​Mat> throttle​(int cost,
                                              scala.concurrent.duration.FiniteDuration per,
                                              int maximumBurst,
                                              Function<Out,​java.lang.Integer> costCalculation,
                                              ThrottleMode mode)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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: - akka.stream.ThrottleMode.Shaping makes pauses before emitting messages to meet throttle rate - akka.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

        Parameters:
        cost - (undocumented)
        per - (undocumented)
        maximumBurst - (undocumented)
        costCalculation - (undocumented)
        mode - (undocumented)
        Returns:
        (undocumented)
      • throttle

        public Source<Out,​Mat> throttle​(int cost,
                                              java.time.Duration per,
                                              int maximumBurst,
                                              Function<Out,​java.lang.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: - akka.stream.ThrottleMode.Shaping makes pauses before emitting messages to meet throttle rate - akka.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

        Parameters:
        cost - (undocumented)
        per - (undocumented)
        maximumBurst - (undocumented)
        costCalculation - (undocumented)
        mode - (undocumented)
        Returns:
        (undocumented)
      • throttleEven

        public Source<Out,​Mat> throttleEven​(int elements,
                                                  scala.concurrent.duration.FiniteDuration per,
                                                  ThrottleMode mode)
        Deprecated.
        Use throttle without `maximumBurst` parameter instead. Since 2.5.12.
        This is a simplified version of throttle that spreads events evenly across the given time interval.

        Use this operator when you need just slow down a stream without worrying about exact amount of time between events.

        If you want to be sure that no time interval has no more than specified number of events you need to use throttle() with maximumBurst attribute.

        Parameters:
        elements - (undocumented)
        per - (undocumented)
        mode - (undocumented)
        Returns:
        (undocumented)
        See Also:
        throttle(int, java.time.Duration)
      • throttleEven

        public Source<Out,​Mat> throttleEven​(int elements,
                                                  java.time.Duration per,
                                                  ThrottleMode mode)
        Deprecated.
        Use throttle without `maximumBurst` parameter instead. Since 2.5.12.
        This is a simplified version of throttle that spreads events evenly across the given time interval.

        Use this operator when you need just slow down a stream without worrying about exact amount of time between events.

        If you want to be sure that no time interval has no more than specified number of events you need to use throttle() with maximumBurst attribute.

        Parameters:
        elements - (undocumented)
        per - (undocumented)
        mode - (undocumented)
        Returns:
        (undocumented)
        See Also:
        throttle(int, java.time.Duration)
      • throttleEven

        public Source<Out,​Mat> throttleEven​(int cost,
                                                  scala.concurrent.duration.FiniteDuration per,
                                                  scala.Function1<Out,​java.lang.Object> costCalculation,
                                                  ThrottleMode mode)
        Deprecated.
        Use throttle without `maximumBurst` parameter instead. Since 2.5.12.
        This is a simplified version of throttle that spreads events evenly across the given time interval.

        Use this operator when you need just slow down a stream without worrying about exact amount of time between events.

        If you want to be sure that no time interval has no more than specified number of events you need to use throttle() with maximumBurst attribute.

        Parameters:
        cost - (undocumented)
        per - (undocumented)
        costCalculation - (undocumented)
        mode - (undocumented)
        Returns:
        (undocumented)
        See Also:
        throttle(int, java.time.Duration)
      • throttleEven

        public Source<Out,​Mat> throttleEven​(int cost,
                                                  java.time.Duration per,
                                                  scala.Function1<Out,​java.lang.Object> costCalculation,
                                                  ThrottleMode mode)
        Deprecated.
        Use throttle without `maximumBurst` parameter instead. Since 2.5.12.
        This is a simplified version of throttle that spreads events evenly across the given time interval.

        Use this operator when you need just slow down a stream without worrying about exact amount of time between events.

        If you want to be sure that no time interval has no more than specified number of events you need to use throttle() with maximumBurst attribute.

        Parameters:
        cost - (undocumented)
        per - (undocumented)
        costCalculation - (undocumented)
        mode - (undocumented)
        Returns:
        (undocumented)
        See Also:
        throttle(int, java.time.Duration)
      • detach

        public Source<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

        Returns:
        (undocumented)
      • watchTermination

        public <M> Source<Out,​M> watchTermination​(Function2<Mat,​java.util.concurrent.CompletionStage<Done>,​M> matF)
        Materializes to Future[Done] 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.
        Parameters:
        matF - (undocumented)
        Returns:
        (undocumented)
      • monitor

        public <M> Source<Out,​M> monitor​(Function2<Mat,​FlowMonitor<Out>,​M> combine)
        Deprecated.
        Use monitor() or monitorMat(combine) instead. Since 2.5.17.
        Materializes to FlowMonitor 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.
        Parameters:
        combine - (undocumented)
        Returns:
        (undocumented)
      • monitorMat

        public <M> Source<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.
        Parameters:
        combine - (undocumented)
        Returns:
        (undocumented)
      • monitor

        public Source<Out,​Pair<Mat,​FlowMonitor<Out>>> monitor()
        Materializes to Pair>, 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 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.

        Returns:
        (undocumented)
      • initialDelay

        public Source<Out,​Mat> initialDelay​(scala.concurrent.duration.FiniteDuration delay)
        Deprecated.
        Use the overloaded one which accepts java.time.Duration instead. Since 2.5.12.
        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

        Parameters:
        delay - (undocumented)
        Returns:
        (undocumented)
      • initialDelay

        public Source<Out,​Mat> initialDelay​(java.time.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

        Parameters:
        delay - (undocumented)
        Returns:
        (undocumented)
      • withAttributes

        public Source<Out,​Mat> withAttributes​(Attributes attr)
        Replace the attributes of this Source with the given ones. If this Source 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:
        withAttributes in interface Graph<Out,​Mat>
        Parameters:
        attr - (undocumented)
        Returns:
        (undocumented)
      • addAttributes

        public Source<Out,​Mat> addAttributes​(Attributes attr)
        Add the given attributes to this Source. 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 Source 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<Out,​Mat>
        Parameters:
        attr - (undocumented)
        Returns:
        (undocumented)
      • named

        public Source<Out,​Mat> named​(java.lang.String name)
        Add a name attribute to this Source.
        Specified by:
        named in interface Graph<Out,​Mat>
        Parameters:
        name - (undocumented)
        Returns:
        (undocumented)
      • async

        public Source<Out,​Mat> async()
        Put an asynchronous boundary around this Source
        Specified by:
        async in interface Graph<Out,​Mat>
        Returns:
        (undocumented)
      • async

        public Source<Out,​Mat> async​(java.lang.String dispatcher)
        Put an asynchronous boundary around this Source

        Specified by:
        async in interface Graph<Out,​Mat>
        Parameters:
        dispatcher - Run the graph on this dispatcher
        Returns:
        (undocumented)
      • async

        public Source<Out,​Mat> async​(java.lang.String dispatcher,
                                           int inputBufferSize)
        Put an asynchronous boundary around this Source

        Specified by:
        async in interface Graph<Out,​Mat>
        Parameters:
        dispatcher - Run the graph on this dispatcher
        inputBufferSize - Set the input buffer to this size for the graph
        Returns:
        (undocumented)
      • log

        public Source<Out,​Mat> log​(java.lang.String name,
                                         Function<Out,​java.lang.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

        Parameters:
        name - (undocumented)
        extract - (undocumented)
        log - (undocumented)
        Returns:
        (undocumented)
      • log

        public Source<Out,​Mat> log​(java.lang.String name,
                                         Function<Out,​java.lang.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 akka.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

        Parameters:
        name - (undocumented)
        extract - (undocumented)
        Returns:
        (undocumented)
      • log

        public Source<Out,​Mat> log​(java.lang.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

        Parameters:
        name - (undocumented)
        log - (undocumented)
        Returns:
        (undocumented)
      • log

        public Source<Out,​Mat> log​(java.lang.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 akka.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

        Parameters:
        name - (undocumented)
        Returns:
        (undocumented)
      • startContextPropagation

        public <Ctx> SourceWithContext<Ctx,​Out,​Mat> startContextPropagation​(Function<Out,​Ctx> extractContext)
        API MAY CHANGE
        Parameters:
        extractContext - (undocumented)
        Returns:
        (undocumented)