Class DatabaseConnection

    • Field Detail

      • FETCH_SIZE

        public static final int FETCH_SIZE
        The fetch size given to Statement.setFetchSize(int). This value may be increased over time as the amount of typical system memory increases. As this may affect the number of round trips, and the speed of light is not likely to change, future increases may be of benefit.

        We've been using a value of 1000 for nearly two decades. As of the year 2020, we've bumped this up to 10000.

        See Also:
        Constant Field Values
    • Constructor Detail

      • DatabaseConnection

        protected DatabaseConnection​(Database database)
    • Method Detail

      • getDatabase

        public Database getDatabase()
      • getConnection

        public Connection getConnection()
                                 throws SQLException
        Gets the read/write connection to the database with a transaction level of Connections.DEFAULT_TRANSACTION_ISOLATION, warning when a connection is already used by this thread.

        Uses a deferred connection strategy. If not previously connected, allocates the connection now. This allows applications to create DatabaseConnection at no cost, only connecting to the database when first needed. This is helpful for when a transaction scope is established at a high level, where the actual use (or lack thereof) of the database is unknown.

        The default auto-commit state depends on the read-only and isolation levels. Upon initial connection, auto-commit is enabled. It then remains unchanged while is read-only and at an isolation level of Connection.TRANSACTION_READ_COMMITTED or below. This means, conversely, that auto-commit is disabled when is either read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above.

        When a connection already exists, its read-only mode may be changed, but may not be changed on a connection that has auto-commit disabled (which typically means it was either already read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above).

        With the default auto-commit behavior (auto-commit not disabled by application), it is an error to try to change from read-only to read-write while at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above, as the necessary actions to make the change would break the repeatable-read guarantee.

        Read-write connections will not be set back to read-only mode when the connection has auto-commit disabled, thus the read-only flag is an optimization and an extra level of protection, but cannot be relied upon due to potentially being within the scope of a larger read-write transaction.

        When a connection already exists, its isolation level may be increased, but will never be decreased. However, the ability to change the isolation level within a transaction is driver dependent. It is best to set the highest isolation level that will be required at the beginning of the transaction.

        If all the connections in the pool are busy and the pool is at capacity, waits until a connection becomes available.

        The connection will be a FailFastConnection, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The fail-fast connection is used to determine whether to roll-back or commit during automatic transaction management.

        The connection will also be a ConnectionTracker, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The connection tracking is used to close/free all objects before returning the connection to the underlying pool.

        Returns:
        The read/write connection to the database.

        This connection may be used in try-with-resources, but any calls to Connection.close() are ignored. Instead, the connection is released and/or closed when this DatabaseConnection is closed.

        Throws:
        SQLException - when an error occurs, or when a thread attempts to allocate more than half the pool
        See Also:
        getConnection(int, boolean, int), Database.getConnection(), Connection.close()
      • getConnection

        public Connection getConnection​(int maxConnections)
                                 throws SQLException
        Gets the read/write connection to the database with a transaction level of Connections.DEFAULT_TRANSACTION_ISOLATION.

        Uses a deferred connection strategy. If not previously connected, allocates the connection now. This allows applications to create DatabaseConnection at no cost, only connecting to the database when first needed. This is helpful for when a transaction scope is established at a high level, where the actual use (or lack thereof) of the database is unknown.

        The default auto-commit state depends on the read-only and isolation levels. Upon initial connection, auto-commit is enabled. It then remains unchanged while is read-only and at an isolation level of Connection.TRANSACTION_READ_COMMITTED or below. This means, conversely, that auto-commit is disabled when is either read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above.

        When a connection already exists, its read-only mode may be changed, but may not be changed on a connection that has auto-commit disabled (which typically means it was either already read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above).

        With the default auto-commit behavior (auto-commit not disabled by application), it is an error to try to change from read-only to read-write while at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above, as the necessary actions to make the change would break the repeatable-read guarantee.

        Read-write connections will not be set back to read-only mode when the connection has auto-commit disabled, thus the read-only flag is an optimization and an extra level of protection, but cannot be relied upon due to potentially being within the scope of a larger read-write transaction.

        When a connection already exists, its isolation level may be increased, but will never be decreased. However, the ability to change the isolation level within a transaction is driver dependent. It is best to set the highest isolation level that will be required at the beginning of the transaction.

        If all the connections in the pool are busy and the pool is at capacity, waits until a connection becomes available.

        The connection will be a FailFastConnection, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The fail-fast connection is used to determine whether to roll-back or commit during automatic transaction management.

        The connection will also be a ConnectionTracker, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The connection tracking is used to close/free all objects before returning the connection to the underlying pool.

        Parameters:
        maxConnections - The maximum number of connections expected to be used by the current thread. This should normally be one to avoid potential deadlock.

        The connection will continue to be considered used by the allocating thread until released (via Connection.close(), even if the connection is shared by another thread.

        Returns:
        The read/write connection to the database.

        This connection may be used in try-with-resources, but any calls to Connection.close() are ignored. Instead, the connection is released and/or closed when this DatabaseConnection is closed.

        Throws:
        SQLException - when an error occurs, or when a thread attempts to allocate more than half the pool
        See Also:
        getConnection(int, boolean, int), Database.getConnection(int), Connection.close()
      • getConnection

        public Connection getConnection​(boolean readOnly)
                                 throws SQLException
        Gets the connection to the database with a transaction level of Connections.DEFAULT_TRANSACTION_ISOLATION, warning when a connection is already used by this thread.

        Uses a deferred connection strategy. If not previously connected, allocates the connection now. This allows applications to create DatabaseConnection at no cost, only connecting to the database when first needed. This is helpful for when a transaction scope is established at a high level, where the actual use (or lack thereof) of the database is unknown.

        The default auto-commit state depends on the read-only and isolation levels. Upon initial connection, auto-commit is enabled. It then remains unchanged while is read-only and at an isolation level of Connection.TRANSACTION_READ_COMMITTED or below. This means, conversely, that auto-commit is disabled when is either read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above.

        When a connection already exists, its read-only mode may be changed, but may not be changed on a connection that has auto-commit disabled (which typically means it was either already read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above).

        With the default auto-commit behavior (auto-commit not disabled by application), it is an error to try to change from read-only to read-write while at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above, as the necessary actions to make the change would break the repeatable-read guarantee.

        Read-write connections will not be set back to read-only mode when the connection has auto-commit disabled, thus the read-only flag is an optimization and an extra level of protection, but cannot be relied upon due to potentially being within the scope of a larger read-write transaction.

        When a connection already exists, its isolation level may be increased, but will never be decreased. However, the ability to change the isolation level within a transaction is driver dependent. It is best to set the highest isolation level that will be required at the beginning of the transaction.

        If all the connections in the pool are busy and the pool is at capacity, waits until a connection becomes available.

        The connection will be a FailFastConnection, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The fail-fast connection is used to determine whether to roll-back or commit during automatic transaction management.

        The connection will also be a ConnectionTracker, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The connection tracking is used to close/free all objects before returning the connection to the underlying pool.

        Parameters:
        readOnly - The read-only flag. Please note: a read-write connection will always be returned while already in the scope of an overall read-write transaction.
        Returns:
        The connection to the database.

        This connection may be used in try-with-resources, but any calls to Connection.close() are ignored. Instead, the connection is released and/or closed when this DatabaseConnection is closed.

        Throws:
        SQLException - when an error occurs, or when a thread attempts to allocate more than half the pool
        See Also:
        getConnection(int, boolean, int), Database.getConnection(boolean), Connection.close()
      • getConnection

        public Connection getConnection​(int isolationLevel,
                                        boolean readOnly)
                                 throws SQLException
        Gets the connection to the database, warning when a connection is already used by this thread.

        Uses a deferred connection strategy. If not previously connected, allocates the connection now. This allows applications to create DatabaseConnection at no cost, only connecting to the database when first needed. This is helpful for when a transaction scope is established at a high level, where the actual use (or lack thereof) of the database is unknown.

        The default auto-commit state depends on the read-only and isolation levels. Upon initial connection, auto-commit is enabled. It then remains unchanged while is read-only and at an isolation level of Connection.TRANSACTION_READ_COMMITTED or below. This means, conversely, that auto-commit is disabled when is either read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above.

        When a connection already exists, its read-only mode may be changed, but may not be changed on a connection that has auto-commit disabled (which typically means it was either already read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above).

        With the default auto-commit behavior (auto-commit not disabled by application), it is an error to try to change from read-only to read-write while at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above, as the necessary actions to make the change would break the repeatable-read guarantee.

        Read-write connections will not be set back to read-only mode when the connection has auto-commit disabled, thus the read-only flag is an optimization and an extra level of protection, but cannot be relied upon due to potentially being within the scope of a larger read-write transaction.

        When a connection already exists, its isolation level may be increased, but will never be decreased. However, the ability to change the isolation level within a transaction is driver dependent. It is best to set the highest isolation level that will be required at the beginning of the transaction.

        If all the connections in the pool are busy and the pool is at capacity, waits until a connection becomes available.

        The connection will be a FailFastConnection, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The fail-fast connection is used to determine whether to roll-back or commit during automatic transaction management.

        The connection will also be a ConnectionTracker, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The connection tracking is used to close/free all objects before returning the connection to the underlying pool.

        Parameters:
        isolationLevel - The transaction isolation level. Please note: a connection of a higher transaction isolation level may be returned while already in the scope of an overall transaction.
        readOnly - The read-only flag. Please note: a read-write connection will always be returned while already in the scope of an overall read-write transaction.
        Returns:
        The connection to the database.

        This connection may be used in try-with-resources, but any calls to Connection.close() are ignored. Instead, the connection is released and/or closed when this DatabaseConnection is closed.

        Throws:
        SQLException - when an error occurs, or when a thread attempts to allocate more than half the pool
        See Also:
        getConnection(int, boolean, int), Database.getConnection(int, boolean), Connection.close()
      • getConnection

        public Connection getConnection​(int isolationLevel,
                                        boolean readOnly,
                                        int maxConnections)
                                 throws SQLException
        Gets the connection to the database.

        Uses a deferred connection strategy. If not previously connected, allocates the connection now. This allows applications to create DatabaseConnection at no cost, only connecting to the database when first needed. This is helpful for when a transaction scope is established at a high level, where the actual use (or lack thereof) of the database is unknown.

        The default auto-commit state depends on the read-only and isolation levels. Upon initial connection, auto-commit is enabled. It then remains unchanged while is read-only and at an isolation level of Connection.TRANSACTION_READ_COMMITTED or below. This means, conversely, that auto-commit is disabled when is either read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above.

        When a connection already exists, its read-only mode may be changed, but may not be changed on a connection that has auto-commit disabled (which typically means it was either already read-write or at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above).

        With the default auto-commit behavior (auto-commit not disabled by application), it is an error to try to change from read-only to read-write while at an isolation level of Connection.TRANSACTION_REPEATABLE_READ or above, as the necessary actions to make the change would break the repeatable-read guarantee.

        Read-write connections will not be set back to read-only mode when the connection has auto-commit disabled, thus the read-only flag is an optimization and an extra level of protection, but cannot be relied upon due to potentially being within the scope of a larger read-write transaction.

        When a connection already exists, its isolation level may be increased, but will never be decreased. However, the ability to change the isolation level within a transaction is driver dependent. It is best to set the highest isolation level that will be required at the beginning of the transaction.

        If all the connections in the pool are busy and the pool is at capacity, waits until a connection becomes available.

        The connection will be a FailFastConnection, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The fail-fast connection is used to determine whether to roll-back or commit during automatic transaction management.

        The connection will also be a ConnectionTracker, which may be unwrapped via Wrapper.unwrap(java.lang.Class). The connection tracking is used to close/free all objects before returning the connection to the underlying pool.

        Parameters:
        isolationLevel - The transaction isolation level. Please note: a connection of a higher transaction isolation level may be returned while already in the scope of an overall transaction.
        readOnly - The read-only flag. Please note: a read-write connection will always be returned while already in the scope of an overall read-write transaction.
        maxConnections - The maximum number of connections expected to be used by the current thread. This should normally be one to avoid potential deadlock.

        The connection will continue to be considered used by the allocating thread until released (via Connection.close(), even if the connection is shared by another thread.

        Returns:
        The connection to the database.

        This connection may be used in try-with-resources, but any calls to Connection.close() are ignored. Instead, the connection is released and/or closed when this DatabaseConnection is closed.

        Throws:
        SQLException - when an error occurs, or when a thread attempts to allocate more than half the pool
        See Also:
        Database.getConnection(int, boolean, int, boolean), Connection.close()
      • rollback

        public boolean rollback()
                         throws SQLException
        Rolls back the current connection, if have connection and is not auto-commit.
        Returns:
        true when connected and rolled-back (or is auto-commit)
        Throws:
        SQLException