org.jminor.common.db

Interface Database

All Known Implementing Classes:

AbstractDatabase, DerbyDatabase, H2Database, HSQLDatabase, MySQLDatabase, OracleDatabase, PostgreSQLDatabase, SQLiteDatabase, SQLServerDatabase

public interface Database

Defines DBMS specific functionality as well as basic database configuration settings.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Database.Statistics Encapsulates basic database usage statistics.
static class	Database.Type The available database types

Field Summary

Fields

Modifier and Type	Field and Description
static PropertyValue<java.lang.Boolean>	DATABASE_EMBEDDED Specifies whether or not the database should be run in embedded mode, if applicable Values: "true"/"false" Default: "false"
static PropertyValue<java.lang.Boolean>	DATABASE_EMBEDDED_IN_MEMORY Specifies whether or not the database should be run in in-memory mode Values: "true"/"false" Default: "false"
static PropertyValue<java.lang.String>	DATABASE_HOST Specifies the machine hosting the database, in the case of embedded databases this specifies the name of the database
static PropertyValue<java.lang.String>	DATABASE_INIT_SCRIPT A comma separated list of paths to scripts to run when initializing the database, implementation specific
static PropertyValue<java.lang.Integer>	DATABASE_PORT Specifies the database port
static PropertyValue<java.lang.String>	DATABASE_SID Specifies the database sid (used for dbname for MySQL, SQLServer and Derby server connections)
static PropertyValue<java.lang.String>	DATABASE_TYPE Specifies the database type by name, this property is case insensitive
static int	DEFAULT_LOGIN_TIMEOUT The default connection login timeout
static java.lang.String	PASSWORD_PROPERTY The constant used to denote the password value in the connection properties
static java.lang.String	USER_PROPERTY The constant used to denote the username value in the connection properties

Method Summary

Modifier and Type	Method and Description
java.util.Properties	addConnectionProperties(java.util.Properties properties) Adds any dbms specific connection properties to the given properties map, called each time a connection is created
java.sql.Connection	createConnection(User user) Creates a connection for the given user.
java.lang.String	getAuthenticationInfo(java.util.Properties connectionProperties) In the case of embedded databases the user login info can be appended to the connection url, this method should return that string in case the dbms requires it and connectionProperties contains the username and password info, otherwise it should be safe to return null.
java.lang.String	getAutoIncrementQuery(java.lang.String idSource) Returns a query string for retrieving the last automatically generated id from the given id source
java.lang.String	getCheckConnectionQuery() 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.
static Database.Type	getDatabaseType()
java.lang.String	getDriverClassName()
java.lang.String	getErrorMessage(java.sql.SQLException exception) Returns a user friendly error message for the given exception, otherwise simply return the message from exception
java.lang.String	getHost()
java.lang.Integer	getPort()
java.lang.String	getSequenceQuery(java.lang.String sequenceName)
java.lang.String	getSid()
Database.Type	getType()
java.lang.String	getURL(java.util.Properties connectionProperties)
java.lang.String	getUrlAppend()
boolean	isAuthenticationException(java.sql.SQLException exception)
boolean	isEmbedded()
boolean	isReferentialIntegrityException(java.sql.SQLException exception)
boolean	isUniqueConstraintException(java.sql.SQLException exception)
void	setUrlAppend(java.lang.String urlAppend)
void	shutdownEmbedded(java.util.Properties connectionProperties) This should shutdown the database in case it is an embedded one and if that is applicable, such as for Derby.
boolean	supportsIsValid()
boolean	supportsNowait() Returns true if the dbms supports the select for update NOWAIT option
boolean	supportsSelectForUpdate()

Field Detail

DATABASE_TYPE

static final PropertyValue<java.lang.String> DATABASE_TYPE

Specifies the database type by name, this property is case insensitive

See Also:

Database.Type.DERBY, Database.Type.HSQL, Database.Type.H2, Database.Type.MYSQL, Database.Type.ORACLE, Database.Type.POSTGRESQL, Database.Type.SQLSERVER, Database.Type.SQLITE

DATABASE_HOST

static final PropertyValue<java.lang.String> DATABASE_HOST

Specifies the machine hosting the database, in the case of embedded databases this specifies the name of the database

DATABASE_SID

static final PropertyValue<java.lang.String> DATABASE_SID

Specifies the database sid (used for dbname for MySQL, SQLServer and Derby server connections)

DATABASE_PORT

static final PropertyValue<java.lang.Integer> DATABASE_PORT

Specifies the database port

DATABASE_EMBEDDED

static final PropertyValue<java.lang.Boolean> DATABASE_EMBEDDED

Specifies whether or not the database should be run in embedded mode, if applicable
Values: "true"/"false"
Default: "false"

DATABASE_EMBEDDED_IN_MEMORY

static final PropertyValue<java.lang.Boolean> DATABASE_EMBEDDED_IN_MEMORY

Specifies whether or not the database should be run in in-memory mode
Values: "true"/"false"
Default: "false"

DATABASE_INIT_SCRIPT

static final PropertyValue<java.lang.String> DATABASE_INIT_SCRIPT

A comma separated list of paths to scripts to run when initializing the database, implementation specific

USER_PROPERTY

static final java.lang.String USER_PROPERTY

The constant used to denote the username value in the connection properties

See Also:

Constant Field Values

PASSWORD_PROPERTY

static final java.lang.String PASSWORD_PROPERTY

The constant used to denote the password value in the connection properties

See Also:

Constant Field Values

DEFAULT_LOGIN_TIMEOUT

static final int DEFAULT_LOGIN_TIMEOUT

The default connection login timeout

See Also:

DriverManager.setLoginTimeout(int), Constant Field Values

Method Detail

getType

Database.Type getType()

Returns:

the name of the dbms in use

getHost

java.lang.String getHost()

Returns:

the database host name

getPort

java.lang.Integer getPort()

Returns:

the database port

getSid

java.lang.String getSid()

Returns:

the database service id

isEmbedded

boolean isEmbedded()

Returns:

true if this database is an embedded one

setUrlAppend

void setUrlAppend(java.lang.String urlAppend)

Parameters:

urlAppend - a string to append to the connection URL

getUrlAppend

java.lang.String getUrlAppend()

Returns:

the string to append to the connection URL

getAutoIncrementQuery

java.lang.String getAutoIncrementQuery(java.lang.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:

java.lang.NullPointerException - in case idSource is required and is null

getSequenceQuery

java.lang.String getSequenceQuery(java.lang.String sequenceName)

Parameters:

sequenceName - the name of the sequence

Returns:

a query for selecting the next value from the given sequence

Throws:

java.lang.UnsupportedOperationException - in case the underlying database does not support sequences

java.lang.NullPointerException - in case sequenceName is null

getURL

java.lang.String getURL(java.util.Properties connectionProperties)

Parameters:

connectionProperties - the connection properties, used primarily to provide embedded databases with user info for authentication purposes

Returns:

the database url of the active database, based on system properties

getAuthenticationInfo

java.lang.String getAuthenticationInfo(java.util.Properties connectionProperties)

In the case of embedded databases the user login info can be appended to the connection url, this method should return that string in case the dbms requires it and connectionProperties contains the username and password info, otherwise it should be safe to return null. This method is usually used in getURL() and onDisconnect().

Parameters:

connectionProperties - the connection properties

Returns:

an authentication string to append to the connection url, f.ex. user=scott;password=tiger, null if none is required

shutdownEmbedded

void shutdownEmbedded(java.util.Properties connectionProperties)

This should shutdown the database in case it is an embedded one and if that is applicable, such as for Derby.

Parameters:

connectionProperties - the connection properties

supportsIsValid

boolean supportsIsValid()

Returns:

true if the dbms supports the Java 6 jdbc call Connection.isValid()

supportsSelectForUpdate

boolean supportsSelectForUpdate()

Returns:

true if the dbms supports the 'select for update' syntax

supportsNowait

boolean supportsNowait()

Returns true if the dbms supports the select for update NOWAIT option

Returns:

true if NOWAIT is supported for select for update

getCheckConnectionQuery

java.lang.String getCheckConnectionQuery()

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()

getErrorMessage

java.lang.String getErrorMessage(java.sql.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(java.sql.SQLException exception)

Parameters:

exception - the exception

Returns:

true if this exception represents a login credentials failure

isReferentialIntegrityException

boolean isReferentialIntegrityException(java.sql.SQLException exception)

Parameters:

exception - the exception

Returns:

true if this exception is a referential integrity exception

isUniqueConstraintException

boolean isUniqueConstraintException(java.sql.SQLException exception)

Parameters:

exception - the exception

Returns:

true if this exception is a unique key exception

addConnectionProperties

java.util.Properties addConnectionProperties(java.util.Properties properties)

Adds any dbms specific connection properties to the given properties map, called each time a connection is created

Parameters:

properties - the properties map to add to

Returns:

the properties map

createConnection

java.sql.Connection createConnection(User user)
                              throws DatabaseException

Creates a connection for the given user.

Parameters:

user - the user for which to create a connection

Returns:

a Connection

Throws:

DatabaseException - in case of a connection error

AuthenticationException - in case of an authentication error

getDriverClassName

java.lang.String getDriverClassName()

Returns:

the name of the driver class

getDatabaseType

static Database.Type getDatabaseType()

Returns:

the database type string as specified by the DATABASE_TYPE system property

See Also:

DATABASE_TYPE