Interface Database

All Superinterfaces:
ConnectionFactory
All Known Implementing Classes:
AbstractDatabase

public interface Database extends ConnectionFactory
Defines DBMS specific functionality as well as basic database configuration settings.
See Also:
  • Field Details

    • DATABASE_URL

      static final PropertyValue<String> DATABASE_URL
      Specifies the jdbc url of the database.
    • DATABASE_INIT_SCRIPTS

      static final PropertyValue<String> DATABASE_INIT_SCRIPTS
      A comma separated list of paths to scripts to run when initializing the database, implementation specific
    • CONNECTION_VALIDITY_CHECK_TIMEOUT

      static final PropertyValue<Integer> CONNECTION_VALIDITY_CHECK_TIMEOUT
      Specifies the timeout (in seconds) to use when checking if database connections are valid.
    • Value type: Integer
    • Default value: 2
    • COUNT_QUERIES

      static final PropertyValue<Boolean> COUNT_QUERIES
      Specifies whether database queries should be counted for collecting statistics.
    • Value type: Boolean
    • Default value: false
    • SELECT_FOR_UPDATE_NOWAIT

      static final PropertyValue<Boolean> SELECT_FOR_UPDATE_NOWAIT
      Specifies whether 'select for update' should be NOWAIT, if supported by the database.
      A database implementation may disregard this.
    • Value type: Boolean
    • Default value: true
    • LOGIN_TIMEOUT

      static final PropertyValue<Integer> LOGIN_TIMEOUT
      Specifies the default login timeout (in seconds).
    • Value type: Integer
    • Default value: 2
    • TRANSACTION_ISOLATION

      static final PropertyValue<Integer> TRANSACTION_ISOLATION
      Specifies the transaction isolation to set for created connections
    • Value type: Integer
    • Default value: null
    • See Also:
    • USER_PROPERTY

      static final String USER_PROPERTY
      The constant used to denote the username value in the connection properties
      See Also:
    • PASSWORD_PROPERTY

      static final String PASSWORD_PROPERTY
      The constant used to denote the password value in the connection properties
      See Also:
  • Method Details

    • name

      String name()
      Returns:
      a name identifying this database
    • autoIncrementQuery

      String autoIncrementQuery(String idSource)
      Returns a query string for retrieving the last automatically generated id from the given id source
      Parameters:
      idSource - the source for the id, for example a sequence name or in the case of Derby, the name of the table auto generating the value
      Returns:
      a query string for retrieving the last auto-increment value from idSource
      Throws:
      NullPointerException - in case idSource is required and is null
    • sequenceQuery

      String sequenceQuery(String sequenceName)
      Returns a query string for selecting the next value from the given sequence.
      Parameters:
      sequenceName - the name of the sequence
      Returns:
      a query for selecting the next value from the given sequence
      Throws:
      UnsupportedOperationException - in case the underlying database does not support sequences
      NullPointerException - in case sequenceName is null
    • selectForUpdateClause

      String selectForUpdateClause()
      Returns a select for update clause, an empty string if not supported.
      Returns:
      a select for update clause
    • limitOffsetClause

      String limitOffsetClause(Integer limit, Integer offset)
      Returns a limit/offset clause variation for this database, based on the given limit and offset values. If both are null an empty string should be returned.
      Parameters:
      limit - the limit
      offset - the offset
      Returns:
      a limit/offset clause
    • subqueryRequiresAlias

      boolean subqueryRequiresAlias()
      Returns true if this database requires that subqueries by aliased.
      Returns:
      true if subqueries require an alias
    • maximumNumberOfParameters

      int maximumNumberOfParameters()
      Returns the maximum number of prepared statement parameters, supported by this database. The default implementation simply returns Integer.MAX_VALUE, as in, no limit.
      Returns:
      the maximum number of prepared statement parameters, supported by this database.
    • errorMessage

      String errorMessage(SQLException exception, Database.Operation operation)
      Returns a user-friendly error message for the given exception, otherwise simply return the message from exception
      Parameters:
      exception - the underlying SQLException
      operation - the operation resulting in the exception
      Returns:
      the message assigned to the given exception
      Throws:
      NullPointerException - in case exception or operation is null
    • exception

      DatabaseException exception(SQLException exception, Database.Operation operation)
      Maps the given SQLException to a DatabaseException.
      Parameters:
      exception - the SQL exception
      operation - the current operation
      Returns:
      a DatabaseException
      Throws:
      NullPointerException - in case exception or operation is null
      See Also:
    • isAuthenticationException

      boolean isAuthenticationException(SQLException exception)
      Returns true if this exception represents a login credentials failure
      Parameters:
      exception - the exception
      Returns:
      true if this exception represents a login credentials failure
      Throws:
      NullPointerException - in case exception is null
    • isReferentialIntegrityException

      boolean isReferentialIntegrityException(SQLException exception)
      Returns true if this exception is a referential integrity exception
      Parameters:
      exception - the exception
      Returns:
      true if this exception is a referential integrity exception
      Throws:
      NullPointerException - in case exception is null
    • isUniqueConstraintException

      boolean isUniqueConstraintException(SQLException exception)
      Returns true if this exception is a unique key exception
      Parameters:
      exception - the exception
      Returns:
      true if this exception is a unique key exception
      Throws:
      NullPointerException - in case exception is null
    • isTimeoutException

      boolean isTimeoutException(SQLException exception)
      Returns true if this exception is a timeout exception
      Parameters:
      exception - the exception
      Returns:
      true if this exception is a timeout exception
      Throws:
      NullPointerException - in case exception is null
    • queryCounter

      Database.QueryCounter queryCounter()
      Returns:
      the Database.QueryCounter for collecting query statistics
    • statistics

      Database.Statistics statistics()
      Returns statistics collected via queryCounter(). Note that calling this method resets the counter.
      Returns:
      collected statistics.
    • createConnectionPool

      ConnectionPoolWrapper createConnectionPool(ConnectionPoolFactory connectionPoolFactory, User poolUser) throws DatabaseException
      Creates a connection pool for the given user in this database.
      Parameters:
      connectionPoolFactory - the ConnectionPoolFactory implementation to use
      poolUser - the user for which to create a connection pool
      Throws:
      DatabaseException - in case of a database exception
    • containsConnectionPool

      boolean containsConnectionPool(String username)
      Parameters:
      username - the username
      Returns:
      true if a connection pool exists for the given username
    • connectionPool

      ConnectionPoolWrapper connectionPool(String username)
      Parameters:
      username - the username
      Returns:
      the connection pool for the given user, null if none exists
      Throws:
      IllegalArgumentException - in case no connection pool exists for the given user
    • connectionPoolUsernames

      Collection<String> connectionPoolUsernames()
      Returns:
      the usernames of all available connection pools
    • closeConnectionPool

      void closeConnectionPool(String username)
      Closes and removes the pool associated with the given user
      Parameters:
      username - the username of the pool that should be removed
    • closeConnectionPools

      void closeConnectionPools()
      Closes and removes all available connection pools
    • connectionProvider

      void connectionProvider(ConnectionProvider connectionProvider)
      Sets the ConnectionProvider instance used when creating connections.
      Parameters:
      connectionProvider - the connection provider
    • instance

      static Database instance()
      Returns a Database instance based on the currently configured JDBC URL (DATABASE_URL). Subsequent calls to this method return the same instance, until the JDBC URL changes, then a new instance is created.
      Returns:
      a Database instance based on the current jdbc url
      Throws:
      IllegalArgumentException - in case an unsupported database type is specified
      RuntimeException - in case of an exception occurring while instantiating the database implementation
      See Also: