Java Reference ยท java.lang
The Throwable class
Reference for java.lang.Throwable, the root of all exceptions and errors: getMessage(), getCause(), stack traces, suppressed exceptions and exception chaining.
java.lang.Throwable is the superclass of everything that can be thrown with throw and caught with catch. Only Throwable objects and their subclasses are allowed there. It has two direct subclasses that split the world in two: Exception for conditions a program may want to handle, and Error for serious JVM-level problems.
A Throwable carries a message, an optional cause (the exception that triggered this one), the stack trace captured when it was created, and a list of suppressed exceptions. You rarely extend Throwable directly; you extend Exception or RuntimeException.
Throwable t = new Throwable("something happened"); t.getMessage(); // "something happened" t.getCause(); // null
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public class Throwable implements Serializable
| Member | Description |
|---|---|
Throwable() / Throwable(String message) |
Creates a throwable with no message or the given message. |
Throwable(String message, Throwable cause) |
Creates a throwable with a message and a cause. |
Throwable(Throwable cause) |
Uses cause.toString() as the message. |
String getMessage() |
The detail message, or null. |
String getLocalizedMessage() |
By default the same as getMessage(); override for localized text. |
Throwable getCause() |
The cause, or null. |
Throwable initCause(Throwable cause) |
Sets the cause once, if it was not set by a constructor. |
StackTraceElement[] getStackTrace() |
The frames captured at creation, innermost first. |
void printStackTrace() |
Prints toString() and the frames (plus causes) to System.err. |
void addSuppressed(Throwable) / Throwable[] getSuppressed() |
Records secondary exceptions (used by try-with-resources). |
Throwable fillInStackTrace() |
Re-captures the current stack. Costly. |
Usage notes
- Message conventions.
toString()is the class name, then": "and the message if there is one. Anullmessage prints only the class name. - Always keep the cause. Pass the original exception to the new one's constructor when you translate exceptions, otherwise the real stack trace is lost.
- Stack traces are expensive to build because the JVM walks the whole stack when the object is created, not when it is thrown. Creating exceptions for ordinary control flow is slow.
- Do not catch
Throwableunless you are a framework boundary, because that also catchesErrorsubclasses such asOutOfMemoryError. - Checked or unchecked is decided by the class hierarchy:
ThrowableandException(but notRuntimeException) are checked;ErrorandRuntimeExceptionare unchecked. - Immutable after construction, apart from the cause, suppressed list and stack trace; avoid mutable state in custom subclasses because exceptions cross threads.
- Serialization:
ThrowableisSerializable, so custom fields should be serializable too.