Appends the specified exception to the exceptions that were
suppressed in order to deliver this exception. This method is
thread-safe and typically called (automatically and implicitly)
The suppression behavior is enabled unless disabled via. When suppression is disabled, this method does nothing other than to validate its argument.
Note that when one exception causes another exception, the first
exception is usually caught and then the second exception is
thrown in response. In other words, there is a causal
connection between the two exceptions.
In contrast, there are situations where two independent
exceptions can be thrown in sibling code blocks, in particular
try block of a
statement and the compiler-generated
which closes the resource.
In these situations, only one of the thrown exceptions can be
propagated. In the
try-with-resources statement, when
there are two such exceptions, the exception originating from
try block is propagated and the exception from the
finally block is added to the list of exceptions
suppressed by the exception from the
try block. As an
exception unwinds the stack, it can accumulate multiple
An exception may have suppressed exceptions while also being caused by another exception. Whether or not an exception has a cause is semantically known at the time of its creation, unlike whether or not an exception will suppress other exceptions which is typically only determined after an exception is thrown.
Note that programmer written code is also able to take advantage of calling this method in situations where there are multiple sibling exceptions and only one can be propagated.
|the exception to be added to the list of suppressed exceptions|
| if |
| if |