java.lang

Класс Throwable

java.lang. Объект

java.lang. Throwable

Все Реализованные Интерфейсы:

Сериализуемый

Прямые Известные Подклассы:

Ошибка, Исключение

public class Throwable
extends Object
implements Serializable

Throwable класс является суперклассом всех ошибок и исключений на языке Java. Только объекты, которые являются экземплярами этого класса (или один из его подклассов) бросаются виртуальной машиной Java или могут быть брошены Java throw оператор. Точно так же только этот класс или один из его подклассов могут быть параметром, вводят a 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 и у его подклассов есть два конструктора, тот, который не берет параметров и того, который берет a String параметр, который может использоваться, чтобы произвести сообщение детали. Далее, у тех подклассов, которым можно было бы, вероятно, связать причину с ними, должно быть еще два конструктора, тот, который берет a Throwable (причина), и тот, который берет a String (сообщение детали) и a Throwable (причина).

С тех пор:

JDK1.0

См. Также:

Сериализированная Форма

См. Спецификацию языка Java™:

11.2 Время компиляции Проверяя Исключений

Сводка конструктора

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

Модификатор	Конструктор и Описание
	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 если причина является несуществующей или неизвестной.
Строка	getLocalizedMessage() Создает локализованное описание этого throwable.
Строка	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() и связанные методы.
Строка	toString() Возвращает краткое описание этого throwable.

Методы java.lang унаследованный от класса. Объект

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

Деталь конструктора

Throwable

public Throwable()

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

fillInStackTrace() метод вызывают, чтобы инициализировать данные трассировки стека в недавно создаваемом throwable.

Throwable

public Throwable(String message)

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

fillInStackTrace() метод вызывают, чтобы инициализировать данные трассировки стека в недавно создаваемом throwable.

Параметры:

message - сообщение детали. Сообщение детали сохраняется для более позднего извлечения getMessage() метод.

Throwable

public Throwable(String message,
         Throwable cause)

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

Отметьте что сообщение детали, связанное с cause автоматически не включается в сообщение детали этого throwable.

fillInStackTrace() метод вызывают, чтобы инициализировать данные трассировки стека в недавно создаваемом throwable.

Параметры:

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

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

С тех пор:

1.4

Throwable

public Throwable(Throwable cause)

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

fillInStackTrace() метод вызывают, чтобы инициализировать данные трассировки стека в недавно создаваемом throwable.

Параметры:

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

С тех пор:

1.4

Throwable

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

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

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

Параметры:

message - сообщение детали.

cause - причина. (A null значение разрешается, и указывает, что причина является несуществующей или неизвестной.)

enableSuppression - включается ли подавление или отключается

writableStackTrace - должна ли трассировка стека быть перезаписываемой

С тех пор:

1.7

См. Также:

OutOfMemoryError, NullPointerException, ArithmeticException

Деталь метода

getMessage

public String getMessage()

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

Возвраты:

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

getLocalizedMessage

public String getLocalizedMessage()

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

Возвраты:

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

С тех пор:

JDK1.1

getCause

public Throwable getCause()

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

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

Возвраты:

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

С тех пор:

1.4

initCause

public Throwable initCause(Throwable cause)

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

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

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

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

Параметры:

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

Возвраты:

ссылка на это Throwable экземпляр.

Броски:

IllegalArgumentException - если cause этот throwable. (throwable не может быть своей собственной причиной.)

IllegalStateException - если этот throwable создавался с Throwable(Throwable) или Throwable(String,Throwable), или этот метод уже вызвали на этом throwable.

С тех пор:

1.4

toString

public String toString()

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

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

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

Переопределения:

toString в классе Object

Возвраты:

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

printStackTrace

public void printStackTrace()

Печатные издания этот throwable и его след к стандартному потоку сообщений об ошибках. Этот метод печатает трассировку стека для этого 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]);
     }
 }
 

След для throwable с инициализированной, ненулевой причиной должен обычно включать след по причине. Формат этой информации зависит от реализации, но следующий пример может быть расценен как типичный:

 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.(Resource2.java:45)
          ... 2 more
 

printStackTrace

public void printStackTrace(PrintStream s)

Печатные издания этот throwable и его след к указанному потоку печати.

Параметры:

s - PrintStream использовать для вывода

printStackTrace

public void printStackTrace(PrintWriter s)

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

Параметры:

s - PrintWriter использовать для вывода

С тех пор:

JDK1.1

fillInStackTrace

public Throwable fillInStackTrace()

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

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

Возвраты:

ссылка на это Throwable экземпляр.

См. Также:

printStackTrace()

getStackTrace

public StackTraceElement[] getStackTrace()

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

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

Возвраты:

массив микроэлементов стека, представляющих трассировку стека, имеющую отношение к этому throwable.

С тех пор:

1.4

setStackTrace

public void setStackTrace(StackTraceElement[] stackTrace)

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

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

Параметры:

stackTrace - микроэлементы стека, которые будут связаны с этим Throwable. Указанный массив копируется этим вызовом; изменения в указанном массиве после возвратов вызова метода будут иметь, не влияют на этом Throwable's складывают трассировку.

Броски:

NullPointerException - если stackTrace null или если любой из элементов stackTrace null

С тех пор:

1.4

addSuppressed

public final void addSuppressed(Throwable exception)

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

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

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

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

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

Параметры:

exception - исключение, которое будет добавлено к списку заблокированных исключительных ситуаций

Броски:

IllegalArgumentException - если exception этот throwable; throwable не может подавить себя.

NullPointerException - если exception null

С тех пор:

1.7

getSuppressed

public final Throwable[] getSuppressed()

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

Возвраты:

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

С тех пор:

1.7