Класс Throwable

public Throwable()

Создаёт новый объект Throwable с null в качестве сообщения об ошибке. Причина не инициализирована и может быть позже инициализирована вызовом initCause(java.lang.Throwable).

Метод fillInStackTrace() вызывается для инициализации данных стека вызовов в созданном объекте Throwable.

public Throwable(String message)

Создаёт новый объект Throwable со строкой-сообщением об ошибке. Причина не инициализирована и может быть позже инициализирована вызовом initCause(java.lang.Throwable).

Метод fillInStackTrace() вызывается для инициализации данных стека вызовов в созданном объекте Throwable.

public Throwable(String message, Throwable cause)

Создаёт новый объект Throwable со строкой-сообщением об ошибке и причиной.

Обратите внимание, что сообщение об ошибке, связанное с cause, не автоматически включается в сообщение об ошибке этого объекта Throwable.

Метод fillInStackTrace() вызывается для инициализации данных стека вызовов в созданном объекте Throwable.

public Throwable(Throwable cause)

Создаёт новый объект Throwable с указанной причиной и сообщением об ошибке (cause==null ? null : cause.toString()) (обычно содержащим класс и сообщение об ошибке cause). Этот конструктор полезен для объектов Throwable, которые являются в основном обёртками для других объектов Throwable (например, PrivilegedActionException).

Метод fillInStackTrace() вызывается для инициализации данных стека вызовов в созданном объекте Throwable.

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

Создаёт новый объект Throwable с указанным сообщением об ошибке, причиной, включением/выключением подавления и включением/выключением записи стека вызовов. Если подавление выключено, getSuppressed() для этого объекта вернёт массив нулевой длины, и вызовы addSuppressed(java.lang.Throwable), которые в противном случае добавляли бы исключение в список подавленных исключений, не будут иметь эффекта. Если запись стека вызовов отключена, этот конструктор не вызовет fillInStackTrace(), значение null будет записано в поле stackTrace, и последующие вызовы fillInStackTrace и setStackTrace(StackTraceElement[]) не установят стек вызовов. Если запись стека вызовов отключена, getStackTrace() вернёт массив нулевой длины.

Обратите внимание, что другие конструкторы Throwable рассматривают подавление как включённое, а стек вызовов как записываемый. Подклассы Throwable должны документировать условия, при которых подавление выключено, и условия, при которых стек вызовов не записывается. Отключение подавления должно происходить только в исключительных случаях, когда существуют особые требования, такие как повторное использование объектов исключений виртуальной машиной в ситуациях с низкой памятью. Другой случай, когда уместны неизменяемые объекты исключений, — это ситуации, когда данный объект исключения многократно перехватывается и перебрасывается, например, для реализации потока управления между двумя подсистемами.

public String getMessage()

Возвращает строку сообщения об ошибке этого объекта Throwable.

public String getLocalizedMessage()

Создаёт локализованное описание этого объекта Throwable. Подклассы могут переопределить этот метод для создания сообщения, специфичного для локали. Для подклассов, которые не переопределяют этот метод, реализация по умолчанию возвращает тот же результат, что и getMessage().

public Throwable getCause()

Возвращает причину этого объекта Throwable, или null, если причина отсутствует или неизвестна. (Причина — это объект Throwable, который вызвал бросок этого исключения.)

Эта реализация возвращает причину, предоставленную через один из конструкторов, требующих Throwable, или установленную после создания с помощью метода initCause(Throwable). Хотя обычно переопределять этот метод не нужно, подкласс может переопределить его, чтобы вернуть причину, установленную каким-то другим способом. Это уместно для «наследованного цепного объекта Throwable», предшествующего добавлению цепных исключений к Throwable. Обратите внимание, что переопределять любые методы PrintStackTrace не нужно, так как все они вызывают метод getCause, чтобы определить причину объекта Throwable.

public Throwable initCause(Throwable cause)

Инициализирует причину этого объекта Throwable заданным значением. (Причина — это объект Throwable, который вызвал бросок этого исключения.)

Этот метод может быть вызван не более одного раза. Обычно он вызывается внутри конструктора или сразу после создания объекта Throwable. Если этот объект Throwable был создан с помощью Throwable(Throwable) или Throwable(String,Throwable), этот метод не может быть вызван ни разу.

Пример использования этого метода для устаревшего типа объекта Throwable без другой поддержки для установки причины:

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

public String toString()

Возвращает краткое описание этого объекта Throwable. Результатом является конкатенация:

• имени класса этого объекта (через getName)
• ": " (двоеточие и пробел)
• результата вызова метода getLocalizedMessage() этого объекта

Если getLocalizedMessage возвращает null, возвращается только имя класса.

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

Начиная с версии 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
 

public void printStackTrace(PrintStream s)

Выводит это исключение и его стек-трейс в указанный поток вывода.

public void printStackTrace(PrintWriter s)

Выводит это исключение и его стек-трейс в указанный поток вывода.

public Throwable fillInStackTrace()

Заполняет стек-трейс выполнения. Этот метод записывает в текущий объект Throwable информацию о текущем состоянии кадров стека для текущей нити.

Если стек-трейс этого Throwable не может быть записан, вызов этого метода не оказывает никакого влияния.

public StackTraceElement[] getStackTrace()

Предоставляет программный доступ к информации стека вызовов, напечатанной методом printStackTrace(). Возвращает массив элементов стека вызовов, каждый из которых представляет один кадр стека. Нулевой элемент массива (при условии, что длина массива не равна нулю) представляет вершину стека, которая является последним вызовом метода в последовательности. Обычно это момент, когда это исключение было создано и вызвано. Последний элемент массива (при условии, что длина массива не равна нулю) представляет низ стека, который является первым вызовом метода в последовательности.

Некоторые виртуальные машины могут в некоторых случаях пропускать один или несколько кадров стека из стека вызовов. В крайнем случае, виртуальная машина, не имеющая информации о стеке вызовов данного исключения, может вернуть массив нулевой длины из этого метода. Как правило, массив, возвращаемый этим методом, будет содержать один элемент на каждый кадр, который был бы напечатан методом printStackTrace. Записи в возвращаемый массив не влияют на последующие вызовы этого метода.

public void setStackTrace(StackTraceElement[] stackTrace)

Устанавливает элементы стека вызовов, которые будут возвращены методом getStackTrace() и напечатаны методом printStackTrace() и родственные методы. Этот метод, предназначенный для использования фреймворками RPC и другими сложными системами, позволяет клиенту переопределить стандартный стек вызовов, который либо генерируется методом fillInStackTrace() при создании исключения, либо десериализуется при чтении исключения из потока сериализации.

Если стек-трейс этого Throwable не может быть записан, вызов этого метода не оказывает никакого влияния, кроме проверки аргумента.

public final void addSuppressed(Throwable exception)

Добавляет указанное исключение к списку исключений, подавленных для обработки данного исключения. Этот метод потокобезопасен и обычно вызывается (автоматически и неявно) оператором try-with-resources.

Поведение подавления включено, если не отключено через конструктор. При отключенном подавлении, этот метод ничего не делает, кроме проверки аргумента.

Обратите внимание, что когда одно исключение является причиной другого исключения, первое исключение обычно перехватывается, а затем во второе исключение выбрасывается в ответ. Другими словами, существует причинно-следственная связь между двумя исключениями. В отличие от этого, существуют ситуации, когда два независимых исключения могут быть выброшены в соседних блоках кода, особенно в блоке try оператора try-with-resources и генерируемом компилятором блоке finally, который закрывает ресурс. В этих ситуациях, только одно из выброшенных исключений может быть распространено. В операторе try-with-resources, когда существуют два таких исключения, исключение, исходящее из блока try, распространяется, а исключение из блока finally добавляется в список исключений, подавленных исключением из блока try. По мере выхода исключения из стека, оно может накапливать несколько подавленных исключений.

Исключение может иметь подавленные исключения, будучи также вызвано другим исключением. Будет ли у исключения причина, определяется семантически в момент его создания, в отличие от того, будет ли оно подавлять другие исключения, которое, как правило, определяется только после того, как исключение будет выброшено.

Обратите внимание, что программистский код также может воспользоваться вызовом этого метода в ситуациях с несколькими соседними исключениями, когда только одно может быть распространено.

public final Throwable[] getSuppressed()

Возвращает массив, содержащий все исключения, которые были подавлены, как правило, оператором try-with-resources, для обработки данного исключения. Если исключения не были подавлены или подавленние отключено, возвращается пустой массив. Этот метод потокобезопасен. Записи в возвращаемый массив не влияют на последующие вызовы этого метода.