java.lang.Throwable
|
CDC 1.1.2 | |||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||
java.lang.Object
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、および java.rmi.RemoteException) を保持する多数のスロー可能オブジェクトが存在していました。Release 1.4 では、これらのスロー可能オブジェクトはすべて、互換性のために「従来の」連鎖機構の実装を維持しつつ、標準の例外連鎖機構を使用できるように改良されています。注:java.rmi.RemoteException は、J2ME RMI オプションパッケージなどの J2ME CDC のオプションパッケージ群に含まれます。
さらに、Release 1.4 では、多数の汎用 Throwable クラス (Exception、RuntimeException、Error など) が、原因を取るコンストラクタに合わせて改良されています。initCause メソッドがすでに存在しているため、これは厳密には必須というわけではありませんが、原因を取るコンストラクタへの委譲を行うより簡便かつ表現力のある方法です。
従来、Throwable クラスおよびそのサブクラスは 2 つのコンストラクタを保持します。 1 つは引数を取らず、もう 1 つは詳細メッセージの生成に使用可能な String 引数を取ります。また、関連付けられた原因を保持可能なこれらのサブクラスは、さらに 2 つのコンストラクタを保持します。 1 つは Throwable (原因) を取り、もう 1 つは String (詳細メッセージ) および Throwable (原因) を取ります。
また、Release 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 メソッドを呼び出して、スロー可能オブジェクトの原因を判別します。
nullpublic Throwable initCause(Throwable cause)
このメソッドは最大で 1 回しか呼び出すことができません。通常は、コンストラクタ内から、または Throwable の作成直後に呼び出されます。Throwable(Throwable) または Throwable(String,Throwable) を使用してこのスロー可能オブジェクトを作成した場合、このメソッドを一度も呼び出すことはできません。
cause - 原因 (あとで getCause() メソッドで取得するために保存される)。null 値が許可されており、原因が存在しないか不明であることを示す
Throwable インスタンスへの参照
IllegalArgumentException - ifcause がこの Throwable である場合 (Throwable はそれ自身の原因にはなれない)
IllegalStateException - このスロー可能オブジェクトが Throwable(Throwable) または Throwable(String,Throwable) を使用して作成されたか、このメソッドがこのスロー可能オブジェクトに対して呼び出しを実行済みである場合public String toString()
Throwable オブジェクトが null でない詳細メッセージ文字列を使って作成された場合、結果は次の 3 つの文字列を連結したものになります。
getMessage() メソッドの結果
Throwable オブジェクトが null の詳細メッセージ文字列を使って作成された場合は、オブジェクトの実際のクラス名が返されます。
Object 内の toStringpublic 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 - 出力に使用する PrintStreampublic void printStackTrace(PrintWriter s)
s - 出力に使用する PrintWriterpublic Throwable fillInStackTrace()
Throwable オブジェクト内に記録します。
Throwable インスタンスへの参照printStackTrace()public StackTraceElement[] getStackTrace()
printStackTrace() によって提供されるスタックトレース情報にプログラムでアクセスできるようにします。それぞれがスタックフレームを表す、スタックトレース要素の配列を返します。配列の長さがゼロ以外であると仮定した場合のゼロ番目の要素は、スタックの最上部を表します。これはシーケンスで呼び出された最後のメソッドです。通常、これは、このスロー可能オブジェクトが作成されてスローされたポイントになります。配列の長さがゼロ以外であると仮定した場合の最後の要素は、スタックの最下部を表します。これはシーケンスで呼び出された最初のメソッドです。
仮想マシンの中には、特定の状況下でスタックトレースから 1 つ以上のスタックフレームを省略するものがあります。極端な場合、このスロー可能オブジェクトに関するスタックトレース情報を保持しない仮想マシンが、このメソッドから長さゼロの配列を返すことが許可されます。一般に、このメソッドにより返される配列は、printStackTrace により出力されるフレームごとに 1 つの要素を格納します。
public void setStackTrace(StackTraceElement[] stackTrace)
getStackTrace() により返され printStackTrace() により出力されるスタックトレース要素と関連メソッドを設定します。
このメソッドは、RPC フレームワークおよびほかの高性能システムでの使用を目的に設計されており、クライアントがデフォルトスタックトレースをオーバーライドできるようにします。 デフォルトスタックトレースは、スロー可能オブジェクトの構築時に fillInStackTrace() により生成されるか、スロー可能オブジェクトが直列化ストリームから読み込む際に直列化復元されます。
stackTrace - この Throwable と関連付けるスタックトレース要素。指定された配列は、この呼び出しによりコピーされる。メソッド呼び出しの復帰後に、指定された配列内で行われた変更は、Throwable のスタックトレースに影響を及ぼさない
NullPointerException - stackTrace が null の場合、または stackTrace のいずれかの要素が null の場合
|
CDC 1.1.2 | |||||||||
| 前のクラス 次のクラス | フレームあり フレームなし | |||||||||
| 概要: 入れ子 | フィールド | コンストラクタ | メソッド | 詳細: フィールド | コンストラクタ | メソッド | |||||||||