Package 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 meta-data.
- Fallback to a fallback translator. `SQLStateSQLExceptionTranslator` is the default fallback translator, analyzing the exception's SQL state only. Since Java 6 which introduces its own `SQLException` subclass hierarchy, we 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 (for example, in the "/WEB-INF/classes" directory), as long as the Spring JDBC package is loaded from the same ClassLoader.

This translator is commonly used by default if a user-provided `sql-error-codes.xml` file has been found in the root of the classpath, as a signal to use this strategy. Otherwise, `SQLExceptionSubclassTranslator` serves as the default translator as of 6.0.

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

## Field Summary

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

`logger`

## Constructor Summary

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

## Method Summary

Modifier and Type
Method
Description
`protected org.springframework.dao.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 org.springframework.dao.DataAccessException`
`customTranslate(String task, String sql, SQLException sqlEx)`
Deprecated.
as of 6.1, in favor of `AbstractFallbackSQLExceptionTranslator.setCustomTranslator(org.springframework.jdbc.support.SQLExceptionTranslator)`
`protected org.springframework.dao.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, getCustomTranslator, getFallbackTranslator, setCustomTranslator, setFallbackTranslator, translate`

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

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

## Constructor Details

### SQLErrorCodeSQLExceptionTranslator

public SQLErrorCodeSQLExceptionTranslator()
Constructor for use as a JavaBean. The SqlErrorCodes or DataSource property must be set.

### SQLErrorCodeSQLExceptionTranslator

public SQLErrorCodeSQLExceptionTranslator(DataSource dataSource)
Create an SQL error code translator for the given DataSource. Invoking this constructor will cause a Connection to be obtained from the DataSource to get the meta-data.

Parameters:
  `dataSource` - the DataSource to use to find meta-data and establish which error codes are usable
See Also:
  - `SQLErrorCodesFactory`

### SQLErrorCodeSQLExceptionTranslator

public SQLErrorCodeSQLExceptionTranslator(String dbName)
Create an SQL error code translator for the given database product name. Invoking this constructor will avoid obtaining a Connection from the DataSource to get the meta-data.

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

### SQLErrorCodeSQLExceptionTranslator

public SQLErrorCodeSQLExceptionTranslator(SQLErrorCodes sec)
Create an SQLErrorCode translator given these error codes. Does not require a database meta-data lookup to be performed using a connection.

Parameters:
  `sec` - error codes

## Method Details

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

Parameters:
  `dataSource` - the DataSource to use to find meta-data 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 meta-data.

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

### setSqlErrorCodes

public void setSqlErrorCodes(@Nullable SQLErrorCodes sec)
Set custom error codes to be used for translation.

Parameters:
  `sec` - custom error codes to use

### getSqlErrorCodes

@Nullable public SQLErrorCodes getSqlErrorCodes()
Return the error codes used by this translator. Usually determined via a DataSource.

See Also:
  - `setDataSource(javax.sql.DataSource)`

### doTranslate

@Nullable protected org.springframework.dao.DataAccessException doTranslate(String task, @Nullable 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` - the SQL query or update that caused the problem (if known)
  `ex` - the offending `SQLException`
Returns:
  the DataAccessException, wrapping the `SQLException`; or `null` if no exception match found

### customTranslate

@Deprecated(since="6.1") @Nullable protected org.springframework.dao.DataAccessException customTranslate(String task, @Nullable String sql, SQLException sqlEx)
Deprecated.
as of 6.1, in favor of `AbstractFallbackSQLExceptionTranslator.setCustomTranslator(org.springframework.jdbc.support.SQLExceptionTranslator)`
Subclasses can override this method to attempt a custom mapping from `SQLException` to `DataAccessException`.

Parameters:
  `task` - readable text describing the task being attempted
  `sql` - the SQL query or update that caused the problem (may be `null`)
  `sqlEx` - the offending SQLException
Returns:
  `null` if no custom translation applies, 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

@Nullable protected org.springframework.dao.DataAccessException createCustomException(String task, @Nullable 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` - the 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<?>)`