The Spring Framework

## org.springframework.jdbc.support
Class SQLErrorCodeSQLExceptionTranslator

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

All Implemented Interfaces:
  SQLExceptionTranslator

    public class SQLErrorCodeSQLExceptionTranslator

extends Object
implements SQLExceptionTranslator

Implementation of SQLExceptionTranslator that analyzes vendor-specific error codes. More precise than an implementation based on SQL state, but 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.
- Use subclass translator. Java 6 introduces its own SQLException hierarchy and in a Java 6 or later environment we will attempt a translation based on the subclass of the exception.
- 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.

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

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

Field Summary
`protected Log` `logger` Logger available to subclasses

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 String` `buildMessage(String task, String sql, SQLException sqlEx)` Build a message String for the given SQLException.
`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.
`SQLExceptionTranslator` `getFallbackTranslator()` Return the fallback exception translator.
`SQLErrorCodes` `getSqlErrorCodes()` Return the error codes used by this translator.
`SQLExceptionTranslator` `getSubclassTranslator()` Return the subclass exception translator.
`void` `setDatabaseProductName(String dbName)` Set the database product name for this translator.
`void` `setDataSource(DataSource dataSource)` Set the DataSource for this translator.
`void` `setFallbackTranslator(SQLExceptionTranslator fallback)` Override the default SQL state fallback translator.
`void` `setSqlErrorCodes(SQLErrorCodes sec)` Set custom error codes to be used for translation.
`void` `setSubclassTranslator(SQLExceptionTranslator subclassTranslator)` Override the default SQLException subclass translator.
`DataAccessException` `translate(String task, String sql, SQLException sqlEx)` Translate the given `SQLException` into a generic `DataAccessException`.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### logger

    protected final Log logger

  Logger available to subclasses

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

### setSubclassTranslator

    public void setSubclassTranslator(SQLExceptionTranslator subclassTranslator)

  Override the default SQLException subclass translator. This is only used for JAva 6.

  Parameters:
    `subclassTranslator` - custom subclass exception translator to use
  See Also:
    `SQLException`

### getSubclassTranslator

    public SQLExceptionTranslator getSubclassTranslator()

  Return the subclass exception translator.

### setFallbackTranslator

    public void setFallbackTranslator(SQLExceptionTranslator fallback)

  Override the default SQL state fallback translator.

  Parameters:
    `fallback` - custom fallback exception translator to use if error code translation fails
  See Also:
    `SQLStateSQLExceptionTranslator`

### getFallbackTranslator

    public SQLExceptionTranslator getFallbackTranslator()

  Return the fallback exception translator.

### translate

    public DataAccessException translate(String task,
                                         String sql,
                                         SQLException sqlEx)

  Description copied from interface: `SQLExceptionTranslator`
  Translate the given `SQLException` into a generic `DataAccessException`.

  The returned DataAccessException is supposed to contain the original `SQLException` as root cause. However, client code may not generally rely on this due to DataAccessExceptions possibly being caused by other resource APIs as well. That said, a `getRootCause() instanceof SQLException` check (and subsequent cast) is considered reliable when expecting JDBC-based access to have happened.

  Specified by:
    `translate` in interface `SQLExceptionTranslator`
  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:
    the DataAccessException, wrapping the `SQLException`
  See Also:
    `NestedRuntimeException.getRootCause()`

### buildMessage

    protected String buildMessage(String task,
                                  String sql,
                                  SQLException sqlEx)

  Build a message String for the given SQLException. Called when creating an instance of a generic DataAccessException class.

  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:
    the message String to use

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

The Spring Framework

Copyright © 2002-2008 The Spring Framework.