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

CKTIS / Java

Throwable.getMessage(): ler a mensagem detalhada de uma exceção

Lê a mensagem de uma exceção específica, lida com a sua ausência e distingue a exceção principal das suas causas e das exceções suprimidas.

Versão: Java SE 21

Sintaxe

public String getMessage()

Throwable.getMessage() é um método de instância sem parâmetros. A chamada e.getMessage() devolve a mensagem detalhada do objeto e como String, ou null. null não é a cadeia de caracteres vazia "". Verifica o resultado antes de o usares como texto. Se a própria referência e for null, a chamada lança uma NullPointerException.

new NullPointerException("name").getMessage() devolve "name". Sem uma mensagem explícita diferente de null, o resultado pode depender da implementação ou ser null. O Java SE 21 não garante o texto exato nem que apareça o nome de uma variável. Uma IllegalArgumentException capturada herda getMessage() e pode devolver o texto passado ao seu construtor.

getCause() devolve o objeto que representa a causa, ou null se a causa não existir ou for desconhecida. Numa cadeia sem ciclos, segue as causas com getCause() até obteres null e chama getMessage() para cada causa. IllegalArgumentException(String, Throwable) não acrescenta a mensagem da causa ao texto fornecido. A sobrecarga IllegalArgumentException(Throwable) obtém a sua mensagem de cause.toString() ou usa null se a causa for null.

Se o corpo de uma instrução try-with-resources e close() lançarem exceções distintas, a do corpo continua a ser a principal. Com a supressão ativada, a exceção do fecho aparece no array devolvido por getSuppressed(), não na cadeia de causas. Lê a mensagem de cada elemento separadamente. O array está vazio se nenhuma exceção tiver sido suprimida ou se a supressão estiver desativada.

getMessage() não devolve um rastreio da pilha nem acrescenta automaticamente o nome da classe. Por predefinição, getLocalizedMessage() devolve o mesmo que getMessage(), mas uma subclasse pode redefini-lo. Usa o texto para diagnóstico, não como código de erro: não o uses para decidir o fluxo do programa nem mostres aos utilizadores mensagens internas que não tenham sido revistas.

Exemplos

public class Main {
    static final class Resource implements AutoCloseable {
        @Override
        public void close() {
            throw new IllegalStateException("close fail");
        }
    }

    public static void main(String[] args) {
        try (Resource resource = new Resource()) {
            throw new IllegalArgumentException("primary", new NullPointerException("name"));
        } catch (IllegalArgumentException e) {
            System.out.println("Caught: " + e.getMessage());
            for (Throwable cause = e.getCause(); cause != null; cause = cause.getCause()) {
                System.out.println("Cause: " + cause.getMessage());
            }
            for (Throwable suppressed : e.getSuppressed()) {
                System.out.println("Suppressed: " + suppressed.getMessage());
            }
        }

        String message = new IllegalArgumentException().getMessage();
        System.out.println("No message: " + (message == null ? "(absent)" : message));
    }
}

Resultado

Caught: primary
Cause: name
Suppressed: close fail
No message: (absent)

A saída distingue a mensagem da `IllegalArgumentException` capturada (`primary`), a da sua causa (`name`) e a da exceção suprimida de `close()` (`close fail`). Na última linha, o programa substitui `null` por `(absent)`.

Lições relacionadas

  • Java · Lição 28 · Intermédio · Versão: 2
  • Java · Lição 29 · Intermédio · Versão: 2
  • Java · Lição 30 · Intermédio · Versão: 2
  • Java · Lição 31 · Intermédio · Versão: 2

Fontes