CDC 1.1.2

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 以前には、非標準の独自例外チェーン機構 (ExceptionInInitializerErrorClassNotFoundExceptionUndeclaredThrowableExceptionInvocationTargetExceptionWriteAbortedExceptionPrivilegedActionException、および java.rmi.RemoteException) を保持する多数のスロー可能オブジェクトが存在していました。Release 1.4 では、これらのスロー可能オブジェクトはすべて、互換性のために「従来の」連鎖機構の実装を維持しつつ、標準の例外連鎖機構を使用できるように改良されています。注:java.rmi.RemoteException は、J2ME RMI オプションパッケージなどの J2ME CDC のオプションパッケージ群に含まれます。

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

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

また、Release 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()) を持つ、新しいスロー可能オブジェクトを構築します。通常、クラスと原因の詳細メッセージを含みます。このコンストラクタは、スロー可能オブジェクトがほかのスロー可能オブジェクト (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) または Throwable(String,Throwable) を使用してこのスロー可能オブジェクトを作成した場合、このメソッドを一度も呼び出すことはできません。

パラメータ:
cause - 原因 (あとで getCause() メソッドで取得するために保存される)。null 値が許可されており、原因が存在しないか不明であることを示す
戻り値:
この Throwable インスタンスへの参照
例外:
IllegalArgumentException - ifcause がこの Throwable である場合 (Throwable はそれ自身の原因にはなれない)
IllegalStateException - このスロー可能オブジェクトが Throwable(Throwable) または Throwable(String,Throwable) を使用して作成されたか、このメソッドがこのスロー可能オブジェクトに対して呼び出しを実行済みである場合
導入されたバージョン:
1.4

toString

public String toString()
このスロー可能オブジェクトの短い記述を返します。この Throwable オブジェクトが null でない詳細メッセージ文字列を使って作成された場合、結果は次の 3 つの文字列を連結したものになります。 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 つ以上のスタックフレームを省略するものがあります。極端な場合、このスロー可能オブジェクトに関するスタックトレース情報を保持しない仮想マシンが、このメソッドから長さゼロの配列を返すことが許可されます。一般に、このメソッドにより返される配列は、printStackTrace により出力されるフレームごとに 1 つの要素を格納します。

戻り値:
このスロー可能オブジェクトに関するスタックトレースを表す、スタックトレース要素の配列
導入されたバージョン:
1.4

setStackTrace

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

パラメータ:
stackTrace - この Throwable と関連付けるスタックトレース要素。指定された配列は、この呼び出しによりコピーされる。メソッド呼び出しの復帰後に、指定された配列内で行われた変更は、Throwable のスタックトレースに影響を及ぼさない
例外:
NullPointerException - stackTracenull の場合、または stackTrace のいずれかの要素が null の場合
導入されたバージョン:
1.4

CDC 1.1.2

Copyright 2006 Sun Microsystems, Inc. All Rights Reserved. Use of this specification is subject to license terms.