- すべての実装されたインタフェース:
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
(原因)を取ります。
- Java言語仕様を参照してください:
-
11.2コンパイル時の例外検査
- 導入されたバージョン:
- 1.0
- 関連項目:
- 直列化された形式
-
コンストラクタのサマリー
コンストラクタ修飾子コンストラクタ説明詳細メッセージがnull
である新規スロー可能オブジェクトを構築します。指定された詳細メッセージを使用して、新規スロー可能オブジェクトを構築します。指定された詳細メッセージおよび原因を使用して新規スロー可能オブジェクトを構築します。protected
指定された詳細メッセージ、原因、抑制の有効化または無効化、書込み可能スタック・トレースの有効化または無効化に基づいて、新しいスロー可能オブジェクトを構築します。指定された原因と詳細メッセージ(cause==null ? null : cause.toString())
を使って新しいスロー可能オブジェクトを構築します(通常、cause
のクラスと詳細メッセージを含みます)。 -
メソッドのサマリー
修飾子と型メソッド説明void
addSuppressed(Throwable exception)
この例外を提供する目的で抑制された例外に、指定された例外を追加します。実行スタック・トレースを埋め込みます。getCause()
このスロー可能オブジェクトの原因を返しますが、原因が存在しないか不明な場合はnull
を返します。このスロー可能オブジェクトの、ローカライズされた記述を作成します。このスロー可能オブジェクトの詳細メッセージ文字列を返します。printStackTrace()
によって出力されるスタック・トレース情報にプログラムでアクセスできるようにします。この例外を提供する目的で(通常try
-with-resources文によって)抑制された例外をすべて含む配列を返します。このスロー可能オブジェクトの原因を、指定された値に初期化します。void
このスロー可能オブジェクトおよびそのバックトレースを標準エラー・ストリームに出力します。void
このスロー可能オブジェクトとそのバックトレースを指定された印刷ストリームに出力します。void
このスロー可能オブジェクトとそのバックトレースを指定されたプリント・ライターに出力します。void
setStackTrace(StackTraceElement[] stackTrace)
getStackTrace()
によって返され、printStackTrace()
と関連メソッドによって出力される、スタック・トレース要素を設定します。toString()
このスロー可能オブジェクトの短い記述を返します。
-
コンストラクタの詳細
-
Throwable
public Throwable()詳細メッセージがnull
である新規スロー可能オブジェクトを構築します。 原因は初期化されません。initCause(java.lang.Throwable)
を呼び出すことによって、あとでこれを初期化することができます。fillInStackTrace()
メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。 -
Throwable
public Throwable(String message)指定された詳細メッセージを使用して、新規スロー可能オブジェクトを構築します。 原因は初期化されません。initCause(java.lang.Throwable)
を呼び出すことによって、あとでこれを初期化することができます。fillInStackTrace()
メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。- パラメータ:
message
- 詳細メッセージ。 詳細メッセージは、あとでgetMessage()
メソッドで取得できるように保存されます。
-
Throwable
指定された詳細メッセージおよび原因を使用して新規スロー可能オブジェクトを構築します。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をスローさせたThrowableです。この実装は、
Throwable
を要求するいずれかのコンストラクタ経由で提供された原因、またはinitCause(Throwable)
メソッドを使用して作成後に設定された原因を返します。 通常、このメソッドをオーバーライドする必要はありませんが、サブクラスはこのメソッドをオーバーライドして、他のなんらかの方法で設定された原因を返すことができます。 これは、チェーンされた例外をThrowable
に追加する前に実行される「レガシー連鎖スロー可能オブジェクト」の場合に適切な動作です。PrintStackTrace
メソッドは、いずれもオーバーライドする必要はありません。これらのメソッドはすべてgetCause
メソッドを呼び出して、スロー可能オブジェクトの原因を判別します。- 戻り値:
- このスロー可能オブジェクトの原因。原因が存在しないか不明の場合は
null
。 - 導入されたバージョン:
- 1.4
-
initCause
このスロー可能オブジェクトの原因を、指定された値に初期化します。 原因はこのThrowableをスローさせたThrowableです。このメソッドは最大で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
がこのスロー可能オブジェクトである場合。 (Throwableはそれ自身の原因にはなれない)IllegalStateException
- このスロー可能オブジェクトがThrowable(Throwable)
またはThrowable(String,Throwable)
で作成されたものである場合、あるいはこのスロー可能オブジェクトでこのメソッドがすでに呼び出されていた場合。- 導入されたバージョン:
- 1.4
-
toString
public String toString()このスロー可能オブジェクトの短い記述を返します。 結果は次のものを連結したものになります。- このオブジェクトのクラスの名前
- ": " (コロンとスペース)
- このオブジェクトの
getLocalizedMessage()
メソッドを呼び出した結果
getLocalizedMessage
がnull
を返す場合、クラス名のみが返されます。 -
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詳細"表記法は、原因で使用するのと同じように抑制された例外で使用されます。 抑制された例外は原因と場合と異なり、「包括元の例外」を超えてインデントされます。ある例外が、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
-