Throwable (Java SE 21 & JDK 21) with Examples.
You will find code examples on most Throwable methods.
Summary
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.
Code examples on this page uses the SampleException class below.
@SuppressWarnings("serial")
public class SampleException extends Exception {
public SampleException() {
}
public SampleException(String message) {
super(message);
}
public SampleException(String message, Throwable cause) {
super(message, cause);
}
public SampleException(Throwable cause) {
super(cause);
}
public SampleException(String message, Throwable cause,
boolean enableSuppression,
boolean writableStackTrace) {
super(message, cause, enableSuppression, writableStackTrace);
}
}
public class Main {
public static void main(String[] args) {
try {
func1();
} catch (SampleException e) {
final Throwable t = e;
t.printStackTrace();
// Result
// ↓
// SampleException
// Main.func2 ...
// Main.func1 ...
// Main.main ...
// ...
}
}
private static void func1() throws SampleException {
func2();
}
private static void func2() throws SampleException {
throw new SampleException();
}
}
Constructors
Throwable ()
Constructs a new throwable with null as its detail message.
final Throwable t = new SampleException();
System.out.println(t); // SampleException
Throwable (String message)
Constructs a new throwable with the specified detail message.
final Throwable t = new SampleException("abcde");
System.out.println(t); // SampleException: abcde
System.out.println(t.getMessage()); // abcde
Throwable (String message, Throwable cause)
Constructs a new throwable with the specified detail message and cause.
final Throwable cause = new SampleException("XYZ");
final Throwable t = new SampleException("abcde", cause);
System.out.println(t); // SampleException: abcde
System.out.println(t.getMessage()); // abcde
System.out.println(t.getCause()); // SampleException: XYZ
System.out.println(t.getCause().getMessage()); // XYZ
Throwable (String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace)
Constructs a new throwable with the specified detail message, cause, suppression enabled or disabled, and writable stack trace enabled or disabled.
final Throwable cause = new SampleException("XYZ");
final Throwable t = new SampleException("abcde", cause, true, true);
System.out.println(t); // SampleException: abcde
System.out.println(t.getCause()); // SampleException: XYZ
t.addSuppressed(new SampleException("E1"));
t.addSuppressed(new SampleException("E2"));
// [SampleException: E1, SampleException: E2]
System.out.println(Arrays.toString(t.getSuppressed()));
System.out.println(t.getStackTrace().length > 0); // true
// enableSuppression = false
final Throwable cause = new SampleException("XYZ");
final Throwable t = new SampleException("abcde", cause, false, true);
System.out.println(t); // SampleException: abcde
System.out.println(t.getCause()); // SampleException: XYZ
t.addSuppressed(new SampleException("E1"));
t.addSuppressed(new SampleException("E2"));
System.out.println(Arrays.toString(t.getSuppressed())); // []
System.out.println(t.getStackTrace().length > 0); // true
// writableStackTrace = false
final Throwable cause = new SampleException("XYZ");
final Throwable t = new SampleException("abcde", cause, true, false);
System.out.println(t); // SampleException: abcde
System.out.println(t.getCause()); // SampleException: XYZ
t.addSuppressed(new SampleException("E1"));
t.addSuppressed(new SampleException("E2"));
// [SampleException: E1, SampleException: E2]
System.out.println(Arrays.toString(t.getSuppressed()));
System.out.println(t.getStackTrace().length); // 0
Throwable (Throwable cause)
Constructs a new throwable with the specified cause and a detail message of (cause==null ? null : cause.toString()) (which typically contains the class and detail message of cause).
final Throwable cause = new SampleException("XYZ");
final Throwable t = new SampleException(cause);
System.out.println(t); // SampleException: SampleException: XYZ
System.out.println(t.getMessage()); // SampleException: XYZ
System.out.println(t.getCause()); // SampleException: XYZ
System.out.println(t.getCause().getMessage()); // XYZ
Methods
final void addSuppressed (Throwable exception)
Appends the specified exception to the exceptions that were suppressed in order to deliver this exception.
final Throwable t = new SampleException("abcd");
System.out.println(t); // SampleException: abcd
t.addSuppressed(new SampleException("E1"));
t.addSuppressed(new SampleException("E2"));
final var ret = t.getSuppressed();
System.out.println(Arrays.toString(ret)); // [SampleException: E1, SampleException: E2]
Throwable fillInStackTrace ()
Fills in the execution stack trace.
public class Main {
public static void main(String[] args) {
try {
func1();
} catch (SampleException e) {
final Throwable t = e;
System.out.println("-- getStackTrace --");
for (final var element : t.getStackTrace()) {
System.out.println(element);
}
// Result
// ↓
//-- getStackTrace --
// Main.func2 ...
// Main.func1 ...
// Main.main ...
// ...
// The stack trace is overwritten.
final var ret = t.fillInStackTrace();
System.out.println(ret); // SampleException
System.out.println("-- getStackTrace --");
for (final var element : t.getStackTrace()) {
System.out.println(element);
}
// Result
// ↓
//-- getStackTrace --
// Main.main ...
// ...
}
}
private static void func1() throws SampleException {
func2();
}
private static void func2() throws SampleException {
throw new SampleException();
}
}
Throwable getCause ()
Returns the cause of this throwable or null if the cause is nonexistent or unknown.
final Throwable t = new SampleException();
System.out.println(t); // SampleException
System.out.println(t.getCause()); // null
final Throwable cause = new SampleException("XYZ");
final Throwable t = new SampleException(cause);
System.out.println(t); // SampleException: SampleException: XYZ
System.out.println(t.getCause()); // SampleException: XYZ
System.out.println(t.getCause().getMessage()); // XYZ
String getLocalizedMessage ()
Creates a localized description of this throwable.
@SuppressWarnings("serial")
class LocalizedException extends Exception {
private final static String MESSAGE_EN = "Exception! (EN)";
private final static String MESSAGE_JA = "Exception! (JA)";
LocalizedException() {
super(MESSAGE_EN);
}
@Override
public String getLocalizedMessage() {
// It is a simple implementation.
final var locale = Locale.getDefault();
return switch (locale.getLanguage()) {
case "ja" -> MESSAGE_JA;
default -> MESSAGE_EN;
};
}
}
{
System.out.println(Locale.getDefault().toLanguageTag()); // en-US
final Throwable t = new LocalizedException();
System.out.println(t); // LocalizedException: Exception! (EN)
System.out.println(t.getMessage()); // Exception! (EN)
System.out.println(t.getLocalizedMessage()); // Exception! (EN)
}
{
Locale.setDefault(Locale.JAPAN);
System.out.println(Locale.getDefault().toLanguageTag()); // ja-JP
final Throwable t = new LocalizedException();
System.out.println(t); // LocalizedException: Exception! (JA)
System.out.println(t.getMessage()); // Exception! (EN)
System.out.println(t.getLocalizedMessage()); // Exception! (JA)
}
String getMessage ()
Returns the detail message string of this throwable.
final Throwable t = new SampleException("abcd");
System.out.println(t); // SampleException: abcd
System.out.println(t.getMessage()); // abcd
StackTraceElement[] getStackTrace ()
Provides programmatic access to the stack trace information printed by printStackTrace().
public class Main {
public static void main(String[] args) {
try {
func1();
} catch (SampleException e) {
final Throwable t = e;
System.out.println("-- getStackTrace --");
for (final var element : t.getStackTrace()) {
System.out.println(element);
}
// Result
// ↓
//-- getStackTrace --
// Main.func2 ...
// Main.func1 ...
// Main.main ...
// ...
}
}
private static void func1() throws SampleException {
func2();
}
private static void func2() throws SampleException {
throw new SampleException();
}
}
final Throwable[] getSuppressed ()
Returns an array containing all of the exceptions that were suppressed, typically by the try-with-resources statement, in order to deliver this exception.
final Throwable t = new SampleException("abcd");
System.out.println(t); // SampleException: abcd
t.addSuppressed(new SampleException("E1"));
t.addSuppressed(new SampleException("E2"));
final var ret = t.getSuppressed();
System.out.println(Arrays.toString(ret)); // [SampleException: E1, SampleException: E2]
Throwable initCause (Throwable cause)
Initializes the cause of this throwable to the specified value.
final Throwable t = new SampleException();
System.out.println(t); // SampleException
System.out.println(t.getCause()); // null
final Throwable cause = new SampleException("XYZ");
System.out.println(t.initCause(cause)); // SampleException
System.out.println(t.getCause()); // SampleException: XYZ
void printStackTrace ()
Prints this throwable and its backtrace to the standard error stream.
public class Main {
public static void main(String[] args) {
try {
func1();
} catch (SampleException e) {
final Throwable t = e;
t.printStackTrace();
// Result
// ↓
// SampleException
// Main.func2 ...
// Main.func1 ...
// Main.main ...
// ...
}
}
private static void func1() throws SampleException {
func2();
}
private static void func2() throws SampleException {
throw new SampleException();
}
}
void printStackTrace (PrintStream s)
Prints this throwable and its backtrace to the specified print stream.
public class Main {
public static void main(String[] args) throws IOException {
try {
func1();
} catch (SampleException e) {
final Throwable t = e;
final var path = Path.of("R:", "java-work", "aaa.txt");
try (final var s = new PrintStream(Files.newOutputStream(path))) {
t.printStackTrace(s);
}
System.out.println("-- readString --");
System.out.println(Files.readString(path));
// Result
// ↓
//-- readString --
// SampleException
// Main.func2 ...
// Main.func1 ...
// Main.main ...
// ...
}
}
private static void func1() throws SampleException {
func2();
}
private static void func2() throws SampleException {
throw new SampleException();
}
}
void printStackTrace (PrintWriter s)
Prints this throwable and its backtrace to the specified print writer.
public class Main {
public static void main(String[] args) throws IOException {
try {
func1();
} catch (SampleException e) {
final Throwable t = e;
final var stringWriter = new StringWriter();
try (final var printWriter = new PrintWriter(stringWriter)) {
t.printStackTrace(printWriter);
}
System.out.println("-- StringWriter --");
System.out.println(stringWriter);
// Result
// ↓
//-- StringWriter --
// SampleException
// Main.func2 ...
// Main.func1 ...
// Main.main ...
// ...
}
}
private static void func1() throws SampleException {
func2();
}
private static void func2() throws SampleException {
throw new SampleException();
}
}
void setStackTrace (StackTraceElement[] stackTrace)
Sets the stack trace elements that will be returned by getStackTrace() and printed by printStackTrace() and related methods.
final Throwable t = new SampleException();
final var elements = List.of(
new StackTraceElement("ClassA", "methodB", "FileC.java", 123),
new StackTraceElement("ClassX", "methodY", "FileZ.java", 456)
);
t.setStackTrace(elements.toArray(new StackTraceElement[0]));
t.printStackTrace();
// Result
// ↓
//SampleException
// at ClassA.methodB(FileC.java:123)
// at ClassX.methodY(FileZ.java:456)
String toString ()
Returns a short description of this throwable.
final Throwable t = new SampleException("abcde");
final var str = t.toString();
System.out.println(str); // SampleException: abcde
Related posts
- API Examples
- Error
- Exception
- RuntimeException
- ArithmeticException
- ArrayIndexOutOfBoundsException
- ArrayStoreException
- CancellationException
- ClassCastException
- ConcurrentModificationException
- DateTimeException
- DateTimeParseException
- IllegalArgumentException
- IllegalStateException
- IndexOutOfBoundsException
- NoSuchElementException
- NullPointerException
- UnsupportedOperationException