Spring Framework 6.1.4 · org.springframework.jdbc.support.SQLErrorCodeSQLExceptionTranslator

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.

Field Summary

Modifier and Type	Field and Description
private static final int	MESSAGE_ONLY_CONSTRUCTOR
private static final int	MESSAGE_SQL_SQLEX_CONSTRUCTOR
private static final int	MESSAGE_SQL_THROWABLE_CONSTRUCTOR
private static final int	MESSAGE_SQLEX_CONSTRUCTOR
private static final int	MESSAGE_THROWABLE_CONSTRUCTOR
private SingletonSupplier<SQLErrorCodes>	sqlErrorCodes
private static final boolean	userProvidedErrorCodesFilePresent

Inherited from org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator:: logger

Constructor Summary

Access	Constructor and Description
public	SQLErrorCodeSQLExceptionTranslator() Constructor for use as a JavaBean.
public	SQLErrorCodeSQLExceptionTranslator(DataSource the DataSource to use to find meta-data and establish which error codes are usable dataSource) Create an SQL error code translator for the given DataSource.
public	SQLErrorCodeSQLExceptionTranslator(String the database product name that identifies the error codes entry dbName) Create an SQL error code translator for the given database product name.
public	SQLErrorCodeSQLExceptionTranslator(SQLErrorCodes error codes sec) Create an SQLErrorCode translator given these error codes.

Method Summary

Modifier and Type	Method and Description
protected DataAccessException	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. createCustomException(String readable text describing the task being attempted task, String the SQL query or update that caused the problem (may be `null`) sql, SQLException the offending SQLException sqlEx, Class<?> the exception class to use, as defined in the `CustomSQLErrorCodesTranslation` definition exceptionClass) Create a custom `DataAccessException`, based on a given exception class from a `CustomSQLErrorCodesTranslation` definition.
protected DataAccessException	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. customTranslate(String readable text describing the task being attempted task, String the SQL query or update that caused the problem (may be `null`) sql, SQLException the offending SQLException sqlEx) Deprecated since 6.1. as of 6.1, in favor of `setCustomTranslator` Subclasses can override this method to attempt a custom mapping from `SQLException` to `DataAccessException`.
protected DataAccessException	doTranslate(String readable text describing the task being attempted task, String the SQL query or update that caused the problem (if known) sql, SQLException the offending `SQLException` ex) Implements abstract org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator.doTranslate. Template method for actually translating the given exception.
public SQLErrorCodes	getSqlErrorCodes() Return the error codes used by this translator.
pack-priv static boolean	hasUserProvidedErrorCodesFile() Check whether there is a user-provided `sql-error-codes.xml` file in the root of the classpath.
private void	logTranslation(String task, String sql, SQLException sqlEx, boolean custom)
public void	setDatabaseProductName(String the database product name that identifies the error codes entry dbName) Set the database product name for this translator.
public void	setDataSource(DataSource the DataSource to use to find meta-data and establish which error codes are usable dataSource) Set the DataSource for this translator.
public void	setSqlErrorCodes(SQLErrorCodes custom error codes to use sec) Set custom error codes to be used for translation.

Inherited from org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator:: buildMessage getCustomTranslator getFallbackTranslator setCustomTranslator setFallbackTranslator translate

Field Detail

MESSAGE_ONLY_CONSTRUCTOR	back to summary
private static final int MESSAGE_ONLY_CONSTRUCTOR

MESSAGE_SQL_SQLEX_CONSTRUCTOR	back to summary
private static final int MESSAGE_SQL_SQLEX_CONSTRUCTOR

MESSAGE_SQL_THROWABLE_CONSTRUCTOR	back to summary
private static final int MESSAGE_SQL_THROWABLE_CONSTRUCTOR

MESSAGE_SQLEX_CONSTRUCTOR	back to summary
private static final int MESSAGE_SQLEX_CONSTRUCTOR

MESSAGE_THROWABLE_CONSTRUCTOR	back to summary
private static final int MESSAGE_THROWABLE_CONSTRUCTOR

sqlErrorCodes	back to summary
private SingletonSupplier<SQLErrorCodes> sqlErrorCodes Annotations @Nullable

userProvidedErrorCodesFilePresent	back to summary
private static final boolean userProvidedErrorCodesFilePresent

Constructor Detail

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

SQLErrorCodeSQLExceptionTranslator back to summary

SQLErrorCodeSQLExceptionTranslator	back to summary
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:DataSource the DataSource to use to find meta-data and establish which error codes are usable See Also `SQLErrorCodesFactory`

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:DataSource: the DataSource to use to find meta-data and establish which error codes are usable

See Also

SQLErrorCodesFactory

SQLErrorCodeSQLExceptionTranslator back to summary

SQLErrorCodeSQLExceptionTranslator	back to summary
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:String the database product name that identifies the error codes entry See Also `SQLErrorCodesFactory`, `java.sql.DatabaseMetaData#getDatabaseProductName()`

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:String: the database product name that identifies the error codes entry

SQLErrorCodeSQLExceptionTranslator	back to summary
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:SQLErrorCodes error codes

SQLErrorCodeSQLExceptionTranslator

back to summary

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:SQLErrorCodes: error codes

Method Detail

createCustomException back to summary

createCustomException	back to 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. Parameters task:String readable text describing the task being attempted sql:String the SQL query or update that caused the problem (may be `null`) sqlEx:SQLException the offending SQLException exceptionClass:Class<?> the exception class to use, as defined in the `CustomSQLErrorCodesTranslation` definition Returns:DataAccessException `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. Annotations @Nullable See Also `CustomSQLErrorCodesTranslation#setExceptionClass`

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:String: readable text describing the task being attempted
sql:String: the SQL query or update that caused the problem (may be null)
sqlEx:SQLException: the offending SQLException
exceptionClass:Class<?>: the exception class to use, as defined in the CustomSQLErrorCodesTranslation definition

Returns:DataAccessException

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.

Annotations

@Nullable

customTranslate back to summary

customTranslate	back to summary
protected DataAccessException customTranslate(String task, String sql, SQLException sqlEx) Deprecated since 6.1. as of 6.1, in favor of `setCustomTranslator` Subclasses can override this method to attempt a custom mapping from `SQLException` to `DataAccessException`. Parameters task:String readable text describing the task being attempted sql:String the SQL query or update that caused the problem (may be `null`) sqlEx:SQLException the offending SQLException Returns:DataAccessException `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. Annotations @Deprecated since:6.1 @Nullable

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

Deprecated

since 6.1.

as of 6.1, in favor of setCustomTranslator

Subclasses can override this method to attempt a custom mapping from SQLException to DataAccessException.

Parameters

task:String: readable text describing the task being attempted
sql:String: the SQL query or update that caused the problem (may be null)
sqlEx:SQLException: the offending SQLException

Returns:DataAccessException

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.

Annotations

@Deprecated
since:6.1
@Nullable

doTranslate back to summary

doTranslate	back to summary
protected DataAccessException doTranslate(String task, String sql, SQLException ex) Implements abstract org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator.doTranslate. Doc from org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator.doTranslate. 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. Parameters task:String readable text describing the task being attempted sql:String the SQL query or update that caused the problem (if known) ex:SQLException the offending `SQLException` Returns:DataAccessException the DataAccessException, wrapping the `SQLException`; or `null` if no exception match found Annotations @SuppressWarnings:deprecation @Override @Nullable

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

Implements abstract org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator.doTranslate.

Doc from org.springframework.jdbc.support.AbstractFallbackSQLExceptionTranslator.doTranslate.

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.

Parameters

task:String: readable text describing the task being attempted
sql:String: the SQL query or update that caused the problem (if known)
ex:SQLException: the offending SQLException

Returns:DataAccessException

the DataAccessException, wrapping the SQLException; or null if no exception match found

Annotations

@SuppressWarnings:deprecation
@Override
@Nullable

getSqlErrorCodes back to summary

getSqlErrorCodes	back to summary
public SQLErrorCodes getSqlErrorCodes() Return the error codes used by this translator. Usually determined via a DataSource. Annotations @Nullable See Also `setDataSource`

public SQLErrorCodes getSqlErrorCodes()

Return the error codes used by this translator. Usually determined via a DataSource.

Annotations

@Nullable

See Also

setDataSource

hasUserProvidedErrorCodesFile	back to summary
pack-priv static boolean hasUserProvidedErrorCodesFile() Check whether there is a user-provided `sql-error-codes.xml` file in the root of the classpath.

logTranslation	back to summary
private void logTranslation(String task, String sql, SQLException sqlEx, boolean custom)

setDatabaseProductName back to summary

setDatabaseProductName	back to summary
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:String the database product name that identifies the error codes entry See Also `SQLErrorCodesFactory#getErrorCodes(String)`, `java.sql.DatabaseMetaData#getDatabaseProductName()`

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:String: the database product name that identifies the error codes entry

setDataSource back to summary

setDataSource	back to summary
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:DataSource the DataSource to use to find meta-data and establish which error codes are usable See Also `SQLErrorCodesFactory#getErrorCodes(javax.sql.DataSource)`, `java.sql.DatabaseMetaData#getDatabaseProductName()`

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:DataSource: the DataSource to use to find meta-data and establish which error codes are usable

setSqlErrorCodes	back to summary
public void setSqlErrorCodes(SQLErrorCodes sec) Set custom error codes to be used for translation. Parameters sec:SQLErrorCodes custom error codes to use

setSqlErrorCodes

back to summary

public void setSqlErrorCodes(SQLErrorCodes sec)

Set custom error codes to be used for translation.

Parameters

sec:SQLErrorCodes: custom error codes to use

public Class SQLErrorCodeSQLExceptionTranslator

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail