Interface Multi<T>
-
- All Superinterfaces:
org.reactivestreams.Publisher<T>
- All Known Subinterfaces:
GroupedMulti<K,T>
- All Known Implementing Classes:
AbstractMulti
,AbstractMultiOperator
,BroadcastProcessor
,CollectionBasedMulti
,ConnectableMulti
,DeferredMulti
,DeferredMultiWithContext
,EmitterBasedMulti
,EmptyMulti
,FailedMulti
,GeneratorBasedMulti
,IntervalMulti
,IterableBasedMulti
,MultiBufferOp
,MultiBufferWithTimeoutOp
,MultiCacheOp
,MultiCollectorOp
,MultiCombineLatestOp
,MultiConcatOp
,MultiConnectAfter
,MultiDistinctOp
,MultiEmitOnOp
,MultiFailOnItemTimeout
,MultiFlatMapOnFailure
,MultiFlatMapOp
,MultiGlobalSpy
,MultiGroupByOp
,MultiGroupByOp.GroupedUnicast
,MultiIgnoreOp
,MultiLastItemOp
,MultiLogger
,MultiMapOp
,MultiOnCancellationCall
,MultiOnCancellationInvoke
,MultiOnCancellationSpy
,MultiOnCompletionCall
,MultiOnCompletionInvoke
,MultiOnCompletionSpy
,MultiOnFailureInvoke
,MultiOnFailureResumeOp
,MultiOnFailureSpy
,MultiOnFailureTransform
,MultiOnItemInvoke
,MultiOnItemSpy
,MultiOnOverflowBufferOp
,MultiOnOverflowDropItemsOp
,MultiOnOverflowKeepLastOp
,MultiOnOverflowSpy
,MultiOnRequestCall
,MultiOnRequestInvoke
,MultiOnRequestSpy
,MultiOnSubscribeCall
,MultiOnSubscribeInvokeOp
,MultiOnSubscribeSpy
,MultiOnTerminationCall
,MultiOnTerminationInvoke
,MultiOnTerminationSpy
,MultiOperator
,MultiPublishOp
,MultiReferenceCount
,MultiRepeatUntilOp
,MultiRepeatWhilstOp
,MultiRetryOp
,MultiRetryWhenOp
,MultiScanOp
,MultiScanWithSeedOp
,MultiSelectFirstOp
,MultiSelectFirstUntilOtherOp
,MultiSelectFirstWhileOp
,MultiSelectLastOp
,MultiSelectWhereOp
,MultiSkipFirstOp
,MultiSkipFirstUntilOp
,MultiSkipLastOp
,MultiSkipRepetitionsOp
,MultiSkipUntilOtherOp
,MultiSubscribeOnOp
,MultiSwitchOnCompletion
,MultiSwitchOnEmpty
,MultiSwitchOnEmptyOp
,MultiWindowOnDurationOp
,MultiWindowOp
,MultiWithContext
,MultiZipOp
,NeverMulti
,ResourceMulti
,StreamBasedMulti
,UnicastProcessor
,UniOnItemTransformToMulti
public interface Multi<T> extends org.reactivestreams.Publisher<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 theItemWithContext
wrapper class.MultiBroadcast<T>
broadcast()
Makes thisMulti
be able to broadcast its events (items
,failure
, andcompletion
) to multiple subscribers.Multi<T>
cache()
Creates a newMulti
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 newMulti
invoking the given @{code action} when anitem
event is received.default Multi<T>
call(java.util.function.Supplier<Uni<?>> action)
Produces a newMulti
invoking the given @{code action} when anitem
event is received, but ignoring it in the callback.MultiCollect<T>
collect()
default <O> Multi<O>
concatMap(java.util.function.Function<? super T,? extends org.reactivestreams.Publisher<? extends O>> mapper)
MultiConvert<T>
convert()
Converts aMulti
to other typesstatic MultiCreateBy
createBy()
static MultiCreate
createFrom()
Multi<T>
emitOn(java.util.concurrent.Executor executor)
Produces a newMulti
invoking theonItem
,onFailure
andonCompletion
methods on the suppliedExecutor
.default Multi<T>
filter(java.util.function.Predicate<? super T> predicate)
default <O> Multi<O>
flatMap(java.util.function.Function<? super T,? extends org.reactivestreams.Publisher<? extends O>> mapper)
MultiGroup<T>
group()
MultiIfNoItem<T>
ifNoItem()
Produces aMulti
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 newMulti
invoking the given callback when anitem
event is fired by the upstream.default Multi<T>
invoke(java.util.function.Consumer<? super T> callback)
Produces a newMulti
invoking the given callback when anitem
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)
MultiOnCancel<T>
onCancellation()
Configures actions when the subscriber cancels the subscription.MultiOnCompletion<T>
onCompletion()
Allows configuring the actions or continuation to execute when thisMulti
fires the completion event.MultiOnFailure<T>
onFailure()
LikeonFailure(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 returnedMultiOnFailure
) 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 returnedMultiOnFailure
) is applied.MultiOnItem<T>
onItem()
Configures the behavior when anitem
event is received from the thisMulti
MultiOverflow<T>
onOverflow()
Configures the back-pressure behavior when the consumer cannot keep up with the emissions from thisMulti
.MultiOnRequest<T>
onRequest()
Configures actions when items are being requested.MultiOnSubscribe<T>
onSubscribe()
Deprecated.useonSubscription()
insteadMultiOnSubscribe<T>
onSubscription()
Configures the action to execute when the observedMulti
sends aSubscription
.MultiOnTerminate<T>
onTermination()
Configures actions when thisMulti
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)
MultiSelect<T>
select()
Selects items from thisMulti
.MultiSkip<T>
skip()
Skips items from thisMulti
.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 thisMulti
.Multi<T>
toHotStream()
Produces a newMulti
transforming thisMulti
into a hot stream.Uni<T>
toUni()
default <R> Multi<R>
withContext(java.util.function.BiFunction<Multi<T>,Context,Multi<R>> builder)
Materialize the subscriberContext
for a sub-pipeline.
-
-
-
Method Detail
-
createFrom
@CheckReturnValue static MultiCreate createFrom()
-
createBy
@CheckReturnValue static MultiCreateBy createBy()
Creates new instances ofMulti
by merging, concatenating or associating items from othersMulti
andPublisher
.- Returns:
- the object to configure the creation process.
-
subscribe
@CheckReturnValue MultiSubscribe<T> subscribe()
Configures the subscriber consuming thisMulti
.- Returns:
- the object to configure the subscriber
-
onItem
@CheckReturnValue MultiOnItem<T> onItem()
Configures the behavior when anitem
event is received from the thisMulti
- 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.
-
toUni
@CheckReturnValue Uni<T> toUni()
Creates aUni
from thisMulti
.When a subscriber subscribes to the returned
Uni
, it subscribes to thisMulti
and requests one item. The event emitted by thisMulti
are then forwarded to theUni
:- 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 producesUni
- 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 passedMulti
is also cancelled.- Returns:
- the produced
Uni
- on item event, the item is fired by the produced
-
onFailure
@CheckReturnValue MultiOnFailure<T> onFailure()
LikeonFailure(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 returnedMultiOnFailure
) 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 typeIOException
.- 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.useonSubscription()
insteadConfigures the action to execute when the observedMulti
sends aSubscription
. 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 observedMulti
sends aSubscription
. 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 returnedMultiOnFailure
) 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 typeIOException
.*- Parameters:
typeOfFailure
- the class of exception, must not benull
- 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 aMulti
reacting when no item event is fired by the upstream multi for the specified length of time.This
Multi
detects if thisMulti
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 newMulti
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()
ProducesUni
collecting/aggregating items from thisMulti
. It allows accumulating the items emitted by thismulti
into a structure such as a into aList
(MultiCollect.asList()
), aMap
(MultiCollect.asMap(Function)
, or a custom collector. When thismulti
sends the completion signal, the structure is emitted by the returnedUni
.If this
Multi
emits a failure, the producedUni
produces the same failure and the aggregated items are discarded.You can also retrieve the first and last items using
MultiCollect.first()
andMultiCollect.last()
. Be aware to not used method collecting items on unbounded / infiniteMulti
.- Returns:
- the object to configure the collection process.
-
group
@CheckReturnValue MultiGroup<T> group()
ProducesMulti
grouping items from thisMulti
into various "form of chunks" (list,Multi
). The grouping can be done linearly (MultiGroup.intoLists()
andMultiGroup.intoMultis()
, or based on a grouping function (MultiGroup.by(Function)
)- Returns:
- the object to configure the grouping.
-
emitOn
@CheckReturnValue Multi<T> emitOn(java.util.concurrent.Executor executor)
Produces a newMulti
invoking theonItem
,onFailure
andonCompletion
methods on the suppliedExecutor
.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 benull
- Returns:
- a new
Multi
-
runSubscriptionOn
@CheckReturnValue Multi<T> runSubscriptionOn(java.util.concurrent.Executor executor)
When a subscriber subscribes to thisMulti
, execute the subscription to the upstreamMulti
on a thread from the given executor. As a result, theSubscriber.onSubscribe(Subscription)
method will be called on this thread (except mentioned otherwise)- Parameters:
executor
- the executor to use, must not benull
- Returns:
- a new
Multi
-
onCompletion
@CheckReturnValue MultiOnCompletion<T> onCompletion()
Allows configuring the actions or continuation to execute when thisMulti
fires the completion event.- Returns:
- the object to configure the action.
-
select
@CheckReturnValue MultiSelect<T> select()
Selects items from thisMulti
.- Returns:
- the object to configure the selection.
-
skip
@CheckReturnValue MultiSkip<T> skip()
Skips items from thisMulti
.- 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 thisMulti
.- Returns:
- the object to configure the overflow strategy
-
broadcast
@CheckReturnValue MultiBroadcast<T> broadcast()
Makes thisMulti
be able to broadcast its events (items
,failure
, andcompletion
) to multiple subscribers.- Returns:
- the object to configure the broadcast
-
convert
@CheckReturnValue MultiConvert<T> convert()
Converts aMulti
to other typesExamples:
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 newMulti
with items from the upstreamMulti
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 benull
- Returns:
- the new
Multi
-
map
@CheckReturnValue default <O> Multi<O> map(java.util.function.Function<? super T,? extends O> mapper)
Produces a newMulti
invoking the given function for each item emitted by the upstreamMulti
.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 benull
- 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 aMulti
containing the items fromPublisher
produced by themapper
for each item emitted by thisMulti
.The operation behaves as follows:
- for each item emitted by this
Multi
, the mapper is called and produces aPublisher
(potentially aMulti
). The mapper must not returnnull
- The items emitted by each of the produced
Publisher
are then merged in the producedMulti
. The flatten process may interleaved items.
multi.onItem().transformToMulti(mapper).merge()
. - for each item emitted by this
-
call
@CheckReturnValue default Multi<T> call(java.util.function.Function<? super T,Uni<?>> action)
Produces a newMulti
invoking the given @{code action} when anitem
event is received. Note that the received item cannot benull
.Unlike
invoke(Consumer)
, the passed function returns aUni
. When the producedUni
sends its result, the result is discarded, and the originalitem
is forwarded downstream. If the producedUni
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.
-
call
@CheckReturnValue default Multi<T> call(java.util.function.Supplier<Uni<?>> action)
Produces a newMulti
invoking the given @{code action} when anitem
event is received, but ignoring it in the callback.Unlike
invoke(Consumer)
, the passed function returns aUni
. When the producedUni
sends its result, the result is discarded, and the originalitem
is forwarded downstream. If the producedUni
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.
-
invoke
@CheckReturnValue default Multi<T> invoke(java.util.function.Consumer<? super T> callback)
Produces a newMulti
invoking the given callback when anitem
event is fired by the upstream. Note that the received item cannot benull
.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 benull
- Returns:
- the new
Multi
-
invoke
@CheckReturnValue default Multi<T> invoke(java.lang.Runnable callback)
Produces a newMulti
invoking the given callback when anitem
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 benull
- 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 aMulti
containing the items fromPublisher
produced by themapper
for each item emitted by thisMulti
.The operation behaves as follows:
- for each item emitted by this
Multi
, the mapper is called and produces aPublisher
(potentially aMulti
). The mapper must not returnnull
- The items emitted by each of the produced
Publisher
are then concatenated in the producedMulti
. The flatten process makes sure that the items are not interleaved.
This method is equivalent to
multi.onItem().transformToMulti(mapper).concatenate()
. - for each item emitted by this
-
onTermination
@CheckReturnValue MultiOnTerminate<T> onTermination()
Configures actions when thisMulti
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.
-
toHotStream
@CheckReturnValue Multi<T> toHotStream()
Produces a newMulti
transforming thisMulti
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 theInfrastructure
class.- Parameters:
identifier
- an identifier of this operator to be used in log events- Returns:
- a new
Multi
- See Also:
Infrastructure.setOperatorLogger(Infrastructure.OperatorLogger)
-
log
@CheckReturnValue 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".Events will be logged as long as the
Multi
hasn't been cancelled or terminated. Logging is framework-agnostic and can be configured in theInfrastructure
class.- Returns:
- a new
Multi
- See Also:
log(String)
,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 subscriberContext
for a sub-pipeline.The provided function takes this
Multi
and theContext
as parameters, and returns aMulti
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.
-
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 theItemWithContext
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)
-
-