Package io.smallrye.mutiny.groups

Class MultiCreate

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

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      <T> Multi<T> completionStage​(java.util.concurrent.CompletionStage<? extends T> stage)
      Creates a Multi from the given CompletionStage or CompletableFuture.
      <T> Multi<T> completionStage​(java.util.function.Supplier<? extends java.util.concurrent.CompletionStage<? extends T>> supplier)
      Creates a Multi from the given CompletionStage or CompletableFuture.
      <T> Multi<T> context​(java.util.function.Function<Context,​Multi<? extends T>> mapper)
      Creates a Multi using Function.apply(Object) on the subscription-bound Context (the mapper is called at subscription time).
      <I,​T>
      Multi<T>      		 converter​(io.smallrye.mutiny.converters.MultiConverter<I,​T> converter, I instance)
      Creates a new Multi from the passed instance with the passed converter.
      <T> Multi<T> deferred​(java.util.function.Supplier<Multi<? extends T>> supplier)
      Creates a Multi that supplies an Multi to subscribe to for each Subscriber.
      <T> Multi<T> emitter​(java.util.function.Consumer<MultiEmitter<? super T>> consumer)
      Like emitter(Consumer, BackPressureStrategy) with the BackPressureStrategy.BUFFER strategy.
      <T> Multi<T> emitter​(java.util.function.Consumer<MultiEmitter<? super T>> consumer, int bufferSize)
      Like emitter(Consumer) with the BackPressureStrategy.BUFFER strategy and the given buffer size.
      <T> Multi<T> emitter​(java.util.function.Consumer<MultiEmitter<? super T>> consumer, BackPressureStrategy strategy)
      Creates a Multi deferring the logic to the given consumer.
      <T> Multi<T> empty()
      Creates a Multi that fires the completion event without having emitted any items.
      <T> Multi<T> failure​(java.lang.Throwable failure)
      Creates a Multi that emits a failure event immediately after being subscribed to.
      <T> Multi<T> failure​(java.util.function.Supplier<java.lang.Throwable> supplier)
      Creates a Multi that emits a failure event produced using the passed supplier immediately after being subscribed to.
      <S,​T>
      Multi<T>      		 generator​(java.util.function.Supplier<S> initialStateSupplier, java.util.function.BiFunction<S,​GeneratorEmitter<? super T>,​S> generator)
      Creates a Multi from on some initial state and a generator function.
      <T> Multi<T> item​(java.util.function.Supplier<? extends T> supplier)
      Creates a new Multi that emits an item immediately after being subscribed to with the specified single (potentially null) value.
      <T> Multi<T> item​(T item)
      Creates a new Multi that emits an item immediately after being subscribed to with the specified single item.
      <T> Multi<T> items​(java.util.function.Supplier<? extends java.util.stream.Stream<? extends T>> supplier)
      Creates a new Multi that emits the items immediately after being subscribed to.
      <T> Multi<T> items​(java.util.stream.Stream<T> items)
      Creates a new Multi that emits the items from the passed Stream individually after being subscribed to (according to the subscriber's request).
      <T> Multi<T> items​(T... items)
      Creates a new Multi that emits the items individually after being subscribed to (according to the subscriber's request).
      <T> Multi<T> iterable​(java.lang.Iterable<T> iterable)
      Creates a new Multi that emits the items individually after being subscribed to (according to the subscriber's request).
      <T> Multi<T> nothing()
      Creates a Multi that will never fire any events.
      <T> Multi<T> optional​(java.util.function.Supplier<java.util.Optional<T>> supplier)
      Creates a new Multi that emits an item immediately after being subscribed to with the value contained in the optional supplied by supplier.
      <T> Multi<T> optional​(java.util.Optional<T> optional)
      Creates a new Multi that emits an item immediately after being subscribed to with the value contained in the given optional if Optional.isPresent() or empty otherwise.
      <T> Multi<T> publisher​(org.reactivestreams.Publisher<T> publisher)
      Creates a Multi from the passed Publisher.
      Multi<java.lang.Integer> range​(int startInclusive, int endExclusive)
      Creates a Multi emitting the sequence of integer from startInclusive to endExclusive.
      <R,​I>
      MultiResource<R,​I>      		 resource​(java.util.function.Supplier<? extends R> resourceSupplier, java.util.function.Function<? super R,​? extends org.reactivestreams.Publisher<I>> streamSupplier)
      Creates a Multi from a resource, generated by a supplier function called for each individual Subscriber, while streaming the items from a Publisher/Multi created from the resource.
      <R,​I>
      MultiResourceUni<R,​I>      		 resourceFromUni​(java.util.function.Supplier<Uni<R>> resourceSupplier, java.util.function.Function<? super R,​? extends org.reactivestreams.Publisher<I>> streamSupplier)
      Creates a Multi from a resource, generated by a supplier function called for each individual Subscriber, while streaming the items from a Publisher/Multi created from the resource.
      <T> Multi<T> safePublisher​(org.reactivestreams.Publisher<T> publisher)
      Creates a Multi from the passed Publisher.
      MultiTimePeriod ticks()
      Creates a Multi that emits long items (ticks) starting with 0 and incrementing at specified time intervals.
      <T> Multi<T> uni​(Uni<T> uni)
      Creates an never of Multi from the given Uni.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

    • Method Detail

      • converter

        @CheckReturnValue
public <I,​T> Multi<T> converter​(io.smallrye.mutiny.converters.MultiConverter<I,​T> converter,
                                      I instance)
        Creates a new Multi from the passed instance with the passed converter.
        Type Parameters:
        I - the type being converted from
        T - the type for the Multi
        Parameters:
        converter - performs the type conversion
        instance - instance to convert from
        Returns:
        the created Multi

      • completionStage

        @CheckReturnValue
public <T> Multi<T> completionStage​(java.util.concurrent.CompletionStage<? extends T> stage)
        Creates a Multi from the given CompletionStage or CompletableFuture. The produced Multi emits the item of the passed CompletionStage and then fires the completion event. If the CompletionStage never completes (or fails), the produced Multi would not emit any item or failure events.

        Cancelling the subscription on the produced Multi 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 Multi 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 completion stage redeems null, it fires the completion event without any item.

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

      • completionStage

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

        The produced Multi emits the item of the passed CompletionStage followed by the completion event. If the CompletionStage never completes (or failed), the produced Multi would not emit an item or a failure.

        Cancelling the subscription on the produced Multi 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 Multi sends the item or failure immediately after subscription. In the case of item, the event is followed by the completion event. If the produced stage is not yet completed, the subscriber's callbacks are called on the thread used by the passed CompletionStage.

        If the produced completion stage redeems null, it fires the completion event without any 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 Multi

      • safePublisher

        @CheckReturnValue
public <T> Multi<T> safePublisher​(org.reactivestreams.Publisher<T> publisher)
        Creates a Multi from the passed Publisher.

        It is assumed that the Publisher is fully compliant with the Reactive Streams protocol and passes the TCK. If this is not the case use publisher(Publisher) instead.

        When a subscriber subscribes to the produced Multi, it subscribes to the Publisher and delegate the requests. Note that each Multi's subscriber would produce a new subscription.

        If the Multi'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 Multi
        See Also:
        publisher(Publisher)

      • publisher

        @CheckReturnValue
public <T> Multi<T> publisher​(org.reactivestreams.Publisher<T> publisher)
        Creates a Multi from the passed Publisher.

        The Publisher is not assumed to be fully compliant with the Reactive Streams TCK, hence it is wrapped around a subscriber that enforces the Reactive Streams protocol. If you know the Publisher is safe then you should use safePublisher(Publisher) instead.

        When a subscriber subscribes to the produced Multi, it subscribes to the Publisher and delegate the requests. Note that each Multi's subscriber would produce a new subscription.

        If the Multi'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 Multi
        See Also:
        safePublisher(Publisher)

      • uni

        @CheckReturnValue
public <T> Multi<T> uni​(Uni<T> uni)
        Creates an never of Multi from the given Uni.

        When a subscriber subscribes to the returned Multi and request an item, it subscribes to the given Uni and the events from this Uni are propagated to the Multi:

        • if the Uni emits a non-null item - this item is propagated to the Multi and followed with the completion event
        • if the Uni emits a null item - the Multi fires the completion event
        • if the Uni emits a failure, this failure event is propagated by the Multi

        It's important to note that the subscription to the Uni happens when the subscriber to the produced Multi requests values, and not at subscription time.

        Type Parameters:
        T - the type of item emitted by the resulting Multi / passed Uni
        Parameters:
        uni - the uni, must not be null
        Returns:
        the produced Multi, never null

      • item

        @CheckReturnValue
public <T> Multi<T> item​(java.util.function.Supplier<? extends T> supplier)
        Creates a new Multi that emits an item immediately after being subscribed to with the specified single (potentially null) value. The value is retrieved lazily at subscription time, using the passed Supplier. Unlike deferred(Supplier), the supplier produces an item and not a Multi.

        If the supplier produces null, the produced Multi fires the completion event. If the supplier produces a non-null item, the produced Multi fires an item event followed with the completion event. If the supplier throws an exception, a failure event with the exception is fired.

        Type Parameters:
        T - the type of item emitted by the produced Multi
        Parameters:
        supplier - the item supplier, must not be null, can produce null
        Returns:
        the new Multi

      • items

        @CheckReturnValue
public <T> Multi<T> items​(java.util.function.Supplier<? extends java.util.stream.Stream<? extends T>> supplier)
        Creates a new Multi that emits the items immediately after being subscribed to. The individual items come from the Stream supplied by the given Supplier. This supplier is called at subscription time.

        If the supplier produces null, the produced Multi fires a failure event. If the supplier produces an empty stream, the produced Multi fires a completion event. For each item from the supplied stream, an item event is fired. When all the items have been emitted, the completion event is fired. If the supplier throws an exception, a failure event with the exception is fired. The stream is consumed sequentially.

        Type Parameters:
        T - the type of item emitted by the produced Multi
        Parameters:
        supplier - the item supplier, must not be null, must not produce null
        Returns:
        the new Multi

      • item

        @CheckReturnValue
public <T> Multi<T> item​(T item)
        Creates a new Multi that emits an item immediately after being subscribed to with the specified single item. If item is null the completion event is fired immediately making the resulting Multi empty. If item is non-null, the item event is fired immediately followed with the completion event.
        Type Parameters:
        T - the type of item emitted by the produced Multi
        Parameters:
        item - the item, can be null which would create an empty Multi
        Returns:
        the new Multi

      • items

        @SafeVarargs
@CheckReturnValue
public final <T> Multi<T> items​(T... items)
        Creates a new Multi that emits the items individually after being subscribed to (according to the subscriber's request).

        If items is null, an IllegalArgumentException is thrown at call time. If one of the item from items is null, a failure event is fired (with an IllegalArgumentException). When all the items have been emitted, the completion event is fired.

        Type Parameters:
        T - the type of item emitted by the produced Multi
        Parameters:
        items - the items, must not be null, must not contain null
        Returns:
        the new Multi

      • iterable

        @CheckReturnValue
public <T> Multi<T> iterable​(java.lang.Iterable<T> iterable)
        Creates a new Multi that emits the items individually after being subscribed to (according to the subscriber's request).

        If iterable is null, an IllegalArgumentException is thrown at call time. If one of the item from iterable is null, a failure event is fired (with an IllegalArgumentException). When all the items have been emitted, the completion event is fired.

        Type Parameters:
        T - the type of item emitted by the produced Multi
        Parameters:
        iterable - the iterable of items, must not be null, must not contain null
        Returns:
        the new Multi

      • items

        @CheckReturnValue
public <T> Multi<T> items​(java.util.stream.Stream<T> items)
        Creates a new Multi that emits the items from the passed Stream individually after being subscribed to (according to the subscriber's request).

        If items is null, an IllegalArgumentException is thrown at call time. If one of the item from the stream is null, a failure event is fired (with an IllegalArgumentException). When all the items have been emitted, the completion event is fired. The stream is consumed sequentially.

        Type Parameters:
        T - the type of item emitted by the produced Multi
        Parameters:
        items - the items, must not be null, must not contain null
        Returns:
        the new Multi

      • optional

        @CheckReturnValue
public <T> Multi<T> optional​(java.util.Optional<T> optional)
        Creates a new Multi that emits an item immediately after being subscribed to with the value contained in the given optional if Optional.isPresent() or empty otherwise.
        Type Parameters:
        T - the type of the produced item
        Parameters:
        optional - the optional, must not be null, an empty optional produces an empty Multi.
        Returns:
        the new Multi

      • optional

        @CheckReturnValue
public <T> Multi<T> optional​(java.util.function.Supplier<java.util.Optional<T>> supplier)
        Creates a new Multi that emits an item immediately after being subscribed to with the value contained in the optional supplied by supplier.

        If the optional is empty, an empty Multi is produced. Otherwise the contained value is emitted as item, followed with the completion event. 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 Multi

      • emitter

        @CheckReturnValue
public <T> Multi<T> emitter​(java.util.function.Consumer<MultiEmitter<? super T>> consumer,
                            int bufferSize)
        Like emitter(Consumer) with the BackPressureStrategy.BUFFER strategy and the given buffer size.

        Note that to create hot streams, you should use a BroadcastProcessor.

        If the buffer is full, a BufferOverflowException in propagated downstream.

        Type Parameters:
        T - the type of item emitted by the produced Multi
        Parameters:
        consumer - the consumer receiving the emitter, must not be null
        bufferSize - the buffer size, must be strictly positive
        Returns:
        the produced Multi

      • emitter

        @CheckReturnValue
public <T> Multi<T> emitter​(java.util.function.Consumer<MultiEmitter<? super T>> consumer,
                            BackPressureStrategy strategy)
        Creates a Multi deferring the logic to the given consumer. The consumer can be used with callback-based APIs to fire items (non-null), failure or completion events.

        Emitting null value is not supported. Emitting values after having fired a failure or the completion event is a no-op. So subsequent item events are dropped.

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

        If the consumer throws an exception, a failure event with the exception is fired.

        Note that to create hot streams, you should use a BroadcastProcessor.

        Type Parameters:
        T - the type of items emitted by the emitter. Must not be null
        Parameters:
        consumer - callback receiving the MultiEmitter and events downstream. The callback is called for each subscriber (at subscription time). Must not be null
        strategy - the back pressure strategy to apply when the downstream subscriber cannot keep up with the items emitted by the emitter.
        Returns:
        the produced Multi

      • deferred

        @CheckReturnValue
public <T> Multi<T> deferred​(java.util.function.Supplier<Multi<? extends T>> supplier)
        Creates a Multi that supplies an Multi to subscribe to for each Subscriber. The supplier is called at subscription time.

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

        Unlike item(Supplier), the supplier produces an Multi (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 Multi

      • context

        @Experimental("Context support is a new experimental API introduced in Mutiny 1.3.0")
@CheckReturnValue
public <T> Multi<T> context​(java.util.function.Function<Context,​Multi<? extends T>> mapper)
        Creates a Multi 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 Multi

      • failure

        @CheckReturnValue
public <T> Multi<T> failure​(java.lang.Throwable failure)
        Creates a Multi that emits a failure event immediately after being subscribed to.
        Type Parameters:
        T - the virtual type of item used by the Multi, must be explicitly set as in Multi.<String>failed(exception);
        Parameters:
        failure - the failure to be fired, must not be null
        Returns:
        the produced Multi

      • failure

        @CheckReturnValue
public <T> Multi<T> failure​(java.util.function.Supplier<java.lang.Throwable> supplier)
        Creates a Multi 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 never 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 Multi, must be explicitly set as in Multi.<String>failed(exception);
        Parameters:
        supplier - the supplier producing the failure, must not be null, must not produce null
        Returns:
        the produced Multi

      • nothing

        @CheckReturnValue
public <T> Multi<T> nothing()
        Creates a Multi that will never fire any events.
        Type Parameters:
        T - the virtual type of item
        Returns:
        a never emitting Multi

      • empty

        @CheckReturnValue
public <T> Multi<T> empty()
        Creates a Multi that fires the completion event without having emitted any items. An empty Multi does not fires a failure event either.
        Type Parameters:
        T - the virtual type of item
        Returns:
        an empty Multi

      • ticks

        @CheckReturnValue
public MultiTimePeriod ticks()
        Creates a Multi that emits long items (ticks) starting with 0 and incrementing at specified time intervals.

        The timer starts at the first request. Once this request is received, the produced stream is a hot stream.

        Be aware that if the subscriber does not request enough items in time, a back pressure failure is fired. The produced Multi never completes until cancellation by the subscriber.

        The callbacks are invoked on the executor passed in MultiTimePeriod.onExecutor(ScheduledExecutorService).

        Returns:
        the object to configure the time period (initial delay, executor, interval)

      • range

        @CheckReturnValue
public Multi<java.lang.Integer> range​(int startInclusive,
                                      int endExclusive)
        Creates a Multi emitting the sequence of integer from startInclusive to endExclusive. Once all the integers have been emitted, the completion event is fired.
        Parameters:
        startInclusive - the start integer (inclusive)
        endExclusive - the end integer (exclusive)
        Returns:
        the Multi emitting the items

      • resource

        @CheckReturnValue
public <R,​I> MultiResource<R,​I> resource​(java.util.function.Supplier<? extends R> resourceSupplier,
                                                     java.util.function.Function<? super R,​? extends org.reactivestreams.Publisher<I>> streamSupplier)
        Creates a Multi from a resource, generated by a supplier function called for each individual Subscriber, while streaming the items from a Publisher/Multi created from the resource.

        This method gets a resource and creates a Publisher from this resource (by calling the streamSupplier function). The subscriber receives the items from this Publisher. When the stream completes, fails or when the subscriber cancels the subscription, a finalizer is called to close the resource. This cleanup process can be either synchronous and asynchronous, as well as distinct for each type of event.

        This method can be seen as a reactive version of the "try/finally" construct.

        Type Parameters:
        R - the type of the resource.
        I - the type of items emitted by the stream produced by the streamSupplier.
        Parameters:
        resourceSupplier - a supplier called for each subscriber to generate the resource, must not be null.
        streamSupplier - a function returning the stream for the given resource instance, must not be null.
        Returns:
        an object to configure the finalizers.

      • resourceFromUni

        @CheckReturnValue
public <R,​I> MultiResourceUni<R,​I> resourceFromUni​(java.util.function.Supplier<Uni<R>> resourceSupplier,
                                                               java.util.function.Function<? super R,​? extends org.reactivestreams.Publisher<I>> streamSupplier)
        Creates a Multi from a resource, generated by a supplier function called for each individual Subscriber, while streaming the items from a Publisher/Multi created from the resource.

        Unlike resource(Supplier, Function), the Supplier produces a Uni. So, the actual resource can be resolved asynchronously.

        This method gets a resource and creates a Publisher from this resource (by calling the streamSupplier function once the Uni emits the resource instance). The subscriber receives the items from this Publisher. When the stream completes, fails or when the subscriber cancels the subscription, a finalizer is called to close the resource. This cleanup process can be either synchronous and asynchronous, as well as distinct for each type of event.

        If the Uni produced by the resourceSupplier emits a failure, the failure is propagated downstream. If the Uni produced by the resourceSupplier does not emit an item before downstream cancellation, the resource creation is cancelled.

        This method can be seen as a reactive version of the "try/finally" construct.

        Type Parameters:
        R - the type of the resource.
        I - the type of items emitted by the stream produced by the streamSupplier.
        Parameters:
        resourceSupplier - a supplier called for each subscriber to generate the resource, must not be null. The supplier produces a Uni emitting the resource.
        streamSupplier - a function returning the stream for the given resource instance, must not be null.
        Returns:
        an object to configure the finalizers.

      • generator

        @CheckReturnValue
public <S,​T> Multi<T> generator​(java.util.function.Supplier<S> initialStateSupplier,
                                      java.util.function.BiFunction<S,​GeneratorEmitter<? super T>,​S> generator)
        Creates a Multi from on some initial state and a generator function.

        The generator function accepts the current state and a GeneratorEmitter to emit items, failures and completion events. The function shall return the new state which will be used for the next item generation, if any. The state can be null, but emitted items cannot be null. A failure is propagated downstream if the function throws an exception.

        Items are being generated based on subscription requests. Requesting Long.MAX_VALUE items can possibly make for an infinite stream unless the generator function calls GeneratorEmitter.complete() at some point.

        Type Parameters:
        S - the state type
        T - the items type
        Parameters:
        initialStateSupplier - a supplier for the initial state, must not be null but can supply null
        generator - the generator function, returns the new state for the next item generation
        Returns:
        a new Multi