Package com.saperion.common.sql

Class DataSource<CommonAccessException extends Exception,CommonReadResultException extends Exception>

java.lang.Object

com.saperion.common.sql.DataSource<CommonAccessException,CommonReadResultException>

Type Parameters:

CommonAccessException - common type of all provided Exceptions during connection-handling and sql-execution

CommonReadResultException - common type of all used ResultReaders during executeQuery(String, ResultReader) -operations to signal business-exceptions during ResultReader.readResult(ResultSet)

Direct Known Subclasses:

SimpleDataSource

public abstract class DataSource<CommonAccessException extends Exception,CommonReadResultException extends Exception>
extends Object

DataSource encapsulates a DataSource and provides simple SQL-execution-methods ( executeUpdate(String), executeQuery(String, ResultReader)) with all the necessary error treatment.

This class contains a lot of methods signaling events in its work flow or requesting for concrete Exceptions in case of an error. This way subclasses may fine-tune the logging, collecting of runtime-informations and error-reporting.

A simple implementation that can be used directly and that has no logging, no runtime-information and treats all errors as IllegalStateExceptions is SimpleDataSource. While this class is easy to use, it is still strongly recommended to write your own subclass in any real project.

Author:

agz

See Also:

• SqlDialect

Field Summary

Fields

Modifier and Type	Field	Description
protected static final Logger	LOGGER

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	DataSource(DataSource dataSource)	Creates a new DataSource encapsulating the specified DataSource.

Method Summary

Modifier and Type	Method	Description
protected abstract void	afterExecuteQuery(String sql)	This event-method is called immediately after Statement.executeQuery(String) was successfully called.
protected abstract void	afterExecuteUpdate(String sql, int rowCount)	This event-method is called immediately after Statement.executeUpdate(String) was successfully called.
protected abstract void	afterReadResult(String sql, int rowCount)	This event-method is called immediately after ResultReader.readResult(ResultSet) was successfully called.It is called after noteReadResultTime(String, long, boolean).
protected abstract void	beforeExecuteQuery(String sql)	This event-method is called immediately before Statement.executeQuery(String) is called.
protected abstract void	beforeExecuteUpdate(String sql)	This event-method is called immediately before Statement.executeUpdate(String) is called.
protected abstract void	beforeReadResult(String sql)	This event-method is called immediately before ResultReader.readResult(ResultSet) is called.
void	executeQuery(String sql, ResultReader<? extends CommonReadResultException> resultReader)	Executes the specified SQL-select statement and calls the specified ResultReader.
int	executeUpdate(String sql)	Executes the specified SQL-update statement and returns the count of manipulated rows.
DataSource	getSqlDataSource()	Returns the underlying raw DataSource.
SqlDialect	getSqlDialect()	Returns the SqlDialect of the underlying DataSource.
protected abstract void	noteExecuteQueryTime(String sql, long timeNanoseconds, boolean success)	This event-method is called immediately after Statement.executeQuery(String) is called, no matter whether the call was successful or not.
protected abstract void	noteExecuteUpdateTime(String sql, long timeNanoseconds, boolean success)	This event-method is called immediately after Statement.executeUpdate(String) is called, no matter whether the call was successful or not.
protected abstract void	noteReadResultTime(String sql, long timeNanoseconds, boolean success)	This event-method is called immediately after ResultReader.readResult(ResultSet) is called, no matter whether the call was successful or not.
protected abstract CommonAccessException	onErrorCreatingStatement(Throwable t, String sql)	This event-method is called by all SQL-execution-methods if there is no Statement available from the underlying Connection.
protected abstract CommonAccessException	onErrorExecutingQuery(Throwable t, String sql)	This event-method is called by executeQuery(String, ResultReader) if there is any error executing the statement.
protected abstract CommonAccessException	onErrorExecutingUpdate(Throwable t, String sql)	This event-method is called by executeUpdate(String) if there is any error executing the statement.
protected abstract CommonAccessException	onErrorGettingConnection(Throwable t, String sql)	This event-method is called by all SQL-execution-methods if there is no Connection available from the underlying DataSource.
protected abstract CommonAccessException	onErrorGettingDatabaseProductName(Throwable t)	This event-method is called by getSqlDialect() if there is any error getting the database product name.
protected abstract CommonAccessException	onErrorGettingMetaData(Throwable t)	This event-method is called by getSqlDialect() if there is any error getting the DatabaseMetaData.
protected abstract CommonAccessException	onErrorReadingResultSet(Throwable t, String sql)	This event-method is called by executeQuery(String, ResultReader) if there is any error reading the ResultSet.

Methods inherited from class java.lang.Object

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

Field Details

LOGGER

protected static final Logger LOGGER

Constructor Details

DataSource

protected DataSource(DataSource dataSource)

Creates a new DataSource encapsulating the specified DataSource.

The specified DataSource must not be null.

Parameters:

dataSource - underlying DataSource

Method Details

getSqlDataSource

public DataSource getSqlDataSource()

Returns the underlying raw DataSource.

Returns:

the underlying raw DataSource

getSqlDialect

public SqlDialect getSqlDialect()
                         throws CommonAccessException

Returns the SqlDialect of the underlying DataSource.

This method caches the result of the analysis, so one can call it cheaply several times.

Returns:

the SqlDialect

Throws:

CommonAccessException - on errors during connection-handling and meta-data analysis

IllegalArgumentException - if the database product name is unknown to SqlDialect

executeUpdate

public int executeUpdate(String sql)
                  throws CommonAccessException

Executes the specified SQL-update statement and returns the count of manipulated rows. (Returns the same as Statement.executeUpdate(String).

The specified SQL-update statement must not be null.

Parameters:

sql - SQL-update statement to execute

Returns:

count of manipulated rows

Throws:

CommonAccessException - on errors during connection-handling and sql-execution

executeQuery

public void executeQuery(String sql,
 ResultReader<? extends CommonReadResultException> resultReader)
                  throws CommonAccessException,
CommonReadResultException

Executes the specified SQL-select statement and calls the specified ResultReader.

The specified SQL-select statement must not be null.

The specified ResultReader must not be null.

Parameters:

sql - SQL-select statement to execute

resultReader - ResultReader to call

Throws:

CommonAccessException - on errors during connection-handling and sql-execution

CommonReadResultException - on business-errors signaled by the ResultReader

onErrorGettingConnection

protected abstract CommonAccessException onErrorGettingConnection(Throwable t,
 String sql)

This event-method is called by all SQL-execution-methods if there is no Connection available from the underlying DataSource. This method must return a suitable Exception.

Parameters:

t - original Throwable thrown by DataSource.getConnection()

sql - SQL-statement of the SQL-execution-method

Returns:

a suitable Exception

onErrorCreatingStatement

protected abstract CommonAccessException onErrorCreatingStatement(Throwable t,
 String sql)

This event-method is called by all SQL-execution-methods if there is no Statement available from the underlying Connection. This method must return a suitable Exception.

Parameters:

t - original Throwable thrown by Connection.createStatement()

sql - SQL-statement of the SQL-execution-method

Returns:

a suitable Exception

onErrorExecutingUpdate

protected abstract CommonAccessException onErrorExecutingUpdate(Throwable t,
 String sql)

This event-method is called by executeUpdate(String) if there is any error executing the statement. This method must return a suitable Exception.

Parameters:

t - original Throwable thrown by Statement.executeUpdate(String)

sql - SQL-statement of the SQL-execution-method

Returns:

a suitable Exception

onErrorExecutingQuery

protected abstract CommonAccessException onErrorExecutingQuery(Throwable t,
 String sql)

This event-method is called by executeQuery(String, ResultReader) if there is any error executing the statement. This method must return a suitable Exception.

Parameters:

t - original Throwable thrown by Statement.executeQuery(String)

sql - SQL-statement of the SQL-execution-method

Returns:

a suitable Exception

onErrorReadingResultSet

protected abstract CommonAccessException onErrorReadingResultSet(Throwable t,
 String sql)

This event-method is called by executeQuery(String, ResultReader) if there is any error reading the ResultSet. This method must return a suitable Exception.

Parameters:

t - original Throwable thrown by any of the ResultSet.get...()-methods

sql - SQL-statement of the SQL-execution-method

Returns:

a suitable Exception

onErrorGettingMetaData

protected abstract CommonAccessException onErrorGettingMetaData(Throwable t)

This event-method is called by getSqlDialect() if there is any error getting the DatabaseMetaData. This method must return a suitable Exception.

Parameters:

t - original Throwable thrown by Connection.getMetaData()

Returns:

a suitable Exception

onErrorGettingDatabaseProductName

protected abstract CommonAccessException onErrorGettingDatabaseProductName(Throwable t)

This event-method is called by getSqlDialect() if there is any error getting the database product name. This method must return a suitable Exception.

Parameters:

t - original Throwable thrown by DatabaseMetaData.getDatabaseProductName()

Returns:

a suitable Exception

beforeExecuteUpdate

protected abstract void beforeExecuteUpdate(String sql)

This event-method is called immediately before Statement.executeUpdate(String) is called.

Parameters:

sql - SQL-statement of the SQL-execution-method

noteExecuteUpdateTime

protected abstract void noteExecuteUpdateTime(String sql,
 long timeNanoseconds,
 boolean success)

This event-method is called immediately after Statement.executeUpdate(String) is called, no matter whether the call was successful or not.

Parameters:

sql - SQL-statement of the SQL-execution-method

timeNanoseconds - the execution-time of Statement.executeUpdate(String) in nanoseconds, no matter whether the call was successful or not

success - indicates whether the call was successful or not

afterExecuteUpdate

protected abstract void afterExecuteUpdate(String sql,
 int rowCount)

This event-method is called immediately after Statement.executeUpdate(String) was successfully called. It is called after noteExecuteUpdateTime(String, long, boolean).

Parameters:

sql - SQL-statement of the SQL-execution-method

rowCount - count of manipulated rows

beforeExecuteQuery

protected abstract void beforeExecuteQuery(String sql)

This event-method is called immediately before Statement.executeQuery(String) is called.

Parameters:

sql - SQL-statement of the SQL-execution-method

noteExecuteQueryTime

protected abstract void noteExecuteQueryTime(String sql,
 long timeNanoseconds,
 boolean success)

This event-method is called immediately after Statement.executeQuery(String) is called, no matter whether the call was successful or not.

Parameters:

sql - SQL-statement of the SQL-execution-method

timeNanoseconds - the execution-time of Statement.executeQuery(String) in nanoseconds, no matter whether the call was successful or not

success - indicates whether the call was successful or not

afterExecuteQuery

protected abstract void afterExecuteQuery(String sql)

This event-method is called immediately after Statement.executeQuery(String) was successfully called. It is called after noteExecuteQueryTime(String, long, boolean).

Parameters:

sql - SQL-statement of the SQL-execution-method

beforeReadResult

protected abstract void beforeReadResult(String sql)

This event-method is called immediately before ResultReader.readResult(ResultSet) is called.

Parameters:

sql - SQL-statement of the SQL-execution-method

noteReadResultTime

protected abstract void noteReadResultTime(String sql,
 long timeNanoseconds,
 boolean success)

This event-method is called immediately after ResultReader.readResult(ResultSet) is called, no matter whether the call was successful or not.

Parameters:

sql - SQL-statement of the SQL-execution-method

timeNanoseconds - the execution-time of ResultReader.readResult(ResultSet) in nanoseconds, no matter whether the call was successful or not

success - indicates whether the call was successful or not

afterReadResult

protected abstract void afterReadResult(String sql,
 int rowCount)

This event-method is called immediately after ResultReader.readResult(ResultSet) was successfully called.It is called after noteReadResultTime(String, long, boolean).

Parameters:

sql - SQL-statement of the SQL-execution-method

rowCount - count of selected rows