T
- the type of item produced by the Uni
public interface Uni<T>
Uni
represent a lazy asynchronous action. It follows a subscription pattern, meaning the the action
is only triggered once a UniSubscriber
subscribes to the Uni
.
A Uni
can have two outcomes:
item
event, forwarding the complete of the action, potentially null
if the action does not
produced a complete, but completed successfully.failure
event, forwarding the exception
To trigger the computation, a UniSubscriber
must subscribe to the Uni. It will be notified of outcome
once they is an item
or failure
event fired by the observed Uni. A subscriber receives
(asynchronously) a UniSubscription
and can cancel the demand at any time. Note that cancelling after
having received the outcome is a no-op.
Modifier and Type | Method and Description |
---|---|
UniAndGroup<T> |
and()
Combines a set of
unis into a joined item. |
<T2> Uni<Tuple2<T,T2>> |
and(Uni<T2> other)
|
UniAwait<T> |
await()
Awaits (blocking the caller thread) until the item or a failure is emitted by the observed
Uni . |
Uni<T> |
cache()
Caches the events (item or failure) of this
Uni and replays it for all further UniSubscriber . |
static UniCombine |
combine()
|
UniConvert<T> |
convert()
Converts an
Uni to other types such as CompletionStage |
static UniCreate |
createFrom()
Creates a new
Uni from various sources such as CompletionStage ,
UniEmitter , direct values, Exception ... |
Uni<T> |
emitOn(Executor executor)
Produces a new
Uni invoking the UniSubscriber.onItem(Object) and
UniSubscriber.onFailure(Throwable) on the supplied Executor . |
default <O> Uni<O> |
flatMap(Function<? super T,Uni<? extends O>> mapper)
Transforms the received item asynchronously, forwarding the events emitted by another
Uni produced by
the given mapper . |
UniIfNoItem<T> |
ifNoItem()
Produces a
Uni reacting when a no item event is fired by the upstream uni during the specified time
period. |
default <O> Uni<O> |
map(Function<? super T,? extends O> mapper)
Transforms the item (potentially null) emitted by this
Uni by applying a (synchronous) function to it. |
UniOnEvent<T> |
on()
Allows adding behavior when various type of events are emitted by the current
Uni (item, failure) or
by the subscriber (cancellation, subscription) |
UniOnFailure<T> |
onFailure()
Like
onFailure(Predicate) but applied to all failures fired by the upstream uni. |
UniOnFailure<T> |
onFailure(Class<? extends Throwable> typeOfFailure)
Configures a type of failure filtering the failures on which the behavior (specified with the returned
UniOnFailure ) is applied. |
UniOnFailure<T> |
onFailure(Predicate<? super Throwable> predicate)
Configures a predicate filtering the failures on which the behavior (specified with the returned
UniOnFailure ) is applied. |
UniOnItem<T> |
onItem()
Configures the action to execute when the observed
Uni emits the item (potentially null ). |
UniOr |
or()
Composes this
Uni with a set of Uni passed to
UniOr.unis(Uni[]) to produce a new Uni forwarding the first event
(item or failure). |
UniSubscribe<T> |
subscribe()
Requests the
Uni to start resolving the item and allows configuring how the signals are propagated
(using a UniSubscriber , callbacks, or a CompletionStage . |
default CompletableFuture<T> |
subscribeAsCompletionStage()
Shortcut for
UniSubscribe.asCompletionStage() . |
Uni<T> |
subscribeOn(Executor executor)
|
default <O> O |
then(Function<Uni<T>,O> stage)
Allows structuring the pipeline by creating a logic separation:
|
Multi<T> |
toMulti()
|
static UniCreate createFrom()
Uni
from various sources such as CompletionStage
,
UniEmitter
, direct values, Exception
...
Examples:
Uni.from().item(1); // Emit 1 at subscription time
Uni.from().item(() -> x); // Emit x at subscription time, the supplier is invoked for each subscription
Uni.from().completionState(cs); // Emit the item from this completion stage
Uni.from().completionState(() -> cs); // Emit the item from this completion stage, the stage is not created before subscription
Uni.from().failure(exception); // Emit the failure at subscription time
Uni.from().deferred(() -> Uni.from().value(x)); // Defer the uni creation until subscription. Each subscription can produce a different uni
Uni.from().item(null); // Emit null at subscription time
Uni.from().nothing(); // Create a Uni not emitting any signal
Uni.from().publisher(publisher); // Create a Uni from a Reactive Streams Publisher
default <O> O then(Function<Uni<T>,O> stage)
Uni uni = upstream
.then(u -> { ...})
.then(u -> { ...})
.then(u -> { ...})
With `then` you can structure and chain groups of processing.
static UniCombine combine()
UniSubscribe<T> subscribe()
Uni
to start resolving the item and allows configuring how the signals are propagated
(using a UniSubscriber
, callbacks, or a CompletionStage
. Unlike await()
, this method
configures non-blocking retrieval of the item and failure.
Examples:
Uni<String> uni = ...;
Subscription sub = uni.subscribe().with( // The return subscription can be used to cancel the operation
item -> {}, // Callback calls on item
failure -> {} // Callback calls on failure
);
UniSubscriber<String> myUniSubscriber = ...
uni.subscribe().withSubscriber(myUniSubscriber); // Subscribes to the Uni with the passed subscriber
CompletableFuture future = uni.subscribe().asCompletableFuture(); // Get a CompletionStage receiving the item or failure
// Cancelling the returned future cancels the subscription.
uni.await()
for waiting (blocking the caller thread) until the resolution of the observed Uni.
default CompletableFuture<T> subscribeAsCompletionStage()
UniSubscribe.asCompletionStage()
.Uni
UniAwait<T> await()
Uni
.
If the observed uni fails, the failure is thrown. In the case of a checked exception, the exception is wrapped
into a CompletionException
.
Examples:
Uni<T> uni = ...;
T res = uni.await().indefinitely(); // Await indefinitely until it get the item.
T res = uni.await().atMost(Duration.ofMillis(1000)); // Awaits at most 1s. After that, a TimeoutException is thrown
Optional<T> res = uni.await().asOptional().indefinitely(); // Retrieves the item as an Optional, empty if the item is null
UniOnItem<T> onItem()
Uni
emits the item (potentially null
).
Examples:
Uni<T> uni = ...;
uni.onItem().apply(x -> ...); // Map to another item
uni.onItem().produceUni(x -> ...); // Map to another Uni (flatMap)
UniAndGroup<T> and()
unis
into a joined item. This item can be a Tuple
or the item of a
combinator function.
If one of the combine Uni
fire a failure, the other unis are cancelled, and the resulting
Uni
fires the failure. If collectFailures()
is called,
it waits for the completion of all the unis
before propagating the failure event. If more than one
Uni
failed, a CompositeException
is fired, wrapping the different collected failures.
Depending on the number of participants, the produced Tuple
is
different from Tuple2
to Tuple5
. For more participants,
use UniAndGroup.unis(Uni[])
or
UniAndGroup.unis(Iterable)
.
Uni.all()
for the equivalent static operator
<T2> Uni<Tuple2<T,T2>> and(Uni<T2> other)
Uni
with the item of other
into a Tuple2
.
If this
or other
fails, the other resolution is cancelled.T2
- the type to pairother
- the other Uni
, must not be null
and
for more options on the combination of items
,
Uni.all()
for the equivalent static operator
UniOr or()
Uni
with a set of Uni
passed to
UniOr.unis(Uni[])
to produce a new Uni
forwarding the first event
(item or failure). It behaves like the fastest of these competing unis.
The process subscribes to the set of Uni
. When one of the Uni
fires an item or a failure,
the event is propagated downstream. Also the other subscriptions are cancelled.
Note that the callback from the subscriber are called on the thread used to fire the winning Uni
.
Use emitOn(Executor)
to change the thread.
If the subscription to the returned Uni
is cancelled, the subscription to the unis
from the
iterable
are also cancelled.
Uni.any
for a static version of this operator, like
Uni first = Uni.any().of(uni1, uni2);
UniOnFailure<T> onFailure()
onFailure(Predicate)
but applied to all failures fired by the upstream uni.
It allows configuring the on failure behavior (recovery, retry...).UniOnFailure<T> onFailure(Predicate<? super Throwable> predicate)
UniOnFailure
) is applied.
For instance, to only when an IOException
is fired as failure you can use:
uni.onFailure(IOException.class).recoverWithItem("hello")
The fallback value (hello
) will only be used if the upstream uni fire a failure of type
IOException
.
predicate
- the predicate, null
means applied to all failuresUniOnFailure<T> onFailure(Class<? extends Throwable> typeOfFailure)
UniOnFailure
) is applied.
For instance, to only when an IOException
is fired as failure you can use:
uni.onFailure(IOException.class).recoverWithItem("hello")
The fallback value (hello
) will only be used if the upstream uni fire a failure of type
IOException
.
typeOfFailure
- the class of exception, must not be null
UniIfNoItem<T> ifNoItem()
Uni
reacting when a no item event is fired by the upstream uni during the specified time
period.
This Uni
detects if this Uni
does not emit an item before the configured timeout.
Examples:
uni.ifNoItem().after(Duration.ofMillis(1000).fail() // Propagate a TimeOutException
uni.ifNoItem().after(Duration.ofMillis(1000).recoverWithValue("fallback") // Inject a fallback item on timeout
uni.ifNoItem().after(Duration.ofMillis(1000).on(myExecutor)... // Configure the executor calling on timeout actions
uni.ifNoItem().after(Duration.ofMillis(1000).retry().atMost(5) // Retry five times
Uni<T> emitOn(Executor executor)
Uni
invoking the UniSubscriber.onItem(Object)
and
UniSubscriber.onFailure(Throwable)
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.
executor
- the executor to use, must not be null
Uni
Uni<T> subscribeOn(Executor executor)
Uni
, executes the subscription to the upstream Uni
on a thread
from the given executor. As a result, the UniSubscriber.onSubscribe(UniSubscription)
method will be called
on this thread (except mentioned otherwise)executor
- the executor to use, must not be null
Uni
Uni<T> cache()
Uni
and replays it for all further UniSubscriber
.default <O> Uni<O> map(Function<? super T,? extends O> mapper)
Uni
by applying a (synchronous) function to it.
This method is equivalent to uni.onItem().apply(x -> ...)
For asynchronous composition, look at flatMap.O
- the output typemapper
- the mapper function, must not be null
Uni
computing an item of type <O>
.default <O> Uni<O> flatMap(Function<? super T,Uni<? extends O>> mapper)
Uni
produced by
the given mapper
.
The mapper is called with the item event of the current Uni
and produces an Uni
, possibly
using another type of item (R
). The events fired by produced Uni
are forwarded to the
Uni
returned by this method.
This operation is generally named flatMap
.
UniConvert<T> convert()
Uni
to other types such as CompletionStage
Examples:
uni.convert().toCompletionStage(); // Convert to CompletionStage using convenience method
uni.convert().with(BuiltinConverters.toCompletionStage()); // Convert to CompletionStage using BuiltInConverters
uni.convert().with(uni -> x); // Convert with a custom lambda converter
Uni
instanceUniConvert
Multi<T> toMulti()
Multi
from this Uni
.
When a subscriber subscribes to the returned Multi
and request an item, it subscribes
to this Uni
and the events from this Uni
are propagated to the Multi
:
Uni
emits a non-null
item - this item is propagated to the Multi
and followed with the completion eventUni
emits a null
item - the Multi
fires the completion eventUni
emits a failure, this failure event is propagated by the Multi
It's important to note that the subscription to this Uni
happens when the subscriber to the produced
Multi
requests items, and not at subscription time.
Multi
, never null
UniOnEvent<T> on()
Uni
(item, failure) or
by the subscriber (cancellation, subscription)Copyright © 2019 SmallRye. All rights reserved.