java.lang
類別 Throwable

java.lang.Object
  java.lang.Throwable

所有已實作的介面：

Serializable

直接已知子類別：

Error, Exception

public class Throwable
extends Object
implements Serializable

Throwable 類別是 Java 語言中所有錯誤或異常的父級類別。只有當物件是此類別（或其子類別之一）的實例時，才能通過 Java 虛擬機器或者 Java throw 語句拋出。類似地，只有此類別或其子類別之一才可以是 catch 子句中的參數型別。

兩個子類別的實例，Error 和 Exception，通常用於指示發生了異常情況。通常，這些實例是在異常情況的上下文中新近創建的，因此套件含了相關的資訊（比如堆疊(stack)空間追蹤資料）。

Throwable 套件含了其執行緒創建時執行緒執行堆疊(stack)空間的快照。它還包含了給出有關錯誤更多資訊的訊息字元串。最後，它還可以包含 cause（原因）：另一個導致此 throwable 拋出的 throwable。此 cause 設施在 1.4 版本中首次出現。它也稱為異常鏈 設施，因為 cause 自身也會有 cause，依此類別推，就形成了異常鏈，每個異常都是由另一個異常引起的。

導致 throwable cause 的一個理由是，拋出它的類別建構在低層抽象之中，而高層操作由於低層操作的失敗而失敗。讓低層拋出的 throwable 向外傳播是一種糟糕的設計方法，因為它通常與高層提供的抽象不相關。此外，這樣做將高層 API 與其實作細節關聯起來，假定低層異常是經過檢查的異常。拋出“經過包裹的異常”（即包含 cause 的異常）允許高層與其調用方交串流失敗詳細資訊，而不會招致上述任何一個缺點。這種方式保留了改變高層實作而不改變其 API 的靈活性（尤其是，異常集合通過其方法拋出）。

導致 throwable cause 的另一個 cause 是，拋出它的方法必須符合通用介面，而通用介面不允許方法直接拋出 cause。例如，假定持久集合符合 Collection 介面，而其持久性在 java.io 的基礎上實作。假定 add 方法的內部可以拋出 IOException。實作可以與其調用方交串流 IOException 的詳細訊息，同時通過以一種合適的未檢查的異常來包裹 IOException，使其符合 Collection 介面。（持久集合的規範應該指示它能夠拋出這種異常。）

Cause 可以通過兩種方式與 throwable 關聯起來：通過一個將 cause 看作參數的建構子；或者通過 initCause(Throwable) 方法。對於那些希望將 cause 與其關聯起來的新 throwable 類別，應該提供帶有 cause 的建構子，並委託（可能間接）給一個帶有 cause 的 Throwable 建構子。例如：

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

因為 initCause 方法是公共的，它允許 cause 與任何 throwable 相關聯，甚至包括“遺留 throwable”，它的實作提前將異常鏈機制的附件應用到 Throwable。例如：

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

在版本 1.4 之前，許多 throwable 有自己的非標準異常鏈機制（ ExceptionInInitializerError、 ClassNotFoundException、 UndeclaredThrowableException、 InvocationTargetException、 WriteAbortedException、 PrivilegedActionException、 PrinterIOException、 RemoteException 和 NamingException）。所有這些 throwable 都已經更新過，可以使用標準異常鏈機制，同時繼續實作其“遺留”鏈機制，以保持相容性。

此外，從版本 1.4 開始，許多通用的 Throwable 類別（例如，Exception、RuntimeException、Error）都已經更新，具有帶 cause 的建構子。由於有 initCause 方法存在，這不是嚴格要求的，但它更方便，也更形象地委託給一個帶有 cause 的建構子。

根據慣例，Throwable 類別及其子類別有兩個建構子，一個不帶參數，另一個帶有 String 參數，此參數可用於產生詳細訊息。此外，這些子類別很可能有與其相關聯的 cause，因此也應有兩個建構子，一個帶 Throwable (cause)，一個帶 String（詳細訊息）和 Throwable (cause)。

在版本 1.4 中還引入了 getStackTrace() 方法，它允許通過各種形式的 printStackTrace() 方法程式存取堆疊(stack)空間追蹤資訊，這些資訊以前只能以文本形式使用。此資訊已經添加到該類別的序列化表示形式，因此 getStackTrace 和 printStackTrace 將可在反序列化時獲得的 throwable 上正確操作。

從以下版本開始：

JDK1.0

另請參見：

序列化表格

建構子摘要

Throwable()
建構一個將 null 作為其詳細訊息的新 throwable。

Throwable(String message)
建構帶指定詳細訊息的新 throwable。

Throwable(String message, Throwable cause)
建構一個帶指定詳細訊息和 cause 的新 throwable。

Throwable(Throwable cause)
建構一個帶指定 cause 和 (cause==null ? null :cause.toString())（它通常包含類別和 cause 的詳細訊息）的詳細訊息的新 throwable。

方法摘要

Throwable	fillInStackTrace() 在異常堆疊(stack)空間追蹤中填充。
Throwable	getCause() 返回此 throwable 的 cause；如果 cause 不存在或未知，則返回 null。
String	getLocalizedMessage() 創建此 throwable 的本地化描述。
String	getMessage() 返回此 throwable 的詳細訊息字元串。
StackTraceElement[]	getStackTrace() 提供程式存取由 printStackTrace() 輸出的堆疊(stack)空間追蹤資訊。
Throwable	initCause(Throwable cause) 將此 throwable 的 cause 初始化為指定值。
void	printStackTrace() 將此 throwable 及其追蹤輸出至標準錯誤串流。
void	printStackTrace(PrintStream s) 將此 throwable 及其追蹤輸出到指定的輸出串流。
void	printStackTrace(PrintWriter s) 將此 throwable 及其追蹤輸出到指定的 PrintWriter。
void	setStackTrace(StackTraceElement[] stackTrace) 設置將由 getStackTrace() 返回，並由 printStackTrace() 和相關方法輸出的堆疊(stack)空間追蹤元素。
String	toString() 返回此 throwable 的簡短描述。

從類別 java.lang.Object 繼承的方法

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

建構子詳細資訊

Throwable

public Throwable()

建構一個將 null 作為其詳細訊息的新 throwable。Cause 尚未進行初始化，可在以後通過調用 initCause(java.lang.Throwable) 來初始化。

調用 fillInStackTrace() 方法來初始化新創建的 throwable 中的堆疊(stack)空間追蹤資料。

Throwable

public Throwable(String message)

建構帶指定詳細訊息的新 throwable。Cause 尚未進行初始化，可在以後通過調用 initCause(java.lang.Throwable) 來初始化。

調用 fillInStackTrace() 方法來初始化新創建的 throwable 中的堆疊(stack)空間追蹤資料。

參數：

message - 詳細訊息。保存這個詳細訊息，以便以後通過 getMessage() 方法對其進行獲取。

Throwable

public Throwable(String message,
                 Throwable cause)

建構一個帶指定詳細訊息和 cause 的新 throwable。

注意，與 cause 相關的詳細訊息不是 自動合併到這個 throwable 的詳細訊息中的。

調用 fillInStackTrace() 方法來初始化新創建的 throwable 中的堆疊(stack)空間追蹤資料。

參數：

message - 詳細訊息（保存此訊息，以便以後通過 getMessage() 方法獲取它）。

cause - 原因（保存此 cause，以便以後通過 getCause() 方法獲取它）。（允許 null 值，指出 cause 是不存在的或是未知的。）

從以下版本開始：

1.4

Throwable

public Throwable(Throwable cause)

建構一個帶指定 cause 和 (cause==null ? null :cause.toString())（它通常包含類別和 cause 的詳細訊息）的詳細訊息的新 throwable。此建構子對於那些與其他 throwable（例如，PrivilegedActionException）的套件裝器相同的 throwable 來說是有用的。

調用 fillInStackTrace() 方法來初始化新創建的 throwable 中的堆疊(stack)空間追蹤資料。

參數：

cause - 原因（保存此 cause，以便以後通過 getCause() 方法獲取它）。（允許 null 值，指出 cause 是不存在的或是未知的。）

從以下版本開始：

1.4

方法詳細資訊

getMessage

public String getMessage()

返回此 throwable 的詳細訊息字元串。

返回：

此 Throwable 實例（可以為 null）的詳細訊息字元串。

getLocalizedMessage

public String getLocalizedMessage()

創建此 throwable 的本地化描述。子類別可以覆寫此方法，以便產生特定於語言環境的訊息。對於不覆寫此方法的子類別，預設實作返回與 getMessage() 相同的結果。

返回：

此 throwable 的本地化描述。

從以下版本開始：

JDK1.1

getCause

public Throwable getCause()

返回此 throwable 的 cause；如果 cause 不存在或未知，則返回 null。（該 Cause 是導致拋出此 throwable 的throwable。）

此實作返回由一個需要 Throwable 的建構子提供的 cause，或者在創建之後通過 initCause(Throwable) 方法進行設置的 cause。雖然通常不需要覆寫此方法，但子類別可以覆寫它，以返回一個通過某些其他方式設置的 cause。這適用於在異常鏈（異常巢狀）機制被加入到 Throwable 之前存在“遺留 Throwable 鏈機制”的情況。注意，不必 覆寫任何 PrintStackTrace 方法，所有方法都調用 getCause 方法來確定 throwable 的 cause。

返回：

此 throwable 的 cause，如果 cause 不存在或是未知的，則返回 null。

從以下版本開始：

1.4

initCause

public Throwable initCause(Throwable cause)

將此 throwable 的 cause 初始化為指定值。（該 Cause 是導致拋出此 throwable 的throwable。）

此方法至多可以調用一次。此方法通常從建構子中調用，或者在創建 throwable 後立即調用。如果此 throwable 通過 Throwable(Throwable) 或 Throwable(String,Throwable) 創建，此方法甚至一次也不能調用。

參數：

cause - 原因（保存此 cause，以便以後通過 getCause() 方法獲取它）。（允許 null 值，指出 cause 是不存在的或是未知的。）

返回：

對此 Throwable 實例的參考。

拋出：

IllegalArgumentException - 如果 cause 是此 throwable。（throwable 不能是它自己的 cause。）

IllegalStateException - 如果此 throwable 通過 Throwable(Throwable) 或 Throwable(String,Throwable) 創建，或者此方法已經在此 throwable 上進行調用。

從以下版本開始：

1.4

toString

public String toString()

返回此 throwable 的簡短描述。結果是以下字元串的串聯：

• 此物件的類別的 name
• ": "（冒號和一個空格）
• 調用此物件 getLocalizedMessage() 方法的結果

如果 getLocalizedMessage 返回 null，則只返回類別名稱。

覆寫：

類別 Object 中的 toString

返回：

該 throwable 的字元串表示形式。

printStackTrace

public void printStackTrace()

將此 throwable 及其追蹤輸出至標準錯誤串流。此方法將此 Throwable 物件的堆疊(stack)空間追蹤輸出至錯誤輸出串流，作為欄位 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) cause 的 throwable 的追蹤，通常應該套件括 cause 的追蹤。此資訊的格式取決於實作，但以下範例是最常見的：

 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
 

注意，存在包含字元 "..." 的行。這些行指示此異常的椎堆疊(stack)空間追蹤的其餘部分比對來自異常（由 "enclosing" 異常引起）的堆疊(stack)空間追蹤底部的指定數量的幀。這種簡便方法可以大大縮短通常情況下的輸出長度，這裡拋出了包裹的異常，其方法與捕獲“作為 cause 的異常”的方法相同。上述範例通過運行以下程序產生：

 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)

將此 throwable 及其追蹤輸出到指定的輸出串流。

參數：

s - 用於輸出的 PrintStream

printStackTrace

public void printStackTrace(PrintWriter s)

將此 throwable 及其追蹤輸出到指定的 PrintWriter。

參數：

s - 用於輸出的 PrintWriter

從以下版本開始：

JDK1.1

fillInStackTrace

public Throwable fillInStackTrace()

在異常堆疊(stack)空間追蹤中填充。此方法在 Throwable 物件資訊中記錄有關當前執行緒堆疊(stack)訊框的當前狀態。

返回：

對此 Throwable 實例的參考。

另請參見：

printStackTrace()

getStackTrace

public StackTraceElement[] getStackTrace()

提供程式存取由 printStackTrace() 輸出的堆疊(stack)空間追蹤資訊。返回堆疊(stack)空間追蹤元素的陣列，每個元素表示一個堆疊(stack)訊框。陣列的第零個元素（假定資料的長度為非零）表示堆疊(stack)空間頂部，它是序列中最後的方法調用。通常，這是創建和拋出該 throwable 的地方。陣列的最後元素（假定資料的長度為非零）表示堆疊(stack)空間底部，它是序列中第一個方法調用。

某些虛擬機器在某些情況下可能會從堆疊(stack)空間追蹤中省略一個或多個堆疊(stack)訊框。在極端情況下，沒有該 throwable 堆疊(stack)空間追蹤資訊的虛擬機器可以從該方法返回一個零長度陣列。一般說來，由此方法返回的陣列將包含由 printStackTrace 輸出的每幀的一個元素。

返回：

堆疊(stack)空間追蹤元素的陣列，表示與此 throwable 相關的堆疊(stack)空間追蹤。

從以下版本開始：

1.4

setStackTrace

public void setStackTrace(StackTraceElement[] stackTrace)

設置將由 getStackTrace() 返回，並由 printStackTrace() 和相關方法輸出的堆疊(stack)空間追蹤元素。 此方法設計用於 RPC 框架和其他高層級系統，允許客戶端覆寫預設堆疊(stack)空間追蹤，這些預設堆疊(stack)空間追蹤要麼在建構 throwable 時由 fillInStackTrace() 產生，要麼在從序列化串流讀取 throwable 時反序列化。

參數：

stackTrace - 要與此 Throwable 關聯的堆疊(stack)空間追蹤元素。指定的陣列由此調用複製；在方法調用返回後，指定陣列中的改變將不會對此 Throwable 的堆疊(stack)空間追蹤產生影響。

拋出：

NullPointerException - 如果 stackTrace 為 null，或者 stackTrace 中的任何元素為 null

從以下版本開始：

1.4