Класс Throwable
- java.lang.Object
-
- java.lang.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 с | |
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 с указанной причиной и сообщением об ошибке |
Методы
| Модификатор и тип | Метод | Описание |
|---|---|---|
void | addSuppressed(Throwable exception) | Добавляет указанное исключение к исключениям, подавленным для доставки этого исключения. |
Throwable | fillInStackTrace() | Заполняет трассировку стека выполнения. |
Throwable | getCause() | Возвращает причину этого throwable или |
String | getLocalizedMessage() | Создает локализованное описание этого throwable. |
String | getMessage() | Возвращает строку сообщения об ошибке этого throwable. |
StackTraceElement[] | getStackTrace() | Предоставляет программно доступ к информации о трассировке стека, выводимой методом |
Throwable[] | getSuppressed() | Возвращает массив, содержащий все подавленные исключения, обычно оператором |
Throwable | initCause(Throwable cause) | Инициализирует причину этого throwable указанным значением. |
void | printStackTrace() | Выводит это throwable и его трассировку стека в стандартный поток ошибок. |
void | printStackTrace(PrintStream s) | Выводит это throwable и его трассировку стека в указанный поток вывода. |
void | printStackTrace(PrintWriter s) | Выводит это throwable и его трассировку стека в указанный объект для записи. |
void | setStackTrace(StackTraceElement[] stackTrace) | Устанавливает элементы трассировки стека, которые будут возвращены методом |
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, возвращается только имя класса. 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