Package reactor.core

Class Exceptions

java.lang.Object

reactor.core.Exceptions

public abstract class Exceptions
extends Object

Global Reactor Core Exception handling and utils to operate on.

Author:

Stephane Maldini, Injae Kim

See Also:

• Reactive-Streams-Commons

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Exceptions.SourceException	A Throwable that wraps the actual cause delivered via Subscriber.onError(Throwable) in case of Publishers that themselves emit items of type Publisher.

Field Summary

Fields

Modifier and Type	Field	Description
static final Consumer<? super AutoCloseable>	AUTO_CLOSE	A general-purpose Consumer that closes AutoCloseable resource.
static final String	BACKPRESSURE_ERROR_QUEUE_FULL	A common error message used when a reactive streams source doesn't seem to respect backpressure signals, resulting in an operator's internal queue to be full.
static final Throwable	TERMINATED	A singleton instance of a Throwable indicating a terminal state for exceptions, don't leak this!

Method Summary

Modifier and Type	Method	Description
static final RuntimeException	addSuppressed(RuntimeException original, Throwable suppressed)	Safely suppress a Throwable on a RuntimeException.
static final Throwable	addSuppressed(Throwable original, Throwable suppressed)	Safely suppress a Throwable on an original Throwable.
static <T> boolean	addThrowable(AtomicReferenceFieldUpdater<T,@Nullable Throwable> field, T instance, Throwable exception)	Update an empty atomic reference with the given exception, or combine further added exceptions together as suppressed exceptions under a root Throwable with the "Multiple exceptions" message, if the atomic reference already holds one.
static RuntimeException	bubble(Throwable t)	Prepare an unchecked RuntimeException that will bubble upstream if thrown by an operator.
static IllegalStateException	duplicateOnSubscribeException()
static UnsupportedOperationException	errorCallbackNotImplemented(Throwable cause)	Return an UnsupportedOperationException indicating that the error callback on a subscriber was not implemented, yet an error was propagated.
static RuntimeException	failWithCancel()	An exception that is propagated upward and considered as "fatal" as per Reactive Stream limited list of exceptions allowed to bubble.
static IllegalStateException	failWithOverflow()	Return an IllegalStateException indicating the receiver is overrun by more signals than expected in case of a bounded queue, or more generally that data couldn't be emitted due to a lack of request
static IllegalStateException	failWithOverflow(String message)	Return an IllegalStateException indicating the receiver is overrun by more signals than expected in case of a bounded queue or more generally that data couldn't be emitted due to a lack of request
static RejectedExecutionException	failWithRejected()	Return a singleton RejectedExecutionException
static RejectedExecutionException	failWithRejected(String message)	Return a new RejectedExecutionException with given message.
static RejectedExecutionException	failWithRejected(Throwable cause)	Return a new RejectedExecutionException with standard message and cause, unless the cause is already a RejectedExecutionException created via failWithRejected(Throwable) (not the singleton-producing variants).
static RejectedExecutionException	failWithRejectedNotTimeCapable()	Return a singleton RejectedExecutionException with a message indicating the reason is due to the scheduler not being time-capable
static boolean	isBubbling(@Nullable Throwable t)	Check if the given exception is a bubbled wrapped exception.
static boolean	isCancel(@Nullable Throwable t)	Check if the given error is a cancel signal.
static boolean	isErrorCallbackNotImplemented(@Nullable Throwable t)	Check if the given error is a callback not implemented exception, in which case its cause will be the propagated error that couldn't be processed.
static boolean	isFatal(@Nullable Throwable t)	Check if a Throwable is considered by Reactor as Fatal and would be thrown by throwIfFatal(Throwable).
static boolean	isJvmFatal(@Nullable Throwable t)	Check if a Throwable is considered by Reactor as Jvm Fatal and would be thrown by both throwIfFatal(Throwable) and throwIfJvmFatal(Throwable).
static boolean	isMultiple(@Nullable Throwable t)	Check a Throwable to see if it is a composite, as created by multiple(Throwable...).
static boolean	isOverflow(@Nullable Throwable t)	Check if the given exception represents an overflow.
static boolean	isRetryExhausted(@Nullable Throwable t)	Check a Throwable to see if it indicates too many retry attempts have failed.
static boolean	isTraceback(@Nullable Throwable t)	Check a Throwable to see if it is a traceback, as created by the checkpoint operator or debug utilities.
static RuntimeException	multiple(Iterable<Throwable> throwables)	Create a composite exception that wraps the given Throwable(s), as suppressed exceptions.
static RuntimeException	multiple(Throwable... throwables)	Create a composite exception that wraps the given Throwable(s), as suppressed exceptions.
static IllegalArgumentException	nullOrNegativeRequestException(long elements)
static RuntimeException	propagate(Throwable t)	Prepare an unchecked RuntimeException that should be propagated downstream through Subscriber.onError(Throwable).
static RuntimeException	retryExhausted(String message, @Nullable Throwable cause)	Return a new RuntimeException that represents too many failures on retry.
static <T> @Nullable Throwable	terminate(AtomicReferenceFieldUpdater<T,@Nullable Throwable> field, T instance)	Atomic utility to safely mark a volatile throwable reference with a terminal marker.
static void	throwIfFatal(@Nullable Throwable t)	Throws a particular Throwable only if it belongs to a set of "fatal" error varieties.
static void	throwIfJvmFatal(@Nullable Throwable t)	Throws a particular Throwable only if it belongs to a set of "fatal" error varieties native to the JVM.
static Throwable	unwrap(Throwable t)	Unwrap a particular Throwable only if it is was wrapped via bubble or propagate.
static List<Throwable>	unwrapMultiple(@Nullable Throwable potentialMultiple)	Attempt to unwrap a Throwable into a List of Throwables.
static List<Throwable>	unwrapMultipleExcludingTracebacks(@Nullable Throwable potentialMultiple)	Attempt to unwrap a Throwable into a List of Throwables, excluding instances that are tracebacks.
static Throwable	wrapSource(Throwable throwable)	Wrap a Throwable delivered via Subscriber.onError(Throwable) from an upstream Publisher that itself emits Publishers to distinguish the error signal from the inner sequence's processing errors.

Methods inherited from class java.lang.Object

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

Field Details

BACKPRESSURE_ERROR_QUEUE_FULL

public static final String BACKPRESSURE_ERROR_QUEUE_FULL

A common error message used when a reactive streams source doesn't seem to respect backpressure signals, resulting in an operator's internal queue to be full.

See Also:

• Constant Field Values

TERMINATED

public static final Throwable TERMINATED

A singleton instance of a Throwable indicating a terminal state for exceptions, don't leak this!

AUTO_CLOSE

public static final Consumer<? super AutoCloseable> AUTO_CLOSE

A general-purpose Consumer that closes AutoCloseable resource. If exception is thrown during closing the resource, it will be propagated by propagate(Throwable).

Method Details

addThrowable

public static <T> boolean addThrowable(AtomicReferenceFieldUpdater<T,@Nullable Throwable> field,
 T instance,
 Throwable exception)

Update an empty atomic reference with the given exception, or combine further added exceptions together as suppressed exceptions under a root Throwable with the "Multiple exceptions" message, if the atomic reference already holds one. This is short-circuited if the reference contains TERMINATED.

Since composite exceptions and traceback exceptions share the same underlying mechanism of suppressed exceptions, a traceback could be made part of a composite exception. Use unwrapMultipleExcludingTracebacks(Throwable) to filter out such elements in a composite if needed.

Type Parameters:

T - the parent instance type

Parameters:

field - the target field updater

instance - the parent instance for the field

exception - the Throwable to add.

Returns:

true if added, false if the field contained the TERMINATED instance.

See Also:

• unwrapMultiple(Throwable)

wrapSource

public static Throwable wrapSource(Throwable throwable)

Wrap a Throwable delivered via Subscriber.onError(Throwable) from an upstream Publisher that itself emits Publishers to distinguish the error signal from the inner sequence's processing errors.

Parameters:

throwable - the source sequence error signal

Returns:

Exceptions.SourceException

multiple

public static RuntimeException multiple(Throwable... throwables)

Create a composite exception that wraps the given Throwable(s), as suppressed exceptions. Instances create by this method can be detected using the isMultiple(Throwable) check. The unwrapMultiple(Throwable) method will correctly unwrap these to a List of the suppressed exceptions. Note that is will also be consistent in producing a List for other types of exceptions by putting the input inside a single-element List.

Since composite exceptions and traceback exceptions share the same underlying mechanism of suppressed exceptions, a traceback could be made part of a composite exception. Use unwrapMultipleExcludingTracebacks(Throwable) to filter out such elements in a composite if needed.

Parameters:

throwables - the exceptions to wrap into a composite

Returns:

a composite exception with a standard message, and the given throwables as suppressed exceptions

See Also:

• addThrowable(AtomicReferenceFieldUpdater, Object, Throwable)

multiple

public static RuntimeException multiple(Iterable<Throwable> throwables)

Create a composite exception that wraps the given Throwable(s), as suppressed exceptions. Instances created by this method can be detected using the isMultiple(Throwable) check. The unwrapMultiple(Throwable) method will correctly unwrap these to a List of the suppressed exceptions. Note that is will also be consistent in producing a List for other types of exceptions by putting the input inside a single-element List.

Since composite exceptions and traceback exceptions share the same underlying mechanism of suppressed exceptions, a traceback could be made part of a composite exception. Use unwrapMultipleExcludingTracebacks(Throwable) to filter out such elements in a composite if needed.

Parameters:

throwables - the exceptions to wrap into a composite

Returns:

a composite exception with a standard message, and the given throwables as suppressed exceptions

See Also:

• addThrowable(AtomicReferenceFieldUpdater, Object, Throwable)

bubble

public static RuntimeException bubble(Throwable t)

Prepare an unchecked RuntimeException that will bubble upstream if thrown by an operator.

This method invokes throwIfFatal(Throwable).

Parameters:

t - the root cause

Returns:

an unchecked exception that should choose bubbling up over error callback path

duplicateOnSubscribeException

public static IllegalStateException duplicateOnSubscribeException()

Returns:

a new IllegalStateException with a cause message abiding to reactive stream specification rule 2.12.

errorCallbackNotImplemented

public static UnsupportedOperationException errorCallbackNotImplemented(Throwable cause)

Return an UnsupportedOperationException indicating that the error callback on a subscriber was not implemented, yet an error was propagated.

Parameters:

cause - original error not processed by a receiver.

Returns:

an UnsupportedOperationException indicating the error callback was not implemented and holding the original propagated error.

See Also:

• isErrorCallbackNotImplemented(Throwable)

failWithCancel

public static RuntimeException failWithCancel()

An exception that is propagated upward and considered as "fatal" as per Reactive Stream limited list of exceptions allowed to bubble. It is not meant to be common error resolution but might assist implementors in dealing with boundaries (queues, combinations and async).

Returns:

a RuntimeException that can be identified via isCancel(java.lang.Throwable)

See Also:

• isCancel(Throwable)

failWithOverflow

public static IllegalStateException failWithOverflow()

Return an IllegalStateException indicating the receiver is overrun by more signals than expected in case of a bounded queue, or more generally that data couldn't be emitted due to a lack of request

Returns:

an IllegalStateException

See Also:

• isOverflow(Throwable)

failWithOverflow

public static IllegalStateException failWithOverflow(String message)

Return an IllegalStateException indicating the receiver is overrun by more signals than expected in case of a bounded queue or more generally that data couldn't be emitted due to a lack of request

Parameters:

message - the exception's message

Returns:

an IllegalStateException

See Also:

• isOverflow(Throwable)

failWithRejected

public static RejectedExecutionException failWithRejected()

Return a singleton RejectedExecutionException

Returns:

a singleton RejectedExecutionException

failWithRejectedNotTimeCapable

public static RejectedExecutionException failWithRejectedNotTimeCapable()

Return a singleton RejectedExecutionException with a message indicating the reason is due to the scheduler not being time-capable

Returns:

a singleton RejectedExecutionException

failWithRejected

public static RejectedExecutionException failWithRejected(Throwable cause)

Return a new RejectedExecutionException with standard message and cause, unless the cause is already a RejectedExecutionException created via failWithRejected(Throwable) (not the singleton-producing variants).

Parameters:

cause - the original exception that caused the rejection

Returns:

a new RejectedExecutionException with standard message and cause

failWithRejected

public static RejectedExecutionException failWithRejected(String message)

Return a new RejectedExecutionException with given message.

Parameters:

message - the rejection message

Returns:

a new RejectedExecutionException with custom message

retryExhausted

public static RuntimeException retryExhausted(String message,
 @Nullable Throwable cause)

Return a new RuntimeException that represents too many failures on retry. This nature can be detected via isRetryExhausted(Throwable). The cause of the last retry attempt is passed and stored as this exception's cause.

Parameters:

message - the message

cause - the cause of the last retry attempt that failed (or null if irrelevant)

Returns:

a new RuntimeException representing retry exhaustion due to too many attempts

isOverflow

public static boolean isOverflow(@Nullable Throwable t)

Check if the given exception represents an overflow.

Parameters:

t - the Throwable error to check

Returns:

true if the given Throwable represents an overflow.

isBubbling

public static boolean isBubbling(@Nullable Throwable t)

Check if the given exception is a bubbled wrapped exception.

Parameters:

t - the Throwable error to check

Returns:

true if given Throwable is a bubbled wrapped exception.

isCancel

public static boolean isCancel(@Nullable Throwable t)

Check if the given error is a cancel signal.

Parameters:

t - the Throwable error to check

Returns:

true if given Throwable is a cancellation token.

isErrorCallbackNotImplemented

public static boolean isErrorCallbackNotImplemented(@Nullable Throwable t)

Check if the given error is a callback not implemented exception, in which case its cause will be the propagated error that couldn't be processed.

Parameters:

t - the Throwable error to check

Returns:

true if given Throwable is a callback not implemented exception.

isMultiple

public static boolean isMultiple(@Nullable Throwable t)

Check a Throwable to see if it is a composite, as created by multiple(Throwable...).

Parameters:

t - the Throwable to check, null always yields false

Returns:

true if the Throwable is an instance created by multiple(Throwable...), false otherwise

isRetryExhausted

public static boolean isRetryExhausted(@Nullable Throwable t)

Check a Throwable to see if it indicates too many retry attempts have failed. Such an exception can be created via retryExhausted(String, Throwable).

Parameters:

t - the Throwable to check, null always yields false

Returns:

true if the Throwable is an instance representing retry exhaustion, false otherwise

isTraceback

public static boolean isTraceback(@Nullable Throwable t)

Check a Throwable to see if it is a traceback, as created by the checkpoint operator or debug utilities.

Parameters:

t - the Throwable to check, null always yields false

Returns:

true if the Throwable is a traceback, false otherwise

nullOrNegativeRequestException

public static IllegalArgumentException nullOrNegativeRequestException(long elements)

Parameters:

elements - the invalid requested demand

Returns:

a new IllegalArgumentException with a cause message abiding to reactive stream specification rule 3.9.

propagate

public static RuntimeException propagate(Throwable t)

Prepare an unchecked RuntimeException that should be propagated downstream through Subscriber.onError(Throwable).

This method invokes throwIfFatal(Throwable).

Parameters:

t - the root cause

Returns:

an unchecked exception to propagate through onError signals.

terminate

public static <T> @Nullable Throwable terminate(AtomicReferenceFieldUpdater<T,@Nullable Throwable> field,
 T instance)

Atomic utility to safely mark a volatile throwable reference with a terminal marker.

Type Parameters:

T - the instance type

Parameters:

field - the atomic container

instance - the reference instance

Returns:

the previously masked throwable

isJvmFatal

public static boolean isJvmFatal(@Nullable Throwable t)

Check if a Throwable is considered by Reactor as Jvm Fatal and would be thrown by both throwIfFatal(Throwable) and throwIfJvmFatal(Throwable). This is a subset of isFatal(Throwable), namely:

• VirtualMachineError
• ThreadDeath
• LinkageError

Unless wrapped explicitly, such exceptions would always be thrown by operators instead of propagation through onError, potentially interrupting progress of Flux/Mono sequences. When they occur, the JVM itself is assumed to be in an unrecoverable state, and so is Reactor.

Parameters:

t - the Throwable to check

Returns:

true if the throwable is considered Jvm Fatal

See Also:

• throwIfFatal(Throwable)
• throwIfJvmFatal(Throwable)
• isFatal(Throwable)

isFatal

public static boolean isFatal(@Nullable Throwable t)

Check if a Throwable is considered by Reactor as Fatal and would be thrown by throwIfFatal(Throwable).

• BubblingException (as detectable by isBubbling(Throwable))
• ErrorCallbackNotImplemented (as detectable by isErrorCallbackNotImplemented(Throwable))
• Jvm Fatal exceptions
  • VirtualMachineError
  • ThreadDeath
  • LinkageError

Unless wrapped explicitly, such exceptions would always be thrown by operators instead of propagation through onError, potentially interrupting progress of Flux/Mono sequences. When they occur, the assumption is that Reactor is in an unrecoverable state (notably because the JVM itself might be in an unrecoverable state).

Parameters:

t - the Throwable to check

Returns:

true if the throwable is considered fatal

See Also:

• throwIfFatal(Throwable)
• isJvmFatal(Throwable)

throwIfFatal

public static void throwIfFatal(@Nullable Throwable t)

Throws a particular Throwable only if it belongs to a set of "fatal" error varieties. These varieties are as follows:

• BubblingException (as detectable by isBubbling(Throwable))
• ErrorCallbackNotImplemented (as detectable by isErrorCallbackNotImplemented(Throwable))
• VirtualMachineError
• ThreadDeath
• LinkageError

Parameters:

t - the exception to evaluate

throwIfJvmFatal

public static void throwIfJvmFatal(@Nullable Throwable t)

Throws a particular Throwable only if it belongs to a set of "fatal" error varieties native to the JVM. These varieties are as follows:

• VirtualMachineError
• ThreadDeath
• LinkageError

Parameters:

t - the exception to evaluate

unwrap

public static Throwable unwrap(Throwable t)

Unwrap a particular Throwable only if it is was wrapped via bubble or propagate.

Parameters:

t - the exception to unwrap

Returns:

the unwrapped exception or current one if null

unwrapMultiple

public static List<Throwable> unwrapMultiple(@Nullable Throwable potentialMultiple)

Attempt to unwrap a Throwable into a List of Throwables. This is only done on the condition that said Throwable is a composite exception built by multiple(Throwable...), in which case the list contains the exceptions wrapped as suppressed exceptions in the composite. In any other case, the list only contains the input Throwable (or is empty in case of null input).

Since composite exceptions and traceback exceptions share the same underlying mechanism of suppressed exceptions, a traceback could be made part of a composite exception. Use unwrapMultipleExcludingTracebacks(Throwable) to filter out such elements in a composite if needed.

Parameters:

potentialMultiple - the Throwable to unwrap if multiple

Returns:

a List of the exceptions suppressed by the Throwable if multiple, or a List containing the Throwable otherwise. Null input results in an empty List.

See Also:

• unwrapMultipleExcludingTracebacks(Throwable)

unwrapMultipleExcludingTracebacks

public static List<Throwable> unwrapMultipleExcludingTracebacks(@Nullable Throwable potentialMultiple)

Attempt to unwrap a Throwable into a List of Throwables, excluding instances that are tracebacks. This is only done on the condition that said Throwable is a composite exception built by multiple(Throwable...), in which case the returned list contains its suppressed exceptions minus the tracebacks. In any other case, the list only contains the input Throwable (or is empty in case of null input).

This is useful because tracebacks are added as suppressed exceptions and thus can appear as components of a composite.

Parameters:

potentialMultiple - the Throwable to unwrap if multiple

Returns:

a List of the exceptions suppressed by the Throwable minus the tracebacks if multiple, or a List containing the Throwable otherwise. Null input results in an empty List.

addSuppressed

public static final RuntimeException addSuppressed(RuntimeException original,
 Throwable suppressed)

Safely suppress a Throwable on a RuntimeException. The returned RuntimeException, bearing the suppressed exception, is most often the same as the original exception unless:

• original and tentatively suppressed exceptions are one and the same: do nothing but return the original.
• original is one of the singleton RejectedExecutionException created by Reactor: make a copy the RejectedExecutionException, add the suppressed exception to it and return that copy.

Parameters:

original - the original RuntimeException to bear a suppressed exception

suppressed - the Throwable to suppress

Returns:

the (most of the time original) RuntimeException bearing the suppressed Throwable

addSuppressed

public static final Throwable addSuppressed(Throwable original,
 Throwable suppressed)

Safely suppress a Throwable on an original Throwable. The returned Throwable, bearing the suppressed exception, is most often the same as the original one unless:

• original and tentatively suppressed exceptions are one and the same: do nothing but return the original.
• original is one of the singleton RejectedExecutionException created by Reactor: make a copy the RejectedExecutionException, add the suppressed exception to it and return that copy.
• original is a special internal TERMINATED singleton instance: return it without suppressing the exception.

Parameters:

original - the original Throwable to bear a suppressed exception

suppressed - the Throwable to suppress

Returns:

the (most of the time original) Throwable bearing the suppressed Throwable