Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Java

Consultar exceções suprimidas com getSuppressed()

Usa `getSuppressed()` para consultar exceções secundárias registadas numa exceção principal, por exemplo quando falham tanto o bloco `try` como o fecho automático de um recurso.

Versão: Java SE 21

Sintaxe

public final Throwable[] getSuppressed()

// Call on a Throwable instance:
Throwable[] suppressed = failure.getSuppressed();

Throwable.getSuppressed() é um método de instância sem argumentos de java.lang.Throwable, disponível desde o Java 7. Invoca-o na exceção capturada para obter um array Throwable[] com as exceções suprimidas registadas diretamente nesse objeto.

Uma instrução try-with-resources fecha automaticamente o recurso. Se o bloco try e close() lançarem objetos de exceção distintos, a exceção do bloco continua a ser a principal. A exceção do fecho fica registada nela como suprimida, se a supressão estiver ativa. Se ambos lançarem a mesma instância de Throwable, a chamada gerada a addSuppressed() tenta adicionar a exceção à sua própria lista de exceções suprimidas e, em vez disso, lança uma IllegalArgumentException. Se o bloco terminar normalmente e só close() lançar uma exceção, a exceção do fecho é a principal.

Se não houver exceções suprimidas registadas ou se a supressão estiver desativada para esse objeto, o método devolve um array vazio, nunca null. O método pode ser usado em segurança por várias threads. Substituir elementos no array devolvido não altera os resultados de chamadas posteriores.

Não confundas este resultado com o de getCause(), que devolve a causa ou null se esta não existir ou for desconhecida. Uma exceção pode ter simultaneamente uma causa e exceções suprimidas.

Exemplos

import java.io.IOException;

public class Main {
    static class DemoResource implements AutoCloseable {
        @Override
        public void close() throws IOException {
            throw new IOException("close failed");
        }
    }

    public static void main(String[] args) {
        try (DemoResource resource = new DemoResource()) {
            throw new IOException("work failed");
        } catch (IOException failure) {
            System.out.println("Primary: " + failure.getMessage());
            for (Throwable suppressed : failure.getSuppressed()) {
                System.out.println("Suppressed: " + suppressed.getMessage());
            }
        }
    }
}

Resultado

Primary: work failed
Suppressed: close failed

O bloco `catch` captura `work failed`. O ciclo lê uma única exceção suprimida, `close failed`, pelo que o programa apresenta ambas as mensagens.

Lições relacionadas

  • Java · Lição 52 · Básico · Versão: 2

Fontes