Throwable (Java Platform SE 8 )

java.lang.Object
- java.lang.Throwable

All Implemented Interfaces:

Serializable

已知直接子类：

Error ，异常
```
public class Throwable
extends Object
implements Serializable
```
Throwable类是Java语言中所有错误和异常的Throwable类。只有作为此类（或其一个子类）的实例的对象由Java虚拟机抛出，或者可以由Java throw语句抛出。类似地，只有这个类或其子类可以是catch子句中的参数类型。对于异常，编译时检查的目的Throwable和任何子类Throwable ，是不是也无论是子类RuntimeException或Error被视为检查的异常。
通常使用两个子类的实例Error和异常来表示出现异常情况。通常，这些实例是在特殊情况的上下文中新创建的，以便包括相关信息（如堆栈跟踪数据）。

throwable在创建时包含其线程的执行堆栈的快照。它还可以包含一个消息字符串，其中提供有关错误的更多信息。随着时间的推移，一个可以抛出的其他可抛物线可以被传播。最后，throwable也可能包含一个原因：另一个可抛出的，导致这个可抛出的构造。这种因果信息的记录被称为链接的异常设施，因为原因本身可能有原因等等，导致“链”的异常，每个异常都由另一个导致。

抛出一个原因的一个原因是抛出它的类被构建在较低层次的抽象之上，上层的操作由于下层的故障而失败。让下层投掷的投掷物向外传播是不好的设计，因为它通常与上层提供的抽象无关。此外，这样做会将上层的API与其实现的细节相结合，假设较低层的异常是被检查的异常。抛出“包装异常”（即，包含原因的异常）允许上层将故障的细节传达给其呼叫者，而不会导致这些缺点之一。它保留了更改上层实现的灵活性，而不改变其API（特别是其方法抛出的一组异常）。

throwable可能有一个原因的第二个原因是抛出它的方法必须符合通用接口，该接口不允许该方法直接引用原因。例如，假设持久集合符合Collection接口，并且其持久性在java.io顶部java.io 。假设add方法的内部可以抛出一个IOException 。实施可以在细节沟通IOException同时符合它的调用者Collection通过封装接口IOException在适当的未经检查的异常。（持久集合的规范应该表明它能够抛出这种异常。）

一个原因可以通过两种方式与一个可抛出的关联：通过构造函数将原因作为参数，或通过initCause(Throwable)方法。希望允许原因与他们相关联的新的可抛出类可以提供构造函数，这些构造函数可以引导和委派（或间接地）到Throwable函数之一的Throwable中。因为initCause方法是公开的，它允许一个原因与任何可抛出的，即使是“传统的可抛出”相关联，其实现早于将异常链接机制添加到Throwable 。

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

从以下版本开始：

JDK1.0

另请参见：

Serialized Form

See The Java™ Language Specification:

11.2编译时检查异常

构造方法摘要

构造方法
Modifier	Constructor and Description
	`Throwable()` 构造一个新的可抛出的 `null`作为其详细信息。
	`Throwable(String message)` 构造一个具有指定的详细消息的新的throwable。
	`Throwable(String message, Throwable cause)` 构造一个具有指定的详细信息和原因的新的throwable。
`protected`	`Throwable(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace)` 构造一个具有指定的详细消息的新的throwable，导致启用或禁用 suppression以及启用或禁用可写栈跟踪。
	`Throwable(Throwable cause)` 构造具有指定的原因和详细消息的新throwable `(cause==null ? null : cause.toString())` （它通常包含的类和详细消息 `cause` ）。

方法摘要

所有方法接口方法具体的方法
Modifier and Type	Method and Description
`void`	`addSuppressed(Throwable exception)` 将指定的异常附加到为了传递此异常而被抑制的异常。
`Throwable`	`fillInStackTrace()` 填写执行堆栈跟踪。
`Throwable`	`getCause()` 如果原因不存在或未知，则返回此throwable的原因或 `null` 。
`String`	`getLocalizedMessage()` 创建此可抛出的本地化描述。
`String`	`getMessage()` 返回此throwable的详细消息字符串。
`StackTraceElement[]`	`getStackTrace()` 提供对 `printStackTrace()`打印的堆栈跟踪信息的编程访问。
`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()` 返回此可抛出的简短描述。

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- 构造方法详细信息
  - Throwable
```
public Throwable()
```
    构造一个新的可抛出的null作为其详细信息。原因未初始化，可以随后通过调用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联的详细信息不会自动并入此可抛出的详细消息。
    
    调用fillInStackTrace()方法来初始化新创建的throwable中的堆栈跟踪数据。
    
    参数
    
    message - 详细信息（保存供 getMessage()方法稍后检索）。
    
    cause - 原因（保存以供getCause()方法稍后检索）。（ null A null值，表示原因不存在或未知。）
    
    从以下版本开始：
    
    1.4
  - Throwable
```
public Throwable(Throwable cause)
```
    构造具有指定的原因和详细消息的新throwable (cause==null ? null : cause.toString()) （它通常包含的类和详细消息cause ）。这个构造函数对于其他throwable的包装器（例如， PrivilegedActionException ）的throwable非常有用。
    调用fillInStackTrace()方法来初始化新创建的throwable中的堆栈跟踪数据。
    
    参数
    
    cause - 原因（由getCause()方法保存供以后检索）。（ null A null值，并表示原因不存在或未知。）
    
    从以下版本开始：
    
    1.4
  - Throwable
```
protected Throwable(String message,
                    Throwable cause,
                    boolean enableSuppression,
                    boolean writableStackTrace)
```
    构造一个具有指定的详细信息的新的throwable，原因是启用或禁用suppression和启用或禁用可写栈跟踪。如果禁用抑制，则此对象的getSuppressed()将返回一个零长度的数组，并调用addSuppressed(java.lang.Throwable) ，否则将附加到禁止列表的异常将不起作用。如果可写栈跟踪为false，该构造函数将不会调用fillInStackTrace() ，一个null将被写入stackTrace字段，后续调用fillInStackTrace和setStackTrace(StackTraceElement[])将不会设置堆栈跟踪。如果可写栈跟踪为false， getStackTrace()将返回零长度数组。
    请注意，Throwable的其他构造Throwable将抑制视为启用，堆栈跟踪可写。 Throwable的Throwable应记录禁用抑制的任何条件和堆栈跟踪不可写入的文档条件。禁止抑制只应在特殊情况下存在特殊要求，例如虚拟机在低内存情况下重用异常对象。给定异常对象被重复捕获并重新引导的情况，例如在两个子系统之间实现控制流的情况是另一种情况，即不可变的可抛出对象是合适的。
    
    参数
    
    message - 详细信息。
    
    cause - 原因。（A null值是允许的，并且表示原因不存在或未知。）
    
    enableSuppression - 是否启用抑制功能
    
    writableStackTrace - 堆栈跟踪是否可写
    
    从以下版本开始：
    
    1.7
    
    另请参见：
    
    OutOfMemoryError ， NullPointerException ， ArithmeticException
- 方法详细信息
  - 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链机制” Throwable 。请注意，没有必要覆盖任何PrintStackTrace方法，所有这些方法都调用getCause方法来确定可抛出的原因。
    
    结果
    
    原因是不可能的或 null如果原因不存在或未知。
    
    从以下版本开始：
    
    1.4
  - initCause
```
public Throwable initCause(Throwable cause)
```
    将此throwable的原因初始化为指定值。（原因是引发这个可抛掷物的抛掷物）
    这个方法最多可以调用一次。它通常从构造函数中调用，或者在创建throwable之后立即调用。如果这个throwable是用Throwable(Throwable)或Throwable(String,Throwable)创建的，那么这个方法也不能被调用一次。
    
    在没有其他支持设置原因的情况下，以传统可抛弃类型使用此方法的示例是：
```
  try {
     lowLevelOp();
 } catch (LowLevelException le) {
     throw (HighLevelException)
           new HighLevelException().initCause(le); // Legacy constructor
 } 
```
    参数
    
    cause - 原因（保存以供getCause()方法稍后检索）。（A null值，表示原因不存在或未知。）
    
    结果
    
    引用这个 Throwable实例。
    
    异常
    
    IllegalArgumentException - 如果cause是这个可扔的。（一个可以不是自己的事业）
    
    IllegalStateException - 如果这个throwable是用 Throwable(Throwable)或 Throwable(String,Throwable)创建的，或者这个方法已经在这个throwable上被调用了。
    
    从以下版本开始：
    
    1.4
  - toString
```
public String toString()
```
    返回此可抛出的简短描述。结果是：
    - 这个对象的类的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]);
     }
 } 
```
    对于具有初始化的非空原因的throwable的回溯通常应包括原因的回溯。该信息的格式取决于实现，但以下示例可能被认为是典型的：
```
  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个更多”符号被用于抑制异常，因为它被用于原因。与原因不同，被禁止的异常超出了它们的“包含异常”。
    异常可以同时导致一个或多个抑制异常：
```
  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用于输出
    
    从以下版本开始：
    
    JDK1.1
  - fillInStackTrace
```
public Throwable fillInStackTrace()
```
    填写执行堆栈跟踪。该方法记录了此Throwable对象信息，了解当前线程的堆栈帧的当前状态。
    如果堆栈跟踪这个Throwable is not writable ，调用这个方法没有影响。
    
    结果
    
    引用这个 Throwable例子。
    
    另请参见：
    
    printStackTrace()
  - getStackTrace
```
public StackTraceElement[] getStackTrace()
```
    提供对printStackTrace()打印的堆栈跟踪信息的编程访问。返回一个堆栈跟踪元素数组，每个数组代表一个堆栈帧。数组的第零个元素（假定数组的长度不为零）表示堆栈的顶部，这是序列中最后一个方法的调用。通常，这是创建和抛出此throwable的点。数组的最后一个元素（假定数组的长度不为零）表示堆栈的底部，这是序列中的第一个方法调用。
    在某些情况下，某些虚拟机可能从堆栈跟踪中省略一个或多个堆栈帧。在极端情况下，允许没有关于此throwable的堆栈跟踪信息的虚拟机从该方法返回零长度数组。一般来说，这个方法返回的数组将包含printStackTrace打印的每个帧的一个元素。写入返回的数组不影响将来调用此方法。
    
    结果
    
    表示与此可抛出的堆栈跟踪相关的堆栈跟踪元素数组。
    
    从以下版本开始：
    
    1.4
  - setStackTrace
```
public void setStackTrace(StackTraceElement[] stackTrace)
```
    设置将被返回的堆栈微量元素getStackTrace()和由印刷printStackTrace()和相关方法。该方法是为RPC框架和其他高级系统使用而设计的，允许客户端覆盖当从序列化流中读取throwable时构造或反序列化时由fillInStackTrace()生成的默认堆栈跟踪。
    如果这个Throwable is not writable的堆栈跟踪，除了验证其参数之外，调用此方法没有任何效果。
    
    参数
    
    stackTrace - 要与此Throwable的堆栈跟踪元素。该调用复制指定的数组; 方法调用返回后指定数组的更改将对此Throwable的堆栈跟踪没有影响。
    
    异常
    
    NullPointerException -如果 stackTrace是 null ，或者如果任何的元件的 stackTrace是 null
    
    从以下版本开始：
    
    1.4
  - addSuppressed
```
public final void addSuppressed(Throwable exception)
```
    将指定的异常附加到为了传递此异常而被抑制的异常。该方法是线程安全的，通常由try -with-resources语句调用（自动和隐式）。
    抑制行为启用，除非禁用via a constructor 。当禁用抑制时，该方法除了验证其参数之外什么都不做。
    
    注意当一个异常causes另外一个异常时，第一个异常通常被捕获，然后第二个异常被抛出来作为响应。换句话说，这两个例外之间有因果关系。与此相反，存在两个独立的异常可以在同级代码块在被抛出，在特定情况下try一个的块try -with资源语句和编译器生成的finally块封闭该资源。在这些情况下，只能传播一个抛出的异常。在try -with-resources语句，当有两个这样的例外，从始发异常try块被传播，并从异常finally块添加到从异常抑制例外列表try块。作为一个例外展开堆栈，它可以累积多个抑制异常。
    
    异常可能会抑制异常，同时也是由另一个异常引起的。异常是否有原因在创建时是语义上已知的，与异常是否会抑制通常仅在抛出异常之后确定的其他异常不同。
    
    请注意，程序员编写的代码还可以利用在存在多个兄弟异常并且只能传播一个异常的情况下调用此方法。
    
    参数
    
    exception - 要添加到抑制异常列表的异常
    
    异常
    
    IllegalArgumentException - 如果exception是这个可抛出的; 一个可耻的不能压制自己。
    
    NullPointerException - 如果 exception是 null
    
    从以下版本开始：
    
    1.7
  - getSuppressed
```
public final Throwable[] getSuppressed()
```
    返回一个包含所有被抑制的异常的数组，通常由try -with-resources语句来传递这个异常。如果没有例外被抑制或suppression is disabled ，返回一个空数组。这种方法是线程安全的。写入返回的数组不影响将来调用此方法。
    
    结果
    
    一个数组，其中包含所有被抑制以提供此异常的异常。
    
    从以下版本开始：
    
    1.7

Class Throwable

构造方法摘要

方法摘要

Methods inherited from class java.lang.Object

构造方法详细信息

Throwable

Throwable

Throwable

Throwable

Throwable

方法详细信息

getMessage

getLocalizedMessage

getCause

initCause

toString

printStackTrace

printStackTrace

printStackTrace

fillInStackTrace

getStackTrace

setStackTrace

addSuppressed

getSuppressed