Package org.apache.pekko.stream.scaladsl

Class Flow<In,Out,Mat>

java.lang.Object
org.apache.pekko.stream.scaladsl.Flow<In,Out,Mat>
All Implemented Interfaces:
Graph<FlowShape<In,Out>,Mat>, FlowOps<Out,Mat>, FlowOpsMat<Out,Mat>
public final class Flow<In,Out,Mat> extends Object implements FlowOpsMat<Out,Mat>, Graph<FlowShape<In,Out>,Mat>
A Flow is a set of stream processing steps that has one open input and one open output.

  • Constructor Details

    • Flow

      public Flow(org.apache.pekko.stream.impl.LinearTraversalBuilder traversalBuilder, FlowShape<In,Out> shape)

  • Method Details

    • fromProcessor

      public static <I, O> Flow<I,O,NotUsed> fromProcessor(scala.Function0<org.reactivestreams.Processor<I,O>> processorFactory)
      Creates a Flow from a Reactive Streams Processor

    • fromProcessorMat

      public static <I, O, M> Flow<I,O,M> fromProcessorMat(scala.Function0<scala.Tuple2<org.reactivestreams.Processor<I,O>,M>> processorFactory)
      Creates a Flow from a Reactive Streams Processor and returns a materialized value.

    • apply

      public static <T> Flow<T,T,NotUsed> apply()
      Returns a Flow which outputs all its inputs.

    • fromFunction

      public static <A, B> Flow<A,B,NotUsed> fromFunction(scala.Function1<A,B> f)
      Creates a [Flow] which will use the given function to transform its inputs to outputs. It is equivalent to Flow[T].map(f)

    • optionalVia

      public static <FIn, FOut, FViaOut, FMat, FViaMat, Mat> Flow<FIn,scala.Option<FViaOut>,Mat> optionalVia(Flow<FIn,scala.Option<FOut>,FMat> flow, Flow<FOut,FViaOut,FViaMat> viaFlow, scala.Function2<FMat,FViaMat,Mat> combine)
      Creates a FlowW from an existing base Flow outputting an optional element and applying an additional viaFlow only if the element in the stream is defined.

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

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

      '''Completes when''' upstream completes

      '''Cancels when''' downstream cancels

      Parameters:
      flow - The base flow that outputs an optional element
      viaFlow - The flow that gets used if the optional element in is defined.
      combine - How to combine the materialized values of flow and viaFlow
      Returns:
      a Flow with the viaFlow applied onto defined elements of the flow. The output value is contained within an Option which indicates whether the original flow's element had viaFlow applied.
      Since:
      1.1.0

    • fromGraph

      public static <I, O, M> Flow<I,O,M> fromGraph(Graph<FlowShape<I,O>,M> g)
      A graph with the shape of a flow logically is a flow, this method makes it so also in type.

    • fromMaterializer

      public static <T, U, M> Flow<T,U,scala.concurrent.Future<M>> fromMaterializer(scala.Function2<Materializer,Attributes,Flow<T,U,M>> factory)
      Defers the creation of a Flow until materialization. The factory function exposes Materializer which is going to be used during materialization and Attributes of the Flow returned by this method.

    • fromSinkAndSource

      public static <I, O> Flow<I,O,NotUsed> fromSinkAndSource(Graph<SinkShape<I>,?> sink, Graph<SourceShape<O>,?> source)
      Creates a Flow from a Sink and a Source where the Flow's input will be sent to the Sink and the Flow's output will come from the Source.

      The resulting flow can be visualized as: 

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

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

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

    • fromSinkAndSourceMat

      public static <I, O, M1, M2, M> Flow<I,O,M> fromSinkAndSourceMat(Graph<SinkShape<I>,M1> sink, Graph<SourceShape<O>,M2> source, scala.Function2<M1,M2,M> combine)
      Creates a Flow from a Sink and a Source where the Flow's input will be sent to the Sink and the Flow's output will come from the Source.

      The resulting flow can be visualized as: 

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

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

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

    • fromSinkAndSourceCoupled

      public static <I, O> Flow<I,O,NotUsed> fromSinkAndSourceCoupled(Graph<SinkShape<I>,?> sink, Graph<SourceShape<O>,?> source)
      Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow from them. Similar to Flow.fromSinkAndSource however couples the termination of these two operators.

      The resulting flow can be visualized as: 

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

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

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

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

    • fromSinkAndSourceCoupledMat

      public static <I, O, M1, M2, M> Flow<I,O,M> fromSinkAndSourceCoupledMat(Graph<SinkShape<I>,M1> sink, Graph<SourceShape<O>,M2> source, scala.Function2<M1,M2,M> combine)
      Allows coupling termination (cancellation, completion, erroring) of Sinks and Sources while creating a Flow from them. Similar to Flow.fromSinkAndSource however couples the termination of these two operators.

      The resulting flow can be visualized as: 

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

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

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

    • futureFlow

      public static <I, O, M> Flow<I,O,scala.concurrent.Future<M>> futureFlow(scala.concurrent.Future<Flow<I,O,M>> flow)
      Turn a Future[Flow] into a flow that will consume the values of the source when the future completes successfully. If the Future is completed with a failure the stream is failed.

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

      The operator's default behavior in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately. This behavior can be controlled by setting the pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested attribute, this will delay downstream cancellation until nested flow's materialization which is then immediately cancelled (with the original cancellation cause).

    • lazyFlow

      public static <I, O, M> Flow<I,O,scala.concurrent.Future<M>> lazyFlow(scala.Function0<Flow<I,O,M>> create)
      Defers invoking the create function to create a future flow until there is downstream demand and passing that downstream demand upstream triggers the first element.

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

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

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

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

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

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

      '''Cancels when''' downstream cancels (see below)

      The operator's default behavior in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately. This behavior can be controlled by setting the pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested attribute, this will delay downstream cancellation until nested flow's materialization which is then immediately cancelled (with the original cancellation cause).

    • lazyFutureFlow

      public static <I, O, M> Flow<I,O,scala.concurrent.Future<M>> lazyFutureFlow(scala.Function0<scala.concurrent.Future<Flow<I,O,M>>> create)
      Defers invoking the create function to create a future flow until there downstream demand has caused upstream to send a first element.

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

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

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

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

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

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

      '''Cancels when''' downstream cancels (see below)

      The operator's default behavior in case of downstream cancellation before nested flow materialization (future completion) is to cancel immediately. This behavior can be controlled by setting the pekko.stream.Attributes.NestedMaterializationCancellationPolicy.PropagateToNested attribute, this will delay downstream cancellation until nested flow's materialization which is then immediately cancelled (with the original cancellation cause).

    • traversalBuilder

      public org.apache.pekko.stream.impl.LinearTraversalBuilder traversalBuilder()
      Description copied from interface: Graph
      INTERNAL API.

      Every materializable element must be backed by a stream layout module

      Specified by:
      traversalBuilder in interface Graph<In,Out>

    • shape

      public FlowShape<In,Out> shape()
      Description copied from interface: Graph
      The shape of a graph is all that is externally visible: its inlets and outlets.
      Specified by:
      shape in interface Graph<In,Out>

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • via

      public <T, Mat2> Flow<In,T,Mat> via(Graph<FlowShape<Out,T>,Mat2> flow)
      Specified by:
      via in interface FlowOps<In,Out>

    • viaMat

      public <T, Mat2, Mat3> Flow<In,T,Mat3> viaMat(Graph<FlowShape<Out,T>,Mat2> flow, scala.Function2<Mat,Mat2,Mat3> combine)
      Description copied from interface: FlowOpsMat
      Transform this Flow by appending the given processing steps. 
      
     +---------------------------------+
     | Resulting Flow[In, T, M2]       |
     |                                 |
     |  +------+            +------+   |
     |  |      |            |      |   |
 In ~~> | this |  ~~Out~~>  | flow |  ~~> T
     |  |   Mat|            |     M|   |
     |  +------+            +------+   |
     +---------------------------------+
      The combine function is used to compose the materialized values of this flow and that flow into the materialized value of the resulting Flow.

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

      Specified by:
      viaMat in interface FlowOpsMat<In,Out>

    • to

      public <Mat2> Sink<In,Mat> to(Graph<SinkShape<Out>,Mat2> sink)
      Connect this Flow to a Sink, concatenating the processing steps of both. 
      
     +------------------------------+
     | Resulting Sink[In, Mat]      |
     |                              |
     |  +------+          +------+  |
     |  |      |          |      |  |
 In ~~> | flow | ~~Out~~> | sink |  |
     |  |   Mat|          |     M|  |
     |  +------+          +------+  |
     +------------------------------+
      The materialized value of the combined Sink will be the materialized value of the current flow (ignoring the given Sink&rsquo;s value), use {@link Flow#toMat[Mat2* toMat} if a different strategy is needed.

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

      Specified by:
      to in interface FlowOps<In,Out>

    • toMat

      public <Mat2, Mat3> Sink<In,Mat3> toMat(Graph<SinkShape<Out>,Mat2> sink, scala.Function2<Mat,Mat2,Mat3> combine)
      Connect this Flow to a Sink, concatenating the processing steps of both. 
      
     +----------------------------+
     | Resulting Sink[In, M2]     |
     |                            |
     |  +------+        +------+  |
     |  |      |        |      |  |
 In ~~> | flow | ~Out~> | sink |  |
     |  |   Mat|        |     M|  |
     |  +------+        +------+  |
     +----------------------------+
      The combine function is used to compose the materialized values of this flow and that Sink into the materialized value of the resulting Sink.

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

      Specified by:
      toMat in interface FlowOpsMat<In,Out>

    • mapMaterializedValue

      public <Mat2> Flow<In,Out,Mat2> mapMaterializedValue(scala.Function1<Mat,Mat2> f)
      Transform the materialized value of this Flow, leaving all other properties as they were.
      Specified by:
      mapMaterializedValue in interface FlowOpsMat<In,Out>

    • preMaterialize

      public scala.Tuple2<Mat,Flow<In,Out,NotUsed>> preMaterialize(Materializer materializer)
      Materializes this Flow, immediately returning (1) its materialized value, and (2) a newly materialized Flow. The returned flow is partial materialized and do not support multiple times materialization.

    • materializeIntoSource

      public <Mat1, Mat2> Source<Mat2,scala.concurrent.Future<NotUsed>> materializeIntoSource(Graph<SourceShape<In>,Mat1> source, Graph<SinkShape<Out>,scala.concurrent.Future<Mat2>> sink)
      Connects the Source to this Flow and materializes it using the Sink, immediately returning the values via the provided Sink as a new Source.

      Parameters:
      source - A source that connects to this flow
      sink - A sink which needs to materialize into a Future, typically one that collects values such as Sink.head or Sink.seq
      Returns:
      A new Source that contains the results of the Flow with the provided Source's elements run with the Sink
      Since:
      1.2.0

    • contramap

      public <In2> Flow<In2,Out,Mat> contramap(scala.Function1<In2,In> f)
      Transform this Flow by applying a function to each *incoming* upstream element before it is passed to the Flow

      '''Backpressures when''' original Flow backpressures

      '''Cancels when''' original Flow cancels

      Since:
      1.1.0

    • dimap

      public <In2, Out2> Flow<In2,Out2,Mat> dimap(scala.Function1<In2,In> f, scala.Function1<Out,Out2> g)
      Transform this Flow by applying a function f to each *incoming* upstream element before it is passed to the Flow, and a function g to each *outgoing* downstream element.

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

      '''Backpressures when''' original Flow backpressures

      '''Completes when''' original Flow completes

      '''Cancels when''' original Flow cancels

      Since:
      1.1.0

    • join

      public <Mat2> RunnableGraph<Mat> join(Graph<FlowShape<Out,In>,Mat2> flow)
      Join this Flow to another Flow, by cross connecting the inputs and outputs, creating a RunnableGraph. 
      
 +------+        +-------+
 |      | ~Out~> |       |
 | this |        | other |
 |      | <~In~  |       |
 +------+        +-------+
      The materialized value of the combined Flow will be the materialized value of the current flow (ignoring the other Flow&rsquo;s value), use {@link Flow#joinMat[Mat2* joinMat} if a different strategy is needed.

    • joinMat

      public <Mat2, Mat3> RunnableGraph<Mat3> joinMat(Graph<FlowShape<Out,In>,Mat2> flow, scala.Function2<Mat,Mat2,Mat3> combine)
      Join this Flow to another Flow, by cross connecting the inputs and outputs, creating a RunnableGraph 
      
 +------+        +-------+
 |      | ~Out~> |       |
 | this |        | other |
 |      | <~In~  |       |
 +------+        +-------+
      The combine function is used to compose the materialized values of this flow and that Flow into the materialized value of the resulting Flow.

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

    • join

      public <I2, O1, Mat2> Flow<I2,O1,Mat> join(Graph<BidiShape<Out,O1,I2,In>,Mat2> bidi)
      Join this Flow to a BidiFlow to close off the &ldquo;top&rdquo; of the protocol stack: 
      
 +---------------------------+
 | Resulting Flow            |
 |                           |
 | +------+        +------+  |
 | |      | ~Out~> |      | ~~> O1
 | | flow |        | bidi |  |
 | |      | <~In~  |      | <~~ I2
 | +------+        +------+  |
 +---------------------------+
      The materialized value of the combined Flow will be the materialized value of the current flow (ignoring the BidiFlow&rsquo;s value), use {@link Flow#joinMat[I2* joinMat} if a different strategy is needed.

    • joinMat

      public <I2, O1, Mat2, M> Flow<I2,O1,M> joinMat(Graph<BidiShape<Out,O1,I2,In>,Mat2> bidi, scala.Function2<Mat,Mat2,M> combine)
      Join this Flow to a BidiFlow to close off the &ldquo;top&rdquo; of the protocol stack: 
      
 +---------------------------+
 | Resulting Flow            |
 |                           |
 | +------+        +------+  |
 | |      | ~Out~> |      | ~~> O1
 | | flow |        | bidi |  |
 | |      | <~In~  |      | <~~ I2
 | +------+        +------+  |
 +---------------------------+
      The combine function is used to compose the materialized values of this flow and that BidiFlow into the materialized value of the resulting Flow.

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

    • withAttributes

      public Flow<In,Out,Mat> withAttributes(Attributes attr)
      Replace the attributes of this Flow with the given ones. If this Flow is a composite of multiple graphs, new attributes on the composite will be less specific than attributes set directly on the individual graphs of the composite.

      Note that this operation has no effect on an empty Flow (because the attributes apply only to the contained processing operators).

      Specified by:
      withAttributes in interface FlowOps<In,Out>
      Specified by:
      withAttributes in interface Graph<In,Out>

    • addAttributes

      public Flow<In,Out,Mat> addAttributes(Attributes attr)
      Add the given attributes to this Flow. If the specific attribute was already present on this graph this means the added attribute will be more specific than the existing one. If this Flow is a composite of multiple graphs, new attributes on the composite will be less specific than attributes set directly on the individual graphs of the composite.
      Specified by:
      addAttributes in interface FlowOps<In,Out>
      Specified by:
      addAttributes in interface Graph<In,Out>

    • named

      public Flow<In,Out,Mat> named(String name)
      Add a name attribute to this Flow.
      Specified by:
      named in interface FlowOps<In,Out>
      Specified by:
      named in interface Graph<In,Out>

    • async

      public Flow<In,Out,Mat> async()
      Put an asynchronous boundary around this Flow
      Specified by:
      async in interface FlowOps<In,Out>
      Specified by:
      async in interface Graph<In,Out>

    • async

      public Flow<In,Out,Mat> async(String dispatcher)
      Put an asynchronous boundary around this Flow

      Specified by:
      async in interface Graph<In,Out>
      Parameters:
      dispatcher - Run the graph on this dispatcher

    • async

      public Flow<In,Out,Mat> async(String dispatcher, int inputBufferSize)
      Put an asynchronous boundary around this Flow

      Specified by:
      async in interface Graph<In,Out>
      Parameters:
      dispatcher - Run the graph on this dispatcher
      inputBufferSize - Set the input buffer to this size for the graph

    • runWith

      public <Mat1, Mat2> scala.Tuple2<Mat1,Mat2> runWith(Graph<SourceShape<In>,Mat1> source, Graph<SinkShape<Out>,Mat2> sink, Materializer materializer)
      Connect the Source to this Flow and then connect it to the Sink and run it. The returned tuple contains the materialized values of the Source and Sink, e.g. the Subscriber of a of a Source#subscriber and and Publisher of a Sink#publisher.

      Note that the ActorSystem can be used as the implicit materializer parameter to use the pekko.stream.SystemMaterializer for running the stream.

    • toProcessor

      public RunnableGraph<org.reactivestreams.Processor<In,Out>> toProcessor()
      Converts this Flow to a RunnableGraph that materializes to a Reactive Streams Processor which implements the operations encapsulated by this Flow. Every materialization results in a new Processor instance, i.e. the returned RunnableGraph is reusable.

      Returns:
      A RunnableGraph that materializes to a Processor when run() is called on it.

    • asFlowWithContext

      public <U, CtxU, CtxOut> FlowWithContext<U,CtxU,Out,CtxOut,Mat> asFlowWithContext(scala.Function2<U,CtxU,In> collapseContext, scala.Function1<Out,CtxOut> extractContext)
      Turns a Flow into a FlowWithContext which manages a context per element along a stream.

      Parameters:
      collapseContext - turn each incoming pair of element and context value into an element of this Flow
      extractContext - turn each outgoing element of this Flow into an outgoing context value

    • asJava

      public <JIn extends In> Flow<JIn,Out,Mat> asJava()
      Converts this Scala DSL element to it's Java DSL counterpart.