Класс Throwable

public Throwable()

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

Для инициализации данных трассировки стека в созданном объекте throwable вызывается метод fillInStackTrace().

public Throwable(String message)

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

Для инициализации данных трассировки стека в созданном объекте throwable вызывается метод fillInStackTrace().

public Throwable(String message, Throwable cause)

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

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

Для инициализации данных трассировки стека в созданном объекте throwable вызывается метод fillInStackTrace().

public Throwable(Throwable cause)

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

Для инициализации данных трассировки стека в созданном объекте throwable вызывается метод fillInStackTrace().

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

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

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

public String getMessage()

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

public String getLocalizedMessage()

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

public Throwable getCause()

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

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

public Throwable initCause(Throwable cause)

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

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

Пример использования этого метода для устаревшего типа 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 и трассировку его стека в стандартный поток ошибок. Этот метод выводит трассировку стека для объекта 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-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)

Выводит этот объект throwable и трассировку его стека в указанный поток вывода.

public void printStackTrace(PrintWriter s)

Выводит этот объект throwable и трассировку его стека в указанный объект PrintWriter.

public Throwable fillInStackTrace()

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

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

public StackTraceElement[] getStackTrace()

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

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

public void setStackTrace(StackTraceElement[] stackTrace)

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

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