Module io.smallrye.mutiny
Package 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 Details

    • INSTANCE

      public static final UniCreate INSTANCE

  • Method Details

    • 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(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(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

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

    • future

      @CheckReturnValue public <T> Uni<T> future(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(Supplier<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(Future<? extends T> future, 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(Supplier<Future<? extends T>> supplier, 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(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(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(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

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

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

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

      @CheckReturnValue public <T> Uni<T> deferred(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(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(Supplier<S> stateSupplier, 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(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(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

      @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