Class SingleSubject<T>
- Type Parameters:
T
- the value type received and emitted
- All Implemented Interfaces:
SingleObserver<T>
,SingleSource<T>
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,
null
s 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 particularScheduler
and theSingleObserver
s get notified on the thread where the terminatingonSuccess
oronError
methods were invoked.- Error handling:
- When the
onError(Throwable)
is called, theSingleSubject
enters into a terminal state and emits the sameThrowable
instance to the last set ofSingleObserver
s. During this emission, if one or moreSingleObserver
s dispose their respectiveDisposable
s, theThrowable
is delivered to the global error handler viaRxJavaPlugins.onError(Throwable)
(multiple times if multipleSingleObserver
s cancel at once). If there were noSingleObserver
s subscribed to thisSingleSubject
when theonError()
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
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static final class
-
Field Summary
FieldsModifier and TypeFieldDescription(package private) static final SingleSubject.SingleDisposable[]
(package private) Throwable
(package private) final AtomicReference
<SingleSubject.SingleDisposable<T>[]> (package private) final AtomicBoolean
(package private) static final SingleSubject.SingleDisposable[]
(package private) T
-
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) boolean
add
(@NonNull SingleSubject.SingleDisposable<T> inner) static <T> @NonNull SingleSubject
<T> create()
Creates a fresh SingleSubject.Returns the terminal error if this SingleSubject has been terminated with an error, null otherwise.getValue()
Returns the success value if this SingleSubject was terminated with a success value.boolean
Returns true if this SingleSubject has observers.boolean
Returns true if this SingleSubject has been terminated with an error.boolean
hasValue()
Returns true if this SingleSubject was terminated with a success value.(package private) int
Returns the number of current observers.void
Notifies theSingleObserver
that theSingle
has experienced an error condition.void
Provides theSingleObserver
with the means of cancelling (disposing) the connection (channel) with the Single in both synchronous (from withinonSubscribe(Disposable)
itself) and asynchronous manner.void
Notifies theSingleObserver
with a single item and that theSingle
has finished sending push-based notifications.(package private) void
protected void
subscribeActual
(@NonNull SingleObserver<? super T> observer) Implement this method in subclasses to handle the incomingSingleObserver
s.Methods inherited from class io.reactivex.rxjava3.core.Single
amb, ambArray, ambWith, blockingGet, blockingSubscribe, blockingSubscribe, blockingSubscribe, blockingSubscribe, cache, cast, compose, concat, concat, concat, concat, concat, concat, concat, concatArray, concatArrayDelayError, concatArrayEager, concatArrayEagerDelayError, concatDelayError, concatDelayError, concatDelayError, concatEager, concatEager, concatEager, concatEager, concatEagerDelayError, concatEagerDelayError, concatEagerDelayError, concatEagerDelayError, concatMap, concatMapCompletable, concatMapMaybe, concatWith, contains, contains, create, defer, delay, delay, delay, delay, delaySubscription, delaySubscription, delaySubscription, delaySubscription, delaySubscription, delaySubscription, dematerialize, doAfterSuccess, doAfterTerminate, doFinally, doOnDispose, doOnError, doOnEvent, doOnLifecycle, doOnSubscribe, doOnSuccess, doOnTerminate, error, error, filter, flatMap, flatMap, flatMap, flatMapCompletable, flatMapMaybe, flatMapObservable, flatMapPublisher, flattenAsFlowable, flattenAsObservable, flattenStreamAsFlowable, flattenStreamAsObservable, fromCallable, fromCompletionStage, fromFuture, fromFuture, fromMaybe, fromMaybe, fromObservable, fromPublisher, fromSupplier, hide, ignoreElement, just, lift, map, mapOptional, materialize, merge, merge, merge, merge, merge, merge, mergeArray, mergeArrayDelayError, mergeDelayError, mergeDelayError, mergeDelayError, mergeDelayError, mergeDelayError, mergeWith, never, observeOn, ofType, onErrorComplete, onErrorComplete, onErrorResumeNext, onErrorResumeWith, onErrorReturn, onErrorReturnItem, onTerminateDetach, repeat, repeat, repeatUntil, repeatWhen, retry, retry, retry, retry, retry, retryUntil, retryWhen, safeSubscribe, sequenceEqual, startWith, startWith, startWith, startWith, startWith, subscribe, subscribe, subscribe, subscribe, subscribe, subscribe, subscribeOn, subscribeWith, switchOnNext, switchOnNextDelayError, takeUntil, takeUntil, takeUntil, test, test, timeInterval, timeInterval, timeInterval, timeInterval, timeout, timeout, timeout, timeout, timer, timer, timestamp, timestamp, timestamp, timestamp, to, toCompletionStage, toFlowable, toFuture, toMaybe, toObservable, unsafeCreate, unsubscribeOn, using, using, wrap, zip, zip, zip, zip, zip, zip, zip, zip, zip, zipArray, zipWith
-
Field Details
-
Constructor Details
-
SingleSubject
SingleSubject()
-
-
Method Details
-
create
Creates a fresh SingleSubject.- Type Parameters:
T
- the value type received and emitted- Returns:
- the new SingleSubject instance
-
onSubscribe
Description copied from interface:SingleObserver
Provides theSingleObserver
with the means of cancelling (disposing) the connection (channel) with the Single in both synchronous (from withinonSubscribe(Disposable)
itself) and asynchronous manner.- Specified by:
onSubscribe
in interfaceSingleObserver<T>
- Parameters:
d
- the Disposable instance whoseDisposable.dispose()
can be called anytime to cancel the connection
-
onSuccess
Description copied from interface:SingleObserver
Notifies theSingleObserver
with a single item and that theSingle
has finished sending push-based notifications.The
Single
will not call this method if it callsSingleObserver.onError(java.lang.Throwable)
.- Specified by:
onSuccess
in interfaceSingleObserver<T>
- Parameters:
value
- the item emitted by theSingle
-
onError
Description copied from interface:SingleObserver
Notifies theSingleObserver
that theSingle
has experienced an error condition.If the
Single
calls this method, it will not thereafter callSingleObserver.onSuccess(T)
.- Specified by:
onError
in interfaceSingleObserver<T>
- Parameters:
e
- the exception encountered by theSingle
-
subscribeActual
Description copied from class:Single
Implement this method in subclasses to handle the incomingSingleObserver
s.There is no need to call any of the plugin hooks on the current
Single
instance or theSingleObserver
; all hooks and basic safeguards have been applied bySingle.subscribe(SingleObserver)
before this method gets called.- Specified by:
subscribeActual
in classSingle<T>
- Parameters:
observer
- theSingleObserver
to handle, notnull
-
add
-
remove
-
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
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
-
observerCount
int observerCount()Returns the number of current observers.- Returns:
- the number of current observers
-