Module io.smallrye.mutiny
Package io.smallrye.mutiny.operators

Class AbstractMulti<T>

java.lang.Object
io.smallrye.mutiny.operators.AbstractMulti<T>
All Implemented Interfaces:
Multi<T>, Flow.Publisher<T>
Direct Known Subclasses:
io.smallrye.mutiny.operators.multi.AbstractMultiOperator, BroadcastProcessor, MultiOperator, UnicastProcessor
public abstract class AbstractMulti<T> extends Object implements Multi<T>

  • Constructor Details

    • AbstractMulti

      public AbstractMulti()

  • Method Details

    • subscribe

      public void subscribe(MultiSubscriber<? super T> subscriber)

    • subscribe

      public void subscribe(Flow.Subscriber<? super T> subscriber)
      Specified by:
      subscribe in interface Flow.Publisher<T>

    • onItem

      public MultiOnItem<T> onItem()
      Description copied from interface: Multi
      Configures the behavior when an item event is received from the this Multi
      Specified by:
      onItem in interface Multi<T>
      Returns:
      the object to configure the behavior.

    • subscribe

      public MultiSubscribe<T> subscribe()
      Description copied from interface: Multi
      Configures the subscriber consuming this Multi.
      Specified by:
      subscribe in interface Multi<T>
      Returns:
      the object to configure the subscriber

    • toUni

      public Uni<T> toUni()
      Description copied from interface: Multi
      Creates a Uni from this Multi.

      When a subscriber subscribes to the returned Uni, it subscribes to this Multi and requests one item. The event emitted by this Multi are then forwarded to the Uni:

      • on item event, the item is fired by the produced Uni
      • on failure event, the failure is fired by the produced Uni
      • on completion event, a null item is fired by the produces Uni
      • any item or failure events received after the first event is dropped

      If the subscription on the produced Uni is cancelled, the subscription to the passed Multi is also cancelled.

      Specified by:
      toUni in interface Multi<T>
      Returns:
      the produced Uni

    • onFailure

      public MultiOnFailure<T> onFailure()
      Description copied from interface: Multi
      Like Multi.onFailure(Predicate) but applied to all failures fired by the upstream multi. It allows configuring the on failure behavior (recovery, retry...).
      Specified by:
      onFailure in interface Multi<T>
      Returns:
      a MultiOnFailure on which you can specify the on failure action

    • onFailure

      public MultiOnFailure<T> onFailure(Predicate<? super Throwable> predicate)
      Description copied from interface: Multi
      Configures a predicate filtering the failures on which the behavior (specified with the returned MultiOnFailure) is applied.

      For instance, to only when an IOException is fired as failure you can use: multi.onFailure(IOException.class).recoverWithItem("hello")

      The fallback value (hello) will only be used if the upstream multi fires a failure of type IOException.

      Specified by:
      onFailure in interface Multi<T>
      Parameters:
      predicate - the predicate, null means applied to all failures
      Returns:
      a MultiOnFailure configured with the given predicate on which you can specify the on failure action

    • onFailure

      public MultiOnFailure<T> onFailure(Class<? extends Throwable> typeOfFailure)
      Description copied from interface: Multi
      Configures a type of failure filtering the failures on which the behavior (specified with the returned MultiOnFailure) is applied.

      For instance, to only when an IOException is fired as failure you can use: multi.onFailure(IOException.class).recoverWithItem("hello")

      The fallback value (hello) will only be used if the upstream multi fire a failure of type IOException.*

      Specified by:
      onFailure in interface Multi<T>
      Parameters:
      typeOfFailure - the class of exception, must not be null
      Returns:
      a MultiOnFailure configured with the given predicate on which you can specify the on failure action

    • ifNoItem

      public MultiIfNoItem<T> ifNoItem()
      Description copied from interface: Multi
      Produces a Multi reacting when no item event is fired by the upstream multi for the specified length of time.

      This Multi detects if this Multi does not emit an item for the configured length of time.

      Examples: multi.ifNoItem().after(Duration.ofMillis(1000)).fail() // Propagate a TimeoutException multi.ifNoItem().after(Duration.ofMillis(1000)).recoverWithCompletion() // Complete the event on timeout multi.ifNoItem().after(Duration.ofMillis(1000)).on(myExecutor)... // Configure the executor calling on timeout actions

      Specified by:
      ifNoItem in interface Multi<T>
      Returns:
      the on item timeout group

    • cache

      public Multi<T> cache()
      Description copied from interface: Multi
      Creates a new Multi that subscribes to this upstream and caches all of its events and replays them, to all the downstream subscribers.
      Specified by:
      cache in interface Multi<T>
      Returns:
      a multi replaying the events from the upstream.

    • emitOn

      public Multi<T> emitOn(Executor executor)
      Description copied from interface: Multi
      Produces a new Multi invoking the onItem, onFailure and onCompletion methods on the supplied Executor.

      This operator delegates to Multi.emitOn(Executor, int) with a default buffer size of Infrastructure.getBufferSizeS() items.

      Instead of receiving the item event on the thread firing the event, this method influences the threading context to switch to a thread from the given executor. Same behavior for failure and completion.

      Note that the subscriber is guaranteed to never be called concurrently.

      Be careful as this operator can lead to concurrency problems with non thread-safe objects such as CDI request-scoped beans. It might also break reactive-streams semantics with items being emitted concurrently.

      Specified by:
      emitOn in interface Multi<T>
      Parameters:
      executor - the executor to use, must not be null
      Returns:
      a new Multi
      See Also:

    • emitOn

      public Multi<T> emitOn(Executor executor, int bufferSize)
      Description copied from interface: Multi
      Produces a new Multi invoking the onItem, onFailure and onCompletion methods on the supplied Executor.

      This operator uses a queue of capacity bufferSize to emit items from a running executor thread, reducing the need for thread context switches when items are emitted fast from the upstream.

      This operator tracks Flow.Subscription.request(long) demand, but it does not forward requests to the upstream. It instead requests bufferSize elements at subscription time and whenever bufferSize items have been emitted, allowing for efficient batching.

      Instead of receiving the item event on the thread firing the event, this method influences the threading context to switch to a thread from the given executor. Same behavior for failure and completion.

      Note that the subscriber is guaranteed to never be called concurrently.

      Be careful as this operator can lead to concurrency problems with non thread-safe objects such as CDI request-scoped beans. It might also break reactive-streams semantics with items being emitted concurrently.

      Specified by:
      emitOn in interface Multi<T>
      Parameters:
      executor - the executor to use, must not be null
      bufferSize - the buffer size, must be strictly positive
      Returns:
      a new Multi

    • runSubscriptionOn

      public Multi<T> runSubscriptionOn(Executor executor)
      Description copied from interface: Multi
      When a subscriber subscribes to this Multi, execute the subscription to the upstream Multi on a thread from the given executor. As a result, the Flow.Subscriber.onSubscribe(Subscription) method will be called on this thread (except mentioned otherwise)
      Specified by:
      runSubscriptionOn in interface Multi<T>
      Parameters:
      executor - the executor to use, must not be null
      Returns:
      a new Multi

    • onCompletion

      public MultiOnCompletion<T> onCompletion()
      Description copied from interface: Multi
      Allows configuring the actions or continuation to execute when this Multi fires the completion event.
      Specified by:
      onCompletion in interface Multi<T>
      Returns:
      the object to configure the action.

    • select

      public MultiSelect<T> select()
      Description copied from interface: Multi
      Selects items from this Multi.
      Specified by:
      select in interface Multi<T>
      Returns:
      the object to configure the selection.

    • skip

      public MultiSkip<T> skip()
      Description copied from interface: Multi
      Skips items from this Multi.
      Specified by:
      skip in interface Multi<T>
      Returns:
      the object to configure the skip.

    • onOverflow

      public MultiOverflow<T> onOverflow()
      Description copied from interface: Multi
      Configures the back-pressure behavior when the consumer cannot keep up with the emissions from this Multi.
      Specified by:
      onOverflow in interface Multi<T>
      Returns:
      the object to configure the overflow strategy

    • onSubscription

      public MultiOnSubscribe<T> onSubscription()
      Description copied from interface: Multi
      Configures the action to execute when the observed Multi sends a Flow.Subscription. The downstream does not have a subscription yet. It will be passed once the configured action completes.

      For example: 

       
 multi.onSubscription().invoke(sub -> System.out.println("subscribed"));
 // Delay the subscription by 1 second (or until an asynchronous action completes)
 multi.onSubscription().call(sub -> Uni.createFrom(1).onItem().delayIt().by(Duration.ofSecond(1)));
      Specified by:
      onSubscription in interface Multi<T>
      Returns:
      the object to configure the action to execution on subscription.

    • broadcast

      public MultiBroadcast<T> broadcast()
      Description copied from interface: Multi
      Makes this Multi be able to broadcast its events (items, failure, and completion) to multiple subscribers.
      Specified by:
      broadcast in interface Multi<T>
      Returns:
      the object to configure the broadcast

    • convert

      public MultiConvert<T> convert()
      Description copied from interface: Multi
      Converts a Multi to other types

      Examples: 

       
 multi.convert().with(multi -> x); // Convert with a custom lambda converter
      Specified by:
      convert in interface Multi<T>
      Returns:
      the object to convert an Multi instance
      See Also:

    • onTermination

      public MultiOnTerminate<T> onTermination()
      Description copied from interface: Multi
      Configures actions when this Multi terminates on completion, on failure or on subscriber cancellation.
      Specified by:
      onTermination in interface Multi<T>
      Returns:
      the object to configure the termination actions

    • onCancellation

      public MultiOnCancel<T> onCancellation()
      Description copied from interface: Multi
      Configures actions when the subscriber cancels the subscription.
      Specified by:
      onCancellation in interface Multi<T>
      Returns:
      the object to configure the cancellation actions

    • onRequest

      public MultiOnRequest<T> onRequest()
      Description copied from interface: Multi
      Configures actions when items are being requested.
      Specified by:
      onRequest in interface Multi<T>
      Returns:
      the object to configure the actions

    • collect

      public MultiCollect<T> collect()
      Description copied from interface: Multi
      Produces Uni collecting/aggregating items from this Multi. It allows accumulating the items emitted by this multi into a structure such as a into a List (MultiCollect.asList()), a Map (MultiCollect.asMap(Function), or a custom collector. When this multi sends the completion signal, the structure is emitted by the returned Uni.

      If this Multi emits a failure, the produced Uni produces the same failure and the aggregated items are discarded.

      You can also retrieve the first and last items using MultiCollect.first() and MultiCollect.last(). Be aware to not used method collecting items on unbounded / infinite Multi.

      Specified by:
      collect in interface Multi<T>
      Returns:
      the object to configure the collection process.

    • group

      public MultiGroup<T> group()
      Description copied from interface: Multi
      Produces Multi grouping items from this Multi into various "form of chunks" (list, Multi). The grouping can be done linearly (MultiGroup.intoLists() and MultiGroup.intoMultis(), or based on a grouping function (MultiGroup.by(Function))
      Specified by:
      group in interface Multi<T>
      Returns:
      the object to configure the grouping.

    • toHotStream

      public Multi<T> toHotStream()
      Description copied from interface: Multi
      Produces a new Multi transforming this Multi into a hot stream.

      With a hot stream, when no subscribers are present, emitted items are dropped. Late subscribers would only receive items emitted after their subscription. If the upstream has already been terminated, the termination event (failure or completion) is forwarded to the subscribers.

      Note that this operator consumes the upstream stream without back-pressure. It still enforces downstream back-pressure. If the subscriber is not ready to receive an item when the upstream emits an item, the subscriber gets a BackPressureFailure failure.

      Specified by:
      toHotStream in interface Multi<T>
      Returns:
      the new multi.

    • log

      public Multi<T> log(String identifier)
      Description copied from interface: Multi
      Log events (onSubscribe, onItem, ...) as they come from the upstream or the subscriber.

      Events will be logged as long as the Multi hasn't been cancelled or terminated. Logging is framework-agnostic and can be configured in the Infrastructure class.

      Specified by:
      log in interface Multi<T>
      Parameters:
      identifier - an identifier of this operator to be used in log events
      Returns:
      a new Multi
      See Also:

    • log

      public Multi<T> log()
      Description copied from interface: Multi
      Log events (onSubscribe, onItem, ...) as they come from the upstream or the subscriber, and derives the identifier from the upstream operator class "simple name".

      Events will be logged as long as the Multi hasn't been cancelled or terminated. Logging is framework-agnostic and can be configured in the Infrastructure class.

      Specified by:
      log in interface Multi<T>
      Returns:
      a new Multi
      See Also:

    • withContext

      public <R> Multi<R> withContext(BiFunction<Multi<T>,Context,Multi<R>> builder)
      Description copied from interface: Multi
      Materialize the subscriber Context for a sub-pipeline.

      The provided function takes this Multi and the Context as parameters, and returns a Multi to build the sub-pipeline, as in: 

       
 someMulti.withContext((multi, ctx) -> multi.onItem().transform(n -> n + "::" + ctx.getOrElse("foo", () -> "yolo")));

      Note that the builder function is called at subscription time, so it cannot see context updates from upstream operators yet.

      Specified by:
      withContext in interface Multi<T>
      Type Parameters:
      R - the resulting Multi type
      Parameters:
      builder - the function that builds the sub-pipeline from this Multi and the Context, must not be null, must not return null.
      Returns:
      the resulting Multi

    • paceDemand

      public MultiDemandPacing<T> paceDemand()
      Description copied from interface: Multi
      A demand-pacer allows controlling upstream demand using a request and a delay.

      Each time the delay expires the pacer can evaluate a new demand based on the previous request and the number of emitted items that have been observed since the previous request.

      In the following example a demand of 25 is issued every 100ms, using the default worker pool to perform requests: 

       var pacer = new FixedDemandPacer(25L, Duration.ofMillis(100L));
 var multi = Multi.createFrom().range(0, 100)
         .paceDemand().on(Infrastructure.getDefaultWorkerPool()).using(pacer);
      Important: this operator is NOT compliant with the reactive streams specification. Downstream demand requests are being ignored, so it is possible that this operator requests more than what the downstream subscriber would want, depending on the DemandPacer object in use.
      Specified by:
      paceDemand in interface Multi<T>
      Returns:
      a group to configure the demand pacing

    • pauseDemand

      public MultiDemandPausing<T> pauseDemand()
      Description copied from interface: Multi
      Allows pausing and resuming demand propagation to upstream using a DemandPauser.

      Unlike cancellation which terminates the subscription, temporarily pausing suspends the demand without unsubscribing. This is useful for implementing flow control patterns where demand needs to be temporarily suspended based on external conditions (e.g., downstream system availability, rate limiting, resource constraints).

      Example: 

       
 DemandPauser pauser = new DemandPauser();

 Multi.createFrom().range(0, 100)
         .pauseDemand().using(pauser)
         .onItem().call(i -> Uni.createFrom().nullItem()
                 .onItem().delayIt().by(Duration.ofMillis(10)))
         .subscribe().with(System.out::println);

 // Later, from anywhere in the application:
 pauser.pause(); // Stop requesting new items
 pauser.resume(); // Continue requesting items

      Reactive Streams Compliance: This operator is compliant with the Reactive Streams specification as long as the DemandPauser used to manage demand is eventually resumed. When the upstream signals completion, if the stream is paused, the completion signal is deferred until the stream is resumed, at which point all buffered items are delivered to downstream before the completion signal is propagated. When the upstream signals failure, any buffered items are discarded and the error is immediately propagated downstream.

      Specified by:
      pauseDemand in interface Multi<T>
      Returns:
      a MultiDemandPausing to configure the pausing behavior
      See Also:

    • capDemandsUsing

      public Multi<T> capDemandsUsing(LongFunction<Long> function)
      Description copied from interface: Multi
      Cap all downstream subscriber requests to a value computed by a function.

      The function must return a valid demand which is strictly positive and below or equal to that of the current outstanding demand. The function argument is the current outstanding demand.

      Specified by:
      capDemandsUsing in interface Multi<T>
      Parameters:
      function - the function, must not be null, must not return null, must return a long such that (0 < n <= outstanding) where outstanding is the current outstanding demand
      Returns:
      the new Multi