Module io.smallrye.mutiny
Package io.smallrye.mutiny.groups

Class UniCreate

  • public class UniCreate
extends java.lang.Object
    Group methods allowing to create Uni instances from various sources.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      <T> Uni<T> completionStage​(java.util.concurrent.CompletionStage<? extends T> stage)
      Creates a Uni from the given CompletionStage or CompletableFuture.
      <T> Uni<T> completionStage​(java.util.function.Supplier<? extends java.util.concurrent.CompletionStage<? extends T>> supplier)
      Creates a Uni from the given CompletionStage or CompletableFuture.
      <T,​S>
      Uni<T>      		 completionStage​(java.util.function.Supplier<S> stateSupplier, java.util.function.Function<S,​? extends java.util.concurrent.CompletionStage<? extends T>> mapper)
      Creates a Uni from the given CompletionStage or CompletableFuture.
      <T> Uni<T> context​(java.util.function.Function<Context,​Uni<? extends T>> mapper)
      Creates a Uni using Function.apply(Object) on the subscription-bound Context (the mapper is called at subscription time).
      <I,​T>
      Uni<T>      		 converter​(io.smallrye.mutiny.converters.UniConverter<I,​T> converter, I instance)
      Creates a new Uni from the passed instance with the passed converter.
      <T> Uni<T> deferred​(java.util.function.Supplier<Uni<? extends T>> supplier)
      Creates a Uni that supplies an Uni to subscribe to for each UniSubscriber.
      <T,​S>
      Uni<T>      		 deferred​(java.util.function.Supplier<S> stateSupplier, java.util.function.Function<S,​Uni<? extends T>> mapper)
      Creates a Uni that supplies an Uni to subscribe to for each UniSubscriber.
      <T> Uni<T> emitter​(java.util.function.Consumer<UniEmitter<? super T>> consumer)
      Creates a Uni deferring the logic to the given consumer.
      <T,​S>
      Uni<T>      		 emitter​(java.util.function.Supplier<S> stateSupplier, java.util.function.BiConsumer<S,​UniEmitter<? super T>> consumer)
      Creates a Uni deferring the logic to the given consumer.
      <T> Uni<T> failure​(java.lang.Throwable failure)
      Creates a Uni that emits a failure event immediately after being subscribed to.
      <T> Uni<T> failure​(java.util.function.Supplier<java.lang.Throwable> supplier)
      Creates a Uni that emits a failure event produced using the passed supplier immediately after being subscribed to.
      <T> Uni<T> future​(java.util.concurrent.Future<? extends T> future)
      Creates a Uni from the given Future.
      <T> Uni<T> future​(java.util.concurrent.Future<? extends T> future, java.time.Duration timeout)
      Creates a Uni from the given Future.
      <T> Uni<T> future​(java.util.function.Supplier<java.util.concurrent.Future<? extends T>> supplier)
      Creates a Uni from the given Future.
      <T> Uni<T> future​(java.util.function.Supplier<java.util.concurrent.Future<? extends T>> supplier, java.time.Duration timeout)
      Creates a Uni from the given Future.
      <T> Uni<T> item​(java.util.function.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​(java.util.function.Supplier<S> stateSupplier, java.util.function.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​(java.util.function.Supplier<java.util.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> optional​(java.util.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> publisher​(java.util.concurrent.Flow.Publisher<? extends T> publisher)
      Creates a Uni from the passed Flow.Publisher.
      Uni<java.lang.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

        @CheckReturnValue
public <I,​T> Uni<T> converter​(io.smallrye.mutiny.converters.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

        @CheckReturnValue
public <T> Uni<T> completionStage​(java.util.concurrent.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

        @CheckReturnValue
public <T,​S> Uni<T> completionStage​(java.util.function.Supplier<S> stateSupplier,
                                          java.util.function.Function<S,​? extends java.util.concurrent.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

        @CheckReturnValue
public <T> Uni<T> completionStage​(java.util.function.Supplier<? extends java.util.concurrent.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

      • future

        @CheckReturnValue
public <T> Uni<T> future​(java.util.concurrent.Future<? extends T> future)
        Creates a Uni from the given Future.

        The produced Uni emits the item produced by the Future. Because Future.get() is blocking, creating a Uni from a Future requires blocking a thread until the future produces a value, a failure, or the subscriber cancels. As a consequence, a thread from the Infrastructure.getDefaultExecutor() is used, and waits until the passed future produces an outcome. If the Future never completes (or fails), the produced Uni will not emit any item or failure, but it would also keep the thread blocked. So, make sure your Future are always completing or failing.

        Cancelling the subscription on the produced Uni cancels the passed Future (calling Future.cancel(boolean)).

        If the produced future has already been completed (or failed), the produced Uni sends the item or failure immediately after subscription. If it's not the case the callbacks of the subscriber are called on the thread used to wait the result (a thread from the Mutiny infrastructure default executor).

        Type Parameters:
        T - the type of item
        Parameters:
        future - the future, must not be null
        Returns:
        the produced Uni

      • future

        @CheckReturnValue
public <T> Uni<T> future​(java.util.function.Supplier<java.util.concurrent.Future<? extends T>> supplier)
        Creates a Uni from the given Future. The future is created by invoking the passed Supplier lazily at subscription time.

        The produced Uni emits the item produced by the Future supplied by the given Supplier. Because Future.get() is blocking, creating a Uni from a Future requires blocking a thread until the future produces a value, a failure, or the subscriber cancels. A thread from the Infrastructure.getDefaultExecutor() is used, and waits until the passed future produces an outcome. If the Future never completes (or fails), the produced Uni will not emit an item or a failure, but it would also keep the thread blocked. So, make sure your Future are always completing or failing.

        Cancelling the subscription on the produced Uni cancels the passed Future (calling Future.cancel(boolean)).

        If the produced future 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 to wait for the result (so a thread from the default executor).

        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

      • future

        @CheckReturnValue
public <T> Uni<T> future​(java.util.concurrent.Future<? extends T> future,
                         java.time.Duration timeout)
        Creates a Uni from the given Future.

        The produced Uni emits the item produced by the Future. Because Future.get() is blocking, creating a Uni from a Future requires blocking a thread until the future produces a value, a failure, a timeout, or the subscriber cancels. As a consequence, a thread from the Infrastructure.getDefaultExecutor() is used, and waits until the passed future produces an outcome.

        Cancelling the subscription on the produced Uni cancels the passed Future (calling Future.cancel(boolean)).

        If the produced future has already been completed (or failed), the produced Uni sends the item or failure immediately after subscription. If it's not the case the callbacks of the subscriber are called on the thread used to wait the result (a thread from the Mutiny infrastructure default executor).

        Type Parameters:
        T - the type of item
        Parameters:
        future - the future, must not be null
        timeout - the future timeout, must not be null
        Returns:
        the produced Uni

      • future

        @CheckReturnValue
public <T> Uni<T> future​(java.util.function.Supplier<java.util.concurrent.Future<? extends T>> supplier,
                         java.time.Duration timeout)
        Creates a Uni from the given Future. The future is created by invoking the passed Supplier lazily at subscription time.

        The produced Uni emits the item produced by the Future supplied by the given Supplier. Because Future.get() is blocking, creating a Uni from a Future requires blocking a thread until the future produces a value, a failure, a timeout, or the subscriber cancels. A thread from the Infrastructure.getDefaultExecutor() is used, and waits until the passed future produces an outcome.

        Cancelling the subscription on the produced Uni cancels the passed Future (calling Future.cancel(boolean)).

        If the produced future 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 to wait for the result (so a thread from the default executor).

        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
        timeout - the future timeout
        Returns:
        the produced Uni

      • publisher

        @CheckReturnValue
public <T> Uni<T> publisher​(java.util.concurrent.Flow.Publisher<? extends T> publisher)
        Creates a Uni from the passed Flow.Publisher.

        The produced Uni emits the first item/value emitted by the passed Flow.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 Flow.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 Flow.Publisher is also cancelled.

        Type Parameters:
        T - the type of item
        Parameters:
        publisher - the publisher, must not be null
        Returns:
        the produced Uni

      • item

        @CheckReturnValue
public <T> Uni<T> item​(java.util.function.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 is null, an IllegalArgumentException is thrown, synchronously.

        Type Parameters:
        T - the type of item
        Parameters:
        supplier - the item supplier, must not be null, can produce null
        Returns:
        the new Uni

      • item

        @CheckReturnValue
public <T,​S> Uni<T> item​(java.util.function.Supplier<S> stateSupplier,
                               java.util.function.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

        @CheckReturnValue
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

        @CheckReturnValue
public Uni<java.lang.Void> voidItem()
        Creates a new Uni that completes with a null item.
        Returns:
        the new Uni with a null item

      • nullItem

        @CheckReturnValue
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

        @CheckReturnValue
public <T> Uni<T> optional​(java.util.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

        @CheckReturnValue
public <T> Uni<T> optional​(java.util.function.Supplier<java.util.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

        @CheckReturnValue
public <T> Uni<T> emitter​(java.util.function.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

        @CheckReturnValue
public <T,​S> Uni<T> emitter​(java.util.function.Supplier<S> stateSupplier,
                                  java.util.function.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

        @CheckReturnValue
public <T> Uni<T> deferred​(java.util.function.Supplier<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 a 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

      • context

        @CheckReturnValue
public <T> Uni<T> context​(java.util.function.Function<Context,​Uni<? extends T>> mapper)
        Creates a Uni using Function.apply(Object) on the subscription-bound Context (the mapper is called at subscription time).

        This method is semantically equivalent to deferred(Supplier), except that it passes a context.

        Type Parameters:
        T - the type of the item
        Parameters:
        mapper - the mapper, must not be null, must not produce null
        Returns:
        the produced Uni

      • deferred

        @CheckReturnValue
public <T,​S> Uni<T> deferred​(java.util.function.Supplier<S> stateSupplier,
                                   java.util.function.Function<S,​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 a 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

        @CheckReturnValue
public <T> Uni<T> failure​(java.lang.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

        @CheckReturnValue
public <T> Uni<T> failure​(java.util.function.Supplier<java.lang.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

        @CheckReturnValue
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

        @CheckReturnValue
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