reactor.core.publisher

Interface Sinks.Empty<T>

Type Parameters:

T - a generic type for the Mono view, allowing composition

All Superinterfaces:

Scannable

All Known Subinterfaces:

Sinks.One<T>

Enclosing class:

Sinks

public static interface Sinks.Empty<T>
extends Scannable

A base interface for standalone Sinks with complete-or-fail semantics.

The sink can be exposed to consuming code as a Mono via its asMono() view.

Author:

Simon Baslé, Stephane Maldini

Nested Class Summary

Nested classes/interfaces inherited from interface reactor.core.Scannable

Scannable.Attr<T>

Field Summary

Fields inherited from interface reactor.core.Scannable

OPERATOR_NAME_UNRELATED_WORDS_PATTERN

Method Summary

Modifier and Type	Method and Description
Mono<T>	asMono() Return a Mono view of this sink.
int	currentSubscriberCount() Get how many Subscribers are currently subscribed to the sink.
void	emitEmpty(Sinks.EmitFailureHandler failureHandler) A simplified attempt at completing via the tryEmitEmpty() API, generating an onComplete signal.
void	emitError(Throwable error, Sinks.EmitFailureHandler failureHandler) A simplified attempt at failing the sequence via the tryEmitError(Throwable) API, generating an onError signal.
Sinks.EmitResult	tryEmitEmpty() Try to complete the Mono without a value, generating only an onComplete signal.
Sinks.EmitResult	tryEmitError(Throwable error) Try to fail the Mono, generating only an onError signal.

Methods inherited from interface reactor.core.Scannable

actuals, from, inners, isScanAvailable, name, parents, scan, scanOrDefault, scanUnsafe, stepName, steps, tags, tagsDeduplicated

Method Detail

tryEmitEmpty

Sinks.EmitResult tryEmitEmpty()

Try to complete the Mono without a value, generating only an onComplete signal. The result of the attempt is represented as an Sinks.EmitResult, which possibly indicates error cases.

See the list of failure Sinks.EmitResult in #emitEmpty(EmitFailureHandler) javadoc for an example of how each of these can be dealt with, to decide if the emit API would be a good enough fit instead.

Returns:

an Sinks.EmitResult, which should be checked to distinguish different possible failures

See Also:

emitEmpty(Sinks.EmitFailureHandler), Subscriber.onComplete()

tryEmitError

Sinks.EmitResult tryEmitError(Throwable error)

Try to fail the Mono, generating only an onError signal. The result of the attempt is represented as an Sinks.EmitResult, which possibly indicates error cases.

See the list of failure Sinks.EmitResult in #emitError(Throwable, EmitFailureHandler) javadoc for an example of how each of these can be dealt with, to decide if the emit API would be a good enough fit instead.

Parameters:

error - the exception to signal, not null

Returns:

an Sinks.EmitResult, which should be checked to distinguish different possible failures

See Also:

emitError(Throwable, Sinks.EmitFailureHandler), Subscriber.onError(Throwable)

emitEmpty

void emitEmpty(Sinks.EmitFailureHandler failureHandler)

A simplified attempt at completing via the tryEmitEmpty() API, generating an onComplete signal. If the result of the attempt is not a success, implementations SHOULD retry the tryEmitEmpty() call IF the provided Sinks.EmitFailureHandler returns true. Otherwise, failures are dealt with in a predefined way that might depend on the actual sink implementation (see below for the vanilla reactor-core behavior).

Generally, tryEmitEmpty() is preferable since it allows a custom handling of error cases, although this implies checking the returned Sinks.EmitResult and correctly acting on it. This API is intended as a good default for convenience.

When the Sinks.EmitResult is not a success, vanilla reactor-core operators have the following behavior:

• Sinks.EmitResult.FAIL_OVERFLOW: irrelevant as onComplete is not driven by backpressure.
• Sinks.EmitResult.FAIL_ZERO_SUBSCRIBER: the completion can be ignored since nobody is listening. Note that most vanilla reactor sinks never trigger this result for onComplete, replaying the terminal signal to later subscribers instead (to the exception of Sinks.UnicastSpec.onBackpressureError()).
• Sinks.EmitResult.FAIL_CANCELLED: the completion can be ignored since nobody is interested.
• Sinks.EmitResult.FAIL_TERMINATED: the extra completion is basically ignored since there was a previous termination signal, but there is nothing interesting to log.
• Sinks.EmitResult.FAIL_NON_SERIALIZED: throw an Sinks.EmissionException mentioning RS spec rule 1.3. Note that Sinks.unsafe() never trigger this result. It would be possible for an Sinks.EmitFailureHandler to busy-loop and optimistically wait for the contention to disappear to avoid this case in safe sinks...

Might throw an unchecked exception as a last resort (eg. in case of a fatal error downstream which cannot be propagated to any asynchronous handler, a bubbling exception, a Sinks.EmitResult.FAIL_NON_SERIALIZED as described above, ...).

Parameters:

failureHandler - the failure handler that allows retrying failed Sinks.EmitResult.

Throws:

Sinks.EmissionException - on non-serialized access

See Also:

tryEmitEmpty(), Subscriber.onComplete()

emitError

void emitError(Throwable error,
               Sinks.EmitFailureHandler failureHandler)

A simplified attempt at failing the sequence via the tryEmitError(Throwable) API, generating an onError signal. If the result of the attempt is not a success, implementations SHOULD retry the tryEmitError(Throwable) call IF the provided Sinks.EmitFailureHandler returns true. Otherwise, failures are dealt with in a predefined way that might depend on the actual sink implementation (see below for the vanilla reactor-core behavior).

Generally, tryEmitError(Throwable) is preferable since it allows a custom handling of error cases, although this implies checking the returned Sinks.EmitResult and correctly acting on it. This API is intended as a good default for convenience.

When the Sinks.EmitResult is not a success, vanilla reactor-core operators have the following behavior:

• Sinks.EmitResult.FAIL_OVERFLOW: irrelevant as onError is not driven by backpressure.
• Sinks.EmitResult.FAIL_ZERO_SUBSCRIBER: the error is ignored since nobody is listening. Note that most vanilla reactor sinks never trigger this result for onError, replaying the terminal signal to later subscribers instead (to the exception of Sinks.UnicastSpec.onBackpressureError()).
• Sinks.EmitResult.FAIL_CANCELLED: the error can be ignored since nobody is interested.
• Sinks.EmitResult.FAIL_TERMINATED: the error unexpectedly follows another terminal signal, so it is dropped via Operators.onErrorDropped(Throwable, Context).
• Sinks.EmitResult.FAIL_NON_SERIALIZED: throw an Sinks.EmissionException mentioning RS spec rule 1.3. Note that Sinks.unsafe() never trigger this result. It would be possible for an Sinks.EmitFailureHandler to busy-loop and optimistically wait for the contention to disappear to avoid this case in safe sinks...

Might throw an unchecked exception as a last resort (eg. in case of a fatal error downstream which cannot be propagated to any asynchronous handler, a bubbling exception, a Sinks.EmitResult.FAIL_NON_SERIALIZED as described above, ...).

Parameters:

error - the exception to signal, not null

failureHandler - the failure handler that allows retrying failed Sinks.EmitResult.

Throws:

Sinks.EmissionException - on non-serialized access

See Also:

tryEmitError(Throwable), Subscriber.onError(Throwable)

currentSubscriberCount

int currentSubscriberCount()

Get how many Subscribers are currently subscribed to the sink.

This is a best effort peek at the sink state, and a subsequent attempt at emitting to the sink might still return Sinks.EmitResult.FAIL_ZERO_SUBSCRIBER where relevant. Request (and lack thereof) isn't taken into account, all registered subscribers are counted.

Returns:

the number of active subscribers at the time of invocation

asMono

Mono<T> asMono()

Return a Mono view of this sink. Every call returns the same instance.

Returns:

the Mono view associated to this Sinks.One