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, ArithmeticExceptionpublic 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.(Resource2.java:45)
... 2 more
public void printStackTrace(PrintStream s)
s - 出力に使用する PrintStreampublic void printStackTrace(PrintWriter s)
s - 出力に使用する PrintWriterpublic 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, 2013, Oracle and/or its affiliates. All rights reserved.