模块  java.base
软件包  java.lang

Class Throwable

  • 实现的所有接口
    Serializable
    已知直接子类：
    Error ， 异常 
    public class Throwable
extends Object
implements Serializable
    Throwable类是Java语言中所有错误和异常的超类。 只有作为此类（或其子类之一）的实例的对象throw Java虚拟机抛出，或者可以由Java throw语句抛出。 类似地，只有这个类或其子类之一可以是catch子句中的参数类型。 出于编译时检查异常的目的， Throwable和任何子类Throwable （也不是RuntimeException或Error的子类）都被视为已检查的例外。

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

    throwable包含其创建时线程执行堆栈的快照。 它还可以包含一个消息字符串，该字符串提供有关错误的更多信息。 随着时间的推移，一个扔掉的东西可能会被传播掉其他的扔掉的东西 。 最后，throwable还可以包含一个原因 ：另一个throwable导致构造这个throwable。 这种因果信息的记录被称为链式异常工具，因为原因本身可能有原因，等等，导致异常的“链”，每个异常由另一个引起。

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

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

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

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

    从以下版本开始：
    1.0
    另请参见：
    Serialized Form
    See The Java™ Language Specification:
    11.2编译时检查异常

    • 构造方法详细信息

      • 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关联的详细消息不会自动合并到此throwable的详细消息中。

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

        参数
        message - 详细消息（保存以供以后通过 getMessage()方法检索）。
        cause - 原因（保存以供以后通过getCause()方法检索）。 （允许值为null ，表示原因不存在或未知。）
        从以下版本开始：
        1.4

      • Throwable

        public Throwable​(Throwable cause)
        构造具有指定的原因和详细消息的新throwable (cause==null ? null : cause.toString()) （它通常包含的类和详细消息cause ）。 这个构造函数对于throwable只有很多其他throwable的包装（例如， PrivilegedActionException ）。

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

        参数
        cause - 原因（保存以供以后通过getCause()方法检索）。 （允许值为null ，表示原因不存在或未知。）
        从以下版本开始：
        1.4

      • Throwable

        protected Throwable​(String message,
                    Throwable cause,
                    boolean enableSuppression,
                    boolean writableStackTrace)
        构造具有指定详细消息的新throwable，原因是，启用或禁用了suppression ，并启用或禁用了可写堆栈跟踪。 如果禁用抑制， 则此对象的getSuppressed()将返回零长度数组，并且调用addSuppressed(java.lang.Throwable) ，否则将对抑制列表附加异常将不起作用。 如果写的堆栈跟踪是假的，这个构造不会叫fillInStackTrace() ，一个null将被写入到stackTrace领域，后续调用fillInStackTrace和setStackTrace(StackTraceElement[])不会设置堆栈跟踪。 如果可写堆栈跟踪为false，则getStackTrace()将返回零长度数组。

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

        参数
        message - 详细信息。
        cause - 原因。 （允许值为null ，表示原因不存在或未知。）
        enableSuppression - 是否启用抑制
        writableStackTrace - 堆栈跟踪是否应该是可写的
        从以下版本开始：
        1.7
        另请参见：
        OutOfMemoryError ， NullPointerException ， ArithmeticException

    • 方法详细信息

      • getMessage

        public String getMessage()
        返回此throwable的详细消息字符串。
        结果
        此 Throwable实例的详细消息字符串（可能是 null ）。

      • getLocalizedMessage

        public String getLocalizedMessage()
        创建此throwable的本地化描述。 子类可以重写此方法以生成特定于语言环境的消息。 对于不重写此方法的子类，默认实现返回与getMessage()相同的结果。
        结果
        这个throwable的本地化描述。
        从以下版本开始：
        1.1

      • getCause

        public Throwable getCause()
        如果原因不存在或未知，则返回此throwable或null的原因。 （原因是导致抛出此抛掷物的抛掷物。）

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

        结果
        如果原因不存在或未知，则抛出此抛出的原因或 null 。
        从以下版本开始：
        1.4

      • initCause

        public Throwable initCause​(Throwable cause)
        将此throwable的原因初始化为指定值。 （原因是导致抛出此抛掷物的抛掷物。）

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

        在没有其他支持来设置原因的情况下在旧的throwable类型上使用此方法的示例是： 

          try {
     lowLevelOp();
 } catch (LowLevelException le) {
     throw (HighLevelException)
           new HighLevelException().initCause(le); // Legacy constructor
 }
        参数
        cause - 原因（保存以供以后通过getCause()方法检索）。 （允许值为null ，表示原因不存在或未知。）
        结果
        对此 Throwable实例的引用。
        异常
        IllegalArgumentException - 如果cause是可cause 。 （抛弃不可能是它自己的原因。）
        IllegalStateException - 如果此throwable是使用 Throwable(Throwable)或 Throwable(String,Throwable)创建的，或者此方法已在此throwable上调用。
        从以下版本开始：
        1.4

      • toString

        public String toString()
        返回此throwable的简短描述。 结果是连接： 如果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]);
     }
 }
        具有初始化非null原因的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 more”符号用于抑制异常，仅用于原因。 与原因不同，被抑制的异常会缩进超出其“包含异常”的范围。

        异常可以同时包含一个原因和一个或多个抑制异常： 

          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及其backtrace打印到指定的打印流。
        参数
        s - PrintStream用于输出

      • printStackTrace

        public void printStackTrace​(PrintWriter s)
        将此throwable及其backtrace打印到指定的打印编写器。
        参数
        s - PrintWriter用于输出
        从以下版本开始：
        1.1

      • fillInStackTrace

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

        如果这个Throwable的堆栈跟踪is not writable ，则调用此方法无效。

        结果
        对此 Throwable实例的引用。
        另请参见：
        printStackTrace()

      • getStackTrace

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

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

        结果
        一个堆栈跟踪元素数组，表示与此throwable相关的堆栈跟踪。
        从以下版本开始：
        1.4

      • setStackTrace

        public void setStackTrace​(StackTraceElement[] stackTrace)
        设置将由getStackTrace()返回并由printStackTrace()和相关方法打印的堆栈跟踪元素。 此方法旨在供RPC框架和其他高级系统使用，允许客户端覆盖默认堆栈跟踪，该跟踪由构造 throwable时由fillInStackTrace()生成，或者在从序列化流中读取throwable时反序列化。

        如果此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是可exception ; 一个扔掉的人无法抑制自己。
        NullPointerException - 如果 exception是 null
        从以下版本开始：
        1.7

      • getSuppressed

        public final Throwable[] getSuppressed()
        返回一个数组，其中包含通常由try -with-resources语句抑制的所有异常，以便传递此异常。 如果没有抑制异常或suppression is disabled ，则返回一个空数组。 此方法是线程安全的。 写入返回的数组不会影响将来对此方法的调用。
        结果
        包含为了传递此异常而被禁止的所有异常的数组。
        从以下版本开始：
        1.7