io.smallrye.mutiny.groups

Class UniCreate

java.lang.Object

io.smallrye.mutiny.groups.UniCreate

public class UniCreate
extends Object

Group methods allowing to create Uni instances from various sources.

Field Summary

Fields

Modifier and Type	Field and Description
static UniCreate	INSTANCE

Method Summary

Modifier and Type	Method and Description
<T> Uni<T>	completionStage(CompletionStage<? extends T> stage) Creates a Uni from the given CompletionStage or CompletableFuture.
<T> Uni<T>	completionStage(Supplier<? extends CompletionStage<? extends T>> supplier) Creates a Uni from the given CompletionStage or CompletableFuture.
<T,S> Uni<T>	completionStage(Supplier<S> stateSupplier, Function<S,? extends CompletionStage<? extends T>> mapper) Creates a Uni from the given CompletionStage or CompletableFuture.
<I,T> Uni<T>	converter(UniConverter<I,T> converter, I instance) Creates a new Uni from the passed instance with the passed converter.
<T> Uni<T>	deferred(Supplier<? extends Uni<? extends T>> supplier) Creates a Uni that supplies an Uni to subscribe to for each UniSubscriber.
<T,S> Uni<T>	deferred(Supplier<S> stateSupplier, Function<S,? extends Uni<? extends T>> mapper) Creates a Uni that supplies an Uni to subscribe to for each UniSubscriber.
<T> Uni<T>	emitter(Consumer<UniEmitter<? super T>> consumer) Creates a Uni deferring the logic to the given consumer.
<T,S> Uni<T>	emitter(Supplier<S> stateSupplier, BiConsumer<S,UniEmitter<? super T>> consumer) Creates a Uni deferring the logic to the given consumer.
<T> Uni<T>	failure(Supplier<Throwable> supplier) Creates a Uni that emits a failure event produced using the passed supplier immediately after being subscribed to.
<T> Uni<T>	failure(Throwable failure) Creates a Uni that emits a failure event immediately after being subscribed to.
<T> Uni<T>	item(Supplier<? extends T> supplier) Creates a new Uni that completes immediately after being subscribed to with the specified (potentially null) value.
<T,S> Uni<T>	item(Supplier<S> stateSupplier, Function<S,? extends T> mapper) Creates a new Uni that completes immediately after being subscribed to with the specified (potentially null) value.
<T> Uni<T>	item(T item) Creates a new Uni that completes immediately after being subscribed to with the specified (potentially null) item.
<T> Uni<T>	multi(Multi<T> multi) Creates a Uni from the given Multi.
<T> Uni<T>	nothing() Creates a Uni that will never fire an item or failure event.
<T> Uni<T>	nullItem() Creates a new Uni that completes with a null item.
<T> Uni<T>	optional(Optional<T> optional) Creates a new Uni that completes immediately after being subscribed to with the item based on the value contained in the given optional if Optional.isPresent() or null otherwise.
<T> Uni<T>	optional(Supplier<Optional<T>> supplier) Creates a new Uni that completes immediately after being subscribed to with the item based on the value contained in the given optional if Optional.isPresent() or null otherwise.
<T> Uni<T>	publisher(org.reactivestreams.Publisher<? extends T> publisher) Creates a Uni from the passed Publisher.
Uni<Void>	voidItem() Creates a new Uni that completes with a null item.

Methods inherited from class java.lang.Object

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

Field Detail

INSTANCE

public static final UniCreate INSTANCE

Method Detail

converter

public <I,T> Uni<T> converter(UniConverter<I,T> converter,
                              I instance)

Creates a new Uni from the passed instance with the passed converter.

Type Parameters:

I - the type being converted from

T - the type for the Uni

Parameters:

converter - performs the type conversion

instance - instance to convert from

Returns:

created Uni

completionStage

public <T> Uni<T> completionStage(CompletionStage<? extends T> stage)

Creates a Uni from the given CompletionStage or CompletableFuture. The produced Uni emits the item of the passed CompletionStage. If the CompletionStage never completes (or failed), the produced Uni would not emit the item or failure events.

Cancelling the subscription on the produced Uni cancels the passed CompletionStage (calling CompletableFuture.cancel(boolean) on the future retrieved using CompletionStage.toCompletableFuture().

If the stage has already been completed (or failed), the produced Uni sends the item or failure immediately after subscription. If it's not the case, the subscriber's callbacks are called on the thread used by the passed CompletionStage.

Type Parameters:

T - the type of item

Parameters:

stage - the stage, must not be null

Returns:

the produced Uni

completionStage

public <T,S> Uni<T> completionStage(Supplier<S> stateSupplier,
                                    Function<S,? extends CompletionStage<? extends T>> mapper)

Creates a Uni from the given CompletionStage or CompletableFuture. The produced Uni emits the item of the passed CompletionStage. If the CompletionStage never completes (or failed), the produced Uni would not emit the item or failure events.

Cancelling the subscription on the produced Uni cancels the passed CompletionStage (calling CompletableFuture.cancel(boolean) on the future retrieved using CompletionStage.toCompletableFuture().

If the stage has already been completed (or failed), the produced Uni sends the item or failure immediately after subscription. If it's not the case, the subscriber's callbacks are called on the thread used by the passed CompletionStage.

This variant of completionStage(CompletionStage) allows passing a state supplier. This supplier allows sharing some state between the subscribers. It is particularly useful when using Uni.repeat() as you can pass a shared state (for example a page counter, like an AtomicInteger, if you implement pagination). The state supplier is called once, during the first subscription. Note that the mapper is called for every subscription.

The state supplier should produce a container wrapping the shared state. This shared state must be thread-safe.

Type Parameters:

T - the type of item

S - the type of the state

Parameters:

stateSupplier - the state supplier, must not return null, must not be null

mapper - the taking the shared state and producing the completion stage.

Returns:

the produced Uni

completionStage

public <T> Uni<T> completionStage(Supplier<? extends CompletionStage<? extends T>> supplier)

Creates a Uni from the given CompletionStage or CompletableFuture. The future is created by invoking the passed Supplier lazily at subscription time.

The produced Uni emits the item of the passed CompletionStage. If the CompletionStage never completes (or failed), the produced Uni would not emit an item or a failure.

Cancelling the subscription on the produced Uni cancels the passed CompletionStage (calling CompletableFuture.cancel(boolean) on the future retrieved using CompletionStage.toCompletableFuture().

If the produced stage has already been completed (or failed), the produced Uni sends the item or failure immediately after subscription. If it's not the case the subscriber's callbacks are called on the thread used by the passed CompletionStage.

If the supplier throws an exception, a failure event with the exception is fired. If the supplier produces null, a failure event containing a NullPointerException is fired.

Type Parameters:

T - the type of item

Parameters:

supplier - the supplier, must not be null, must not produce null

Returns:

the produced Uni

publisher

public <T> Uni<T> publisher(org.reactivestreams.Publisher<? extends T> publisher)

Creates a Uni from the passed Publisher.

The produced Uni emits the first item/value emitted by the passed Publisher. If the publisher emits multiple values, others are dropped. If the publisher emits a failure after a value, the failure is dropped. If the publisher emits the completion signal before having emitted a value, the produced Uni emits a null item event.

When a subscriber subscribes to the produced Uni, it subscribes to the Publisher and requests 1 item. When the first item is received, the subscription is cancelled. Note that each Uni's subscriber would produce a new subscription.

If the Uni's observer cancels its subscription, the subscription to the Publisher is also cancelled.

Type Parameters:

T - the type of item

Parameters:

publisher - the publisher, must not be null

Returns:

the produced Uni

item

public <T> Uni<T> item(Supplier<? extends T> supplier)

Creates a new Uni that completes immediately after being subscribed to with the specified (potentially null) value. The item is retrieved lazily at subscription time, using the passed Supplier. Unlike deferred(Supplier), the supplier produces an item and not an Uni.

If the supplier produces null, null is used as item event. If the supplier throws an exception, a failure event with the exception is fired. If the supplier produces null, a failure event containing a NullPointerException is fired.

Type Parameters:

T - the type of item

Parameters:

supplier - the item supplier, must not be null, can produce null

Returns:

the new Uni

item

public <T,S> Uni<T> item(Supplier<S> stateSupplier,
                         Function<S,? extends T> mapper)

Creates a new Uni that completes immediately after being subscribed to with the specified (potentially null) value. The item is retrieved lazily at subscription time, using the passed Supplier. Unlike deferred(Supplier), the supplier produces an item and not an Uni.

This variant of item(Supplier) allows passing a state supplier. This supplier allows sharing some state between the subscribers. It is particularly useful when using Uni.repeat() as you can pass a shared state (for example a page counter, like an AtomicInteger, if you implement pagination). The state supplier is called once, during the first subscription. Note that the mapper is called for every subscription.

The state supplier should produce a container wrapping the shared state. This shared state must be thread-safe.

Type Parameters:

T - the type of item

S - the type of the state

Parameters:

stateSupplier - the state supplier, must not return null, must not be null

mapper - the taking the shared state and producing the item.

Returns:

the produced Uni

item

public <T> Uni<T> item(T item)

Creates a new Uni that completes immediately after being subscribed to with the specified (potentially null) item.

Type Parameters:

T - the type of item

Parameters:

item - the item, can be null

Returns:

the new Uni

voidItem

public Uni<Void> voidItem()

Creates a new Uni that completes with a null item.

Returns:

the new Uni with a null item

nullItem

public <T> Uni<T> nullItem()

Creates a new Uni that completes with a null item.

Type Parameters:

T - the type of item

Returns:

the new Uni with a null item

optional

public <T> Uni<T> optional(Optional<T> optional)

Creates a new Uni that completes immediately after being subscribed to with the item based on the value contained in the given optional if Optional.isPresent() or null otherwise.

Type Parameters:

T - the type of the produced item

Parameters:

optional - the optional, must not be null

Returns:

the new Uni

optional

public <T> Uni<T> optional(Supplier<Optional<T>> supplier)

Creates a new Uni that completes immediately after being subscribed to with the item based on the value contained in the given optional if Optional.isPresent() or null otherwise. Unlike optional(Optional), the passed Supplier is called lazily at subscription time.

If the supplier throws an exception, a failure event with the exception is fired. If the supplier produces null, a failure event containing a NullPointerException is fired.

Type Parameters:

T - the type of the produced item

Parameters:

supplier - the supplier, must not be null, must not return null

Returns:

the new Uni

emitter

public <T> Uni<T> emitter(Consumer<UniEmitter<? super T>> consumer)

Creates a Uni deferring the logic to the given consumer. The consumer can be used with callback-based APIs to fire at most one item (potentially null), or a failure event.

Using this method, you can produce a Uni based on listener or callbacks APIs. You register the listener in the consumer and emits the item / failure events when the listener is invoked. Don't forget to unregister the listener on cancellation.

Note that the emitter only forwards the first event, subsequent events are dropped.

If the consumer throws an exception, a failure event with the exception is fired if the first event was already fired.

Type Parameters:

T - the type of item

Parameters:

consumer - callback receiving the UniEmitter and events downstream. The callback is called for each subscriber (at subscription time). Must not be null

Returns:

the produced Uni

emitter

public <T,S> Uni<T> emitter(Supplier<S> stateSupplier,
                            BiConsumer<S,UniEmitter<? super T>> consumer)

Creates a Uni deferring the logic to the given consumer. The consumer can be used with callback-based APIs to fire at most one item (potentially null), or a failure event.

Using this method, you can produce a Uni based on listener or callbacks APIs. You register the listener in the consumer and emits the item / failure events when the listener is invoked. Don't forget to unregister the listener on cancellation.

Note that the emitter only forwards the first event, subsequent events are dropped.

If the consumer throws an exception, a failure event with the exception is fired if the first event was already fired. This variant of emitter(Consumer) allows passing a state supplier. This supplier allows sharing some state between the subscribers. It is particularly useful when using Uni.repeat() as you can pass a shared state (for example a page counter, like an AtomicInteger, if you implement pagination). The state supplier is called once, during the first subscription. Note that the mapper is called for every subscription.

The state supplier should produce a container wrapping the shared state. This shared state must be thread-safe.

Type Parameters:

T - the type of item

S - the type of the state

Parameters:

stateSupplier - the state supplier, must not return null, must not be null

consumer - callback receiving the UniEmitter and events downstream. The callback is called for each subscriber (at subscription time). Must not be null

Returns:

the produced Uni

deferred

public <T> Uni<T> deferred(Supplier<? extends Uni<? extends T>> supplier)

Creates a Uni that supplies an Uni to subscribe to for each UniSubscriber. The supplier is called at subscription time.

In practice, it defers the Uni creation at subscription time and allows each subscriber to get different Uni. So, it does not create the Uni until an subscriber subscribes, and creates a fresh Uni for each subscriber.

Unlike item(Supplier), the supplier produces an Uni (and not an item).

If the supplier throws an exception, a failure event with the exception is fired. If the supplier produces null, a failure event containing a NullPointerException is fired.

Type Parameters:

T - the type of item

Parameters:

supplier - the supplier, must not be null, must not produce null

Returns:

the produced Uni

deferred

public <T,S> Uni<T> deferred(Supplier<S> stateSupplier,
                             Function<S,? extends Uni<? extends T>> mapper)

Creates a Uni that supplies an Uni to subscribe to for each UniSubscriber. The supplier is called at subscription time.

In practice, it defers the Uni creation at subscription time and allows each subscriber to get different Uni. So, it does not create the Uni until an subscriber subscribes, and creates a fresh Uni for each subscriber.

Unlike item(Supplier), the supplier produces an Uni (and not an item).

If the supplier throws an exception, a failure event with the exception is fired. If the supplier produces null, a failure event containing a NullPointerException is fired.

This variant of deferred(Supplier) allows passing a state supplier. This supplier allows sharing some state between the subscribers. It is particularly useful when using Uni.repeat() as you can pass a shared state (for example a page counter, like an AtomicInteger, if you implement pagination). The state supplier is called once, during the first subscription. Note that the mapper is called for every subscription.

The state supplier should produce a container wrapping the shared state. This shared state must be thread-safe.

Type Parameters:

T - the type of item

S - the type of the state

Parameters:

stateSupplier - the state supplier, must not return null, must not be null

mapper - the taking the shared state and producing the completion stage.

Returns:

the produced Uni

failure

public <T> Uni<T> failure(Throwable failure)

Creates a Uni that emits a failure event immediately after being subscribed to.

Type Parameters:

T - the virtual type of item used by the Uni, must be explicitly set as in Uni.<String>failed(exception);

Parameters:

failure - the failure to be fired, must not be null

Returns:

the produced Uni

failure

public <T> Uni<T> failure(Supplier<Throwable> supplier)

Creates a Uni that emits a failure event produced using the passed supplier immediately after being subscribed to. The supplier is called at subscription time, and produces an instance of Throwable. If the supplier throws an exception, a failure event is fired with this exception. If the supplier produces null, a failure event is fired with a NullPointerException.

Type Parameters:

T - the virtual type of item used by the Uni, must be explicitly set as in Uni.<String>failed(exception);

Parameters:

supplier - the supplier producing the failure, must not be null, must not produce null

Returns:

the produced Uni

nothing

public <T> Uni<T> nothing()

Creates a Uni that will never fire an item or failure event.

Type Parameters:

T - the virtual type of item

Returns:

a never completing Uni

multi

public <T> Uni<T> multi(Multi<T> multi)

Creates a Uni from the given Multi.

When a subscriber subscribes to the returned Uni, it subscribes to the Multi and requests one item. The event emitted by the 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.

Type Parameters:

T - the type of item

Parameters:

multi - the multi, must not be null

Returns:

the produced Uni