|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
前のクラス 次のクラス | フレームあり フレームなし | |||||||||
概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド |
java.lang.Objectjava.lang.Throwable
public class Throwable
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 が直列化復元により取得されたスロー可能オブジェクトに対して適正に機能します。
コンストラクタの概要 | |
---|---|
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 |
コンストラクタの詳細 |
---|
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)
PrivilegedActionException
など) のラッパーである場合に有用です。
fillInStackTrace()
メソッドを呼び出して、新規作成されたスロー可能オブジェクト内のスタックトレースデータを初期化します。
cause
- 原因 (あとで getCause()
メソッドで取得するために保存される)。null 値が許可されており、原因が存在しないか不明であることを示すメソッドの詳細 |
---|
public String getMessage()
public String getLocalizedMessage()
getMessage()
と同じ結果が返されます。
public Throwable getCause()
null
の原因を返します。原因はこの Throwable をスローさせた Throwable です。
この実装は、Throwable を要求するいずれかのコンストラクタ経由で提供された原因、または initCause(Throwable)
メソッドを使用して作成後に設定された原因を返します。通常、このメソッドをオーバーライドする必要はありませんが、サブクラスはこのメソッドをオーバーライドして、他の何らかの方法で設定された原因を返すことができます。これは、チェーンされた例外の Throwable への追加前に実行される「レガシー連鎖スロー可能オブジェクト」の場合に適切な動作です。PrintStackTrace メソッドのいずれかをオーバーライドする必要はありません。これらのメソッドはすべて getCause メソッドを呼び出して、スロー可能オブジェクトの原因を判別します。
null
public Throwable initCause(Throwable cause)
このメソッドは、1 回だけ呼び出すことができます。通常、このメソッドは、コンストラクタ内部から呼び出されるか、スロー可能オブジェクトの作成後すぐに呼び出されます。Throwable(Throwable)
または Throwable(String,Throwable)
を使用してこのスロー可能オブジェクトを作成した場合、このメソッドを一度も呼び出すことはできません。
cause
- 原因 (あとで getCause()
メソッドで取得するために保存される)。null 値が許可されており、原因が存在しないか不明であることを示す
Throwable
インスタンスへの参照
IllegalArgumentException
- cause
がこの Throwable である場合 (Throwable はそれ自身の原因にはなれない)
IllegalStateException
- このスロー可能オブジェクトが Throwable(Throwable)
または Throwable(String,Throwable)
を使用して作成されたか、このメソッドがこのスロー可能オブジェクトに対して呼び出しを実行済みである場合public String toString()
Throwable
オブジェクトが非 null の詳細メッセージ文字列を使用して作成された場合、結果は次の 3 つの文字列を連結したものになります。getMessage()
メソッドの結果
Throwable
オブジェクトが null の詳細メッセージ文字列を使用して作成された場合は、このオブジェクトの実際のクラス名が返されます。
Object
内の toString
public void printStackTrace()
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 { }
public void printStackTrace(PrintStream s)
s
- 出力に使用する PrintStream
public void printStackTrace(PrintWriter s)
s
- 出力に使用する PrintWriter
public Throwable fillInStackTrace()
Throwable
オブジェクト内に記録します。
Throwable
インスタンスへの参照printStackTrace()
public StackTraceElement[] getStackTrace()
printStackTrace()
により出力されたスタックトレース情報への、プログラム化されたアクセスを提供します。スタックトレース要素 (各要素は 1 つのスタックフレームを表す) の配列を返します。配列のゼロ番目の要素 (配列の長さがゼロでない場合) は、スタックの先頭 (一連のメソッド呼び出しの最後) を表します。通常、これはスロー可能オブジェクトが作成およびスローされたポイントです。配列の最後の要素 (配列の長さがゼロではない場合) は、スタックの末尾 (一連のメソッド呼び出しの最初) を表します。
仮想マシンの中には、特定の状況下でスタックトレースから 1 つ以上のスタックフレームを省略するものがあります。極端な場合、このスロー可能オブジェクトに関するスタックトレース情報を保持しない仮想マシンが、このメソッドから長さゼロの配列を返すことが許可されます。一般に、このメソッドにより返される配列は、printStackTrace により出力されるフレームごとに 1 つの要素を格納します。
public void setStackTrace(StackTraceElement[] stackTrace)
getStackTrace()
により返され、printStackTrace()
および関連するメソッドにより出力される、スタックトレース要素を設定します。
このメソッドは、RPC フレームワークおよび他の高性能システムでの使用を目的に設計されており、クライアントがデフォルトスタックトレースをオーバーライドできるようにします。デフォルトスタックトレースは、スロー可能オブジェクトの構築時に fillInStackTrace()
により生成されるか、スロー可能オブジェクトが直列化ストリームから読み込む際に直列化復元されます。
stackTrace
- この Throwable
と関連付けるスタックトレース要素。指定された配列は、この呼び出しによりコピーされる。メソッド呼び出しの復帰後に、指定された配列内で行われた変更は、Throwable
のスタックトレースに影響を及ぼさない
NullPointerException
- stackTrace
が null
の場合、または stackTrace
のいずれかの要素が null
の場合
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
前のクラス 次のクラス | フレームあり フレームなし | |||||||||
概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド |
Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Documentation Redistribution Policy も参照してください。