モジュール java.base
パッケージ java.lang

クラスThrowable

  • すべての実装されたインタフェース:
    Serializable
    直系の既知のサブクラス:
    Error, Exception
    public class Throwable
extends Object
implements Serializable
    Throwableクラスは、Java言語のすべてのエラーと例外のスーパー・クラスです。 このクラス(またはそのサブクラスの内の1つ)のインスタンスであるオブジェクトだけがJava仮想マシンによってスローされるか、Javaのthrow構文によってスローされます。 同じように、このクラスまたはそのサブクラスの内の1つだけがcatch節の引数の型に指定できます。 コンパイル時に例外をチェックする目的で、 ThrowableとThrowableのサブクラスで、RuntimeExceptionまたはErrorのサブクラスでもないものは、チェック例外としてみなされます。

    2つのサブクラスErrorとExceptionのインスタンスは従来、例外的な状況が発生したことを示すために使用されます。 これらのインスタンスは、通常、関連する情報(スタック・トレース・データなど)を格納するために、例外的な状況に応じて新しく作成されます。

    スロー可能オブジェクトには、作成時のそのスレッドの実行スタックのスナップショットが含まれます。 これには、エラーについての詳細情報を示すメッセージ文字列を含めることもできます。 時間の経過に従い、あるスロー可能オブジェクトがほかのスロー可能オブジェクトの伝播を抑制する可能性があります。 最後に、スロー可能オブジェクトには、原因 (このスロー可能オブジェクトが構築される原因となった別のスロー可能オブジェクト)を含めることもできます。 この原因情報の記録は例外チェーン機能と呼ばれますが、それは、原因自体に原因がある、といった具合に例外のチェーン(各例外がそれぞれ別の例外の原因となる)が形成されるからです。

    スロー可能オブジェクトが原因を保持できる1つの理由として、スロー可能オブジェクトをスローするクラスが下位レイヤー抽象化の上に構築されていることが挙げられます。このため、上位レイヤーに対する操作が失敗するのは、下位レイヤーでの操作が失敗するためです。 下位レイヤーによりスローされるスロー可能オブジェクトを外部に送信するのは、不適切な設計方法です。これは、通常、上位レイヤーにより提供される抽象化機能とは関係がないためです。 さらに、このような操作を行うと、上位レイヤーのAPIを実装の詳細に結び付けてしまうため、下位レイヤーの例外がチェック例外と見なされてしまいます。 「ラップされた例外」(原因を含む例外)をスローすると、これらの欠点に触れずに上位レイヤーが障害の詳細を呼出し側に通信できるようになります。 このため、上位レイヤーの実装(特にメソッドによりスローされる例外のセット)をAPIを変更せずに柔軟に変更できます。

    スロー可能オブジェクトが原因を保持する2番目の理由は、スロー可能オブジェクトをスローするメソッドが、原因を直接スローすることをメソッドに許可しない汎用インタフェースに準拠する必要があることです。 たとえば、永続コレクションがCollectionインタフェースに準拠し、その永続性がjava.ioの上位に実装される場合を考えましょう。 addメソッドの内部でIOExceptionがスローされる可能性があるとします。 この場合、適切な非チェック例外のIOExceptionをラップすることにより、実装はCollectionインタフェースに準拠しつつ、IOExceptionの詳細を呼出し側に通知できます。 永続コレクションの仕様に、この種の例外をスロー可能であることが示されている必要があります。

    原因は、2つの方法でスロー可能オブジェクトに関連付けることができます。1つは原因を引数として取るコンストラクタを使用する方法、もう1つはinitCause(Throwable)メソッドを使用する方法です。 原因の関連付けを可能にする新規スロー可能クラスは、原因を受け取るコンストラクタを提供し、原因を受け取るいずれかのThrowableコンストラクタに(通常間接的に)委譲する必要があります。 initCauseメソッドはpublicであるため、原因を任意のスロー可能オブジェクトに関連付けることが可能です。これは、実装が例外チェーン・メカニズムのThrowableへの追加に先行するレガシー・スロー可能オブジェクトであっても当てはまります。

    従来、Throwableクラスおよびそのサブクラスは2つのコンストラクタを保持します。1つは引数を取らず、もう1つは詳細メッセージの生成に使用可能なString引数を取ります。 また、関連付けられた原因を保持可能なこれらのサブクラスは、さらに2つのコンストラクタを保持します。1つはThrowable (原因)を取り、もう1つはString (詳細メッセージ)およびThrowable (原因)を取ります。

    導入されたバージョン:
    1.0
    関連項目:
    直列化された形式
    Java™言語仕様:
    11.2コンパイル時の例外検査

    • コンストラクタのサマリー

      コンストラクタ 
      修飾子 コンストラクタ 説明
        Throwable()
      詳細メッセージがnullである新規スロー可能オブジェクトを構築します。
        Throwable​(String message)
      指定された詳細メッセージを使用して、新規スロー可能オブジェクトを構築します。
        Throwable​(String message, Throwable cause)
      指定された詳細メッセージおよび原因を使用して新規スロー可能オブジェクトを構築します。
      protected Throwable​(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace)
      指定された詳細メッセージ、原因、抑制の有効化または無効化、書込み可能スタック・トレースの有効化または無効化に基づいて、新しいスロー可能オブジェクトを構築します。
        Throwable​(Throwable cause)
      指定された原因と詳細メッセージ(cause==null ? null : cause.toString())を使って新しいスロー可能オブジェクトを構築します(通常、causeのクラスと詳細メッセージを含みます)。

    • コンストラクタの詳細

      • Throwable

        public Throwable()
        詳細メッセージがnullである新規スロー可能オブジェクトを構築します。 原因は初期化されません。initCause(java.lang.Throwable)を呼び出すことによって、あとでこれを初期化することができます。

        fillInStackTrace()メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。

      • Throwable

        public Throwable​(String message)
        指定された詳細メッセージを使用して、新規スロー可能オブジェクトを構築します。 原因は初期化されません。initCause(java.lang.Throwable)を呼び出すことによって、あとでこれを初期化することができます。

        fillInStackTrace()メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。

        パラメータ:
        message - 詳細メッセージ。 詳細メッセージは、あとでgetMessage()メソッドで取得できるように保存されます。

      • Throwable

        public Throwable​(String message,
                 Throwable cause)
        指定された詳細メッセージおよび原因を使用して新規スロー可能オブジェクトを構築します。

        causeと関連付けられた詳細メッセージが、このスロー可能オブジェクトの詳細メッセージに自動的に統合されることはありません。

        fillInStackTrace()メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。

        パラメータ:
        message - 詳細メッセージ(あとでgetMessage()メソッドで取得できるように保存される)。
        cause - 原因(あとでgetCause()メソッドで取得できるように保存される)。 (null値が許可されており、原因が存在しないか不明であることを示す。)
        導入されたバージョン:
        1.4

      • Throwable

        public Throwable​(Throwable cause)
        指定された原因と詳細メッセージ(cause==null ? null : cause.toString())を使って新しいスロー可能オブジェクトを構築します(通常、causeのクラスと詳細メッセージを含みます)。 このコンストラクタは、スロー可能オブジェクトがほかのスロー可能オブジェクト(PrivilegedActionExceptionなど)のラッパーである場合に有用です。

        fillInStackTrace()メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。

        パラメータ:
        cause - 原因(あとでgetCause()メソッドで取得できるように保存される)。 (null値が許可されており、原因が存在しないか不明であることを示す。)
        導入されたバージョン:
        1.4

      • Throwable

        protected Throwable​(String message,
                    Throwable cause,
                    boolean enableSuppression,
                    boolean writableStackTrace)
        指定された詳細メッセージ、原因、抑制の有効化または無効化、書込み可能スタック・トレースの有効化または無効化に基づいて、新しいスロー可能オブジェクトを構築します。 抑制が無効になっている場合、このオブジェクトのgetSuppressed()から長さゼロの配列が返され、通常であれば抑制リストに例外を追加するはずのaddSuppressed(java.lang.Throwable)呼出しが、何の効果も持たなくなります。 書き込み可能なスタック・トレースがfalseの場合、このコンストラクタはfillInStackTrace()を呼び出さず、nullがstackTraceフィールドに書き込まれ、その後の fillInStackTraceおよびsetStackTrace(StackTraceElement[])の呼び出しはスタック・トレースを設定しません。 書込み可能スタック・トレースがfalseの場合、getStackTrace()から長さゼロの配列が返されます。

        Throwableのほかのコンストラクタでは、抑制は有効であり、スタック・トレースも書込み可能であるとみなされます。 Throwableのサブクラスでは、抑制が無効になる条件をすべてドキュメント化するほか、スタック・トレースが書込み可能でなくなる条件もドキュメント化しておくべきです。 抑制の無効化が発生するのは、メモリーの少ない状況で仮想マシンが例外オブジェクトを再利用する場合など、特殊な要件が存在する例外的な状況の場合だけにすべきです。 2つのサブシステム間の制御フローを実装する目的などで、ある特定の例外オブジェクトのキャッチと再スローが繰り返されるような状況も、不変のスロー可能オブジェクトが適する状況の一例です。

        パラメータ:
        message - 詳細メッセージ。
        cause - 原因。 (null値が許可されており、原因が存在しないか不明であることを示す。)
        enableSuppression - 抑制を有効化するか、それとも無効化するか
        writableStackTrace - スタック・トレースを書込み可能にするかどうか
        導入されたバージョン:
        1.7
        関連項目:
        OutOfMemoryError, NullPointerException, ArithmeticException

    • メソッドの詳細

      • getMessage

        public String getMessage()
        このスロー可能オブジェクトの詳細メッセージ文字列を返します。
        戻り値:
        このThrowableインスタンスの詳細メッセージ文字列(nullも可)。

      • getLocalizedMessage

        public String getLocalizedMessage()
        このスロー可能オブジェクトの、ローカライズされた記述を作成します。 サブクラスはこのメソッドをオーバーライドして、ロケールに固有のメッセージを作成できます。 このメソッドをオーバーライドしないサブクラスの場合は、デフォルトの実装によってgetMessage()と同じ結果が返されます。
        戻り値:
        このスロー可能オブジェクトの、ローカライズされた記述。
        導入されたバージョン:
        1.1

      • getCause

        public Throwable getCause()
        このスロー可能オブジェクトの原因を返しますが、原因が存在しないか不明な場合はnullを返します。 (原因はこのスロー可能オブジェクトをスローさせたスロー可能オブジェクトです。)

        この実装は、Throwableを要求するいずれかのコンストラクタ経由で提供された原因、またはinitCause(Throwable)メソッドを使用して作成後に設定された原因を返します。 通常、このメソッドをオーバーライドする必要はありませんが、サブクラスはこのメソッドをオーバーライドして、他のなんらかの方法で設定された原因を返すことができます。 これは、チェーンされた例外をThrowableに追加する前に実行されるレガシー連鎖スロー可能オブジェクトの場合に適切な動作です。 PrintStackTraceメソッドは、いずれもオーバーライドする必要はありません。これらのメソッドはすべてgetCauseメソッドを呼び出して、スロー可能オブジェクトの原因を判別します。

        戻り値:
        このスロー可能オブジェクトの原因。原因が存在しないか不明の場合はnull。
        導入されたバージョン:
        1.4

      • initCause

        public Throwable initCause​(Throwable cause)
        このスロー可能オブジェクトの原因を、指定された値に初期化します。 (原因はこのスロー可能オブジェクトをスローさせたスロー可能オブジェクトです。)

        このメソッドは最大で1回しか呼び出すことができません。 通常は、コンストラクタ内から、またはThrowableの作成直後に呼び出されます。 このスロー可能オブジェクトがThrowable(Throwable)またはThrowable(String,Throwable)を使用して作成された場合、このメソッドは1回も呼び出すことができません。

        原因を設定するためのその他のサポートを含まないレガシー・スロー可能型でこのメソッドを使用する例を、次に示します。 

         try {
     lowLevelOp();
 } catch (LowLevelException le) {
     throw (HighLevelException)
           new HighLevelException().initCause(le); // Legacy constructor
 }
        パラメータ:
        cause - 原因(あとでgetCause()メソッドで取得できるように保存される)。 (null値が許可されており、原因が存在しないか不明であることを示す。)
        戻り値:
        このThrowableインスタンスへの参照。
        例外:
        IllegalArgumentException - causeがこのスロー可能オブジェクトである場合。 (スロー可能オブジェクトはそれ自身の原因にはなれない。)
        IllegalStateException - このスロー可能オブジェクトがThrowable(Throwable)またはThrowable(String,Throwable)で作成されたものである場合、あるいはこのスロー可能オブジェクトでこのメソッドがすでに呼び出されていた場合。
        導入されたバージョン:
        1.4

      • toString

        public String toString()
        このスロー可能オブジェクトの短い記述を返します。 結果は次のものを連結したものになります。
        • このオブジェクトのクラスの名前
        • ": " (コロンとスペース)
        • このオブジェクトのgetLocalizedMessage()メソッドを呼び出した結果
        getLocalizedMessageがnullを返す場合、クラス名のみが返されます。
        オーバーライド:
        toString 、クラス:  Object
        戻り値:
        このスロー可能オブジェクトの文字列表現。

      • printStackTrace

        public void printStackTrace()
        このスロー可能オブジェクトおよびそのバックトレースを標準エラー・ストリームに出力します。 このメソッドは、このThrowableオブジェクトのスタック・トレースを、System.errフィールドの値であるエラー出力ストリームで出力します。 出力の先頭行には、このオブジェクトに対するtoString()メソッドの結果が含まれます。 残りの行は、以前にfillInStackTrace()メソッドによって記録されたデータを表します。 この情報の書式は実装によって異なりますが、典型的な書式の例を次に示します。 
         java.lang.NullPointerException
         at MyClass.mash(MyClass.java:9)
         at MyClass.crunch(MyClass.java:6)
         at MyClass.main(MyClass.java:3)
        この例は、次のプログラムを実行することによって作成されたものです。 
         class MyClass {
     public static void main(String[] args) {
         crunch(null);
     }
     static void crunch(int[] a) {
         mash(a);
     }
     static void mash(int[] b) {
         System.out.println(b[0]);
     }
 }
        初期化された非nullの原因を保持するスロー可能オブジェクトのバックトレースには、通常、原因のバックトレースが含まれます。 この情報の書式は実装によって異なりますが、典型的な書式の例を次に示します。 
         HighLevelException: MidLevelException: LowLevelException
         at Junk.a(Junk.java:13)
         at Junk.main(Junk.java:4)
 Caused by: MidLevelException: LowLevelException
         at Junk.c(Junk.java:23)
         at Junk.b(Junk.java:17)
         at Junk.a(Junk.java:11)
         ... 1 more
 Caused by: LowLevelException
         at Junk.e(Junk.java:30)
         at Junk.d(Junk.java:27)
         at Junk.c(Junk.java:21)
         ... 3 more
        文字"..."を含む行が存在することに注目してください。 これらの行は、この例外のスタック・トレースの残りが、この例外により引き起こされた例外のスタック・トレースの下からのフレーム数と一致することを示します。 通常の(「原因となる例外」をキャッチするのと同じメソッドからラップされた例外がスローされる)場合、この短縮形を使用することで、出力の長さを大幅に短縮できます。 上の例は、次のプログラムを実行することで生成されます。 
         public class Junk {
     public static void main(String args[]) {
         try {
             a();
         } catch(HighLevelException e) {
             e.printStackTrace();
         }
     }
     static void a() throws HighLevelException {
         try {
             b();
         } catch(MidLevelException e) {
             throw new HighLevelException(e);
         }
     }
     static void b() throws MidLevelException {
         c();
     }
     static void c() throws MidLevelException {
         try {
             d();
         } catch(LowLevelException e) {
             throw new MidLevelException(e);
         }
     }
     static void d() throws LowLevelException {
        e();
     }
     static void e() throws LowLevelException {
         throw new LowLevelException();
     }
 }

 class HighLevelException extends Exception {
     HighLevelException(Throwable cause) { super(cause); }
 }

 class MidLevelException extends Exception {
     MidLevelException(Throwable cause)  { super(cause); }
 }

 class LowLevelException extends Exception {
 }
        リリース7以降のプラットフォームでは、抑制された例外という概念が、( try-with-resources文の概念と組み合わせて)サポートされています。 ある例外を提供する目的で抑制されたすべての例外が、スタック・トレースの下に出力されます。 この情報の書式は実装によって異なりますが、典型的な書式の例を次に示します。 
         Exception in thread "main" java.lang.Exception: Something happened
  at Foo.bar(Foo.java:10)
  at Foo.main(Foo.java:5)
  Suppressed: Resource$CloseFailException: Resource ID = 0
          at Resource.close(Resource.java:26)
          at Foo.bar(Foo.java:9)
          ... 1 more
        抑制された例外では原因の場合とまったく同様に、「... n more」という表記が使用されます。 抑制された例外は原因と場合と異なり、「包括元の例外」を超えてインデントされます。

        ある例外が、1つの原因と1つ以上の抑制された例外の両方を持つこともあります。 

         Exception in thread "main" java.lang.Exception: Main block
  at Foo3.main(Foo3.java:7)
  Suppressed: Resource$CloseFailException: Resource ID = 2
          at Resource.close(Resource.java:26)
          at Foo3.main(Foo3.java:5)
  Suppressed: Resource$CloseFailException: Resource ID = 1
          at Resource.close(Resource.java:26)
          at Foo3.main(Foo3.java:5)
 Caused by: java.lang.Exception: I did it
  at Foo3.main(Foo3.java:8)
        同様に、抑制された例外が原因を持つこともあります。 
         Exception in thread "main" java.lang.Exception: Main block
  at Foo4.main(Foo4.java:6)
  Suppressed: Resource2$CloseFailException: Resource ID = 1
          at Resource2.close(Resource2.java:20)
          at Foo4.main(Foo4.java:5)
  Caused by: java.lang.Exception: Rats, you caught me
          at Resource2$CloseFailException.<init>(Resource2.java:45)
          ... 2 more

      • printStackTrace

        public void printStackTrace​(PrintStream s)
        このスロー可能オブジェクトとそのバックトレースを指定された印刷ストリームに出力します。
        パラメータ:
        s - 出力に使用するPrintStream

      • printStackTrace

        public void printStackTrace​(PrintWriter s)
        このスロー可能オブジェクトとそのバックトレースを指定されたプリント・ライターに出力します。
        パラメータ:
        s - 出力に使用するPrintWriter
        導入されたバージョン:
        1.1

      • fillInStackTrace

        public Throwable fillInStackTrace()
        実行スタック・トレースを埋め込みます。 このメソッドは、現行スレッドのスタック・フレームの現在の状態に関する情報を、このThrowableオブジェクト内に記録します。

        このThrowableのスタック・トレースが書込み可能でない場合、このメソッドを呼び出しても何の効果もありません。

        戻り値:
        このThrowableインスタンスへの参照。
        関連項目:
        printStackTrace()

      • getStackTrace

        public StackTraceElement[] getStackTrace()
        printStackTrace()によって出力されるスタック・トレース情報にプログラムでアクセスできるようにします。 それぞれがスタック・フレームを表す、スタック・トレース要素の配列を返します。 配列の長さがゼロ以外であると仮定した場合のゼロ番目の要素は、スタックの最上部を表します。これはシーケンスで呼び出された最後のメソッドです。 通常、これは、このスロー可能オブジェクトが作成されてスローされたポイントになります。 配列の長さがゼロ以外であると仮定した場合の最後の要素は、スタックの最下部を表します。これはシーケンスで呼び出された最初のメソッドです。

        仮想マシンの中には、特定の状況下でスタック・トレースから1つ以上のスタック・フレームを省略するものがあります。 極端な場合、このスロー可能オブジェクトに関するスタック・トレース情報を保持しない仮想マシンが、このメソッドから長さゼロの配列を返すことが許可されます。 一般に、このメソッドにより返される配列は、printStackTraceにより出力されるフレームごとに1つの要素を格納します。 返された配列への書込みを行っても、このメソッドのその後の呼出しには何の影響もありません。

        戻り値:
        このスロー可能オブジェクトに関するスタック・トレースを表す、スタック・トレース要素の配列。
        導入されたバージョン:
        1.4

      • setStackTrace

        public void setStackTrace​(StackTraceElement[] stackTrace)
        getStackTrace()によって返され、printStackTrace()と関連メソッドによって出力される、スタック・トレース要素を設定します。 このメソッドは、RPCフレームワークおよび他の高性能システムでの使用を目的に設計されており、クライアントがデフォルト・スタック・トレースをオーバーライドできるようにします。デフォルト・スタック・トレースは、スロー可能オブジェクトの構築時にfillInStackTrace()により生成されるか、スロー可能オブジェクトが直列化ストリームから読み取られる際に直列化復元されます。

        このThrowableのスタック・トレースが書込み可能でない場合、このメソッドを呼び出しても、その引数を検証すること以外の効果は何もありません。

        パラメータ:
        stackTrace - このThrowableと関連付けるスタック・トレース要素。 指定された配列は、この呼出しによりコピーされる。メソッド呼出しの復帰後に、指定された配列内で行われた変更は、Throwableのスタック・トレースに影響を及ぼさない。
        例外:
        NullPointerException - stackTraceがnullの場合、またはstackTraceのいずれの要素がnullの場合
        導入されたバージョン:
        1.4

      • addSuppressed

        public final void addSuppressed​(Throwable exception)
        この例外を提供する目的で抑制された例外に、指定された例外を追加します。 このメソッドはスレッドセーフであり、通常は、try-with-resources文によって(自動的かつ暗黙的に)呼び出されます。

        抑制の動作は、コンストラクタ経由で無効化されないかぎり、有効化されます。 抑制が無効になっている場合、このメソッドが行うのは、その引数を検証することだけです。

        ある例外が別の例外の原因となる場合、通常は、最初の例外がキャッチされたあと、応答として2番目の例外がスローされます。 つまり、この2つの例外の間には因果関係が存在します。 これに対し、兄弟関係にあるコード・ブロック内(特にtry-with-resources文のtryブロック内と、リソースを閉じるコンパイラ生成finallyブロック内)で独立した2つの例外がスローされる可能性があるような状況も存在します。 こうした状況では、スローされた例外のいずれか1つしか伝播させることができません。 try-with-resources文にそのような例外が2つ存在している場合、tryブロックから発行された例外が伝播され、finallyブロックからの例外は、tryブロックからの例外によって抑制された例外のリストに追加されます。 例外でのスタックのアンワインドが進むにつれ、抑制済みの例外が複数個蓄積される可能性があります。

        ある例外が、抑制済みの例外を持つ一方で、同時に別の例外を原因として持つことがあります。 ある例外の原因が存在するかどうかはその作成時に意味的に知られますが、これは、ある例外がほかの例外を抑制するかどうかの判定は通常、その例外スローがされたあとでしか判定できないのと異なります。

        またプログラマによって記述されたコードでも、兄弟関係の例外が複数存在し、伝播できるのはその一方のみであるような状況では、このメソッドの呼出しを活用できます。

        パラメータ:
        exception - 抑制済み例外リストに追加する例外
        例外:
        IllegalArgumentException - exceptionがこのスロー可能オブジェクトである場合。スロー可能オブジェクトが自分自身を抑制することはできない。
        NullPointerException - exceptionがnullである場合
        導入されたバージョン:
        1.7

      • getSuppressed

        public final Throwable[] getSuppressed()
        この例外を提供する目的で(通常try-with-resources文によって)抑制された例外をすべて含む配列を返します。 抑制された例外が1つも存在しないか、抑制が無効になっている場合は、空の配列が返されます。 このメソッドはスレッドセーフです。 返された配列への書込みを行っても、このメソッドのその後の呼出しには何の影響もありません。
        戻り値:
        この例外を提供する目的で抑制された例外をすべて含む配列。
        導入されたバージョン:
        1.7