Module io.helidon.common.reactive

Package io.helidon.common.reactive

Interface Single<T>

Type Parameters:

T - item type

All Superinterfaces:

Flow.Publisher<T>, Subscribable<T>

public interface Single<T>
extends Subscribable<T>

Single item publisher utility.

Method Summary

Modifier and Type	Method	Description
default Single<T>	defaultIfEmpty(T defaultItem)	Signals the default item if the upstream is empty.
static <T> Single<T>	defer(Supplier<? extends Single<? extends T>> supplier)	Call the given supplier function for each individual downstream Subscriber to return a Flow.Publisher to subscribe to.
static <T> Single<T>	empty()	Get a Single instance that completes immediately.
static <T> Single<T>	error(Throwable error)	Create a Single instance that reports the given given exception to its subscriber(s).
default <U> Multi<U>	flatMap(Function<? super T,? extends Flow.Publisher<? extends U>> mapper)	Map this Single instance to a publisher using the given Mapper.
default <U> Multi<U>	flatMapIterable(Function<? super T,? extends Iterable<? extends U>> mapper)	Maps the single upstream value into an Iterable and relays its items to the downstream.
default <U> Single<U>	flatMapSingle(Function<T,Single<U>> mapper)	Map this Single instance to a Single using the given Mapper.
static <T> Single<T>	from(Flow.Publisher<T> source)	Create a Single instance that publishes the first and only item received from the given publisher.
default T	get()	Short-hand for toFuture().toCompletableFuture().get().
default T	get(long timeout, TimeUnit unit)	Short-hand for toFuture().toCompletableFuture().get().
static <T> Single<T>	just(T item)	Create a Single instance that publishes the given item to its subscriber(s).
default <U> Single<U>	map(Mapper<T,U> mapper)	Map this Single instance to a new Single of another type using the given Mapper.
default <U> Multi<U>	mapMany(Mapper<T,Flow.Publisher<U>> mapper)	Deprecated. Use flatMap(java.util.function.Function<? super T, ? extends java.util.concurrent.Flow.Publisher<? extends U>>)
static <T> Single<T>	never()	Get a Single instance that never completes.
default Single<T>	onComplete(Runnable onTerminate)	Executes given Runnable when onComplete signal is received.
default Single<T>	onError(Consumer<Throwable> onErrorConsumer)	Executes given Runnable when onError signal is received.
default Single<T>	onErrorResume(Function<? super Throwable,? extends T> onError)	Function providing one item to be submitted as onNext in case of onError signal is received.
default Single<T>	onErrorResumeWith(Function<? super Throwable,? extends Single<? extends T>> onError)	Resume stream from supplied publisher if onError signal is intercepted.
default Single<T>	onTerminate(Runnable onTerminate)	Executes given Runnable when any of signals onComplete, onCancel or onError is received.
default Single<T>	peek(Consumer<T> consumer)	Invoke provided consumer for the item in stream.
default Single<T>	switchIfEmpty(Single<T> other)	Switch to the other Single if the upstream is empty.
default <U> Single<T>	takeUntil(Flow.Publisher<U> other)	Relay upstream items until the other source signals an item or completes.
static Single<Long>	timer(long time, TimeUnit unit, ScheduledExecutorService executor)	Signal 0L and complete the sequence after the given time elapsed.
default CompletionStage<Optional<T>>	toOptionalStage()	Exposes this Single instance as a CompletionStage with Optional<T> return type of the asynchronous operation.
default CompletionStage<T>	toStage()	Exposes this Single instance as a CompletionStage.

Methods inherited from interface java.util.concurrent.Flow.Publisher

subscribe

Methods inherited from interface io.helidon.common.reactive.Subscribable

subscribe, subscribe, subscribe, subscribe

Method Detail

defer

static <T> Single<T> defer(Supplier<? extends Single<? extends T>> supplier)

Call the given supplier function for each individual downstream Subscriber to return a Flow.Publisher to subscribe to.

Type Parameters:

T - the element type of the sequence

Parameters:

supplier - the callback to return a Flow.Publisher for each Subscriber

Returns:

Multi

Throws:

NullPointerException - if supplier is null

map

default <U> Single<U> map(Mapper<T,U> mapper)

Map this Single instance to a new Single of another type using the given Mapper.

Type Parameters:

U - mapped item type

Parameters:

mapper - mapper

Returns:

Single

Throws:

NullPointerException - if mapper is null

defaultIfEmpty

default Single<T> defaultIfEmpty(T defaultItem)

Signals the default item if the upstream is empty.

Parameters:

defaultItem - the item to signal if the upstream is empty

Returns:

Single

Throws:

NullPointerException - if defaultItem is null

switchIfEmpty

default Single<T> switchIfEmpty(Single<T> other)

Switch to the other Single if the upstream is empty.

Parameters:

other - the Single to switch to if the upstream is empty.

Returns:

Single

Throws:

NullPointerException - if other is null

mapMany

@Deprecated
default <U> Multi<U> mapMany(Mapper<T,Flow.Publisher<U>> mapper)

Deprecated.

Use flatMap(java.util.function.Function<? super T, ? extends java.util.concurrent.Flow.Publisher<? extends U>>)

Map this Single instance to a publisher using the given Mapper.

Type Parameters:

U - mapped items type

Parameters:

mapper - mapper

Returns:

Publisher

Throws:

NullPointerException - if mapper is null

flatMap

default <U> Multi<U> flatMap(Function<? super T,? extends Flow.Publisher<? extends U>> mapper)

Map this Single instance to a publisher using the given Mapper.

Type Parameters:

U - mapped items type

Parameters:

mapper - mapper

Returns:

Publisher

Throws:

NullPointerException - if mapper is null

flatMapSingle

default <U> Single<U> flatMapSingle(Function<T,Single<U>> mapper)

Map this Single instance to a Single using the given Mapper.

Type Parameters:

U - mapped items type

Parameters:

mapper - mapper

Returns:

Single

Throws:

NullPointerException - if mapper is null

flatMapIterable

default <U> Multi<U> flatMapIterable(Function<? super T,? extends Iterable<? extends U>> mapper)

Maps the single upstream value into an Iterable and relays its items to the downstream.

Type Parameters:

U - the result type

Parameters:

mapper - the function that receives the single upstream value and should return an Iterable instance

Returns:

Multi

Throws:

NullPointerException - if mapper is null

toStage

default CompletionStage<T> toStage()

Exposes this Single instance as a CompletionStage. Note that if this Single completes without a value, the resulting CompletionStage will be completed exceptionally with an IllegalStateException

Returns:

CompletionStage

toOptionalStage

default CompletionStage<Optional<T>> toOptionalStage()

Exposes this Single instance as a CompletionStage with Optional<T> return type of the asynchronous operation. Note that if this Single completes without a value, the resulting CompletionStage will be completed exceptionally with an IllegalStateException

Returns:

CompletionStage

get

default T get()
       throws InterruptedException,
              ExecutionException

Short-hand for toFuture().toCompletableFuture().get().

Returns:

T

Throws:

InterruptedException - if the current thread was interrupted while waiting

ExecutionException - if the future completed exceptionally

get

default T get(long timeout,
              TimeUnit unit)
       throws InterruptedException,
              ExecutionException,
              TimeoutException

Short-hand for toFuture().toCompletableFuture().get().

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

T

Throws:

InterruptedException - if the current thread was interrupted while waiting

ExecutionException - if the future completed exceptionally

TimeoutException - if the wait timed out

from

static <T> Single<T> from(Flow.Publisher<T> source)

Create a Single instance that publishes the first and only item received from the given publisher. Note that if the publisher publishes more than one item, the resulting Single will hold an error. Use Multi.first() instead in order to get the first item of a publisher that may publish more than one item.

Type Parameters:

T - item type

Parameters:

source - source publisher

Returns:

Single

Throws:

NullPointerException - if source is null

just

static <T> Single<T> just(T item)

Create a Single instance that publishes the given item to its subscriber(s).

Type Parameters:

T - item type

Parameters:

item - item to publish

Returns:

Single

Throws:

NullPointerException - if item is null

error

static <T> Single<T> error(Throwable error)

Create a Single instance that reports the given given exception to its subscriber(s). The exception is reported by invoking Flow.Subscriber.onError(java.lang.Throwable) when Flow.Publisher.subscribe(Subscriber) is called.

Type Parameters:

T - item type

Parameters:

error - exception to hold

Returns:

Single

Throws:

NullPointerException - if error is null

empty

static <T> Single<T> empty()

Get a Single instance that completes immediately.

Type Parameters:

T - item type

Returns:

Single

never

static <T> Single<T> never()

Get a Single instance that never completes.

Type Parameters:

T - item type

Returns:

Single

timer

static Single<Long> timer(long time,
                          TimeUnit unit,
                          ScheduledExecutorService executor)

Signal 0L and complete the sequence after the given time elapsed.

Parameters:

time - the time to wait before signaling 0L and completion

unit - the unit of time

executor - the executor to run the waiting on

Returns:

Single

Throws:

NullPointerException - if unit or executor is null

takeUntil

default <U> Single<T> takeUntil(Flow.Publisher<U> other)

Relay upstream items until the other source signals an item or completes.

Type Parameters:

U - the element type of the other sequence

Parameters:

other - the other sequence to signal the end of the main sequence

Returns:

Single

Throws:

NullPointerException - if other is null

onTerminate

default Single<T> onTerminate(Runnable onTerminate)

Executes given Runnable when any of signals onComplete, onCancel or onError is received.

Parameters:

onTerminate - Runnable to be executed.

Returns:

Single

onComplete

default Single<T> onComplete(Runnable onTerminate)

Executes given Runnable when onComplete signal is received.

Parameters:

onTerminate - Runnable to be executed.

Returns:

Single

onError

default Single<T> onError(Consumer<Throwable> onErrorConsumer)

Executes given Runnable when onError signal is received.

Parameters:

onErrorConsumer - Runnable to be executed.

Returns:

Single

peek

default Single<T> peek(Consumer<T> consumer)

Invoke provided consumer for the item in stream.

Parameters:

consumer - consumer to be invoked

Returns:

Single

onErrorResume

default Single<T> onErrorResume(Function<? super Throwable,? extends T> onError)

Function providing one item to be submitted as onNext in case of onError signal is received.

Parameters:

onError - Function receiving Throwable as argument and producing one item to resume stream with.

Returns:

Single

onErrorResumeWith

default Single<T> onErrorResumeWith(Function<? super Throwable,? extends Single<? extends T>> onError)

Resume stream from supplied publisher if onError signal is intercepted.

Parameters:

onError - supplier of new stream publisher

Returns:

Single