Exceptions (reactor-core 3.7.0-M5)

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 and Description
`static class`	`Exceptions.SourceException` A `Throwable` that wraps the actual `cause` delivered via `Subscriber.onError(Throwable)` in case of `Publisher`s that themselves emit items of type `Publisher`.

Field Summary

Fields
Modifier and Type	Field and Description
`static Consumer<? super AutoCloseable>`	`AUTO_CLOSE` A general-purpose `Consumer` that closes `AutoCloseable` resource.
`static 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 Throwable`	`TERMINATED` A singleton instance of a Throwable indicating a terminal state for exceptions, don't leak this!

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static RuntimeException`	`addSuppressed(RuntimeException original, Throwable suppressed)` Safely suppress a `Throwable` on a `RuntimeException`.
`static Throwable`	`addSuppressed(Throwable original, Throwable suppressed)` Safely suppress a `Throwable` on an original `Throwable`.
`static <T> boolean`	`addThrowable(AtomicReferenceFieldUpdater<T,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(Throwable t)` Check if the given exception is a `bubbled` wrapped exception.
`static boolean`	`isCancel(Throwable t)` Check if the given error is a `cancel signal`.
`static boolean`	`isErrorCallbackNotImplemented(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(Throwable t)` Check if a `Throwable` is considered by Reactor as Fatal and would be thrown by `throwIfFatal(Throwable)`.
`static boolean`	`isJvmFatal(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(Throwable t)` Check a `Throwable` to see if it is a composite, as created by `multiple(Throwable...)`.
`static boolean`	`isOverflow(Throwable t)` Check if the given exception represents an `overflow`.
`static boolean`	`isRetryExhausted(Throwable t)` Check a `Throwable` to see if it indicates too many retry attempts have failed.
`static boolean`	`isTraceback(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, Throwable cause)` Return a new `RuntimeException` that represents too many failures on retry.
`static <T> Throwable`	`terminate(AtomicReferenceFieldUpdater<T,Throwable> field, T instance)` Atomic utility to safely mark a volatile throwable reference with a terminal marker.
`static void`	`throwIfFatal(Throwable t)` Throws a particular `Throwable` only if it belongs to a set of "fatal" error varieties.
`static void`	`throwIfJvmFatal(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(Throwable potentialMultiple)` Attempt to unwrap a `Throwable` into a `List` of Throwables.
`static List<Throwable>`	`unwrapMultipleExcludingTracebacks(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 `Publisher`s 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 Detail
  - 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 Detail
  - addThrowable
```
public static <T> boolean addThrowable(AtomicReferenceFieldUpdater<T,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
```
@Nullable
public static <T> Throwable terminate(AtomicReferenceFieldUpdater<T,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:
    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:
    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

Class Exceptions

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BACKPRESSURE_ERROR_QUEUE_FULL

TERMINATED

AUTO_CLOSE

Method Detail

addThrowable

wrapSource

multiple

multiple

bubble

duplicateOnSubscribeException

errorCallbackNotImplemented

failWithCancel

failWithOverflow

failWithOverflow

failWithRejected

failWithRejectedNotTimeCapable

failWithRejected

failWithRejected

retryExhausted

isOverflow

isBubbling

isCancel

isErrorCallbackNotImplemented

isMultiple

isRetryExhausted

isTraceback

nullOrNegativeRequestException

propagate

terminate

isJvmFatal

isFatal

throwIfFatal

throwIfJvmFatal

unwrap

unwrapMultiple

unwrapMultipleExcludingTracebacks

addSuppressed

addSuppressed