Package com.microsoft.sqlserver.jdbc

Interface ISQLServerMessageHandler

  • 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)

    • Method Detail

      • messageHandler

        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.