Throwable.AddSuppressed(Throwable) Method
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Appends the specified exception to the exceptions that were suppressed in order to deliver this exception.
[Android.Runtime.Register("addSuppressed", "(Ljava/lang/Throwable;)V", "")]
public void AddSuppressed (Java.Lang.Throwable exception);
[<Android.Runtime.Register("addSuppressed", "(Ljava/lang/Throwable;)V", "")>]
member this.AddSuppressed : Java.Lang.Throwable -> unit
Parameters
- exception
- Throwable
the exception to be added to the list of suppressed exceptions
- Attributes
Exceptions
if throwable == this
.
if throwable == null
.
Remarks
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) by the try
-with-resources statement.
The suppression behavior is enabled <em>unless</em> disabled #Throwable(String, Throwable, boolean, boolean) via a constructor. When suppression is disabled, this method does nothing other than to validate its argument.
Note that when one exception #initCause(Throwable) 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 in the try
block of a try
-with-resources statement and the compiler-generated finally
block 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 the 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 suppressed exceptions.
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.
Added in 1.7.
Java documentation for java.lang.Throwable.addSuppressed(java.lang.Throwable)
.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.