Package org.apache.pekko.stream.javadsl

Class Sink<In,Mat>

java.lang.Object
org.apache.pekko.stream.javadsl.Sink<In,Mat>
All Implemented Interfaces:
Graph<SinkShape<In>,Mat>
public final class Sink<In,Mat> extends Object implements Graph<SinkShape<In>,Mat>
Java API

A Sink is a set of stream processing steps that has one open input. Can be used as a Subscriber

  • Constructor Details

  • Method Details

    • fold

      public static <U, In> Sink<In,CompletionStage<U>> fold(U zero, Function2<U,In,U> f)
      A Sink that will invoke the given function 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.

    • foldWhile

      public static <U, In> Sink<In,CompletionStage<U>> foldWhile(U zero, Predicate<U> p, Function2<U,In,U> f)
      A Sink that will invoke the given function 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, predicate p returns false, or completed with Failure if there is a failure is signaled in the stream.

      Since:
      1.1.0

    • foldAsync

      public static <U, In> Sink<In,CompletionStage<U>> foldAsync(U zero, Function2<U,In,CompletionStage<U>> f)
      A Sink that will invoke the given asynchronous function 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.

    • forall

      public static <In> Sink<In,CompletionStage<Boolean>> forall(Predicate<In> p)
      A Sink that will test the given predicate p for every received element and 1. completes and returns CompletionStage of true if the predicate is true for all elements; 2. completes and returns CompletionStage of true if the stream is empty (i.e. completes before signalling any elements); 3. completes and returns CompletionStage of false if the predicate is false for any element.

      The materialized value CompletionStage will be completed with the value true or false when the input stream ends, or completed with Failure if there is a failure signaled in the stream.

      Adheres to the ActorAttributes.SupervisionStrategy attribute.

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

      '''Backpressures when''' the invocation of predicate p has not yet completed

      '''Cancels when''' predicate p returns false

      Since:
      1.1.0

    • none

      public static <In> Sink<In,CompletionStage<Boolean>> none(Predicate<In> p)
      A Sink that will test the given predicate p for every received element and 1. completes and returns CompletionStage of true if the predicate is false for all elements; 2. completes and returns CompletionStage of true if the stream is empty (i.e. completes before signalling any elements); 3. completes and returns CompletionStage of false if the predicate is true for any element.

      The materialized value CompletionStage will be completed with the value true or false when the input stream ends, or completed with Failure if there is a failure signaled in the stream.

      Adheres to the ActorAttributes.SupervisionStrategy attribute.

      '''Completes when''' upstream completes or the predicate p returns true

      '''Backpressures when''' the invocation of predicate p has not yet completed

      '''Cancels when''' predicate p returns true

      Since:
      1.2.0

    • exists

      public static <In> Sink<In,CompletionStage<Boolean>> exists(Predicate<In> p)
      A Sink that will test the given predicate p for every received element and 1. completes and returns CompletionStage of true if the predicate is true for any element; 2. completes and returns CompletionStage of false if the stream is empty (i.e. completes before signalling any elements); 3. completes and returns CompletionStage of false if the predicate is false for all elements.

      The materialized value CompletionStage will be completed with the value true or false when the input stream ends, or completed with Failure if there is a failure signaled in the stream.

      Adheres to the ActorAttributes.SupervisionStrategy attribute.

      '''Completes when''' upstream completes or the predicate p returns true

      '''Backpressures when''' the invocation of predicate p has not yet completed

      '''Cancels when''' predicate p returns true

      Since:
      1.1.0

    • collect

      public static <U, In> Sink<In,CompletionStage<U>> collect(Collector<In,?,U> collector)
      Creates a sink which materializes into a CompletionStage which will be completed with a result of the Java Collector transformation and reduction operations. This allows usage of Java streams transformations for reactive streams. The Collector will trigger demand downstream. Elements emitted through the stream will be accumulated into a mutable result container, optionally transformed into a final representation after all input elements have been processed. The Collector can also do reduction at the end. Reduction processing is performed sequentially.

    • reduce

      public static <In> Sink<In,CompletionStage<In>> reduce(Function2<In,In,In> f)
      A Sink that will invoke the given function for every received element, giving it its previous output (from the second element) 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 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.

    • fromSubscriber

      public static <In> Sink<In,NotUsed> fromSubscriber(org.reactivestreams.Subscriber<In> subs)
      Helper to create Sink from Subscriber.

    • cancelled

      public static <T> Sink<T,NotUsed> cancelled()
      A Sink that immediately cancels its upstream after materialization.

    • ignore

      public static <T> Sink<T,CompletionStage<Done>> ignore()
      A Sink that will consume the stream and discard the elements.

    • never

      public static <T> Sink<T,CompletionStage<Done>> never()
      A Sink that will always backpressure never cancel and never consume any elements from the stream.

    • asPublisher

      public static <T> Sink<T,org.reactivestreams.Publisher<T>> asPublisher(AsPublisher fanout)
      A Sink that materializes into a Publisher.

      If fanout is true, the materialized Publisher will support multiple Subscribers and the size of the inputBuffer configured for this operator becomes the maximum number of elements that the fastest Subscriber can be ahead of the slowest one before slowing the processing down due to back pressure.

      If fanout is false then the materialized Publisher will only support a single Subscriber and reject any additional Subscribers.

    • source

      public static <T> Sink<T,Source<T,NotUsed>> source()
      A Sink that materializes this Sink itself as a Source. The returned Source is a "live view" onto the Sink and only supports a single Subscriber.

      Use BroadcastHub#sink if you need a Source that allows multiple subscribers.

      Note: even if the Source is directly connected to the Sink, there is still an asynchronous boundary between them; performance may be improved in the future.

      Since:
      1.3.0

    • foreach

      public static <T> Sink<T,CompletionStage<Done>> foreach(Procedure<T> f)
      A Sink that will invoke the given procedure for each received element. The sink is materialized into a CompletionStage which will be completed with Success when reaching the normal end of the stream, or completed with Failure if there is a failure signaled in the stream.

    • foreachAsync

      public static <T> Sink<T,CompletionStage<Done>> foreachAsync(int parallelism, Function<T,CompletionStage<Void>> f)
      A Sink that will invoke the given procedure asynchronously for each received element. The sink is materialized into a CompletionStage which will be completed with Success when reaching the normal end of the stream, or completed with Failure if there is a failure signaled in the stream.

    • onComplete

      public static <In> Sink<In,NotUsed> onComplete(Procedure<scala.util.Try<Done>> callback)
      A Sink that when the flow is completed, either through a failure or normal completion, apply the provided function with Success or Failure.

    • head

      public static <In> Sink<In,CompletionStage<In>> head()
      A Sink that materializes into a CompletionStage of the first value received. If the stream completes before signaling at least a single element, the CompletionStage will be failed with a NoSuchElementException. If the stream signals an error before signaling at least a single element, the CompletionStage will be failed with the streams exception.

      See also <In>headOption().

    • headOption

      public static <In> Sink<In,CompletionStage<Optional<In>>> headOption()
      A Sink that materializes into a CompletionStage of the optional first value received. If the stream completes before signaling at least a single element, the value of the CompletionStage will be an empty Optional. If the stream signals an error errors before signaling at least a single element, the CompletionStage will be failed with the streams exception.

      See also <In>head().

    • last

      public static <In> Sink<In,CompletionStage<In>> last()
      A Sink that materializes into a CompletionStage of the last value received. If the stream completes before signaling at least a single element, the CompletionStage will be failed with a NoSuchElementException. If the stream signals an error errors before signaling at least a single element, the CompletionStage will be failed with the streams exception.

      See also <In>lastOption(), <In>takeLast(int).

    • lastOption

      public static <In> Sink<In,CompletionStage<Optional<In>>> lastOption()
      A Sink that materializes into a CompletionStage of the optional last value received. If the stream completes before signaling at least a single element, the value of the CompletionStage will be an empty Optional. If the stream signals an error errors before signaling at least a single element, the CompletionStage will be failed with the streams exception.

      See also <In>head(), <In>takeLast(int).

    • takeLast

      public static <In> Sink<In,CompletionStage<List<In>>> takeLast(int n)
      A Sink that materializes into a CompletionStage of List containing the last n collected elements.

      If the stream completes before signaling at least n elements, the CompletionStage will complete with all elements seen so far. If the stream never completes the CompletionStage will never complete. If there is a failure signaled in the stream the CompletionStage will be completed with failure.

    • seq

      public static <In> Sink<In,CompletionStage<List<In>>> seq()
      A Sink that keeps on collecting incoming elements until upstream terminates. As upstream may be unbounded, Flow[T].take or the stricter Flow[T].limit (and their variants) may be used to ensure boundedness. Materializes into a CompletionStage of Seq[T] containing all the collected elements. List is limited to Integer.MAX_VALUE elements, this Sink will cancel the stream after having received that many elements.

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

    • count

      public static <In> Sink<In,CompletionStage<Long>> count()
      A Sink that counts all incoming elements until upstream terminates.

      Since upstream may be unbounded, consider using Flow[T].take or the stricter Flow[T].limit (and their variants) to ensure boundedness. The sink materializes into a CompletionStage of Long containing the total count of elements that passed through.

      '''Completes when''' upstream completes

      '''Backpressures when''' never (counting is a lightweight operation)

      '''Cancels when''' never

      Returns:
      a Sink that materializes to a CompletionStage[Long] with the element count
      Since:
      2.0.0

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

    • actorRef

      public static <In> Sink<In,NotUsed> actorRef(ActorRef ref, Object onCompleteMessage)
      Sends the elements of the stream to the given ActorRef. If the target actor terminates the stream will be canceled. When the stream is completed successfully the given onCompleteMessage will be sent to the destination actor. When the stream is completed with failure a pekko.actor.Status.Failure message will be sent to the destination actor.

      It will request at most maxInputBufferSize number of elements from upstream, but there is no back-pressure signal from the destination actor, i.e. if the actor is not consuming the messages fast enough the mailbox of the actor will grow. For potentially slow consumer actors it is recommended to use a bounded mailbox with zero mailbox-push-timeout-time or use a rate limiting operator in front of this Sink.

    • actorRefWithBackpressure

      public static <In> Sink<In,NotUsed> actorRefWithBackpressure(ActorRef ref, Object onInitMessage, Object ackMessage, Object onCompleteMessage, Function<Throwable,Object> onFailureMessage)
      Sends the elements of the stream to the given ActorRef that sends back back-pressure signal. First element is always onInitMessage, then stream is waiting for acknowledgement message ackMessage from the given actor which means that it is ready to process elements. It also requires ackMessage message after each stream element to make backpressure work.

      If the target actor terminates the stream will be canceled. When the stream is completed successfully the given onCompleteMessage will be sent to the destination actor. When the stream is completed with failure - result of onFailureMessage(throwable) message will be sent to the destination actor.

    • actorRefWithBackpressure

      public static <In> Sink<In,NotUsed> actorRefWithBackpressure(ActorRef ref, Object onInitMessage, Object onCompleteMessage, Function<Throwable,Object> onFailureMessage)
      Sends the elements of the stream to the given ActorRef that sends back back-pressure signal. First element is always onInitMessage, then stream is waiting for acknowledgement message from the given actor which means that it is ready to process elements. It also requires an ack message after each stream element to make backpressure work. This variant will consider any message as ack message.

      If the target actor terminates the stream will be canceled. When the stream is completed successfully the given onCompleteMessage will be sent to the destination actor. When the stream is completed with failure - result of onFailureMessage(throwable) message will be sent to the destination actor.

    • fromGraph

      public static <T, M> Sink<T,M> fromGraph(Graph<SinkShape<T>,M> g)
      A graph with the shape of a sink logically is a sink, this method makes it so also in type.

    • fromMaterializer

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

    • combine

      public static <T, U> Sink<T,NotUsed> combine(Sink<U,?> output1, Sink<U,?> output2, List<Sink<U,?>> rest, Function<Integer,Graph<UniformFanOutShape<T,U>,NotUsed>> fanOutStrategy)
      Combine several sinks with fan-out strategy like Broadcast or Balance and returns Sink.

    • combineMat

      public static <T, U, M1, M2, M> Sink<T,M> combineMat(Sink<U,M1> first, Sink<U,M2> second, Function<Integer,Graph<UniformFanOutShape<T,U>,NotUsed>> fanOutStrategy, Function2<M1,M2,M> matF)
      Combine two sinks with fan-out strategy like Broadcast or Balance and returns Sink with 2 outlets.
      Since:
      1.1.0

    • combine

      public static <T, U, M> Sink<T,List<M>> combine(List<? extends Graph<SinkShape<U>,M>> sinks, Function<Integer,Graph<UniformFanOutShape<T,U>,NotUsed>> fanOutStrategy)
      Combine several sinks with fan-out strategy like Broadcast or Balance and returns Sink. The fanoutGraph's outlets size must match the provides sinks'.
      Since:
      1.1.0

    • queue

      public static <T> Sink<T,SinkQueueWithCancel<T>> queue(int maxConcurrentPulls)
      Creates a Sink that is materialized as an pekko.stream.javadsl.SinkQueueWithCancel. pekko.stream.javadsl.SinkQueueWithCancel.pull method is pulling element from the stream and returns CompletionStage[Option[T}. CompletionStage completes when element is available.

      Before calling pull method second time you need to ensure that number of pending pulls is less then maxConcurrentPulls or wait until some of the previous Futures completes. Pull returns Failed future with ''IllegalStateException'' if there will be more then maxConcurrentPulls number of pending pulls.

      Sink will request at most number of elements equal to size of inputBuffer from upstream and then stop back pressure. You can configure size of input buffer by using Sink.withAttributes method.

      For stream completion you need to pull all elements from pekko.stream.javadsl.SinkQueueWithCancel including last None as completion marker

      See Also:
      • pekko.stream.javadsl.SinkQueueWithCancel

    • queue

      public static <T> Sink<T,SinkQueueWithCancel<T>> queue()
      Creates a Sink that is materialized as an pekko.stream.javadsl.SinkQueueWithCancel. pekko.stream.javadsl.SinkQueueWithCancel.pull method is pulling element from the stream and returns CompletionStage[Option[T}. CompletionStage completes when element is available.

      Before calling pull method second time you need to wait until previous CompletionStage completes. Pull returns Failed future with ''IllegalStateException'' if previous future has not yet completed.

      Sink will request at most number of elements equal to size of inputBuffer from upstream and then stop back pressure. You can configure size of input buffer by using Sink.withAttributes method.

      For stream completion you need to pull all elements from pekko.stream.javadsl.SinkQueueWithCancel including last None as completion marker

      See Also:
      • pekko.stream.javadsl.SinkQueueWithCancel

    • completionStageSink

      public static <T, M> Sink<T,CompletionStage<M>> completionStageSink(CompletionStage<Sink<T,M>> future)
      Turn a Future[Sink] into a Sink 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 sink or failed with a NeverMaterializedException if upstream fails or downstream cancels before the future has completed.

    • lazySink

      public static <T, M> Sink<T,CompletionStage<M>> lazySink(Creator<Sink<T,M>> create)
      Defers invoking the create function to create a sink until there is a first element passed from upstream.

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

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

    • lazyCompletionStageSink

      public static <T, M> Sink<T,CompletionStage<M>> lazyCompletionStageSink(Creator<CompletionStage<Sink<T,M>>> create)
      Defers invoking the create function to create a future sink until there is a first element passed from upstream.

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

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

    • shape

      public SinkShape<In> 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,Mat>

    • 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,Mat>

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • asScala

      public Sink<In,Mat> asScala()
      Converts this Sink to its Scala DSL counterpart.

    • runWith

      public <M> M runWith(Graph<SourceShape<In>,M> source, ClassicActorSystemProvider systemProvider)
      Connect this Sink to a Source and run it.

      Note that the ActorSystem can be used as the systemProvider parameter.

    • runWith

      public <M> M runWith(Graph<SourceShape<In>,M> source, Materializer materializer)
      Connect this Sink to a Source and run it.

    • contramap

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

      '''Backpressures when''' original Sink backpressures

      '''Cancels when''' original Sink backpressures

      Since:
      1.1.0

    • mapMaterializedValue

      public <Mat2> Sink<In,Mat2> mapMaterializedValue(Function<Mat,Mat2> f)
      Transform only the materialized value of this Sink, leaving all other properties as they were.

    • preMaterialize

      public Pair<Mat,Sink<In,NotUsed>> preMaterialize(ClassicActorSystemProvider systemProvider)
      Materializes this Sink, immediately returning (1) its materialized value, and (2) a new Sink that can be consume elements 'into' the pre-materialized one.

      Useful for when you need a materialized value of a Sink when handing it out to someone to materialize it for you.

      Note that the ActorSystem can be used as the systemProvider parameter.

    • preMaterialize

      public Pair<Mat,Sink<In,NotUsed>> preMaterialize(Materializer materializer)
      Materializes this Sink, immediately returning (1) its materialized value, and (2) a new Sink that can be consume elements 'into' the pre-materialized one.

      Useful for when you need a materialized value of a Sink when handing it out to someone to materialize it for you.

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

    • withAttributes

      public Sink<In,Mat> withAttributes(Attributes attr)
      Replace the attributes of this Sink with the given ones. If this Sink 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<In,Mat>

    • addAttributes

      public Sink<In,Mat> addAttributes(Attributes attr)
      Add the given attributes to this Sink. 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 Sink is a composite of multiple graphs, new attributes on the composite will be less specific than attributes set directly on the individual graphs of the composite.
      Specified by:
      addAttributes in interface Graph<In,Mat>

    • named

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

    • async

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

    • async

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

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

    • async

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

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

    • getAttributes

      public Attributes getAttributes()
      Specified by:
      getAttributes in interface Graph<In,Mat>