Java : Throwable with Examples

Throwable (Java SE 22 & JDK 22) 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.

Class diagram

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

API Examples

Java : Throwable with Examples

Summary

Constructors

Throwable ()

Throwable (String message)

Throwable (String message, Throwable cause)

Throwable (String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace)

Throwable (Throwable cause)

Methods

final void addSuppressed (Throwable exception)

Throwable fillInStackTrace ()

Throwable getCause ()

String getLocalizedMessage ()

String getMessage ()

StackTraceElement[] getStackTrace ()

final Throwable[] getSuppressed ()

Throwable initCause (Throwable cause)

void printStackTrace ()

void printStackTrace (PrintStream s)

void printStackTrace (PrintWriter s)

void setStackTrace (StackTraceElement[] stackTrace)

String toString ()

Related posts