Tratando erros

Artigo
08/05/2024

Ao usar o Microsoft JDBC Driver para SQL Server, todas as condições de erro de banco de dados são retornadas para seu aplicativo Java como exceções usando a classe SQLServerException. Os seguintes métodos da classe SQLServerException são herdados de java.sql.SQLException e java.lang.Throwable; e eles podem ser usados para retornar informações específicas sobre o erro do SQL Server que ocorreu:

O getSQLState() retorna o X/Open padrão ou código de estado SQL99 da exceção.
O getErrorCode() retorna o número de erro de banco de dados específico.
O getMessage() retorna o texto completo da exceção. O texto de mensagem de erro descreve o problema e geralmente inclui espaços reservados para informações, como nomes de objeto, que são inseridos na mensagem de erro quando é exibido.
O getSQLServerError() retorna o objeto SQLServerError que contém informações detalhadas sobre a exceção, conforme recebido do SQL Server. Esse método retornará nulo se nenhum erro de servidor tiver ocorrido.

Os métodos a seguir da classe SQLServerError podem ser usados para obter detalhes adicionais sobre o erro gerado no servidor.

O SQLServerError.getErrorMessage() retorna a mensagem de erro como recebida do servidor.
O SQLServerError.getErrorNumber() retorna um número que identifica o tipo do erro.
O SQLServerError.getErrorState() retorna um código de erro numérico do SQL Server que representa um erro, aviso ou mensagem "nenhum dado encontrado".
O SQLServerError.getErrorSeverity() retorna o nível de gravidade do erro recebido.
O SQLServerError.getServerName() retorna o nome do computador que está executando uma instância do SQL Server que gerou o erro.
O SQLServerError.getProcedureName() retorna o nome do procedimento armazenado ou RPC (chamada de procedimento remoto) que gerou o erro.
O SQLServerError.getLineNumber() retorna o número de linha no lote de comandos Transact-SQL ou no procedimento armazenado que gerou o erro.

No exemplo a seguir, uma conexão aberta com o banco de dados de exemplo AdventureWorks2022 do SQL Server é transmitida para a função e uma instrução SQL malformada que não tem uma cláusula FROM é construída. Em seguida, a instrução é executada e uma exceção SQL é processada.

public static void executeSQLException(Connection con) {
    try (Statement stmt = con.createStatement();) {
        String SQL = "SELECT TOP 10 * Person.Contact";
        ResultSet rs = stmt.executeQuery(SQL);

        while (rs.next()) {
            System.out.println(rs.getString("FirstName") + " " + rs.getString("LastName"));
        }
    }
    catch (SQLException se) {
        do {
            System.out.println("SQL STATE: " + se.getSQLState());
            System.out.println("ERROR CODE: " + se.getErrorCode());
            System.out.println("MESSAGE: " + se.getMessage());
            System.out.println();
        }
        while (se != null);
    }
}

Usando o ServerMessageHandler

A partir da versão 12.8.0, o driver tem um ServerMessageHandler adicional que permite uma maior quantidade de controle sobre o feedback de erro e os logs. Para usar o ServerMessageHandler, é necessário implementar a interface ISQLServerMessageHandler. Os recursos do ServerMessageHandler incluem:

Comentários da mensagem

Permite que você receba feedback de consultas de longa duração (como mensagens de progresso). Por exemplo, RAISERROR ('Progress message...', 0, 1) WITH NOWAIT.

Log de erros universal

Permite que o manipulador de mensagens manipule os logs de todos os erros.

Tratamento de erros universal

Permite que você coloque a lógica de tratamento de erros apenas como ServerMessageHandler, em vez de repetir o mesmo tratamento de erros em todo o aplicativo.

Remapeamento da gravidade da mensagem de erro

Permite reconhecer e alterar a gravidade de mensagens de erro específicas:

SQLServerError.toSQLServerInfoMessage() retorna um ISQLServerMessage, criado pelo downgrade de uma mensagem de erro para uma mensagem de informação.
SQLServerError.toSQLServerInfoMessage(int newErrorSeverity) retorna um ISQLServerMessage, criado pelo downgrade de uma mensagem de erro para uma mensagem de informação, com uma nova severidade de erro.
SQLServerError.toSQLServerInfoMessage(int newErrorSeverity, int newErrorNumber) retorna um ISQLServerMessage, criado pelo downgrade de uma mensagem de erro para uma mensagem de informação, com uma nova severidade de erro e um número de erro.
SQLServerInfoMessage.toSQLServerError() retorna um ISQLServerMessage, criado pelo upgrade de uma mensagem de informação para uma mensagem de erro.
SQLServerInfoMessage.toSQLServerError(int newErrorSeverity) retorna um ISQLServerMessage, criado pelo upgrade de uma mensagem de informação para uma mensagem de erro, com uma nova severidade de erro.
SQLServerInfoMessage.toSQLServerError(int newErrorSeverity, int newErrorNumber) retorna um ISQLServerMessage, criado pelo upgrade de uma mensagem de informação para uma mensagem de' erro, com uma nova severidade de erro e um número de erro.

SQLExceptionChaining

Também na versão 12.8.0, as SQLExceptions podem ser encadeadas, de modo que a mensagem de exceção final contém automaticamente todas as exceções que podem ter sido perdidas. Esse recurso está habilitado por padrão.

Confira também

Diagnosticando problemas com o JDBC Driver

Compartilhar via