-
- All Superinterfaces:
ConnectionFactory
- All Known Implementing Classes:
AbstractDatabase
public interface Database extends ConnectionFactory
Defines DBMS specific functionality as well as basic database configuration settings.
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
Database.SelectForUpdateSupport
The possible select for update support values.static interface
Database.Statistics
Encapsulates basic database usage statistics.
-
Field Summary
Fields Modifier and Type Field Description static PropertyValue<Integer>
CONNECTION_VALIDITY_CHECK_TIMEOUT
Specifies the timeout (in seconds) to use when checking if database connections are valid.static PropertyValue<String>
DATABASE_INIT_SCRIPTS
A comma separated list of paths to scripts to run when initializing the database, implementation specificstatic PropertyValue<String>
DATABASE_URL
Specifies the jdbc url of the database.static PropertyValue<Integer>
LOGIN_TIMEOUT
Specifies the default login timeout (in seconds).
Value type: Integer
Default value: 2static String
PASSWORD_PROPERTY
The constant used to denote the password value in the connection propertiesstatic PropertyValue<Boolean>
QUERY_COUNTER_ENABLED
Specifies whether database queries should be counted.
Value type: Boolean
Default value: truestatic 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: truestatic PropertyValue<Integer>
TRANSACTION_ISOLATION
Specifies the transaction isolation to set for created connections.
Value type: Integer
Default value: nullstatic String
USER_PROPERTY
The constant used to denote the username value in the connection properties
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Modifier and Type Method Description String
autoIncrementQuery(String idSource)
Returns a query string for retrieving the last automatically generated id from the given id sourceString
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.void
closeConnectionPool(String username)
Closes and removes the pool associated with the given uservoid
closeConnectionPools()
Closes and removes all available connection poolsstatic void
closeSilently(Connection connection)
Closes the given Connection instance, suppressing any SQLExceptions that may occur.static void
closeSilently(ResultSet resultSet)
Closes the given ResultSet instance, suppressing any SQLExceptions that may occur.static void
closeSilently(Statement statement)
Closes the given Statement instance, suppressing any SQLExceptions that may occur.ConnectionPoolWrapper
connectionPool(String username)
Collection<String>
connectionPoolUsernames()
void
countQuery(String query)
Counts this query, based on the first character.void
createConnectionPool(ConnectionPoolFactory connectionPoolFactory, User poolUser)
Creates a connection pool for the given user in this database.String
errorMessage(SQLException exception)
Returns a user-friendly error message for the given exception, otherwise simply return the message fromexception
static Database
instance()
Returns aDatabase
instance based on the currently configured JDBC URL (DATABASE_URL
).boolean
isAuthenticationException(SQLException exception)
Returns true if this exception represents a login credentials failureboolean
isReferentialIntegrityException(SQLException exception)
Returns true if this exception is a referential integrity exceptionboolean
isTimeoutException(SQLException exception)
Returns true if this exception is a timeout exceptionboolean
isUniqueConstraintException(SQLException exception)
Returns true if this exception is a unique key exceptionString
limitOffsetClause(Integer limit, Integer offset)
Returns a limit/offset clause variation for this database, based on the given limit and offset values.int
maximumNumberOfParameters()
Returns the maximum number of prepared statement parameters, supported by this database.String
name()
String
selectForUpdateClause()
Returns a select for update clause, an empty string if not supported.String
sequenceQuery(String sequenceName)
Returns a query string for selecting the next value from the given sequence.void
setConnectionProvider(ConnectionProvider connectionProvider)
Sets theConnectionProvider
instance used when creating connections.void
shutdownEmbedded()
This should shut down the database in case it is an embedded one and if that is applicable, such as for Derby.Database.Statistics
statistics()
Returns statistics collected viacountQuery(String)
.boolean
subqueryRequiresAlias()
Returns true if this database requires that subqueries by aliased.boolean
supportsIsValid()
Returns true if the dbms supports the Java 6 jdbc callConnection.isValid(int)
.int
validityCheckTimeout()
-
Methods inherited from interface is.codion.common.db.pool.ConnectionFactory
createConnection, isConnectionValid, url
-
-
-
-
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 caseidSource
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 sequencesNullPointerException
- in casesequenceName
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 limitoffset
- the offset- Returns:
- a limit/offset clause
-
supportsIsValid
boolean supportsIsValid()
Returns true if the dbms supports the Java 6 jdbc callConnection.isValid(int)
.- Returns:
- true if the dbms supports the Java 6 jdbc call
Connection.isValid(int)
-
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 returnsInteger.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 fromexception
- 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()
-
statistics
Database.Statistics statistics()
Returns statistics collected viacountQuery(String)
. Note that calling this method resets the counter.- Returns:
- collected 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 usepoolUser
- 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 theConnectionProvider
instance used when creating connections.- Parameters:
connectionProvider
- the connection provider
-
instance
static Database instance()
Returns aDatabase
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 specifiedRuntimeException
- 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
-
-