Language

JavaException Class

Definition

The Throwable class is the superclass of all errors and exceptions in the Java language.

[Java.Interop.JniTypeSignature("java/lang/Throwable", GenerateJavaPeer=false)]
public class JavaException : Exception, IDisposable, Java.Interop.IJavaPeerable
[<Java.Interop.JniTypeSignature("java/lang/Throwable", GenerateJavaPeer=false)>]
type JavaException = class
    inherit Exception
    interface IJavaPeerable
    interface IDisposable
Inheritance
JavaException
Derived
Attributes
Implements

Remarks

The Throwable class is the superclass of all errors and exceptions in the Java language. Only objects that are instances of this class (or one of its subclasses) are thrown by the Java Virtual Machine or can be thrown by the Java throw statement. Similarly, only this class or one of its subclasses can be the argument type in a catch clause. For the purposes of compile-time checking of exceptions, Throwable and any subclass of Throwable that is not also a subclass of either RuntimeException or Error are regarded as checked exceptions. Instances of two subclasses, Error and Exception, are conventionally used to indicate that exceptional situations have occurred. Typically, these instances are freshly created in the context of the exceptional situation so as to include relevant information (such as stack trace data). A throwable contains a snapshot of the execution stack of its thread at the time it was created. It can also contain a message string that gives more information about the error. Over time, a throwable can suppress other throwables from being propagated. Finally, the throwable can also contain a cause: another throwable that caused this throwable to be constructed. The recording of this causal information is referred to as the chained exception facility, as the cause can, itself, have a cause, and so on, leading to a "chain" of exceptions, each caused by another. One reason that a throwable may have a cause is that the class that throws it is built atop a lower layered abstraction, and an operation on the upper layer fails due to a failure in the lower layer. It would be bad design to let the throwable thrown by the lower layer propagate outward, as it is generally unrelated to the abstraction provided by the upper layer. Further, doing so would tie the API of the upper layer to the details of its implementation, assuming the lower layer's exception was a checked exception. Throwing a "wrapped exception" (i.e., an exception containing a cause) allows the upper layer to communicate the details of the failure to its caller without incurring either of these shortcomings. It preserves the flexibility to change the implementation of the upper layer without changing its API (in particular, the set of exceptions thrown by its methods). A second reason that a throwable may have a cause is that the method that throws it must conform to a general-purpose interface that does not permit the method to throw the cause directly. For example, suppose a persistent collection conforms to the Collection interface, and that its persistence is implemented atop java.io. Suppose the internals of the add method can throw an IOException. The implementation can communicate the details of the IOException to its caller while conforming to the Collection interface by wrapping the IOException in an appropriate unchecked exception. (The specification for the persistent collection should indicate that it is capable of throwing such exceptions.) A cause can be associated with a throwable in two ways: via a constructor that takes the cause as an argument, or via the initCause(Throwable) method. New throwable classes that wish to allow causes to be associated with them should provide constructors that take a cause and delegate (perhaps indirectly) to one of the Throwable constructors that takes a cause. Because the initCause method is public, it allows a cause to be associated with any throwable, even a "legacy throwable" whose implementation predates the addition of the exception chaining mechanism to Throwable. By convention, class Throwable and its subclasses have two constructors, one that takes no arguments and one that takes a String argument that can be used to produce a detail message. Further, those subclasses that might likely have a cause associated with them should have two more constructors, one that takes a Throwable (the cause), and one that takes a String (the detail message) and a Throwable (the cause).

Java reference for 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.

Constructors

Name Description
JavaException()

Constructs a new throwable with null as its detail message.

JavaException(JniObjectReference, JniObjectReferenceOptions, JniObjectReference)

Constructs a peer while reading exception details from an alternate throwable.

JavaException(JniObjectReference, JniObjectReferenceOptions)

Reads the Java throwable details and initializes a managed exception peer.

JavaException(String, Exception)

Creates a Java throwable with a message and retains a separate managed inner exception.

JavaException(String)

Constructs a new throwable with the specified detail message.

Fields

Name Description
InvalidJniObjectReference

A null pointer sentinel used only with None to defer peer initialization.

Properties

Name Description
JavaStackTrace

Gets the Java stack trace captured from the throwable.

JniIdentityHashCode

Returns the same hash code for the given object as would be returned by the default method hashCode(), whether or not the given object's class overrides hashCode().

JniManagedPeerState

Gets the state flags last assigned by the runtime.

JniPeerMembers

Gets the member-access information for this managed Java peer.

PeerReference

Gets the JNI reference currently stored in the peer control block.

StackTrace

Gets the managed stack trace followed by the captured Java stack trace.

Methods

Name Description
Construct(JniObjectReference, JniObjectReferenceOptions)

Delegates construction of this peer to the runtime's value manager.

Dispose()

Delegates peer disposal to the runtime's value manager.

Dispose(Boolean)

Disposes the inner exception when it is also a JavaException.

DisposeUnlessReferenced()

Asks the value manager to dispose this peer unless its mapping retains this same managed instance.

Equals(Object)

Tests whether another managed peer refers to the same Java object.

Finalize()

Passes this peer to the runtime's finalization policy.

GetHashCode()

Returns a hash code value for the object.

SetJavaStackTrace(JniObjectReference)

Refreshes the captured Java stack trace from a throwable.

SetPeerReference(JniObjectReference, JniObjectReferenceOptions)

Stores a reference value in the control block without creating a JNI reference copy.

UnregisterFromRuntime()

Removes this managed peer from the runtime mapping without disposing its JNI reference.

Explicit Interface Implementations

Name Description
IJavaPeerable.Disposed()

Marks this peer as disposed and calls Dispose with disposing set to true.

IJavaPeerable.Finalized()

Marks this peer as disposed and calls Dispose with disposing set to false.

IJavaPeerable.JniObjectReferenceControlBlock

Gets the native control-block pointer used by this peer.

IJavaPeerable.SetJniIdentityHashCode(Int32)

Stores the identity hash code supplied by the runtime.

IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates)

Replaces the stored managed peer state flags.

IJavaPeerable.SetPeerReference(JniObjectReference)

Updates the peer reference and releases a disposed peer's control block when the reference is invalid.

Extension Methods

Name Description
GetJniTypeName(IJavaPeerable)

Gets the JNI name of the type of the instance self.

JavaAs<TResult>(IJavaPeerable)

Try to coerce self to type TResult, checking that the coercion is valid on the Java side.

TryJavaCast<TResult>(IJavaPeerable, TResult)

Try to coerce self to type TResult, checking that the coercion is valid on the Java side.

Applies to