com.microsoft.sqlserver.jdbc.ISQLServerMessageHandler Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of mssql-jdbc Show documentation
Microsoft JDBC Driver for SQL Server.
There is a newer version: 12.8.1.jre11
/*
 * Microsoft JDBC Driver for SQL Server Copyright(c) Microsoft Corporation All rights reserved. This program is made
 * available under the terms of the MIT License. See the LICENSE file in the project root for more information.
 */
package com.microsoft.sqlserver.jdbc;

/**
 * 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 {@link #messageHandler(ISQLServerMessage)}
 */
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.
     * 
     * 
     * 
     * 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;
     * }
     * 
     * 
     * 
     * @param serverErrorOrWarning
     *        server error or warning
     * @return
     *         
     *         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.
     *         
     *         
     */
    ISQLServerMessage messageHandler(ISQLServerMessage serverErrorOrWarning);
}