Package io.smallrye.mutiny

Interface Multi<T>

    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods 
      Modifier and Type Method Description
      default Multi<ItemWithContext<T>> attachContext()
      Materialize the context by attaching it to items using the ItemWithContext wrapper class.
      MultiBroadcast<T> broadcast()
      Makes this Multi be able to broadcast its events (items, failure, and completion) to multiple subscribers.
      Multi<T> cache()
      Creates a new Multi that subscribes to this upstream and caches all of its events and replays them, to all the downstream subscribers.
      default Multi<T> call​(java.util.function.Function<? super T,​Uni<?>> action)
      Produces a new Multi invoking the given @{code action} when an item event is received.
      default Multi<T> call​(java.util.function.Supplier<Uni<?>> action)
      Produces a new Multi invoking the given @{code action} when an item event is received, but ignoring it in the callback.
      MultiCollect<T> collect()
      Produces Uni collecting/aggregating items from this Multi.
      default <O> Multi<O> concatMap​(java.util.function.Function<? super T,​? extends org.reactivestreams.Publisher<? extends O>> mapper)
      Produces a Multi containing the items from Publisher produced by the mapper for each item emitted by this Multi.
      MultiConvert<T> convert()
      Converts a Multi to other types
      static MultiCreateBy createBy()
      Creates new instances of Multi by merging, concatenating or associating items from others Multi and Publisher.
      static MultiCreate createFrom()  
      Multi<T> emitOn​(java.util.concurrent.Executor executor)
      Produces a new Multi invoking the onItem, onFailure and onCompletion methods on the supplied Executor.
      default Multi<T> filter​(java.util.function.Predicate<? super T> predicate)
      Produces a new Multi with items from the upstream Multi matching the predicate.
      default <O> Multi<O> flatMap​(java.util.function.Function<? super T,​? extends org.reactivestreams.Publisher<? extends O>> mapper)
      Produces a Multi containing the items from Publisher produced by the mapper for each item emitted by this Multi.
      MultiGroup<T> group()
      Produces Multi grouping items from this Multi into various "form of chunks" (list, Multi).
      MultiIfNoItem<T> ifNoItem()
      Produces a Multi reacting when no item event is fired by the upstream multi for the specified length of time.
      default Multi<T> invoke​(java.lang.Runnable callback)
      Produces a new Multi invoking the given callback when an item event is fired by the upstream.
      default Multi<T> invoke​(java.util.function.Consumer<? super T> callback)
      Produces a new Multi invoking the given callback when an item event is fired by the upstream.
      Multi<T> log()
      Log events (onSubscribe, onItem, ...) as they come from the upstream or the subscriber, and derives the identifier from the upstream operator class "simple name".
      Multi<T> log​(java.lang.String identifier)
      Log events (onSubscribe, onItem, ...) as they come from the upstream or the subscriber.
      default <O> Multi<O> map​(java.util.function.Function<? super T,​? extends O> mapper)
      Produces a new Multi invoking the given function for each item emitted by the upstream Multi.
      MultiOnCancel<T> onCancellation()
      Configures actions when the subscriber cancels the subscription.
      MultiOnCompletion<T> onCompletion()
      Allows configuring the actions or continuation to execute when this Multi fires the completion event.
      MultiOnFailure<T> onFailure()
      Like onFailure(Predicate) but applied to all failures fired by the upstream multi.
      MultiOnFailure<T> onFailure​(java.lang.Class<? extends java.lang.Throwable> typeOfFailure)
      Configures a type of failure filtering the failures on which the behavior (specified with the returned MultiOnFailure) is applied.
      MultiOnFailure<T> onFailure​(java.util.function.Predicate<? super java.lang.Throwable> predicate)
      Configures a predicate filtering the failures on which the behavior (specified with the returned MultiOnFailure) is applied.
      MultiOnItem<T> onItem()
      Configures the behavior when an item event is received from the this Multi
      MultiOverflow<T> onOverflow()
      Configures the back-pressure behavior when the consumer cannot keep up with the emissions from this Multi.
      MultiOnRequest<T> onRequest()
      Configures actions when items are being requested.
      MultiOnSubscribe<T> onSubscribe()
      Deprecated.
      use onSubscription() instead
      MultiOnSubscribe<T> onSubscription()
      Configures the action to execute when the observed Multi sends a Subscription.
      MultiOnTerminate<T> onTermination()
      Configures actions when this Multi terminates on completion, on failure or on subscriber cancellation.
      default <R> Multi<R> plug​(java.util.function.Function<Multi<T>,​Multi<R>> operatorProvider)
      Plug a user-defined operator that does not belong to the existing Mutiny API.
      Multi<T> runSubscriptionOn​(java.util.concurrent.Executor executor)
      When a subscriber subscribes to this Multi, execute the subscription to the upstream Multi on a thread from the given executor.
      MultiSelect<T> select()
      Selects items from this Multi.
      MultiSkip<T> skip()
      Skips items from this Multi.
      default <O> O stage​(java.util.function.Function<Multi<T>,​O> stage)
      Allows structuring the pipeline by creating a logic separation:
      MultiSubscribe<T> subscribe()
      Configures the subscriber consuming this Multi.
      Multi<T> toHotStream()
      Produces a new Multi transforming this Multi into a hot stream.
      Uni<T> toUni()
      Creates a Uni from this Multi.
      default <R> Multi<R> withContext​(java.util.function.BiFunction<Multi<T>,​Context,​Multi<R>> builder)
      Materialize the subscriber Context for a sub-pipeline.

      • Methods inherited from interface org.reactivestreams.Publisher

        subscribe

    • Method Detail

      • createFrom

        @CheckReturnValue
static MultiCreate createFrom()

      • createBy

        @CheckReturnValue
static MultiCreateBy createBy()
        Creates new instances of Multi by merging, concatenating or associating items from others Multi and Publisher.
        Returns:
        the object to configure the creation process.

      • subscribe

        @CheckReturnValue
MultiSubscribe<T> subscribe()
        Configures the subscriber consuming this Multi.
        Returns:
        the object to configure the subscriber

      • onItem

        @CheckReturnValue
MultiOnItem<T> onItem()
        Configures the behavior when an item event is received from the this Multi
        Returns:
        the object to configure the behavior.

      • stage

        @CheckReturnValue
default <O> O stage​(java.util.function.Function<Multi<T>,​O> stage)
        Allows structuring the pipeline by creating a logic separation: 
         
     Multi multi = upstream
      .stage(m -> { ...})
      .stage(m -> { ...})
      .stage(m -> { ...})

        With `stage` you can structure and chain groups of processing.

        Type Parameters:
        O - the outcome type
        Parameters:
        stage - the function receiving this Multi as parameter and producing the outcome (can be a Multi or something else), must not be null.
        Returns:
        the outcome of the function.

      • toUni

        @CheckReturnValue
Uni<T> toUni()
        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.

        Returns:
        the produced Uni

      • onFailure

        @CheckReturnValue
MultiOnFailure<T> onFailure()
        Like onFailure(Predicate) but applied to all failures fired by the upstream multi. It allows configuring the on failure behavior (recovery, retry...).
        Returns:
        a MultiOnFailure on which you can specify the on failure action

      • onFailure

        @CheckReturnValue
MultiOnFailure<T> onFailure​(java.util.function.Predicate<? super java.lang.Throwable> predicate)
        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.

        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

      • onSubscribe

        @Deprecated
@CheckReturnValue
MultiOnSubscribe<T> onSubscribe()
        Deprecated.
        use onSubscription() instead
        Configures the action to execute when the observed Multi sends a Subscription. The downstream don't have a subscription yet. It will be passed once the configured action completes.

        For example: 

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

      • onSubscription

        @CheckReturnValue
MultiOnSubscribe<T> onSubscription()
        Configures the action to execute when the observed Multi sends a 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)));
        Returns:
        the object to configure the action to execution on subscription.

      • onFailure

        @CheckReturnValue
MultiOnFailure<T> onFailure​(java.lang.Class<? extends java.lang.Throwable> typeOfFailure)
        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.*

        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

        @Experimental("Multi timeouts are an experimental feature.")
@CheckReturnValue
MultiIfNoItem<T> ifNoItem()
        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

        Returns:
        the on item timeout group

      • cache

        @CheckReturnValue
Multi<T> cache()
        Creates a new Multi that subscribes to this upstream and caches all of its events and replays them, to all the downstream subscribers.
        Returns:
        a multi replaying the events from the upstream.

      • collect

        @CheckReturnValue
MultiCollect<T> collect()
        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.

        Returns:
        the object to configure the collection process.

      • emitOn

        @CheckReturnValue
Multi<T> emitOn​(java.util.concurrent.Executor executor)
        Produces a new Multi invoking the onItem, onFailure and onCompletion methods on the supplied Executor.

        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.

        Parameters:
        executor - the executor to use, must not be null
        Returns:
        a new Multi

      • runSubscriptionOn

        @CheckReturnValue
Multi<T> runSubscriptionOn​(java.util.concurrent.Executor executor)
        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 Subscriber.onSubscribe(Subscription) method will be called on this thread (except mentioned otherwise)
        Parameters:
        executor - the executor to use, must not be null
        Returns:
        a new Multi

      • onCompletion

        @CheckReturnValue
MultiOnCompletion<T> onCompletion()
        Allows configuring the actions or continuation to execute when this Multi fires the completion event.
        Returns:
        the object to configure the action.

      • select

        @CheckReturnValue
MultiSelect<T> select()
        Selects items from this Multi.
        Returns:
        the object to configure the selection.

      • skip

        @CheckReturnValue
MultiSkip<T> skip()
        Skips items from this Multi.
        Returns:
        the object to configure the skip.

      • onOverflow

        @CheckReturnValue
MultiOverflow<T> onOverflow()
        Configures the back-pressure behavior when the consumer cannot keep up with the emissions from this Multi.
        Returns:
        the object to configure the overflow strategy

      • broadcast

        @CheckReturnValue
MultiBroadcast<T> broadcast()
        Makes this Multi be able to broadcast its events (items, failure, and completion) to multiple subscribers.
        Returns:
        the object to configure the broadcast

      • convert

        @CheckReturnValue
MultiConvert<T> convert()
        Converts a Multi to other types

        Examples: 

         
 multi.convert().with(multi -> x); // Convert with a custom lambda converter
        Returns:
        the object to convert an Multi instance
        See Also:
        MultiConvert

      • filter

        @CheckReturnValue
default Multi<T> filter​(java.util.function.Predicate<? super T> predicate)
        Produces a new Multi with items from the upstream Multi matching the predicate.

        Items that do not satisfy the predicate are discarded.

        This method is a shortcut for multi.transform().byFilteringItemsWith(predicate).

        Parameters:
        predicate - a predicate, must not be null
        Returns:
        the new Multi

      • map

        @CheckReturnValue
default <O> Multi<O> map​(java.util.function.Function<? super T,​? extends O> mapper)
        Produces a new Multi invoking the given function for each item emitted by the upstream Multi.

        The function receives the received item as parameter, and can transform it. The returned object is sent downstream as item event.

        This method is a shortcut for multi.onItem().transform(mapper).

        Type Parameters:
        O - the type of item produced by the mapper function
        Parameters:
        mapper - the mapper function, must not be null
        Returns:
        the new Multi

      • flatMap

        @CheckReturnValue
default <O> Multi<O> flatMap​(java.util.function.Function<? super T,​? extends org.reactivestreams.Publisher<? extends O>> mapper)
        Produces a Multi containing the items from Publisher produced by the mapper for each item emitted by this Multi.

        The operation behaves as follows:

        • for each item emitted by this Multi, the mapper is called and produces a Publisher (potentially a Multi). The mapper must not return null
        • The items emitted by each of the produced Publisher are then merged in the produced Multi. The flatten process may interleaved items.
        This method is a shortcut for multi.onItem().transformToMulti(mapper).merge().
        Type Parameters:
        O - the type of item emitted by the Publisher produced by the mapper
        Parameters:
        mapper - the Function producing Publisher / Multi for each items emitted by the upstream Multi
        Returns:
        the produced Multi

      • call

        @CheckReturnValue
default Multi<T> call​(java.util.function.Function<? super T,​Uni<?>> action)
        Produces a new Multi invoking the given @{code action} when an item event is received. Note that the received item cannot be null.

        Unlike invoke(Consumer), the passed function returns a Uni. When the produced Uni sends its result, the result is discarded, and the original item is forwarded downstream. If the produced Uni fails, the failure is propagated downstream.

        If the asynchronous action throws an exception, this exception is propagated downstream.

        This method preserves the order of the items, meaning that the downstream received the items in the same order as the upstream has emitted them.

        Parameters:
        action - the function taking the item and returning a Uni, must not be null
        Returns:
        the new Multi

      • call

        @CheckReturnValue
default Multi<T> call​(java.util.function.Supplier<Uni<?>> action)
        Produces a new Multi invoking the given @{code action} when an item event is received, but ignoring it in the callback.

        Unlike invoke(Consumer), the passed function returns a Uni. When the produced Uni sends its result, the result is discarded, and the original item is forwarded downstream. If the produced Uni fails, the failure is propagated downstream.

        If the asynchronous action throws an exception, this exception is propagated downstream.

        This method preserves the order of the items, meaning that the downstream received the items in the same order as the upstream has emitted them.

        Parameters:
        action - the function taking the item and returning a Uni, must not be null
        Returns:
        the new Multi

      • invoke

        @CheckReturnValue
default Multi<T> invoke​(java.util.function.Consumer<? super T> callback)
        Produces a new Multi invoking the given callback when an item event is fired by the upstream. Note that the received item cannot be null.

        If the callback throws an exception, this exception is propagated to the downstream as failure. No more items will be consumed.

        This method is a shortcut on MultiOnItem.invoke(Consumer).

        Parameters:
        callback - the callback, must not be null
        Returns:
        the new Multi

      • invoke

        @CheckReturnValue
default Multi<T> invoke​(java.lang.Runnable callback)
        Produces a new Multi invoking the given callback when an item event is fired by the upstream.

        If the callback throws an exception, this exception is propagated to the downstream as failure. No more items will be consumed.

        Parameters:
        callback - the callback, must not be null
        Returns:
        the new Multi

      • concatMap

        @CheckReturnValue
default <O> Multi<O> concatMap​(java.util.function.Function<? super T,​? extends org.reactivestreams.Publisher<? extends O>> mapper)
        Produces a Multi containing the items from Publisher produced by the mapper for each item emitted by this Multi.

        The operation behaves as follows:

        • for each item emitted by this Multi, the mapper is called and produces a Publisher (potentially a Multi). The mapper must not return null
        • The items emitted by each of the produced Publisher are then concatenated in the produced Multi. The flatten process makes sure that the items are not interleaved.

        This method is equivalent to multi.onItem().transformToMulti(mapper).concatenate().

        Type Parameters:
        O - the type of item emitted by the Publisher produced by the mapper
        Parameters:
        mapper - the Function producing Publisher / Multi for each items emitted by the upstream Multi
        Returns:
        the produced Multi

      • onTermination

        @CheckReturnValue
MultiOnTerminate<T> onTermination()
        Configures actions when this Multi terminates on completion, on failure or on subscriber cancellation.
        Returns:
        the object to configure the termination actions

      • onCancellation

        @CheckReturnValue
MultiOnCancel<T> onCancellation()
        Configures actions when the subscriber cancels the subscription.
        Returns:
        the object to configure the cancellation actions

      • onRequest

        @CheckReturnValue
MultiOnRequest<T> onRequest()
        Configures actions when items are being requested.
        Returns:
        the object to configure the actions

      • plug

        @CheckReturnValue
default <R> Multi<R> plug​(java.util.function.Function<Multi<T>,​Multi<R>> operatorProvider)
        Plug a user-defined operator that does not belong to the existing Mutiny API.
        Type Parameters:
        R - the output type
        Parameters:
        operatorProvider - a function to create and bind a new operator instance, taking this Multi as a parameter and returning a new Multi. Must neither be null nor return null.
        Returns:
        the new Multi

      • toHotStream

        @CheckReturnValue
Multi<T> toHotStream()
        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.

        Returns:
        the new multi.

      • log

        @CheckReturnValue
Multi<T> log​(java.lang.String identifier)
        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.

        Parameters:
        identifier - an identifier of this operator to be used in log events
        Returns:
        a new Multi
        See Also:
        Infrastructure.setOperatorLogger(Infrastructure.OperatorLogger)

      • withContext

        @Experimental("Context support is a new experimental API introduced in Mutiny 1.3.0")
@CheckReturnValue
default <R> Multi<R> withContext​(java.util.function.BiFunction<Multi<T>,​Context,​Multi<R>> builder)
        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.

        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

      • attachContext

        @Experimental("Context support is a new experimental API introduced in Mutiny 1.3.0")
@CheckReturnValue
default Multi<ItemWithContext<T>> attachContext()
        Materialize the context by attaching it to items using the ItemWithContext wrapper class.

        This is a shortcut for: 

         
 someMulti.withContext((multi, ctx) -> multi.onItem().transform(item -> new ItemWithContext<>(ctx, item)));
        Returns:
        the resulting Multi
        See Also:
        withContext(BiFunction)