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

Interface Database

    • Field Detail

      • 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

      • QUERY_COUNTER_ENABLED

        static final PropertyValue<Boolean> QUERY_COUNTER_ENABLED
        Specifies whether database queries should be counted.
        Value type: Boolean
        Default value: true

      • 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

      • USER_PROPERTY

        static final String USER_PROPERTY
        The constant used to denote the username value in the connection properties
        See Also:
        Constant Field Values

      • PASSWORD_PROPERTY

        static final String PASSWORD_PROPERTY
        The constant used to denote the password value in the connection properties
        See Also:
        Constant Field Values

    • Method Detail

      • 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

      • shutdownEmbedded

        void shutdownEmbedded()
        This should shut down the database in case it is an embedded one and if that is applicable, such as for Derby.

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

      • checkConnectionQuery

        String checkConnectionQuery()
        Returns a query to use when checking if the connection is valid, this is used in cases where the dbms does not support the isValid() call. Returning null is safe if isValid() is supported.
        Returns:
        a check connection query
        See Also:
        supportsIsValid()

      • validityCheckTimeout

        int validityCheckTimeout()
        Returns:
        the timeout in seconds to use when checking connection validity

      • errorMessage

        String errorMessage​(SQLException exception)
        Returns a user-friendly error message for the given exception, otherwise simply return the message from exception
        Parameters:
        exception - the underlying SQLException
        Returns:
        the message assigned to the given exception

      • 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

      • 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

      • 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

      • 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

      • countQuery

        void countQuery​(String query)
        Counts this query, based on the first character.
        Parameters:
        query - the query to count
        See Also:
        statistics()

      • createConnectionPool

        void 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

      • connectionPool

        ConnectionPoolWrapper connectionPool​(String username)
        Parameters:
        username - the username
        Returns:
        the connection pool for the given user, null if none exists

      • 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

      • setConnectionProvider

        void setConnectionProvider​(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:
        DATABASE_URL

      • closeSilently

        static void closeSilently​(ResultSet resultSet)
        Closes the given ResultSet instance, suppressing any SQLExceptions that may occur.
        Parameters:
        resultSet - the result set to close

      • closeSilently

        static void closeSilently​(Statement statement)
        Closes the given Statement instance, suppressing any SQLExceptions that may occur.
        Parameters:
        statement - the statement to close

      • closeSilently

        static void closeSilently​(Connection connection)
        Closes the given Connection instance, suppressing any SQLExceptions that may occur.
        Parameters:
        connection - the connection to close