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 (e.g. 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 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)	Deprecated. as of 6.1, in favor of AbstractFallbackSQLExceptionTranslator.setCustomTranslator(org.springframework.jdbc.support.SQLExceptionTranslator)
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, 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 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 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 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<?>)