Package io.smallrye.mutiny

Interface Multi<T>

    • Method Detail

      • createBy

        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

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

      • onItem

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

      • then

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

        With `then` 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.

      • stage

        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

        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

        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

        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

        MultiOnSubscribe<T> onSubscribe()
        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.

      • onFailure

        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

      • on

        @Deprecated
MultiOnEvent<T> on()
        Deprecated.
        Use the specialized groups in Multi, e.g. onItem() or onSubscribe() instead
        Allows adding behavior when various type of events are emitted by the current Multi (item, failure, completion) or by the subscriber (cancellation, request, subscription)
        Returns:
        the object to configure the action to execute when events happen

      • cache

        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.

      • collectItems

        @Deprecated
default MultiCollect<T> collectItems()
        Deprecated.
        Use collect() instead
        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.

      • collect

        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

        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

        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

        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.

      • transform

        @Deprecated
MultiTransform<T> transform()
        Deprecated.
        Use select() and skip()instead
        Transforms the streams by skipping, selecting, or merging.
        Returns:
        the object to configure the transformation.

      • select

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

      • skip

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

      • onOverflow

        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

        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

        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

        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

        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().apply(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

        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

        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

        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

        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

        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

      • invokeUni

        @Deprecated
default Multi<T> invokeUni​(java.util.function.Function<? super T,​Uni<?>> action)
        Deprecated.
        Use call(Function)
        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 action throws an exception, this exception is propagated downstream as failure.

        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, must not return null
        Returns:
        the new Multi

      • concatMap

        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

        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

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

      • onRequest

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

      • plug

        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

        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.