Java : Throwable - API使用例

Throwable (Java SE 22 & JDK 22) の使い方まとめです。
ほとんどのメソッドにサンプルコードがあります。
API仕様書のおともにどうぞ。

概要

Throwableクラスは、Java言語のすべてのエラーと例外のスーパー・クラスです。このクラス(またはそのサブクラスの内の1つ)のインスタンスであるオブジェクトだけがJava仮想マシンによってスローされるか、Javaのthrow構文によってスローされます。

クラス構成

Throwable は、すべての例外およびエラーのベースとなるクラスです。

注意：

通常のプログラムでは、Throwable や Exception を直接 new することはおすすめしません。
Throwable や Exception の代わりに、Exception のサブクラスで new しましょう。
本記事では、SampleException というサブクラスを使い、それをメインにコード例を記載していきます。
スタックトレース情報が欲しいだけであれば StackWalker が使えるかもしれません。

@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();

            // 結果
            // ↓
            // SampleException
            //   Main.func2 ...
            //   Main.func1 ...
            //   Main.main ...
            // ...
        }
    }

    private static void func1() throws SampleException {
        func2();
    }

    private static void func2() throws SampleException {
        throw new SampleException();
    }
}

コンストラクタ

Throwable ()

詳細メッセージがnullである新規スロー可能オブジェクトを構築します。

final Throwable t = new SampleException();
System.out.println(t); // SampleException

Throwable (String message)

指定された詳細メッセージを使用して、新規スロー可能オブジェクトを構築します。

final Throwable t = new SampleException("abcde");
System.out.println(t); // SampleException: abcde
System.out.println(t.getMessage()); // abcde

Throwable (String message, Throwable 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)

指定された詳細メッセージ、原因、抑制の有効化または無効化、書込み可能スタック・トレースの有効化または無効化に基づいて、新しいスロー可能オブジェクトを構築します。

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)

指定された原因と詳細メッセージ(cause==null ? null : cause.toString())を使って新しいスロー可能オブジェクトを構築します(通常、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

メソッド

final void addSuppressed (Throwable 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 ()

実行スタック・トレースを埋め込みます。

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);
            }

            // 結果
            // ↓
            //-- getStackTrace --
            // Main.func2 ...
            // Main.func1 ...
            // Main.main ...
            // ...

            // スタックトレースが上書きされます。
            final var ret = t.fillInStackTrace();
            System.out.println(ret); // SampleException

            System.out.println("-- getStackTrace --");
            for (final var element : t.getStackTrace()) {
                System.out.println(element);
            }

            // 結果
            // ↓
            //-- getStackTrace --
            // Main.main ...
            // ...
        }
    }

    private static void func1() throws SampleException {
        func2();
    }

    private static void func2() throws SampleException {
        throw new SampleException();
    }
}

Throwable getCause ()

このスロー可能オブジェクトの原因を返しますが、原因が存在しないか不明な場合はnullを返します。

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 ()

このスロー可能オブジェクトの、ローカライズされた記述を作成します。

@SuppressWarnings("serial")
class LocalizedException extends Exception {

    private final static String MESSAGE_EN = "Exception occurred!";
    private final static String MESSAGE_JA = "例外発生!";

    LocalizedException() {
        super(MESSAGE_EN);
    }

    @Override
    public String getLocalizedMessage() {
        // 注意 : 簡易的な実装です。
        final var locale = Locale.getDefault();
        return switch (locale.getLanguage()) {
            case "ja" -> MESSAGE_JA;
            default -> MESSAGE_EN;
        };
    }
}

System.out.println(Locale.getDefault().toLanguageTag()); // ja-JP

final Throwable t = new LocalizedException();

System.out.println(t); // LocalizedException: 例外発生!
System.out.println(t.getMessage()); // Exception occurred!
System.out.println(t.getLocalizedMessage()); // 例外発生!

String getMessage ()

このスロー可能オブジェクトの詳細メッセージ文字列を返します。

final Throwable t = new SampleException("abcd");

System.out.println(t); // SampleException: abcd
System.out.println(t.getMessage()); // abcd

StackTraceElement[] getStackTrace ()

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);
            }

            // 結果
            // ↓
            //-- 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 ()

この例外を提供する目的で(通常try-with-resources文によって)抑制された例外をすべて含む配列を返します。

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)

このスロー可能オブジェクトの原因を、指定された値に初期化します。

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 ()

このスロー可能オブジェクトおよびそのバックトレースを標準エラー・ストリームに出力します。

public class Main {

    public static void main(String[] args) {
        try {
            func1();
        } catch (SampleException e) {

            final Throwable t = e;
            t.printStackTrace();

            // 結果
            // ↓
            // 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)

このスロー可能オブジェクトとそのバックトレースを指定された印刷ストリームに出力します。

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));

            // 結果
            // ↓
            //-- 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)

このスロー可能オブジェクトとそのバックトレースを指定されたプリント・ライターに出力します。

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);

            // 結果
            // ↓
            //-- 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)

getStackTrace()によって返され、printStackTrace()と関連メソッドによって出力される、スタック・トレース要素を設定します。

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();

// 結果
// ↓
//SampleException
//  at ClassA.methodB(FileC.java:123)
//  at ClassX.methodY(FileZ.java:456)

String toString ()

このスロー可能オブジェクトの短い記述を返します。

final Throwable t = new SampleException("abcde");

final var str = t.toString();
System.out.println(str); // SampleException: abcde

例外 vs. 戻り値でエラーチェック

API 使用例

Java : Throwable - API使用例

概要

コンストラクタ

Throwable ()

Throwable (String message)

Throwable (String message, Throwable cause)

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

Throwable (Throwable cause)

メソッド

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 ()

関連記事