広告

Java : Throwable - API使用例

Throwable (Java SE 21 & JDK 21) の使用例まとめです。
だいたいのメソッドを網羅済みです。
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

関連記事

ページの先頭へ