io.smallrye.mutiny.groups

Class MultiCreate

java.lang.Object

io.smallrye.mutiny.groups.MultiCreate

public class MultiCreate
extends Object

Group methods allowing to create Multi instances from various sources.

Field Summary

Fields

Modifier and Type	Field and Description
static MultiCreate	INSTANCE

Method Summary

Modifier and Type	Method and Description
<T> Multi<T>	completionStage(CompletionStage<? extends T> stage) Creates a Multi from the given CompletionStage or CompletableFuture.
<T> Multi<T>	completionStage(Supplier<? extends CompletionStage<? extends T>> supplier) Creates a Multi from the given CompletionStage or CompletableFuture.
<I,T> Multi<T>	converter(MultiConverter<I,T> converter, I instance) Creates a new Uni from the passed instance with the passed converter.
<T> Multi<T>	deferred(Supplier<? extends Multi<? extends T>> supplier) Creates a Multi that supplies an Multi to subscribe to for each Subscriber.
<T> Multi<T>	emitter(Consumer<MultiEmitter<? super T>> consumer) Like emitter(Consumer, BackPressureStrategy) with the BackPressureStrategy.BUFFER strategy.
<T> Multi<T>	emitter(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(Supplier<Throwable> supplier) Creates a Multi that emits a failure event produced using the passed supplier immediately after being subscribed to.
<T> Multi<T>	failure(Throwable failure) Creates a Multi that emits a failure event immediately after being subscribed to.
<T> Multi<T>	item(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(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(Supplier<? extends Stream<? extends T>> supplier) Creates a new Multi that emits the items immediately after being subscribed to.
<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(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(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>	optional(Supplier<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>	publisher(org.reactivestreams.Publisher<T> publisher) Creates a Multi from the passed Publisher.
Multi<Integer>	range(int startInclusive, int endExclusive) Creates a Multi emitting the sequence of integer from startInclusive to endExclusive.
<R,I> MultiResource<R,I>	resource(Supplier<? extends R> resourceSupplier, 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.
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

INSTANCE

public static final MultiCreate INSTANCE

Method Detail

converter

public <I,T> Multi<T> converter(MultiConverter<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> Multi<T> completionStage(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

public <T> Multi<T> completionStage(Supplier<? extends 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

publisher

public <T> Multi<T> publisher(org.reactivestreams.Publisher<T> publisher)

Creates a Multi from the passed Publisher.

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

uni

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

public <T> Multi<T> item(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

public <T> Multi<T> items(Supplier<? extends 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

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

public <T> Multi<T> iterable(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

public <T> Multi<T> items(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

public <T> Multi<T> optional(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

public <T> Multi<T> optional(Supplier<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

public <T> Multi<T> emitter(Consumer<MultiEmitter<? super T>> consumer)

Like emitter(Consumer, BackPressureStrategy) with the BackPressureStrategy.BUFFER strategy. Note that to create hot streams, you should use a BroadcastProcessor.

Type Parameters:

T - the type of item emitted by the produced Multi

Parameters:

consumer - the consumer receiving the emitter, must not be null

Returns:

the produced Multi

emitter

public <T> Multi<T> emitter(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

public <T> Multi<T> deferred(Supplier<? extends 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

failure

public <T> Multi<T> failure(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

public <T> Multi<T> failure(Supplier<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

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

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

public MultiTimePeriod ticks()

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

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

public Multi<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

public <R,I> MultiResource<R,I> resource(Supplier<? extends R> resourceSupplier,
                                         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.