Класс Throwable

public Throwable()

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

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

public Throwable(String message)

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

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

public Throwable(String message, Throwable cause)

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

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

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

public Throwable(Throwable cause)

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

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

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

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

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

public String getMessage()

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

public String getLocalizedMessage()

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

public Throwable getCause()

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

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

public Throwable initCause(Throwable cause)

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

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

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

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

public String toString()

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

• имени класса этого объекта
• ": " (двоеточие и пробел)
• результата вызова метода 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-with-resources.

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

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

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

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

public final Throwable[] getSuppressed()

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