Класс Throwable

Все реализованные интерфейсы:
Serializable
Прямые известные подклассы:
Error, Exception
public class Throwable
extends Object
implements Serializable

Класс Throwable является суперклассом всех ошибок и исключений в языке Java. Только объекты, являющиеся экземплярами этого класса (или одного из его подклассов), выбрасываются виртуальной машиной Java или могут быть выброшены оператором Java throw. Аналогично, только этот класс или один из его подклассов может быть типом аргумента в операторе catch. Для целей проверки исключений во время компиляции, Throwable и любой подкласс Throwable, который не является также подклассом RuntimeException или Error, считаются проверяемыми исключениями.

Экземпляры двух подклассов, Error и Exception, обычно используются для указания возникновения исключительных ситуаций. Обычно эти экземпляры создаются непосредственно в контексте исключительной ситуации, чтобы содержать соответствующую информацию (такую как данные трассировки стека).

Throwable содержит моментальный снимок стека выполнения потока на момент его создания. Он также может содержать строку сообщения, которая предоставляет дополнительную информацию об ошибке. Со временем throwable может подавлять другие throwables, предотвращая их распространение. Наконец, throwable также может содержать причину: другой throwable, который вызвал создание этого throwable. Запись этой причинно-следственной информации называется механизмом вложенных исключений, так как причина может сама иметь причину, и так далее, что приводит к «цепочке» исключений, каждое из которых вызвано другим.

Одна из причин, по которой throwable может иметь причину, заключается в том, что класс, выбрасывающий его, построен на основе более низкого уровня абстракции, и операция на верхнем уровне терпит неудачу из-за сбоя на нижнем уровне. Плохим дизайном будет позволить throwable, выброшенному нижним слоем, распространяться наружу, поскольку он, как правило, не связан с абстракцией, предоставляемой верхним слоем. Кроме того, это свяжет API верхнего слоя с деталями его реализации, если исключение нижнего слоя было проверяемым исключением. Выбрасывание «оборачивающего исключения» (т. е. исключения, содержащего причину) позволяет верхнему слою передать детали сбоя своему вызывающему методу, не испытывая ни одной из этих проблем. Это сохраняет гибкость изменения реализации верхнего слоя без изменения его API (в частности, набора исключений, выбрасываемых его методами).

Вторая причина, по которой throwable может иметь причину, заключается в том, что метод, который его выбрасывает, должен соответствовать общецелевому интерфейсу, который не позволяет методу непосредственно выбрасывать причину. Например, предположим, что постоянное хранилище соответствует интерфейсу Collection, и что его постоянство реализовано на основе java.io. Предположим, что внутренние методы add могут выбрасывать IOException. Реализация может передать детали IOException своему вызывающему методу, сохраняя при этом соответствие интерфейсу Collection путем обертывания IOException в соответствующее необрабатываемое исключение. (В спецификации постоянного хранилища должно быть указано, что оно может выбрасывать такие исключения.)

Причина может быть связана с throwable двумя способами: через конструктор, принимающий причину в качестве аргумента, или через метод initCause(Throwable). Новые классы throwable, которые хотят разрешить связь с причиной, должны предоставлять конструкторы, которые принимают причину и делегируют (возможно, косвенно) одному из конструкторов Throwable, принимающих причину. Поскольку метод initCause является общедоступным, он позволяет связать причину с любым throwable, даже «наследованным throwable», чья реализация предшествовала добавлению механизма цепочек исключений в Throwable.

Согласно соглашению, класс Throwable и его подклассы имеют два конструктора: один без аргументов и один с аргументом String, который может использоваться для создания сообщения об ошибке. Кроме того, те подклассы, у которых, скорее всего, будет связана причина, должны иметь еще два конструктора: один, принимающий Throwable (причину), и один, принимающий String (сообщение об ошибке) и Throwable (причину).

С тех пор:
1.0
См. также:
Сериализованная форма

Конструкторы

Модификатор Конструктор Описание
Throwable()

Создает новый throwable с null в качестве сообщения об ошибке.

Throwable​(String message)

Создает новый throwable со строкой сообщения об ошибке.

Throwable​(String message, Throwable cause)

Создает новый throwable со строкой сообщения об ошибке и причиной.

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

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

Throwable​(Throwable cause)

Создает новый throwable с указанной причиной и сообщением об ошибке (cause==null ? null : cause.toString()) (обычно содержащим класс и сообщение об ошибке cause).

Методы

Модификатор и тип Метод Описание
void addSuppressed​(Throwable exception)

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

Throwable fillInStackTrace()

Заполняет трассировку стека выполнения.

Throwable getCause()

Возвращает причину этого throwable или null, если причина отсутствует или неизвестна.

String getLocalizedMessage()

Создает локализованное описание этого throwable.

String getMessage()

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

StackTraceElement[] getStackTrace()

Предоставляет программно доступ к информации о трассировке стека, выводимой методом printStackTrace().

Throwable[] getSuppressed()

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

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()

Возвращает краткое описание этого throwable.

Методы, объявленные в классе java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Конструкторы

Throwable

public Throwable()

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

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

Throwable

public Throwable(String message)

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

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

Параметры:
message - сообщение об ошибке. Сообщение об ошибке сохраняется для последующего извлечения методом getMessage().

Throwable

public Throwable(String message,
                 Throwable cause)

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

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

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

Параметры:
message - сообщение об ошибке (которое сохраняется для последующего извлечения методом getMessage()).
cause - причина (которая сохраняется для последующего извлечения методом getCause()). (Разрешено значение null, указывающее, что причина отсутствует или неизвестна.)
С:
1.4

Throwable

public Throwable(Throwable cause)

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

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

Параметры:
cause - причина (которая сохраняется для последующего извлечения методом getCause()). (Разрешено значение null, указывающее, что причина отсутствует или неизвестна.)
С:
1.4

Throwable

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

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

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

Параметры:
message - сообщение об ошибке.
cause - причина. (Разрешено значение null, указывающее, что причина отсутствует или неизвестна.)
enableSuppression - включён или отключён режим подавления.
writableStackTrace - включён или отключён режим записи стека вызовов.
С:
1.7
См. также:
OutOfMemoryError, NullPointerException, ArithmeticException

Методы

getMessage

public String getMessage()

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

Возвращает:
строку детали сообщения этого Throwable экземпляра (которая может быть null).

getLocalizedMessage

public String getLocalizedMessage()

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

Возвращает:
Локализованное описание этого исключения.
С:
1.1

getCause

public Throwable getCause()

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

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

Возвращает:
причину этого исключения или null если причина отсутствует или неизвестна.
С:
1.4

initCause

public Throwable initCause(Throwable cause)

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

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

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

try {
     lowLevelOp();
 } catch (LowLevelException le) {
     throw (HighLevelException)
           new HighLevelException().initCause(le); // Legacy constructor
 }
Параметры:
cause — причина (которая сохраняется для последующего получения методом getCause()). (Разрешено значение null, которое указывает, что причина отсутствует или неизвестна.)
Возвращает:
ссылку на этот Throwable экземпляр.
Исключения:
IllegalArgumentException - если cause является этим исключением. (Исключение не может быть своей собственной причиной.)
IllegalStateException - если это исключение было создано с помощью Throwable(Throwable) или Throwable(String,Throwable), или этот метод уже был вызван для этого исключения.
С:
1.4

toString

public String toString()

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

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

Переопределяет:
toString в классе Object
Возвращает:
строковое представление этого исключения.

printStackTrace

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]);
     }
 }
Стек-трейс исключения со связанной непустой причиной обычно включает стек-трейс причины. Формат этой информации зависит от реализации, но следующий пример можно считать типичным:
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-с-ресурсами). Любые исключения, которые были подавлены для доставки исключения, выводятся под стеком-трейсом. Формат этой информации зависит от реализации, но следующий пример можно считать типичным:
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)

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

Параметры:
s - PrintStream для вывода

printStackTrace

public void printStackTrace(PrintWriter s)

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

Параметры:
s - PrintWriter для вывода
С:
1.1

fillInStackTrace

public Throwable fillInStackTrace()

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

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

Возвращает:
ссылку на этот Throwable экземпляр.
См. также:
printStackTrace()

getStackTrace

public StackTraceElement[] getStackTrace()

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

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

Возвращает:
массив элементов стека-трейса, представляющих стек-трейс, относящийся к этому исключению.
С:
1.4

setStackTrace

public void setStackTrace(StackTraceElement[] stackTrace)

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

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

Параметры:
stackTrace - элементы стека-трейса, которые будут связаны с этим Throwable. Указанный массив копируется в этом вызове; изменения в указанном массиве после возвращения метода не повлияют на стек-трейс этого Throwable.
Исключения:
NullPointerException - если stackTrace является null или если любой из элементов stackTrace является null
С:
1.4

addSuppressed

public final void addSuppressed(Throwable exception)

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

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

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

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

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

Parameters:
exception - исключение, которое нужно добавить в список подавленных исключений
Throws:
IllegalArgumentException - если exception является этим исключением; исключение не может подавлять само себя.
NullPointerException - если exception является null
Since:
1.7

getSuppressed

public final Throwable[] getSuppressed()

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

Returns:
массив, содержащий все исключения, подавленные для доставки этого исключения.
Since:
1.7

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Throwable.html

Spec-Zone .ru
спецификации, руководства, описания, API