io.reactivex.rxjava3.subjects

Class SingleSubject<T>

java.lang.Object

io.reactivex.rxjava3.core.Single<T>

io.reactivex.rxjava3.subjects.SingleSubject<T>

Type Parameters:

T - the value type received and emitted

All Implemented Interfaces:

SingleObserver<T>, SingleSource<T>

public final class SingleSubject<T>
extends Single<T>
implements SingleObserver<T>

Represents a hot Single-like source and consumer of events similar to Subjects.

This subject does not have a public constructor by design; a new non-terminated instance of this SingleSubject can be created via the create() method.

Since the SingleSubject is conceptionally derived from the Processor type in the Reactive Streams specification, nulls are not allowed (Rule 2.13) as parameters to onSuccess(Object) and onError(Throwable). Such calls will result in a NullPointerException being thrown and the subject's state is not changed.

Since a SingleSubject is a Single, calling onSuccess or onError will move this SingleSubject into its terminal state atomically.

All methods are thread safe. Calling onSuccess(Object) multiple times has no effect. Calling onError(Throwable) multiple times relays the Throwable to the RxJavaPlugins.onError(Throwable) global error handler.

Even though SingleSubject implements the SingleObserver interface, calling onSubscribe is not required (Rule 2.12) if the subject is used as a standalone source. However, calling onSubscribe after the SingleSubject reached its terminal state will result in the given Disposable being disposed immediately.

This SingleSubject supports the standard state-peeking methods hasThrowable(), getThrowable() and hasObservers() as well as means to read any success item in a non-blocking and thread-safe manner via hasValue() and getValue().

The SingleSubject does not support clearing its cached onSuccess value.

Scheduler:

SingleSubject does not operate by default on a particular Scheduler and the SingleObservers get notified on the thread where the terminating onSuccess or onError methods were invoked.

Error handling:

When the onError(Throwable) is called, the SingleSubject enters into a terminal state and emits the same Throwable instance to the last set of SingleObservers. During this emission, if one or more SingleObservers dispose their respective Disposables, the Throwable is delivered to the global error handler via RxJavaPlugins.onError(Throwable) (multiple times if multiple SingleObservers cancel at once). If there were no SingleObservers subscribed to this SingleSubject when the onError() was called, the global error handler is not invoked.

Example usage:

 SingleSubject<Integer> subject1 = SingleSubject.create();
 
 TestObserver<Integer> to1 = subject1.test();
 
 // SingleSubjects are empty by default
 to1.assertEmpty();
 
 subject1.onSuccess(1);
 
 // onSuccess is a terminal event with SingleSubjects
 // TestObserver converts onSuccess into onNext + onComplete
 to1.assertResult(1);

 TestObserver<Integer> to2 = subject1.test();
 
 // late Observers receive the terminal signal (onSuccess) too
 to2.assertResult(1);
 

History: 2.0.5 - experimental

Since:

2.1

Method Summary

Modifier and Type	Method and Description
static <T> SingleSubject<T>	create() Creates a fresh SingleSubject.
Throwable	getThrowable() Returns the terminal error if this SingleSubject has been terminated with an error, null otherwise.
T	getValue() Returns the success value if this SingleSubject was terminated with a success value.
boolean	hasObservers() Returns true if this SingleSubject has observers.
boolean	hasThrowable() Returns true if this SingleSubject has been terminated with an error.
boolean	hasValue() Returns true if this SingleSubject was terminated with a success value.
void	onError(Throwable e) Notifies the SingleObserver that the Single has experienced an error condition.
void	onSubscribe(Disposable d) Provides the SingleObserver with the means of cancelling (disposing) the connection (channel) with the Single in both synchronous (from within onSubscribe(Disposable) itself) and asynchronous manner.
void	onSuccess(T value) Notifies the SingleObserver with a single item and that the Single has finished sending push-based notifications.
protected void	subscribeActual(SingleObserver<? super T> observer) Implement this method in subclasses to handle the incoming SingleObservers.

Methods inherited from class io.reactivex.rxjava3.core.Single

amb, ambArray, ambWith, blockingGet, cache, cast, compose, concat, concat, concat, concat, concat, concat, concat, concatArray, concatArrayEager, concatEager, concatEager, concatWith, contains, contains, create, defer, delay, delay, delay, delay, delaySubscription, delaySubscription, delaySubscription, delaySubscription, delaySubscription, delaySubscription, dematerialize, doAfterSuccess, doAfterTerminate, doFinally, doOnDispose, doOnError, doOnEvent, doOnSubscribe, doOnSuccess, doOnTerminate, equals, error, error, filter, flatMap, flatMapCompletable, flatMapMaybe, flatMapObservable, flatMapPublisher, flattenAsFlowable, flattenAsObservable, fromCallable, fromFuture, fromFuture, fromFuture, fromFuture, fromObservable, fromPublisher, fromSupplier, hide, ignoreElement, just, lift, map, materialize, merge, merge, merge, merge, merge, merge, mergeDelayError, mergeDelayError, mergeDelayError, mergeDelayError, mergeDelayError, mergeWith, never, observeOn, onErrorResumeNext, onErrorResumeWith, onErrorReturn, onErrorReturnItem, onTerminateDetach, repeat, repeat, repeatUntil, repeatWhen, retry, retry, retry, retry, retry, retryWhen, subscribe, subscribe, subscribe, subscribe, subscribe, subscribeOn, subscribeWith, takeUntil, takeUntil, takeUntil, test, test, timeout, timeout, timeout, timeout, timer, timer, to, toFlowable, toFuture, toMaybe, toObservable, unsafeCreate, unsubscribeOn, using, using, wrap, zip, zip, zip, zip, zip, zip, zip, zip, zip, zipArray, zipWith

Methods inherited from class java.lang.Object

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

Method Detail

create

@CheckReturnValue
 @NonNull
public static <T> SingleSubject<T> create()

Creates a fresh SingleSubject.

Type Parameters:

T - the value type received and emitted

Returns:

the new SingleSubject instance

onSubscribe

public void onSubscribe(@NonNull
                        Disposable d)

Description copied from interface: SingleObserver

Provides the SingleObserver with the means of cancelling (disposing) the connection (channel) with the Single in both synchronous (from within onSubscribe(Disposable) itself) and asynchronous manner.

Specified by:

onSubscribe in interface SingleObserver<T>

Parameters:

d - the Disposable instance whose Disposable.dispose() can be called anytime to cancel the connection

onSuccess

public void onSuccess(@NonNull
                      T value)

Description copied from interface: SingleObserver

Notifies the SingleObserver with a single item and that the Single has finished sending push-based notifications.

The Single will not call this method if it calls SingleObserver.onError(java.lang.Throwable).

Specified by:

onSuccess in interface SingleObserver<T>

Parameters:

value - the item emitted by the Single

onError

public void onError(@NonNull
                    Throwable e)

Description copied from interface: SingleObserver

Notifies the SingleObserver that the Single has experienced an error condition.

If the Single calls this method, it will not thereafter call SingleObserver.onSuccess(T).

Specified by:

onError in interface SingleObserver<T>

Parameters:

e - the exception encountered by the Single

subscribeActual

protected void subscribeActual(@NonNull
                               SingleObserver<? super T> observer)

Description copied from class: Single

Implement this method in subclasses to handle the incoming SingleObservers.

There is no need to call any of the plugin hooks on the current Single instance or the SingleObserver; all hooks and basic safeguards have been applied by Single.subscribe(SingleObserver) before this method gets called.

Specified by:

subscribeActual in class Single<T>

Parameters:

observer - the SingleObserver to handle, not null

getValue

@Nullable
public T getValue()

Returns the success value if this SingleSubject was terminated with a success value.

Returns:

the success value or null

hasValue

public boolean hasValue()

Returns true if this SingleSubject was terminated with a success value.

Returns:

true if this SingleSubject was terminated with a success value

getThrowable

@Nullable
public Throwable getThrowable()

Returns the terminal error if this SingleSubject has been terminated with an error, null otherwise.

Returns:

the terminal error or null if not terminated or not with an error

hasThrowable

public boolean hasThrowable()

Returns true if this SingleSubject has been terminated with an error.

Returns:

true if this SingleSubject has been terminated with an error

hasObservers

public boolean hasObservers()

Returns true if this SingleSubject has observers.

Returns:

true if this SingleSubject has observers