Класс 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.)

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

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
}

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 и его трассировку стека в указанный объект печати.

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