Package io.smallrye.mutiny.operators

Class AbstractUni<T>

java.lang.Object

io.smallrye.mutiny.operators.AbstractUni<T>

All Implemented Interfaces:

Uni<T>

Direct Known Subclasses:

UniOperator

public abstract class AbstractUni<T>
extends java.lang.Object
implements Uni<T>

Constructor Summary

Constructors

Constructor	Description
AbstractUni()

Method Summary

Modifier and Type	Method	Description
UniAwait<T>	await()	Awaits (blocking the caller thread) until the item or a failure is emitted by the observed Uni.
UniAwait<T>	awaitUsing(Context context)	Awaits (blocking the caller thread) until the item or a failure is emitted by the observed Uni.
Uni<T>	cache()
UniConvert<T>	convert()	Converts an Uni to other types such as CompletionStage
Uni<T>	emitOn(java.util.concurrent.Executor executor)	Produces a new Uni invoking the UniSubscriber.onItem(Object) and UniSubscriber.onFailure(Throwable) on the supplied Executor.
UniIfNoItem<T>	ifNoItem()	Produces a Uni reacting when a no item event is fired by the upstream uni during the specified time period.
Uni<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".
Uni<T>	log(java.lang.String identifier)	Log events (onSubscribe, onItem, ...) as they come from the upstream or the subscriber.
UniMemoize<T>	memoize()	Configure memoization of the Uni item or failure.
UniOnCancel<T>	onCancellation()	Configures actions to be performed when the subscriber cancels the subscription.
UniOnFailure<T>	onFailure()	Like Uni.onFailure(Predicate) but applied to all failures fired by the upstream uni.
UniOnFailure<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 UniOnFailure) is applied.
UniOnFailure<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 UniOnFailure) is applied.
UniOnItem<T>	onItem()	Configures the action to execute when the observed Uni emits the item (potentially null).
UniOnItemOrFailure<T>	onItemOrFailure()	Configures the action to execute when the observed Uni emits either an item (potentially null)) or a failure.
UniOnSubscribe<T>	onSubscribe()	Configures the action to execute when the observed Uni sends a UniSubscription.
UniOnSubscribe<T>	onSubscription()	Configures the action to execute when the observed Uni sends a UniSubscription.
UniOnTerminate<T>	onTermination()	Configures actions to be performed on termination, that is, on item, on failure, or when the subscriber cancels the subscription.
UniRepeat<T>	repeat()	Allows configuring repeating behavior.
Uni<T>	runSubscriptionOn(java.util.concurrent.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.
abstract void	subscribe(UniSubscriber<? super T> subscriber)
static <T> void	subscribe(Uni<? extends T> upstream, UniSubscriber<? super T> subscriber)	Encapsulates subscription to slightly optimize the AbstractUni case.
Multi<T>	toMulti()	Creates an instance of Multi from this Uni.
<R> Uni<R>	withContext(java.util.function.BiFunction<Uni<T>,Context,Uni<R>> builder)	Materialize the subscriber Context for a sub-pipeline.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.smallrye.mutiny.Uni

attachContext, call, call, chain, chain, eventually, eventually, flatMap, invoke, invoke, map, plug, replaceIfNullWith, replaceIfNullWith, replaceWith, replaceWith, replaceWith, replaceWithNull, replaceWithVoid, stage, subscribeAsCompletionStage, subscribeAsCompletionStage

Constructor Detail

AbstractUni

public AbstractUni()

Method Detail

subscribe

public abstract void subscribe(UniSubscriber<? super T> subscriber)

subscribe

public static <T> void subscribe(Uni<? extends T> upstream,
                                 UniSubscriber<? super T> subscriber)

Encapsulates subscription to slightly optimize the AbstractUni case. In the case of AbstractUni, it avoid creating the UniSubscribe group instance.

Type Parameters:

T - the type of item

Parameters:

upstream - the upstream, must not be null (not checked)

subscriber - the subscriber, must not be null (not checked)

subscribe

public UniSubscribe<T> subscribe()

Description copied from interface: Uni

Requests the Uni to start resolving the item and allows configuring how the signals are propagated (using a UniSubscriber, callbacks, or a CompletionStage. Unlike Uni.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.
 
 

Specified by:

subscribe in interface Uni<T>

Returns:

the object to configure the subscription.

See Also:

uni.await() for waiting (blocking the caller thread) until the resolution of the observed Uni.

onItem

public UniOnItem<T> onItem()

Description copied from interface: Uni

Configures the action to execute when the observed Uni emits the item (potentially null).

Examples:

 
 Uni<T> uni = ...;
 uni.onItem().transform(x -> ...); // Transform the item into another item (~ map)
 uni.onItem().transformToUni(x -> ...); // Transform the item into a Uni (~ flatMap)
 
 

Specified by:

onItem in interface Uni<T>

Returns:

the object to configure the action to execute when an item is emitted

ifNoItem

public UniIfNoItem<T> ifNoItem()

Description copied from interface: Uni

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

Specified by:

ifNoItem in interface Uni<T>

Returns:

the on timeout group

onFailure

public UniOnFailure<T> onFailure()

Description copied from interface: Uni

Like Uni.onFailure(Predicate) but applied to all failures fired by the upstream uni. It allows configuring the on failure behavior (recovery, retry...).

Specified by:

onFailure in interface Uni<T>

Returns:

a UniOnFailure on which you can specify the on failure action

onFailure

public UniOnFailure<T> onFailure(java.util.function.Predicate<? super java.lang.Throwable> predicate)

Description copied from interface: Uni

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.

Specified by:

onFailure in interface Uni<T>

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

public UniOnFailure<T> onFailure(java.lang.Class<? extends java.lang.Throwable> typeOfFailure)

Description copied from interface: Uni

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.

Specified by:

onFailure in interface Uni<T>

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

onSubscribe

public UniOnSubscribe<T> onSubscribe()

Description copied from interface: Uni

Configures the action to execute when the observed Uni sends a UniSubscription. The downstream don't have a subscription yet. It will be passed once the configured action completes.

Example:

 
 uni.onSubscribe().invoke(sub -> System.out.println("subscribed"));
 // Delay the subscription by 1 second (or until an asynchronous action completes)
 uni.onSubscribe().call(sub -> Uni.createFrom(1).onItem().delayIt().by(Duration.ofSecond(1)));
 
 

Specified by:

onSubscribe in interface Uni<T>

Returns:

the object to configure the action to execution on subscription.

onSubscription

public UniOnSubscribe<T> onSubscription()

Description copied from interface: Uni

Configures the action to execute when the observed Uni sends a UniSubscription. The downstream does not have a subscription yet. It will be passed once the configured action completes.

Example:

 
 uni.onSubscription().invoke(sub -> System.out.println("subscribed"));
 // Delay the subscription by 1 second (or until an asynchronous action completes)
 uni.onSubscription().call(sub -> Uni.createFrom(1).onItem().delayIt().by(Duration.ofSecond(1)));
 
 

Specified by:

onSubscription in interface Uni<T>

Returns:

the object to configure the action to execution on subscription.

onItemOrFailure

public UniOnItemOrFailure<T> onItemOrFailure()

Description copied from interface: Uni

Configures the action to execute when the observed Uni emits either an item (potentially null)) or a failure. Unlike Uni.onItem() and Uni.onFailure() the action would handle both cases in on "go".

Specified by:

onItemOrFailure in interface Uni<T>

Returns:

the object to configure the action to execute when an item is emitted or when a failure is propagated.

await

public UniAwait<T> await()

Description copied from interface: Uni

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
 
 

Specified by:

await in interface Uni<T>

Returns:

the object to configure the retrieval.

awaitUsing

public UniAwait<T> awaitUsing(Context context)

Description copied from interface: Uni

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.awaitUsing(context).indefinitely(); // Await indefinitely until it get the item.
 T res = uni.awaitUsing(context).atMost(Duration.ofMillis(1000)); // Awaits at most 1s. After that, a TimeoutException is thrown
 Optional<T> res = uni.awaitUsing(context).asOptional().indefinitely(); // Retrieves the item as an Optional, empty if the item is null
 
 

Specified by:

awaitUsing in interface Uni<T>

Parameters:

context - the context, cannot be null

Returns:

the object to configure the retrieval.

emitOn

public Uni<T> emitOn(java.util.concurrent.Executor executor)

Description copied from interface: Uni

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.

Specified by:

emitOn in interface Uni<T>

Parameters:

executor - the executor to use, must not be null

Returns:

a new Uni

runSubscriptionOn

public Uni<T> runSubscriptionOn(java.util.concurrent.Executor executor)

Description copied from interface: Uni

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)

Specified by:

runSubscriptionOn in interface Uni<T>

Parameters:

executor - the executor to use, must not be null

Returns:

a new Uni

memoize

public UniMemoize<T> memoize()

Description copied from interface: Uni

Configure memoization of the Uni item or failure.

Specified by:

memoize in interface Uni<T>

Returns:

the object to configure memoization

cache

public Uni<T> cache()

convert

public UniConvert<T> convert()

Description copied from interface: Uni

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
 
 

Specified by:

convert in interface Uni<T>

Returns:

the object to convert an Uni instance

See Also:

UniConvert

toMulti

public Multi<T> toMulti()

Description copied from interface: Uni

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.

Specified by:

toMulti in interface Uni<T>

Returns:

the produced Multi, never null

repeat

public UniRepeat<T> repeat()

Description copied from interface: Uni

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.

Specified by:

repeat in interface Uni<T>

Returns:

the object to configure the repeating behavior.

onTermination

public UniOnTerminate<T> onTermination()

Description copied from interface: Uni

Configures actions to be performed on termination, that is, on item, on failure, or when the subscriber cancels the subscription.

Specified by:

onTermination in interface Uni<T>

Returns:

the object to configure the termination actions.

onCancellation

public UniOnCancel<T> onCancellation()

Description copied from interface: Uni

Configures actions to be performed when the subscriber cancels the subscription.

Specified by:

onCancellation in interface Uni<T>

Returns:

the object to configure the cancellation actions.

log

public Uni<T> log(java.lang.String identifier)

Description copied from interface: Uni

Log events (onSubscribe, onItem, ...) as they come from the upstream or the subscriber.

Events will be logged as long as the Uni hasn't been cancelled or terminated. Logging is framework-agnostic and can be configured in the Infrastructure class.

Specified by:

log in interface Uni<T>

Parameters:

identifier - an identifier of this operator to be used in log events

Returns:

a new Uni

See Also:

Infrastructure.setOperatorLogger(Infrastructure.OperatorLogger)

log

public Uni<T> log()

Description copied from interface: Uni

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 Uni hasn't been cancelled or terminated. Logging is framework-agnostic and can be configured in the Infrastructure class.

Specified by:

log in interface Uni<T>

Returns:

a new Uni

See Also:

Uni.log(String), Infrastructure.setOperatorLogger(Infrastructure.OperatorLogger)

withContext

public <R> Uni<R> withContext(java.util.function.BiFunction<Uni<T>,Context,Uni<R>> builder)

Description copied from interface: Uni

Materialize the subscriber Context for a sub-pipeline.

The provided function takes this Uni and the Context as parameters, and returns a Uni to build the sub-pipeline, as in:

 
 someUni.withContext((uni, ctx) -> uni.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.

Specified by:

withContext in interface Uni<T>

Type Parameters:

R - the resulting Uni type

Parameters:

builder - the function that builds the sub-pipeline from this Uni and the Context, must not be null, must not return null.

Returns:

the resulting Uni