java.lang
クラス Throwable

java.lang.Object
  java.lang.Throwable

すべての実装されたインタフェース:

Serializable

直系の既知のサブクラス:

Error, Exception

public class Throwable
extends Object
implements Serializable

Throwable クラスは、Java 言語のすべてのエラーと例外のスーパークラスです。このクラス （またはそのサブクラスの内の 1 つ） のインスタンスであるオブジェクトだけが Java 仮想マシンによってスローされるか、Java の throw 構文によってスローされます。同じように、このクラスまたはそのサブクラスの内の 1 つだけが catch 節の引数の型に指定できます。

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

スロー可能オブジェクトには、作成時のそのスレッドの実行スタックのスナップショットが含まれます。このクラスには、エラーについての詳細な情報を示すメッセージ文字列も含まれます。最終的に、これは「原因」 (このスロー可能オブジェクトのスローを引き起こした別のスロー可能オブジェクト) を含めることができます。原因機能は、リリース 1.4 の新機能です。これは、原因自体が原因を保持して例外の連鎖を作成できるため、「チェーンされた例外」機能とも呼ばれます。

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

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

原因は、2 つの方法でスロー可能オブジェクトに関連付けることができます。1 つは原因を引数として取るコンストラクタを使用する方法、もう 1 つは initCause(Throwable) メソッドを使用する方法です。原因の関連付けを可能にする新規スロー可能クラスは、原因を受け取るコンストラクタを提供し、原因を受け取るいずれかの Throwable コンストラクタに (通常間接的に) 委譲する必要があります。次に例を示します。

     try {
         lowLevelOp();
     } catch (LowLevelException le) {
         throw new HighLevelException(le);  // Chaining-aware constructor
     }
 

initCause メソッドは public であるため、原因を任意のスロー可能オブジェクトに関連付けることが可能です。これは、実装が例外チェーン機構の Throwable への追加に先行する「レガシースロー可能オブジェクト」であっても当てはまります。次に例を示します。

     try {
         lowLevelOp();
     } catch (LowLevelException le) {
         throw (HighLevelException)
                 new HighLevelException().initCause(le);  // Legacy constructor
     }
 

リリース 1.4 以前には、非標準の独自例外チェーン機構 (ExceptionInInitializerError、ClassNotFoundException、UndeclaredThrowableException、InvocationTargetException、WriteAbortedException、PrivilegedActionException、PrinterIOException、RemoteException、および NamingException) を保持する多数のスロー可能オブジェクトが存在していました。リリース 1.4 では、これらのスロー可能オブジェクトはすべて、互換性のために「従来の」連鎖機構の実装を維持しつつ、標準の例外連鎖機構を使用できるように改良されています。

さらに、リリース 1.4 では、多数の汎用 Throwable クラス (Exception、RuntimeException、Error など) が、原因を取るコンストラクタに合わせて改良されています。initCause メソッドがすでに存在しているため、これは厳密には必須というわけではありませんが、原因を取るコンストラクタへの委譲を行うより簡便かつ表現力のある方法です。

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

また、リリース 1.4 では、getStackTrace() メソッドも導入されました。このメソッドを使用すると、これまで printStackTrace() メソッドを使用してテキスト形式でしか利用できなかったスタックトレース情報に、プログラム化されたアクセスを実行できます。この情報がこのクラスの「直列化表現」に追加されたため、getStackTrace および printStackTrace が直列化復元により取得されたスロー可能オブジェクトに対して適正に機能します。

導入されたバージョン:

JDK1.0

関連項目:

直列化された形式

コンストラクタの概要

Throwable()
詳細メッセージに null を使用して、新規スロー可能オブジェクトを構築します。

Throwable(String message)
指定された詳細メッセージを使用して、新規スロー可能オブジェクトを構築します。

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

Throwable(Throwable cause)
(cause==null ? null : cause.toString()) の指定された原因および詳細メッセージを使用して新規例外を構築します。

メソッドの概要

Throwable	fillInStackTrace() 実行スタックトレースを埋め込みます。
Throwable	getCause() 原因が存在しないか不明な場合に、この Throwable または null の原因を返します。
String	getLocalizedMessage() このスロー可能オブジェクトの、地域対応された記述を作成します。
String	getMessage() この Throwable オブジェクトの詳細メッセージ文字列を返します。
StackTraceElement[]	getStackTrace() printStackTrace() により出力されたスタックトレース情報への、プログラム化されたアクセスを提供します。
Throwable	initCause(Throwable cause) 指定された値に対するこの Throwable の「原因」を初期化します。
void	printStackTrace() このスロー可能オブジェクトおよびそのバックトレースを標準エラーストリームに出力します。
void	printStackTrace(PrintStream s) このスロー可能オブジェクトとそのバックトレースを指定された印刷ストリームに出力します。
void	printStackTrace(PrintWriter s) このスロー可能オブジェクトとそのバックトレースを指定されたプリントライターに出力します。
void	setStackTrace(StackTraceElement[] stackTrace) getStackTrace() により返され、printStackTrace() および関連するメソッドにより出力される、スタックトレース要素を設定します。
String	toString() このスロー可能オブジェクトの短い記述を返します。

クラス java.lang.Object から継承されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

コンストラクタの詳細

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==null ? null : cause.toString()) には、cause のクラスおよび詳細メッセージが含まれます。このコンストラクタは、スロー可能オブジェクトが他のスロー可能オブジェクト (PrivilegedActionException など) のラッパーである場合に有用です。

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

パラメータ:

cause - 原因 (あとで getCause() メソッドで取得するために保存される)。null 値が許可されており、原因が存在しないか不明であることを示す

導入されたバージョン:

1.4

メソッドの詳細

getMessage

public String getMessage()

この Throwable オブジェクトの詳細メッセージ文字列を返します。

戻り値:

この Throwable インスタンスの詳細メッセージ文字列 (null も可)

getLocalizedMessage

public String getLocalizedMessage()

このスロー可能オブジェクトの、地域対応された記述を作成します。サブクラスはこのメソッドをオーバーライドして、ロケールに固有のメッセージを作成できます。このメソッドをオーバーライドしないサブクラスの場合は、デフォルトの実装によって getMessage() と同じ結果が返されます。

戻り値:

このスロー可能オブジェクトの、地域対応された記述

導入されたバージョン:

JDK1.1

getCause

public Throwable getCause()

原因が存在しないか不明な場合に、この Throwable または null の原因を返します。原因はこの Throwable をスローさせた Throwable です。

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

戻り値:

スロー可能なオブジェクトの原因。原因が存在しないか不明の場合は null

導入されたバージョン:

1.4

initCause

public Throwable initCause(Throwable cause)

指定された値に対するこの Throwable の「原因」を初期化します。原因はこの Throwable をスローさせた Throwable です。

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

パラメータ:

cause - 原因 (あとで getCause() メソッドで取得するために保存される)。null 値が許可されており、原因が存在しないか不明であることを示す

戻り値:

この Throwable インスタンスへの参照

例外:

IllegalArgumentException - cause がこの Throwable である場合 (Throwable はそれ自身の原因にはなれない)

IllegalStateException - このスロー可能オブジェクトが Throwable(Throwable) または Throwable(String,Throwable) を使用して作成されたか、このメソッドがこのスロー可能オブジェクトに対して呼び出しを実行済みである場合

導入されたバージョン:

1.4

toString

public String toString()

このスロー可能オブジェクトの短い記述を返します。この Throwable オブジェクトが非 null の詳細メッセージ文字列を使用して作成された場合、結果は次の 3 つの文字列を連結したものになります。

• このオブジェクト実際のクラス名
• ": " (コロンとスペース)
• このオブジェクトに対する getMessage() メソッドの結果

この Throwable オブジェクトが null の詳細メッセージ文字列を使用して作成された場合は、このオブジェクトの実際のクラス名が返されます。

オーバーライド:

クラス Object 内の toString

戻り値:

このスロー可能オブジェクトの文字列表現

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 {
 }
 

printStackTrace

public void printStackTrace(PrintStream s)

このスロー可能オブジェクトとそのバックトレースを指定された印刷ストリームに出力します。

パラメータ:

s - 出力に使用する PrintStream

printStackTrace

public void printStackTrace(PrintWriter s)

このスロー可能オブジェクトとそのバックトレースを指定されたプリントライターに出力します。

パラメータ:

s - 出力に使用する PrintWriter

導入されたバージョン:

JDK1.1

fillInStackTrace

public Throwable fillInStackTrace()

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

戻り値:

この Throwable インスタンスへの参照

関連項目:

printStackTrace()

getStackTrace

public StackTraceElement[] getStackTrace()

printStackTrace() により出力されたスタックトレース情報への、プログラム化されたアクセスを提供します。スタックトレース要素 (各要素は 1 つのスタックフレームを表す) の配列を返します。配列のゼロ番目の要素 (配列の長さがゼロでない場合) は、スタックの先頭 (一連のメソッド呼び出しの最後) を表します。通常、これはスロー可能オブジェクトが作成およびスローされたポイントです。配列の最後の要素 (配列の長さがゼロではない場合) は、スタックの末尾 (一連のメソッド呼び出しの最初) を表します。

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

戻り値:

このスロー可能オブジェクトに関するスタックトレースを表す、スタックトレース要素の配列

導入されたバージョン:

1.4

setStackTrace

public void setStackTrace(StackTraceElement[] stackTrace)

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

パラメータ:

stackTrace - この Throwable と関連付けるスタックトレース要素。指定された配列は、この呼び出しによりコピーされる。メソッド呼び出しの復帰後に、指定された配列内で行われた変更は、Throwable のスタックトレースに影響を及ぼさない

例外:

NullPointerException - stackTrace が null の場合、または stackTrace のいずれかの要素が null の場合

導入されたバージョン:

1.4