## 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
`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
`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)`