Класс 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), которые в противном случае добавили бы исключение в список подавленных, не окажут никакого эффекта. Если запись стека вызовов false, этот конструктор не вызовет fillInStackTrace(), a null будет записан в поле stackTrace, и последующие вызовы fillInStackTrace и setStackTrace(StackTraceElement[]) не установят стек вызовов. Если запись стека вызовов false, getStackTrace() вернёт массив нулевой длины.

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

public String getMessage()

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

public String getLocalizedMessage()

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

public Throwable getCause()

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

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

public Throwable initCause(Throwable cause)

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

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

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

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

public String toString()

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

• имени класса этого объекта
• ": " (двоеточие и пробел)
• результата вызова метода 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, для передачи этого исключения. Если исключения не были подавлены или подавленно отключено, возвращается пустой массив. Этот метод потокобезопасен. Записи в возвращаемый массив не влияют на последующие вызовы этого метода.