Module com.microsoft.sqlserver.jdbc
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 Summary

All Methods Instance Methods Abstract Methods
`ISQLServerMessage` `messageHandler​(ISQLServerMessage serverErrorOrWarning)` You can use the ISQLServerMessageHandler interface to customize the way JDBC handles error messages generated by the SQL Server.

### 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.