Uni (SmallRye Mutiny 0.5.0 API)

Type Parameters:

T - the type of item produced by the Uni

All Known Implementing Classes:

AbstractUni, UniAndCombination, UniCache, UniCallSubscribeOn, UniCreateFromCompletionStage, UniCreateFromDeferredSupplier, UniCreateFromPublisher, UniCreateWithEmitter, UniDelayOnItem, UniDelayUntil, UniEmitOn, UniFailOnTimeout, UniFlatMapCompletionStageOnItem, UniFlatMapOnFailure, UniFlatMapOnItem, UniMapOnFailure, UniMapOnResult, UniNever, UniOnCancellation, UniOnEventConsume, UniOnSubscription, UniOnTermination, UniOperator, UniOrCombination, UniRetryAtMost
```
public interface Uni<T>
```
A Uni represents a lazy asynchronous action. It follows the subscription pattern, meaning that the action is only triggered once a UniSubscriber subscribes to the Uni.
A Uni can have two outcomes:
1. An item event, forwarding the completion of the action (potentially null if the item does not represent a value, but the action was completed successfully)
2. A failure event, forwarding an exception
To trigger the computation, a UniSubscriber must subscribe to the Uni. It will be notified of the outcome once there 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.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods
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)` Combines the item of this `Uni` with the item of `other` into a `Tuple2`.
`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()` Creates a new `Uni` combining several others unis such as `all` or `any`.
`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<T>`	`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).
`UniRepeat<T>`	`repeat()` Allows configuring repeating behavior.
`Uni<T>`	`runSubscriptionOn(Executor executor)` When a subscriber subscribes to this `Uni`, executes the subscription to the upstream `Uni` on a thread from the given executor.
`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()`.
`default Uni<T>`	`subscribeOn(Executor executor)` Deprecated. Use `runSubscriptionOn(Executor)` instead
`default <O> O`	`then(Function<Uni<T>,O> stage)` Allows structuring the pipeline by creating a logic separation:
`Multi<T>`	`toMulti()` Creates an instance of `Multi` from this `Uni`.

- Method Detail
  - createFrom
```
static UniCreate createFrom()
```
    Creates a new Uni from various sources such as CompletionStage, UniEmitter, direct values, Exception...
    Examples:
```
 
 Uni.createFrom().item(1); // Emit 1 at subscription time
 Uni.createFrom().item(() -> x); // Emit x at subscription time, the supplier is invoked for each subscription
 Uni.createFrom().completionStage(cs); // Emit the item from this completion stage
 Uni.createFrom().completionStage(() -> cs); // Emit the item from this completion stage, the stage is not created before subscription
 Uni.createFrom().failure(exception); // Emit the failure at subscription time
 Uni.createFrom().deferred(() -> Uni.from().value(x)); // Defer the uni creation until subscription. Each subscription can produce a different uni
 Uni.createFrom().item(null); // Emit null at subscription time
 Uni.createFrom().nothing(); // Create a Uni not emitting any signal
 Uni.createFrom().publisher(publisher); // Create a Uni from a Reactive Streams Publisher
 
 
```
    Returns:
    
    the factory used to create Uni instances.
    
    See Also:
    
    UniCreate
  - then
```
default <O> O then(Function<Uni<T>,O> stage)
```
    Allows structuring the pipeline by creating a logic separation:
```
 
     Uni uni = upstream
      .then(u -> { ...})
      .then(u -> { ...})
      .then(u -> { ...})
 
 
```
    With `then` you can structure and chain groups of processing.
    Type Parameters:
    
    O - the outcome type
    
    Parameters:
    
    stage - the function receiving the this Uni as parameter and producing the outcome (can be a Uni or something else), must not be null.
    
    Returns:
    
    the outcome of the function.
  - combine
```
static UniCombine combine()
```
    Creates a new Uni combining several others unis such as all or any.
    
    Returns:
    
    the factory use to combine the uni instances
  - subscribe
```
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. 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.
 
 
```
    Returns:
    
    the object to configure the subscription.
    
    See Also:
    
    uni.await() for waiting (blocking the caller thread) until the resolution of the observed Uni.
  - subscribeAsCompletionStage
```
default CompletableFuture<T> subscribeAsCompletionStage()
```
    Shortcut for UniSubscribe.asCompletionStage().
    
    Returns:
    
    the completion stage receiving the items emitted by this Uni
  - await
```
UniAwait<T> await()
```
    Awaits (blocking the caller thread) until the item or a failure is emitted by the observed 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
 
 
```
    Returns:
    
    the object to configure the retrieval.
  - onItem
```
UniOnItem<T> onItem()
```
    Configures the action to execute when the observed 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)
 
 
```
    Returns:
    
    the object to configure the action to execute when an item is emitted
  - and
```
UniAndGroup<T> and()
```
    Combines a set of 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).
    
    Returns:
    
    the object to configure the join
    
    See Also:
    
    Uni.all() for the equivalent static operator
  - and
```
<T2> Uni<Tuple2<T,T2>> and(Uni<T2> other)
```
    Combines the item of this Uni with the item of other into a Tuple2. If this or other fails, the other resolution is cancelled.
    
    Type Parameters:
    
    T2 - the type to pair
    
    Parameters:
    
    other - the other Uni, must not be null
    
    Returns:
    
    the combination of the pair combining the two items.
    
    See Also:
    
    and for more options on the combination of items, Uni.all() for the equivalent static operator
  - or
```
UniOr<T> 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). 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.
    
    Returns:
    
    the object to enlist the participants
    
    See Also:
    
    Uni.any for a static version of this operator, like Uni first = Uni.any().of(uni1, uni2);
  - onFailure
```
UniOnFailure<T> onFailure()
```
    Like onFailure(Predicate) but applied to all failures fired by the upstream uni. It allows configuring the on failure behavior (recovery, retry...).
    
    Returns:
    
    a UniOnFailure on which you can specify the on failure action
  - onFailure
```
UniOnFailure<T> onFailure(Predicate<? super Throwable> predicate)
```
    Configures a predicate filtering the failures on which the behavior (specified with the returned 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.
    
    Parameters:
    
    predicate - the predicate, null means applied to all failures
    
    Returns:
    
    a UniOnFailure configured with the given predicate on which you can specify the on failure action
  - onFailure
```
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.
    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.
    
    Parameters:
    
    typeOfFailure - the class of exception, must not be null
    
    Returns:
    
    a UniOnFailure configured with the given predicate on which you can specify the on failure action
  - ifNoItem
```
UniIfNoItem<T> ifNoItem()
```
    Produces a 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
    
    Returns:
    
    the on timeout group
  - emitOn
```
Uni<T> emitOn(Executor executor)
```
    Produces a new 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.
    
    Parameters:
    
    executor - the executor to use, must not be null
    
    Returns:
    
    a new Uni
  - subscribeOn
```
@Deprecated
default Uni<T> subscribeOn(Executor executor)
```
    Deprecated. Use runSubscriptionOn(Executor) instead
    
    When a subscriber subscribes to this 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)
    
    Parameters:
    
    executor - the executor to use, must not be null
    
    Returns:
    
    a new Uni
  - runSubscriptionOn
```
Uni<T> runSubscriptionOn(Executor executor)
```
    When a subscriber subscribes to this 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)
    
    Parameters:
    
    executor - the executor to use, must not be null
    
    Returns:
    
    a new Uni
  - cache
```
Uni<T> cache()
```
    Caches the events (item or failure) of this Uni and replays it for all further UniSubscriber.
    
    Returns:
    
    the new Uni. Unlike regular Uni, re-subscribing to this Uni does not re-compute the outcome but replayed the cached events.
  - map
```
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. This method is equivalent to uni.onItem().apply(x -> ...) For asynchronous composition, look at flatMap.
    
    Type Parameters:
    
    O - the output type
    
    Parameters:
    
    mapper - the mapper function, must not be null
    
    Returns:
    
    a new Uni computing an item of type <O>.
  - flatMap
```
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.
    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.
    
    Type Parameters:
    
    O - the type of item
    
    Parameters:
    
    mapper - the function called with the item of the this Uni and producing the Uni, must not be null, must not return null.
    
    Returns:
    
    a new Uni that would fire events from the uni produced by the mapper function, possibly in an asynchronous manner.
  - convert
```
UniConvert<T> convert()
```
    Converts an 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
 
 
```
    Returns:
    
    the object to convert an Uni instance
    
    See Also:
    
    UniConvert
  - toMulti
```
Multi<T> toMulti()
```
    Creates an instance of 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:
    - if this Uni emits a non-null item - this item is propagated to the Multi and followed with the completion event
    - if this Uni emits a null item - the Multi fires the completion event
    - if this Uni 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.
    Returns:
    
    the produced Multi, never null
  - on
```
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)
    
    Returns:
    
    the object to configure the action to execute when events happen
  - repeat
```
UniRepeat<T> repeat()
```
    Allows configuring repeating behavior. Repeating allow transforming a Uni into a Multi either a specific amount of times or indefinitely. Each time, a new subscription is attempted on the Uni. Cancelling the subscription stops the repeating behavior.
    
    Returns:
    
    the object to configure the repeating behavior.

Interface Uni<T>

Method Summary

Method Detail

createFrom

then

combine

subscribe

subscribeAsCompletionStage

await

onItem

and

and

or

onFailure

onFailure

onFailure

ifNoItem

emitOn

subscribeOn

runSubscriptionOn

cache

map

flatMap

convert

toMulti

on

repeat