Package com.saperion.common.sql

Class DataSource<CommonAccessException extends java.lang.Exception,​CommonReadResultException extends java.lang.Exception>

  • 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 java.lang.Exception,​CommonReadResultException extends java.lang.Exception>
extends java.lang.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 Detail

      • LOGGER

        protected static final Logger LOGGER

    • Constructor Detail

      • DataSource

        protected DataSource​(javax.sql.DataSource dataSource)
        Creates a new DataSource encapsulating the specified DataSource.

        The specified DataSource must not be null.

        Parameters:
        dataSource - underlying DataSource

    • Method Detail

      • getSqlDataSource

        public javax.sql.DataSource getSqlDataSource()
        Returns the underlying raw DataSource.
        Returns:
        the underlying raw DataSource

      • executeUpdate

        public int executeUpdate​(java.lang.String sql)
                  throws CommonAccessException extends java.lang.Exception
        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
        CommonAccessException extends java.lang.Exception

      • onErrorGettingConnection

        protected abstract CommonAccessException onErrorGettingConnection​(java.lang.Throwable t,
                                                                  java.lang.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​(java.lang.Throwable t,
                                                                  java.lang.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​(java.lang.Throwable t,
                                                                java.lang.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​(java.lang.Throwable t,
                                                               java.lang.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​(java.lang.Throwable t,
                                                                 java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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