ISQLServerMessageHandler Interface

Package:
com.microsoft.sqlserver.jdbc
Maven Artifact:
com.microsoft.sqlserver:mssql-jdbc:12.8.0.jre11

public interface ISQLServerMessageHandler

You can use the ISQLServerMessageHandler interface to customize the way JDBC handles error messages generated by the SQL Server. Implementing ISQLServerMessageHandler in your own class for handling error messages can provide the following benefits:

  • "message feedback" Display Server messages from a long running SQL Statement Like RAISERROR ('Progress message...', 0, 1) WITH NOWAIT Or Status messages from a running backup...

  • "Universal" error logging Your error-message handler can contain the logic for handling all error logging.

  • "Universal" error handling Error-handling logic can be placed in your error-message handler, instead of being repeated throughout your application.

  • Remapping of error-message severity, based on application requirements Your error-message handler can contain logic for recognizing specific error messages, and downgrading or upgrading their severity based on application considerations rather than the severity rating of the server. For example, during a cleanup operation that deletes old rows, you might want to downgrade the severity of a message that a row does not exist. However, you may want to upgrade the severity in other circumstances.

For example code, see messageHandler(ISQLServerMessage serverErrorOrWarning)

Method Summary

Modifier and Type Method and Description
abstract ISQLServerMessage messageHandler(ISQLServerMessage serverErrorOrWarning)

You can use the ISQLServerMessageHandler interface to customize the way JDBC handles error messages generated by the SQL Server.

Method Details

messageHandler

public abstract ISQLServerMessage messageHandler(ISQLServerMessage serverErrorOrWarning)

You can use the ISQLServerMessageHandler interface to customize the way JDBC handles error messages generated by the SQL Server. Implementing ISQLServerMessageHandler in your own class for handling error messages can provide the following benefits:

  • "message feedback" Display Server messages from a long running SQL Statement Like RAISERROR ('Progress message...', 0, 1) WITH NOWAIT Or Status messages from a running backup...

  • "Universal" error logging Your error-message handler can contain the logic for handling all error logging.

  • "Universal" error handling Error-handling logic can be placed in your error-message handler, instead of being repeated throughout your application.

  • Remapping of error-message severity, based on application requirements Your error-message handler can contain logic for recognizing specific error messages, and downgrading or upgrading their severity based on application considerations rather than the severity rating of the server. For example, during a cleanup operation that deletes old rows, you might want to downgrade the severity of a message that a row does not exist. However, you may want to upgrade the severity in other circumstances.

Example code:

public ISQLServerMessage messageHandler(ISQLServerMessage serverErrorOrWarning) {
     ISQLServerMessage retObj = serverErrorOrWarning;

     if (serverErrorOrWarning.isErrorMessage()) {

         // Downgrade: 2601 -- Cannot insert duplicate key row...
         if (2601 == serverErrorOrWarning.getErrorNumber()) {
             retObj = serverErrorOrWarning.getSQLServerMessage().toSQLServerInfoMessage();
         }

         // Discard: 3701 -- Cannot drop the table ...
         if (3701 == serverErrorOrWarning.getErrorNumber()) {
             retObj = null;
         }
     }

     return retObj;
 }

Parameters:

serverErrorOrWarning - server error or warning

Returns:

  • unchanged same object as passed in.
    The JDBC driver will work as if no message hander was installed
    Possibly used for logging functionality
  • null
    The JDBC driver will discard this message. No SQLException will be thrown
  • SQLServerInfoMessage object
    Create a "SQL warning" from a input database error, and return it. This results in the warning being added to the warning-message chain.
  • SQLServerError object
    If the originating message is a SQL warning (SQLServerInfoMessage object), messageHandler can evaluate the SQL warning as urgent and create and return a SQL exception (SQLServerError object) to be thrown once control is returned to the JDBC Driver.

Applies to