Module is.codion.common.db
Package is.codion.common.db.database

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.

Note that the PropertyValue configuration settings declared here are read once, when the Database implementation is loaded or constructed; changing them afterwards has no effect.

Connection pool management (createConnectionPool(is.codion.common.db.pool.ConnectionPoolFactory, is.codion.common.utilities.user.User), closeConnectionPool(java.lang.String), closeConnectionPools()) is expected to be performed at application startup from a single thread and is not synchronized.

See Also:

  • Field Details

    • URL

      static final PropertyValue<String> URL
      Specifies the jdbc url of the database.

    • URL_SCOPED_INSTANCE

      static final PropertyValue<Boolean> URL_SCOPED_INSTANCE
      Specifies whether instance() should create a new instance each time the database URL has changed. This is convenient when running tests using in-memory databases.
      • Value type: Boolean
      • Default value: false
      See Also:

    • INIT_SCRIPTS

      static final PropertyValue<String> 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. This determines how long to wait for a connection validity check before considering it failed. Lower values detect failed connections faster but may timeout prematurely on slow networks.
      • Value type: Integer
      • Default value: 2 seconds
      • Property name: codion.db.validityCheckTimeout

    • 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).

      Applied JVM-wide via DriverManager.setLoginTimeout(int) when the Database implementation is loaded, affecting all JDBC usage in the process, not only Codion's.

      • 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:

    • LEGACY_JDBC

      static final PropertyValue<Boolean> LEGACY_JDBC
      Specifies whether temporal columns are read using the pre-JDBC-4.2 java.sql accessors (ResultSet.getTimestamp(int) etc.) instead of ResultSet.getObject(int, Class), for platforms whose java.sql.ResultSet predates JDBC 4.2 — notably Android, whose ResultSet does not declare getObject(int, Class). Leaves every other column type unchanged.
      • Value type: Boolean
      • Default value: false

    • USER

      static final String USER
      The key used to specify the username in connection properties
      See Also:

    • PASSWORD

      static final String PASSWORD
      The key used to specify the password in connection properties
      See Also:

  • Method Details

    • name

      String name()
      Returns:
      a name identifying this database

    • getter

      GetValue<?> getter(int sqlType)
      Returns the GetValue for reading a value of the given SQL type from a ResultSet.
      Parameters:
      sqlType - the SQL type
      Returns:
      the GetValue for the given SQL type
      Throws:
      IllegalArgumentException - in case no getter is available for the given type
      See Also:

    • setter

      SetValue<?> setter(int sqlType)
      Returns the SetValue for setting a value of the given SQL type on a PreparedStatement.
      Parameters:
      sqlType - the SQL type
      Returns:
      the SetValue for the given SQL type
      Throws:
      IllegalArgumentException - in case no setter is available for the given type

    • 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 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(@Nullable Integer limit, @Nullable 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 is 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

    • maximumParameters

      int maximumParameters()
      Returns the maximum number of prepared statement parameters supported by this database, Integer.MAX_VALUE indicating no limit.
      Returns:
      the maximum number of prepared statement parameters, supported by this database.

    • errorMessage

      @Nullable 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)
      Wraps the given SQLException in a relevant 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)
      Creates a connection pool for the given user in this database. The pool is keyed on the username, case-insensitively.
      Parameters:
      connectionPoolFactory - the ConnectionPoolFactory implementation to use
      poolUser - the user for which to create a connection pool
      Returns:
      a new ConnectionPoolWrapper
      Throws:
      DatabaseException - in case of a database exception
      IllegalStateException - in case a connection pool already exists for the given user

    • containsConnectionPool

      boolean containsConnectionPool(String username)
      The username is case-insensitive.
      Parameters:
      username - the username
      Returns:
      true if a connection pool exists for the given username

    • connectionPool

      ConnectionPoolWrapper connectionPool(String username)
      The username is case-insensitive.
      Parameters:
      username - the username
      Returns:
      the connection pool for the given user
      Throws:
      IllegalArgumentException - in case no connection pool exists for the given user

    • connectionPoolUsernames

      Collection<String> connectionPoolUsernames()
      Note that the returned usernames are lower case.
      Returns:
      the usernames of all available connection pools

    • closeConnectionPool

      void closeConnectionPool(String username)
      Closes and removes the pool associated with the given user. The username is case-insensitive.
      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 to use when creating connections.
      Parameters:
      connectionProvider - the connection provider

    • close

      void close()
      Closes this database, releasing any local resources, like connection pools or in memory storage.
      See Also:

    • instance

      static Database instance()
      Returns a Database instance based on the currently configured JDBC URL (URL). Subsequent changes to URL will cause an exception to be thrown unless URL_SCOPED_INSTANCE is enabled, then a new instance is created and returned.
      Returns:
      a Database instance based on the current jdbc url
      Throws:
      IllegalStateException - in case an unsupported database type is specified
      RuntimeException - in case of an exception occurring while instantiating the database implementation
      DatabaseException - in case URL has changed and URL_SCOPED_INSTANCE is not enabled
      See Also: