模块 java.base

包 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 子句中的参数类型。出于编译时检查异常的目的， Throwable 和 Throwable 的任何子类（不是 RuntimeException 或 Error 的子类）都被视为已检查异常。

两个子类 Error 和 Exception 的实例通常用于指示发生了异常情况。通常，这些实例是在异常情况的上下文中新创建的，以便包含相关信息（例如堆栈跟踪数据）。

throwable 包含其线程在创建时执行堆栈的快照。它还可以包含一个消息字符串，提供有关错误的更多信息。随着时间的推移，一个 throwable 可以阻止其他 throwable 被传播。最后，throwable 还可以包含一个原因: 另一个导致构建此 throwable 的 throwable。这种因果信息的记录被称为链式异常设施作为原因本身可以有一个原因，依此类推，导致异常“链”，每个异常都由另一个异常引起。

throwable 可能有原因的一个原因是抛出它的类构建在较低层的抽象之上，并且由于较低层的故障而导致上层的操作失败。让下层抛出的throwable向外传播是不好的设计，因为它通常与上层提供的抽象无关。此外，假设下层的异常是已检查异常，这样做会将上层的 API 与其实现细节联系起来。抛出“包装的异常”（即包含原因的异常）允许上层将失败的详细信息传达给其调用者，而不会导致这些缺点中的任何一个。它保留了更改上层实现而不更改其 API（特别是其方法抛出的异常集）的灵活性。

throwable 可能有 cause 的第二个原因是抛出它的方法必须符合不允许该方法直接抛出 cause 的通用接口。例如，假设一个持久化集合符合 Collection 接口，并且它的持久化是在 java.io 之上实现的。假设 add 方法的内部可以抛出一个 IOException 。通过将 IOException 包装在适当的未经检查的异常中，实现可以将 IOException 的详细信息传达给其调用者，同时符合 Collection 接口。 （持久性集合的规范应该表明它能够抛出此类异常。）

一个 cause 可以通过两种方式与一个 throwable 相关联：通过一个将 cause 作为参数的构造函数，或者通过 initCause(Throwable) 方法。希望允许原因与它们关联的新的可抛出类应该提供接受原因的构造函数，并委托（可能间接地）给接受原因的 Throwable 构造函数之一。因为 initCause 方法是公共的，它允许一个原因与任何可抛出对象相关联，甚至是一个“遗留可抛出对象”，其实现早于将异常链接机制添加到 Throwable 。

按照惯例，类 Throwable 及其子类有两个构造函数，一个不带参数，一个带 String 参数，可用于生成详细消息。此外，那些可能有与之关联的原因的子类应该有两个构造函数，一个接受 Throwable（原因），另一个接受 String（详细消息）和 Throwable（原因）。

看Java 语言规范:

11.2 异常的编译时检查

自从：

1.0

参见：

• Serialized Form

构造方法总结

构造方法

修饰符	构造方法	描述
	Throwable()	用 null 作为它的详细消息构造一个新的 throwable。
	Throwable(String message)	使用指定的详细消息构造一个新的 throwable。
	Throwable(String message, Throwable cause)	使用指定的详细消息和原因构造一个新的 throwable。
protected	Throwable(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace)	使用指定的详细消息、原因、抑制 启用或禁用以及可写堆栈跟踪启用或禁用构造一个新的 throwable。
	Throwable(Throwable cause)	构造一个具有指定原因和 (cause==null ? null : cause.toString()) 详细消息（通常包含 cause 的类和详细消息）的新 throwable。

方法总结

修饰符和类型	方法	描述
final void	addSuppressed(Throwable exception)	将指定的异常附加到被抑制的异常以传递此异常。
Throwable	fillInStackTrace()	填写执行堆栈跟踪。
Throwable	getCause()	如果原因不存在或未知，则返回此 throwable 或 null 的原因。
String	getLocalizedMessage()	创建此 throwable 的本地化描述。
String	getMessage()	返回此 throwable 的详细消息字符串。
StackTraceElement[]	getStackTrace()	提供对 printStackTrace() 打印的堆栈跟踪信息的编程访问。
final Throwable[]	getSuppressed()	返回一个数组，其中包含所有被抑制的异常，通常由 try -with-resources 语句来传递此异常。
Throwable	initCause(Throwable cause)	初始化原因此 throwable 的指定值。
void	printStackTrace()	将此 throwable 及其回溯打印到标准错误流。
void	printStackTrace(PrintStream s)	将此 throwable 及其回溯打印到指定的打印流。
void	printStackTrace(PrintWriter s)	将此 throwable 及其回溯打印到指定的打印编写器。
void	setStackTrace(StackTraceElement[] stackTrace)	设置将由 getStackTrace() 返回并由 printStackTrace() 和相关方法打印的堆栈跟踪元素。
String	toString()	返回此 throwable 的简短描述。

在类 java.lang.Object 中声明的方法

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

构造方法详细信息

Throwable

public Throwable()
            

用 null 作为它的详细消息构造一个新的 throwable。原因未初始化，随后可能会通过调用 initCause(java.lang.Throwable) 进行初始化。

fillInStackTrace() 方法被调用来初始化新创建的 throwable 中的堆栈跟踪数据。

Throwable

public Throwable(String  message)
            

使用指定的详细消息构造一个新的 throwable。原因未初始化，随后可能会通过调用 initCause(java.lang.Throwable) 进行初始化。

fillInStackTrace() 方法被调用来初始化新创建的 throwable 中的堆栈跟踪数据。

参数：

message - 详细信息。保存详细消息以供以后通过 getMessage() 方法检索。

Throwable

public Throwable(String  message, Throwable  cause)
            

使用指定的详细消息和原因构造一个新的 throwable。

请注意，与 cause 关联的详细消息是not自动合并到这个 throwable 的详细消息中。

fillInStackTrace() 方法被调用来初始化新创建的 throwable 中的堆栈跟踪数据。

参数：

message - 详细消息（保存以供以后通过 getMessage() 方法检索）。

cause - 原因（保存以供以后通过 getCause() 方法检索）。 （允许使用 null 值，表示原因不存在或未知。）

自从：

1.4

Throwable

public Throwable(Throwable  cause)
            

构造一个具有指定原因和 (cause==null ? null : cause.toString()) 详细消息（通常包含 cause 的类和详细消息）的新 throwable。此构造函数对于仅比其他可抛出对象（例如 PrivilegedActionException ）的包装器多一点的可抛出对象很有用。

fillInStackTrace() 方法被调用来初始化新创建的 throwable 中的堆栈跟踪数据。

参数：

cause - 原因（保存以供以后通过 getCause() 方法检索）。 （允许使用 null 值，表示原因不存在或未知。）

自从：

1.4

Throwable

protected Throwable(String  message, Throwable  cause, boolean enableSuppression, boolean writableStackTrace)
            

使用指定的详细消息、原因、抑制 启用或禁用以及可写堆栈跟踪启用或禁用构造一个新的 throwable。如果禁用抑制，则此对象的 getSuppressed() 将返回一个零长度数组，并且调用 addSuppressed(java.lang.Throwable) 否则会将异常附加到抑制列表将无效。如果可写堆栈跟踪为 false，此构造函数将不会调用 fillInStackTrace() ，null 将写入 stackTrace 字段，随后对 fillInStackTrace 和 setStackTrace(StackTraceElement[]) 的调用将不会设置堆栈跟踪。如果可写堆栈跟踪为假，getStackTrace() 将返回一个零长度数组。

请注意，Throwable 的其他构造函数将抑制视为已启用，并将堆栈跟踪视为可写。 Throwable 的子类应记录禁用抑制的任何条件以及堆栈跟踪不可写的记录条件。仅应在存在特殊要求的特殊情况下禁用抑制，例如虚拟机在低内存情况下重用异常对象。给定异常对象被反复捕获和重新抛出的情况，例如在两个子系统之间实现控制流，是不可变可抛出对象适用的另一种情况。

参数：

message - 详细信息。

cause - 原因。 （允许使用 null 值，表示原因不存在或未知。）

enableSuppression - 是否启用抑制

writableStackTrace - 堆栈跟踪是否可写

自从：

1.7

参见：

• OutOfMemoryError
• NullPointerException
• ArithmeticException

方法详情

getMessage

public String  getMessage()
            

返回此 throwable 的详细消息字符串。

返回：

此 Throwable 实例的详细消息字符串（可能是 null ）。

getLocalizedMessage

public String  getLocalizedMessage()
            

创建此 throwable 的本地化描述。子类可以覆盖此方法以生成特定于locale的消息。对于不覆盖此方法的子类，默认实现返回与 getMessage() 相同的结果。

返回：

此 throwable 的本地化描述。

自从：

1.1

getCause

public Throwable  getCause()
            

如果原因不存在或未知，则返回此 throwable 或 null 的原因。 （原因是导致该 throwable 被抛出的 throwable。）

此实现返回通过需要 Throwable 的构造函数之一提供的原因，或者在使用 initCause(Throwable) 方法创建后设置的原因。虽然通常不需要覆盖此方法，但子类可以覆盖它以返回通过其他方式设置的原因。这适用于早于向 Throwable 添加链式异常的“遗留链式抛出”。请注意，它是not有必要覆盖任何 PrintStackTrace 方法，所有这些方法都会调用 getCause 方法来确定可抛出的原因。

返回：

此 throwable 的原因或 null 如果原因不存在或未知。

自从：

1.4

initCause

public Throwable  initCause(Throwable  cause)
            

初始化原因此 throwable 的指定值。 （原因是导致该 throwable 被抛出的 throwable。）

该方法最多可以调用一次。它通常在构造函数中调用，或者在创建 throwable 之后立即调用。如果此 throwable 是使用 Throwable(Throwable) 或 Throwable(String,Throwable) 创建的，则此方法不能被调用一次。

在没有其他支持设置原因的遗留可抛出类型上使用此方法的示例是：

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

参数：

cause - 原因（保存以供以后通过 getCause() 方法检索）。 （允许使用 null 值，表示原因不存在或未知。）

返回：

对此 Throwable 实例的引用。

抛出：

IllegalArgumentException - 如果 cause 是可抛出的。 （throwable 不能是它自己的原因。）

IllegalStateException - 如果此 throwable 是使用 Throwable(Throwable) 或 Throwable(String,Throwable) 创建的，或者此方法已在此 throwable 上调用。

自从：

1.4

toString

public String  toString()
            

返回此 throwable 的简短描述。结果是以下内容的串联：

• 这个对象的类的name
• “：”（一个冒号和一个空格）
• 调用此对象的 getLocalizedMessage() 方法的结果

如果 getLocalizedMessage 返回 null ，则只返回类名。

重写：

toString 在类 Object 中

返回：

此 throwable 的字符串表示形式。

printStackTrace

public void printStackTrace()
            

将此 throwable 及其回溯打印到标准错误流。此方法在错误输出流上打印此 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]);
   }
 }
 

具有已初始化非空原因的可抛出对象的回溯通常应包括该原因的回溯。此信息的格式取决于实现，但以下示例可被视为典型示例：

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

从版本 7 开始，该平台支持以下概念被抑制的异常（结合 try -with-resources 声明）。为了传递异常而被抑制的任何异常都会在堆栈跟踪下方打印出来。此信息的格式取决于实现，但以下示例可能被视为典型示例：

 Exception in thread "main" java.lang.Exception: Something happened
     at Foo.bar(Foo.java:10)
     at Foo.main(Foo.java:5)
     Suppressed: Resource$CloseFailException: Resource ID = 0
         at Resource.close(Resource.java:26)
         at Foo.bar(Foo.java:9)
         ... 1 more
 

请注意，“...n more”符号用于抑制的异常，就像它用于原因一样。与 causes 不同，被抑制的异常的缩进超出了它们的“包含异常”。

异常可以同时具有原因和一个或多个被抑制的异常：

 Exception in thread "main" java.lang.Exception: Main block
     at Foo3.main(Foo3.java:7)
     Suppressed: Resource$CloseFailException: Resource ID = 2
         at Resource.close(Resource.java:26)
         at Foo3.main(Foo3.java:5)
     Suppressed: Resource$CloseFailException: Resource ID = 1
         at Resource.close(Resource.java:26)
         at Foo3.main(Foo3.java:5)
 Caused by: java.lang.Exception: I did it
     at Foo3.main(Foo3.java:8)
 

同样，被抑制的异常可能有一个原因：

 Exception in thread "main" java.lang.Exception: Main block
     at Foo4.main(Foo4.java:6)
     Suppressed: Resource2$CloseFailException: Resource ID = 1
         at Resource2.close(Resource2.java:20)
         at Foo4.main(Foo4.java:5)
     Caused by: java.lang.Exception: Rats, you caught me
         at Resource2$CloseFailException.<init>(Resource2.java:45)
         ... 2 more
 

printStackTrace

public void printStackTrace(PrintStream  s)
            

将此 throwable 及其回溯打印到指定的打印流。

参数：

s - PrintStream 用于输出

printStackTrace

public void printStackTrace(PrintWriter  s)
            

将此 throwable 及其回溯打印到指定的打印编写器。

参数：

s - PrintWriter 用于输出

自从：

1.1

fillInStackTrace

public Throwable  fillInStackTrace()
            

填写执行堆栈跟踪。此方法在此 Throwable 对象中记录有关当前线程堆栈帧的当前状态的信息。

如果此 Throwable 不可写 的堆栈跟踪，则调用此方法无效。

返回：

对此 Throwable 实例的引用。

参见：

• printStackTrace()

getStackTrace

public StackTraceElement [] getStackTrace()
            

提供对 printStackTrace() 打印的堆栈跟踪信息的编程访问。返回一组堆栈跟踪元素，每个元素代表一个堆栈帧。数组的第零个元素（假设数组的长度不为零）表示堆栈的顶部，这是序列中的最后一个方法调用。通常，这是创建和抛出此 throwable 的点。数组的最后一个元素（假设数组的长度不为零）表示堆栈的底部，这是序列中的第一个方法调用。

在某些情况下，某些虚拟机可能会从堆栈跟踪中省略一个或多个堆栈帧。在极端情况下，没有关于此 throwable 的堆栈跟踪信息的虚拟机被允许从此方法返回一个零长度数组。一般来说，此方法返回的数组将为 printStackTrace 打印的每一帧包含一个元素。写入返回的数组不会影响以后对此方法的调用。

返回：

一组堆栈跟踪元素，表示与此 throwable 相关的堆栈跟踪。

自从：

1.4

setStackTrace

public void setStackTrace(StackTraceElement [] stackTrace)
            

设置将由 getStackTrace() 返回并由 printStackTrace() 和相关方法打印的堆栈跟踪元素。此方法专为 RPC 框架和其他高级系统使用而设计，允许客户端覆盖默认堆栈跟踪，该堆栈跟踪由 fillInStackTrace() 在构造可抛出对象时生成或在从序列化流读取可抛出对象时反序列化。

如果此 Throwable 不可写 的堆栈跟踪，则调用此方法除了验证其参数外没有任何效果。

参数：

stackTrace - 与此 Throwable 关联的堆栈跟踪元素。指定的数组被这个调用复制；方法调用返回后指定数组中的更改不会影响此 Throwable 的堆栈跟踪。

抛出：

NullPointerException - 如果 stackTrace 是 null 或者如果 stackTrace 的任何元素是 null

自从：

1.4

addSuppressed

public final void addSuppressed(Throwable  exception)
            

将指定的异常附加到被抑制的异常以传递此异常。此方法是线程安全的，通常由 try -with-resources 语句调用（自动和隐式）。

抑制行为已启用 unless 已禁用 通过构造函数。禁用抑制时，此方法除了验证其参数外什么都不做。

请注意，当一个异常原因另一个异常时，通常会捕获第一个异常，然后抛出第二个异常作为响应。换句话说，这两个异常之间存在因果关系。相反，在某些情况下，可以在同级代码块中抛出两个独立的异常，特别是在 try -with-resources 语句的 try 块和编译器生成的关闭资源的 finally 块中。在这些情况下，只能传播抛出的异常之一。在 try -with-resources 语句中，当存在两个此类异常时，将传播源自 try 块的异常，并将来自 finally 块的异常添加到由来自 try 块的异常抑制的异常列表中。当异常展开堆栈时，它可以累积多个被抑制的异常。

一个异常可能有被抑制的异常，同时也可能是由另一个异常引起的。异常是否有原因在其创建时在语义上是已知的，这与异常是否会抑制其他异常不同，后者通常仅在抛出异常后才确定。

请注意，程序员编写的代码也可以在存在多个同级异常且只能传播一个异常的情况下利用调用此方法的优势。

参数：

exception - 要添加到抑制异常列表的异常

抛出：

IllegalArgumentException - 如果 exception 是可抛出的； throwable 不能抑制自己。

NullPointerException - 如果 exception 是 null

自从：

1.7

getSuppressed

public final Throwable [] getSuppressed()
            

返回一个数组，其中包含所有被抑制的异常，通常由 try -with-resources 语句来传递此异常。如果没有异常被抑制或 禁用抑制 ，则返回一个空数组。这个方法是线程安全的。写入返回的数组不会影响以后对此方法的调用。

返回：

一个数组，其中包含为传递此异常而被抑制的所有异常。

自从：

1.7