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
(原因)を取ります。
修飾子 | コンストラクタと説明 |
---|---|
|
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 のクラスと詳細メッセージを含みます)。 |
修飾子と型 | メソッドと説明 |
---|---|
void |
addSuppressed(Throwable exception)
この例外を提供する目的で抑制された例外に、指定された例外を追加します。
|
Throwable |
fillInStackTrace()
実行スタック・トレースを埋め込みます。
|
Throwable |
getCause()
このスロー可能オブジェクトの原因を返しますが、原因が存在しないか不明な場合は
null を返します。 |
String |
getLocalizedMessage()
このスロー可能オブジェクトの、ローカライズされた記述を作成します。
|
String |
getMessage()
このスロー可能オブジェクトの詳細メッセージ文字列を返します。
|
StackTraceElement[] |
getStackTrace()
printStackTrace() によって出力されるスタック・トレース情報にプログラムでアクセスできるようにします。 |
Throwable[] |
getSuppressed()
この例外を提供する目的で(通常
try -with-resources文によって)抑制された例外をすべて含む配列を返します。 |
Throwable |
initCause(Throwable cause)
このスロー可能オブジェクトの原因を、指定された値に初期化します。
|
void |
printStackTrace()
このスロー可能オブジェクトおよびそのバックトレースを標準エラー・ストリームに出力します。
|
void |
printStackTrace(PrintStream s)
このスロー可能オブジェクトとそのバックトレースを指定された印刷ストリームに出力します。
|
void |
printStackTrace(PrintWriter s)
このスロー可能オブジェクトとそのバックトレースを指定されたプリント・ライターに出力します。
|
void |
setStackTrace(StackTraceElement[] stackTrace)
getStackTrace() によって返され、printStackTrace() と関連メソッドによって出力される、スタック・トレース要素を設定します。 |
String |
toString()
このスロー可能オブジェクトの短い記述を返します。
|
public Throwable()
null
である新規スロー可能オブジェクトを構築します。原因は初期化されません。initCause(java.lang.Throwable)
を呼び出すことによって、あとでこれを初期化することができます。
fillInStackTrace()
メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。
public Throwable(String message)
initCause(java.lang.Throwable)
を呼び出すことによって、あとでこれを初期化することができます。
fillInStackTrace()
メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。
message
- 詳細メッセージ。詳細メッセージは、あとでgetMessage()
メソッドで取得できるように保存されます。public Throwable(String message, Throwable cause)
cause
と関連付けられた詳細メッセージが、このスロー可能オブジェクトの詳細メッセージに自動的に統合されることはありません。
fillInStackTrace()
メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。
message
- 詳細メッセージ(あとでgetMessage()
メソッドで取得できるように保存される)。cause
- 原因(あとでgetCause()
メソッドで取得できるように保存される)。(null
値が許可されており、原因が存在しないか不明であることを示す。)public Throwable(Throwable cause)
(cause==null ? null : cause.toString())
を使って新しいスロー可能オブジェクトを構築します(通常、cause
のクラスと詳細メッセージを含みます)。このコンストラクタは、スロー可能オブジェクトがほかのスロー可能オブジェクト(PrivilegedActionException
など)のラッパーである場合に有用です。
fillInStackTrace()
メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタック・トレース・データを初期化します。
cause
- 原因(あとでgetCause()
メソッドで取得できるように保存される)。(null
値が許可されており、原因が存在しないか不明であることを示す。)protected Throwable(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace)
getSuppressed()
から長さゼロの配列が返され、通常であれば抑制リストに例外を追加するはずのaddSuppressed(java.lang.Throwable)
呼出しが、何の効果も持たなくなります。書込み可能スタック・トレースがfalseの場合、このコンストラクタからfillInStackTrace()
が呼び出されず、stackTrace
フィールドにはnull
が書き込まれ、以降にfillInStackTrace
やsetStackTrace(StackTraceElement[])
を呼び出してもスタック・トレースは設定されません。書込み可能スタック・トレースがfalseの場合、getStackTrace()
から長さゼロの配列が返されます。
Throwable
のほかのコンストラクタでは、抑制は有効であり、スタック・トレースも書込み可能であるとみなされます。Throwable
のサブクラスでは、抑制が無効になる条件をすべてドキュメント化するほか、スタック・トレースが書込み可能でなくなる条件もドキュメント化しておくべきです。抑制の無効化が発生するのは、メモリーの少ない状況で仮想マシンが例外オブジェクトを再利用する場合など、特殊な要件が存在する例外的な状況の場合だけにすべきです。2つのサブシステム間の制御フローを実装する目的などで、ある特定の例外オブジェクトのキャッチと再スローが繰り返されるような状況も、不変のスロー可能オブジェクトが適する状況の一例です。
message
- 詳細メッセージ。cause
- 原因。(null
値が許可されており、原因が存在しないか不明であることを示す。)enableSuppression
- 抑制を有効化するか、それとも無効化するかwritableStackTrace
- スタック・トレースを書込み可能にするかどうかOutOfMemoryError
, NullPointerException
, ArithmeticException
public String getMessage()
Throwable
インスタンスの詳細メッセージ文字列(null
も可)。public String getLocalizedMessage()
getMessage()
と同じ結果が返されます。public Throwable getCause()
null
を返します。(原因はこのスロー可能オブジェクトをスローさせたスロー可能オブジェクトです。)
この実装は、Throwable
を要求するいずれかのコンストラクタ経由で提供された原因、またはinitCause(Throwable)
メソッドを使用して作成後に設定された原因を返します。通常、このメソッドをオーバーライドする必要はありませんが、サブクラスはこのメソッドをオーバーライドして、ほかの何らかの方法で設定された原因を返すことができます。これは、チェーンされた例外のThrowable
への追加前に実行される「レガシー連鎖スロー可能オブジェクト」の場合に適切な動作です。PrintStackTrace
メソッドのいずれかをオーバーライドする必要はありません。これらのメソッドはすべてgetCause
メソッドを呼び出して、スロー可能オブジェクトの原因を判別します。
null
。public Throwable initCause(Throwable cause)
このメソッドは最大で1回しか呼び出すことができません。通常は、コンストラクタ内から、またはスロー可能オブジェクトの作成直後に呼び出されます。このスロー可能オブジェクトが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)
で作成されたものである場合、あるいはこのスロー可能オブジェクトでこのメソッドがすでに呼び出されていた場合。public String toString()
getLocalizedMessage()
メソッドを呼び出した結果
getLocalizedMessage
がnull
を返す場合、クラス名のみが返されます。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
public void printStackTrace(PrintStream s)
s
- 出力に使用するPrintStream
public void printStackTrace(PrintWriter s)
s
- 出力に使用するPrintWriter
public Throwable fillInStackTrace()
Throwable
オブジェクト内に記録します。
このThrowable
のスタック・トレースが書込み可能でない場合、このメソッドを呼び出しても何の効果もありません。
Throwable
インスタンスへの参照。printStackTrace()
public StackTraceElement[] getStackTrace()
printStackTrace()
によって出力されるスタック・トレース情報にプログラムでアクセスできるようにします。それぞれがスタック・フレームを表す、スタック・トレース要素の配列を返します。配列の長さがゼロ以外であると仮定した場合のゼロ番目の要素は、スタックの最上部を表します。これはシーケンスで呼び出された最後のメソッドです。通常、これは、このスロー可能オブジェクトが作成されてスローされたポイントになります。配列の長さがゼロ以外であると仮定した場合の最後の要素は、スタックの最下部を表します。これはシーケンスで呼び出された最初のメソッドです。
仮想マシンの中には、特定の状況下でスタック・トレースから1つ以上のスタック・フレームを省略するものがあります。極端な場合、このスロー可能オブジェクトに関するスタック・トレース情報を保持しない仮想マシンが、このメソッドから長さゼロの配列を返すことが許可されます。一般に、このメソッドにより返される配列は、printStackTrace
により出力されるフレームごとに1つの要素を格納します。返された配列への書込みを行っても、このメソッドのその後の呼出しには何の影響もありません。
public void setStackTrace(StackTraceElement[] stackTrace)
getStackTrace()
によって返され、printStackTrace()
と関連メソッドによって出力される、スタック・トレース要素を設定します。このメソッドは、RPCフレームワークおよび他の高性能システムでの使用を目的に設計されており、クライアントがデフォルト・スタック・トレースをオーバーライドできるようにします。デフォルト・スタック・トレースは、スロー可能オブジェクトの構築時にfillInStackTrace()
により生成されるか、スロー可能オブジェクトが直列化ストリームから読み取られる際に直列化復元されます。
このThrowable
のスタック・トレースが書込み可能でない場合、このメソッドを呼び出しても、その引数を検証すること以外の効果は何もありません。
stackTrace
- このThrowable
と関連付けるスタック・トレース要素。指定された配列は、この呼出しによりコピーされる。メソッド呼出しの復帰後に、指定された配列内で行われた変更は、Throwable
のスタック・トレースに影響を及ぼさない。NullPointerException
- stackTrace
がnull
の場合、またはstackTrace
のいずれの要素がnull
の場合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
である場合public final Throwable[] getSuppressed()
try
-with-resources文によって)抑制された例外をすべて含む配列を返します。抑制された例外が1つも存在しないか、抑制が無効になっている場合は、空の配列が返されます。このメソッドはスレッドセーフです。返された配列への書込みを行っても、このメソッドのその後の呼出しには何の影響もありません。 バグまたは機能を送信
詳細なAPIリファレンスおよび開発者ドキュメントについては、Java SEのドキュメントを参照してください。そのドキュメントには、概念的な概要、用語の定義、回避方法、有効なコード例などの、開発者を対象にしたより詳細な説明が含まれています。
Copyright © 1993, 2020, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Documentation Redistribution Policyも参照してください。