SQLErrorCodeSQLExceptionTranslator (Spring Framework 3.2.1.RELEASE API)
Date: 2013-01-24

org.springframework.jdbc.support

## Class SQLErrorCodeSQLExceptionTranslator

- java.lang.Object
- - org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator
  - - org.springframework.jdbc.support.SQLErrorCodeSQLExceptionTranslator

- All Implemented Interfaces:
    SQLExceptionTranslator

      public class SQLErrorCodeSQLExceptionTranslator
      extends AbstractFallbackSQLExceptionTranslator

  Implementation of `SQLExceptionTranslator` that analyzes vendor-specific error codes. More precise than an implementation based on SQL state, but heavily vendor-specific.

  This class applies the following matching rules:

  - Try custom translation implemented by any subclass. Note that this class is concrete and is typically used itself, in which case this rule doesn't apply.
  - Apply error code matching. Error codes are obtained from the SQLErrorCodesFactory by default. This factory loads a "sql-error-codes.xml" file from the class path, defining error code mappings for database names from database metadata.
  - Fallback to a fallback translator. `SQLStateSQLExceptionTranslator` is the default fallback translator, analyzing the exception's SQL state only. On Java 6 which introduces its own `SQLException` subclass hierarchy, we will use `SQLExceptionSubclassTranslator` by default, which in turns falls back to Spring's own SQL state translation when not encountering specific subclasses.

  The configuration file named "sql-error-codes.xml" is by default read from this package. It can be overridden through a file of the same name in the root of the class path (e.g. in the "/WEB-INF/classes" directory), as long as the Spring JDBC package is loaded from the same ClassLoader.

  Author:
    Rod Johnson, Thomas Risberg, Juergen Hoeller
  See Also:
    `SQLErrorCodesFactory`, `SQLStateSQLExceptionTranslator`

- - ### Field Summary

    - ### Fields inherited from class org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator

      `logger`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SQLErrorCodeSQLExceptionTranslator()` Constructor for use as a JavaBean.
    `SQLErrorCodeSQLExceptionTranslator(DataSource dataSource)` Create a SQL error code translator for the given DataSource.
    `SQLErrorCodeSQLExceptionTranslator(SQLErrorCodes sec)` Create a SQLErrorCode translator given these error codes.
    `SQLErrorCodeSQLExceptionTranslator(String dbName)` Create a SQL error code translator for the given database product name.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected DataAccessException` | `createCustomException(String task, String sql, SQLException sqlEx, Class exceptionClass)` Create a custom DataAccessException, based on a given exception class from a CustomSQLErrorCodesTranslation definition.
    `protected DataAccessException` | `customTranslate(String task, String sql, SQLException sqlEx)` Subclasses can override this method to attempt a custom mapping from SQLException to DataAccessException.
    `protected DataAccessException` | `doTranslate(String task, String sql, SQLException ex)` Template method for actually translating the given exception.
    `SQLErrorCodes` | `getSqlErrorCodes()` Return the error codes used by this translator.
    `void` | `setDatabaseProductName(String dbName)` Set the database product name for this translator.
    `void` | `setDataSource(DataSource dataSource)` Set the DataSource for this translator.
    `void` | `setSqlErrorCodes(SQLErrorCodes sec)` Set custom error codes to be used for translation.

    - ### Methods inherited from class org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator

      `buildMessage, getFallbackTranslator, setFallbackTranslator, translate`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### SQLErrorCodeSQLExceptionTranslator

          public SQLErrorCodeSQLExceptionTranslator()

      Constructor for use as a JavaBean. The SqlErrorCodes or DataSource property must be set.

    - #### SQLErrorCodeSQLExceptionTranslator

          public SQLErrorCodeSQLExceptionTranslator(DataSource dataSource)

      Create a SQL error code translator for the given DataSource. Invoking this constructor will cause a Connection to be obtained from the DataSource to get the metadata.
      Parameters:
        `dataSource` - DataSource to use to find metadata and establish which error codes are usable
      See Also:
        `SQLErrorCodesFactory`

    - #### SQLErrorCodeSQLExceptionTranslator

          public SQLErrorCodeSQLExceptionTranslator(String dbName)

      Create a SQL error code translator for the given database product name. Invoking this constructor will avoid obtaining a Connection from the DataSource to get the metadata.
      Parameters:
        `dbName` - the database product name that identifies the error codes entry
      See Also:
        `SQLErrorCodesFactory`, `DatabaseMetaData.getDatabaseProductName()`

    - #### SQLErrorCodeSQLExceptionTranslator

          public SQLErrorCodeSQLExceptionTranslator(SQLErrorCodes sec)

      Create a SQLErrorCode translator given these error codes. Does not require a database metadata lookup to be performed using a connection.
      Parameters:
        `sec` - error codes

  - ### Method Detail

    - #### setDataSource

          public void setDataSource(DataSource dataSource)

      Set the DataSource for this translator.

      Setting this property will cause a Connection to be obtained from the DataSource to get the metadata.

      Parameters:
        `dataSource` - DataSource to use to find metadata and establish which error codes are usable
      See Also:
        `SQLErrorCodesFactory.getErrorCodes(javax.sql.DataSource)`, `DatabaseMetaData.getDatabaseProductName()`

    - #### setDatabaseProductName

          public void setDatabaseProductName(String dbName)

      Set the database product name for this translator.

      Setting this property will avoid obtaining a Connection from the DataSource to get the metadata.

      Parameters:
        `dbName` - the database product name that identifies the error codes entry
      See Also:
        `SQLErrorCodesFactory.getErrorCodes(String)`, `DatabaseMetaData.getDatabaseProductName()`

    - #### setSqlErrorCodes

          public void setSqlErrorCodes(SQLErrorCodes sec)

      Set custom error codes to be used for translation.
      Parameters:
        `sec` - custom error codes to use

    - #### getSqlErrorCodes

          public SQLErrorCodes getSqlErrorCodes()

      Return the error codes used by this translator. Usually determined via a DataSource.
      See Also:
        `setDataSource(javax.sql.DataSource)`

    - #### doTranslate

          protected DataAccessException doTranslate(String task,
                                        String sql,
                                        SQLException ex)

      Description copied from class: `AbstractFallbackSQLExceptionTranslator`
      Template method for actually translating the given exception.

      The passed-in arguments will have been pre-checked. Furthermore, this method is allowed to return `null` to indicate that no exception match has been found and that fallback translation should kick in.

      Specified by:
        `doTranslate` in class `AbstractFallbackSQLExceptionTranslator`
      Parameters:
        `task` - readable text describing the task being attempted
        `sql` - SQL query or update that caused the problem (may be `null`)
        `ex` - the offending `SQLException`
      Returns:
        the DataAccessException, wrapping the `SQLException`; or `null` if no exception match found

    - #### customTranslate

          protected DataAccessException customTranslate(String task,
                                            String sql,
                                            SQLException sqlEx)

      Subclasses can override this method to attempt a custom mapping from SQLException to DataAccessException.
      Parameters:
        `task` - readable text describing the task being attempted
        `sql` - SQL query or update that caused the problem. May be `null`.
        `sqlEx` - the offending SQLException
      Returns:
        null if no custom translation was possible, otherwise a DataAccessException resulting from custom translation. This exception should include the sqlEx parameter as a nested root cause. This implementation always returns null, meaning that the translator always falls back to the default error codes.

    - #### createCustomException

          protected DataAccessException createCustomException(String task,
                                                  String sql,
                                                  SQLException sqlEx,
                                                  Class exceptionClass)

      Create a custom DataAccessException, based on a given exception class from a CustomSQLErrorCodesTranslation definition.
      Parameters:
        `task` - readable text describing the task being attempted
        `sql` - SQL query or update that caused the problem. May be `null`.
        `sqlEx` - the offending SQLException
        `exceptionClass` - the exception class to use, as defined in the CustomSQLErrorCodesTranslation definition
      Returns:
        null if the custom exception could not be created, otherwise the resulting DataAccessException. This exception should include the sqlEx parameter as a nested root cause.
      See Also:
        `CustomSQLErrorCodesTranslation.setExceptionClass(java.lang.Class)`