org.opensubsystems.core.persist.db
Interface Database

All Known Implementing Classes:

DatabaseImpl, DB2DatabaseImpl, HsqlDBDatabaseImpl, MaxDBDatabaseImpl, MSSQLDatabaseImpl, MySQLDatabaseImpl, OracleDatabaseImpl, PostgreSQLDatabaseImpl, SapDBDatabaseImpl, SybaseDatabaseImpl

public interface Database

Interface to define abstraction for initialization and management of database instance accessed by the application. The main purpose is to define a standard way how to interact with the database, which is used by the application to persist data so that the application can eventually bring the database online or shut it down in case the application runs in embedded environment or environment without DBA babysitting the database. It also define interfaces to access database dependent information such as different SQL functions or statements which can be then used by database schemas.

Version:

$Id: Database.java,v 1.24 2007/01/23 05:59:34 bastafidli Exp $

Author:

Miro Halas

Code reviewer:

Miro Halas

Code reviewed:

1.18 2004/12/22 12:14:53 jlegeny

Field Summary

static int	BATCH_ITERATOR Value specifying after how namy iterations the batch will be executed
static int	DB2_DATABASE_TYPE The current database is IBM DB2
static java.lang.String	DB2_DATABASE_TYPE_IDENTIFIER The current database is IBM DB2
static int	HSQLDB_DATABASE_TYPE The current database is HSQLDB
static java.lang.String	HSQLDB_DATABASE_TYPE_IDENTIFIER The current database is HSQLDB
static int	MAXDB_DATABASE_TYPE The current database is MaxDB
static java.lang.String	MAXDB_DATABASE_TYPE_IDENTIFIER The current database is MaxDB
static int	MSSQL_DATABASE_TYPE The current database is MSSQL
static java.lang.String	MSSQL_DATABASE_TYPE_IDENTIFIER The current database is MS SQL Server
static int	MYSQL_DATABASE_TYPE The current database is MySQL
static java.lang.String	MYSQL_DATABASE_TYPE_IDENTIFIER The current database is MySQL
static int	ORACLE_DATABASE_TYPE The current database is Oracle
static java.lang.String	ORACLE_DATABASE_TYPE_IDENTIFIER The current database is Oracle
static int	POSTGRESQL_DATABASE_TYPE The current database is PostgreSQL
static java.lang.String	POSTGRESQL_DATABASE_TYPE_IDENTIFIER The current database is PostgreSQL
static int	SAPDB_DATABASE_TYPE The current database is SAP DB
static java.lang.String	SAPDB_DATABASE_TYPE_IDENTIFIER The current database is SAP DB
static int	SYBASE_DATABASE_TYPE The current database is Sybase ASE
static java.lang.String	SYBASE_DATABASE_TYPE_IDENTIFIER The current database is Sybase

Method Summary

void	add(java.lang.Class clsSchema) Add new schema to the database schema by specifying the generic schema class or interface.
void	add(DatabaseSchema dsSchema) Add new schema to the database schema.
java.lang.String	getConnectionTestStatement() Get very efficient parameterless SQL statement which can be used to test connection validity.
java.lang.String	getCurrentTimestampFunctionCall() Get string which can be used in SQL queries to retrieve timestamp representing current time.
int	getDatabaseType() Returns the type of database currently in use.
java.lang.String	getDatabaseTypeIdentifier() Returns the identifier for the type of database currently in use which can be used to construct package and class names.
int	getSelectListResultSetConcurrency() This method returns default result set concurrency which should be used to load lists of items from the result set efficiently.
int	getSelectListResultSetType() This method returns default result set type which should be used to load lists of items from the result set efficiently.
java.lang.Object[]	getSQLAnalyzeFunctionCall(java.util.Map mapTableNames) Get DB specific SQL queries for analyzing tables or updating statistics on the tables (it is good for performance).
java.lang.String	getSQLCountFunctionCall() Get string which can be used in SQL queries to retrieve record count.
int	getTransactionIsolation(int iTransactionIsolation) Different databases have different bugs about what they support so this method will take the desired transaction isolation level and convert it to the one supported by database.
boolean	hasAbsolutePositioningSupport() Find out if database (driver) allows us to call methods such as absolute() or last() for retrieved result sets.
boolean	hasSelectListRangeSupport() Find out if database allows us to support rows limitation.
void	insertAndFetchGeneratedValues(java.sql.Connection dbConnection, java.sql.PreparedStatement insertStatement, boolean bIsInDomain, java.lang.String strTableName, int iIndex, BasicDataObject data) Insert the data, fetch from the database id and generated creation and optionally modification timestamps for the newly created data object.
boolean	isCallableStatement(java.lang.String strQuery) Test if the specified query invokes stored procedure or if it is just a regular prepared statement.
boolean	isStarted() Test if the database is started.
boolean	preferCountToLast() Find out if when trying to find out size of the result set we should use rather count(*)/count(1)/count(id) instead of using hasAbsolutePositioningSupport.
void	start() Start the database.
void	stop() Stop the database.
void	updatedAndFetchGeneratedValues(java.lang.String strDataName, java.sql.Connection dbConnection, java.sql.PreparedStatement updateStatement, boolean bIsInDomain, java.lang.String strTableName, int iIndex, ModifiableDataObject data) Update the data, check for errors and fetch from the database generated modification timestamps for the updated data object.

Field Detail

BATCH_ITERATOR

static final int BATCH_ITERATOR

Value specifying after how namy iterations the batch will be executed

See Also:

Constant Field Values

HSQLDB_DATABASE_TYPE

static final int HSQLDB_DATABASE_TYPE

The current database is HSQLDB

See Also:

Constant Field Values

HSQLDB_DATABASE_TYPE_IDENTIFIER

static final java.lang.String HSQLDB_DATABASE_TYPE_IDENTIFIER

The current database is HSQLDB

See Also:

Constant Field Values

SAPDB_DATABASE_TYPE

static final int SAPDB_DATABASE_TYPE

The current database is SAP DB

See Also:

Constant Field Values

SAPDB_DATABASE_TYPE_IDENTIFIER

static final java.lang.String SAPDB_DATABASE_TYPE_IDENTIFIER

The current database is SAP DB

See Also:

Constant Field Values

POSTGRESQL_DATABASE_TYPE

static final int POSTGRESQL_DATABASE_TYPE

The current database is PostgreSQL

See Also:

Constant Field Values

POSTGRESQL_DATABASE_TYPE_IDENTIFIER

static final java.lang.String POSTGRESQL_DATABASE_TYPE_IDENTIFIER

The current database is PostgreSQL

See Also:

Constant Field Values

MYSQL_DATABASE_TYPE

static final int MYSQL_DATABASE_TYPE

The current database is MySQL

See Also:

Constant Field Values

MYSQL_DATABASE_TYPE_IDENTIFIER

static final java.lang.String MYSQL_DATABASE_TYPE_IDENTIFIER

The current database is MySQL

See Also:

Constant Field Values

MSSQL_DATABASE_TYPE

static final int MSSQL_DATABASE_TYPE

The current database is MSSQL

See Also:

Constant Field Values

MSSQL_DATABASE_TYPE_IDENTIFIER

static final java.lang.String MSSQL_DATABASE_TYPE_IDENTIFIER

The current database is MS SQL Server

See Also:

Constant Field Values

DB2_DATABASE_TYPE

static final int DB2_DATABASE_TYPE

The current database is IBM DB2

See Also:

Constant Field Values

DB2_DATABASE_TYPE_IDENTIFIER

static final java.lang.String DB2_DATABASE_TYPE_IDENTIFIER

The current database is IBM DB2

See Also:

Constant Field Values

SYBASE_DATABASE_TYPE

static final int SYBASE_DATABASE_TYPE

The current database is Sybase ASE

See Also:

Constant Field Values

SYBASE_DATABASE_TYPE_IDENTIFIER

static final java.lang.String SYBASE_DATABASE_TYPE_IDENTIFIER

The current database is Sybase

See Also:

Constant Field Values

ORACLE_DATABASE_TYPE

static final int ORACLE_DATABASE_TYPE

The current database is Oracle

See Also:

Constant Field Values

ORACLE_DATABASE_TYPE_IDENTIFIER

static final java.lang.String ORACLE_DATABASE_TYPE_IDENTIFIER

The current database is Oracle

See Also:

Constant Field Values

MAXDB_DATABASE_TYPE

static final int MAXDB_DATABASE_TYPE

The current database is MaxDB

See Also:

Constant Field Values

MAXDB_DATABASE_TYPE_IDENTIFIER

static final java.lang.String MAXDB_DATABASE_TYPE_IDENTIFIER

The current database is MaxDB

See Also:

Constant Field Values

Method Detail

start

void start()
           throws OSSException

Start the database.

Throws:

OSSException - - database cannot be started.

stop

void stop()
          throws OSSException

Stop the database. After the database is stopped, no more requests can be issued until the database is started again.

Throws:

OSSException - - problems stopping the database

add

void add(DatabaseSchema dsSchema)
         throws OSSException

Add new schema to the database schema.

Parameters:

dsSchema - - schema to add to the database

Throws:

OSSException - - database cannot be started.

add

void add(java.lang.Class clsSchema)
         throws OSSException

Add new schema to the database schema by specifying the generic schema class or interface. The schema itself will be created by DatabaseSchemaManager for current environment and based on any configuration settings.

Parameters:

clsSchema - - class representing schema to add to the database

Throws:

OSSException - - database cannot be started.

getDatabaseType

int getDatabaseType()

Returns the type of database currently in use. It will be one of the constants defined in this class (SAPDB, HSQLDB, etc.).

Returns:

int - database type

getDatabaseTypeIdentifier

java.lang.String getDatabaseTypeIdentifier()

Returns the identifier for the type of database currently in use which can be used to construct package and class names. It will be one of the constants defined in this class (SAPDB, HSQLDB, etc.).

Returns:

String - database type

isStarted

boolean isStarted()

Test if the database is started.

Returns:

boolean - true if started

getConnectionTestStatement

java.lang.String getConnectionTestStatement()

Get very efficient parameterless SQL statement which can be used to test connection validity.

Returns:

String - SQL statement

getTransactionIsolation

int getTransactionIsolation(int iTransactionIsolation)

Different databases have different bugs about what they support so this method will take the desired transaction isolation level and convert it to the one supported by database.

Parameters:

iTransactionIsolation - - desired transaction isolation level

Returns:

int - supported transaction isolation level

getSelectListResultSetType

int getSelectListResultSetType()

This method returns default result set type which should be used to load lists of items from the result set efficiently. Some databases supports efficient absolute cursors that allow us to efficiently find out the size of result set and efficiently allocate memory for it and they may require special result set type to do so.

Returns:

int - result set type to use load list, see ResultSet.TYPE_XXX constants

getSelectListResultSetConcurrency

int getSelectListResultSetConcurrency()

This method returns default result set concurrency which should be used to load lists of items from the result set efficiently. Some databases supports efficient absolute cursors that allow us to efficiently find out the size of result set and efficiently allocate memory for it and they may require special result set concurrency to do so.

Returns:

int - result set concurrency to use load list, see ResultSet.CONCUR_XXX constants

hasAbsolutePositioningSupport

boolean hasAbsolutePositioningSupport()

Find out if database (driver) allows us to call methods such as absolute() or last() for retrieved result sets.

Returns:

boolean - true if it is possible to call methods such as absolute, last() for retrieved result sets.

preferCountToLast

boolean preferCountToLast()

Find out if when trying to find out size of the result set we should use rather count(*)/count(1)/count(id) instead of using hasAbsolutePositioningSupport.

Returns:

boolean - true if should use count(x) instead of last()

getCurrentTimestampFunctionCall

java.lang.String getCurrentTimestampFunctionCall()

Get string which can be used in SQL queries to retrieve timestamp representing current time.

Returns:

String - SQL representation of function call to get current timestamp

getSQLAnalyzeFunctionCall

java.lang.Object[] getSQLAnalyzeFunctionCall(java.util.Map mapTableNames)

Get DB specific SQL queries for analyzing tables or updating statistics on the tables (it is good for performance).

Parameters:

mapTableNames - - map of table names the update statistics will be processed on. Key is the data object data of which are stored in the table and value is te name of the table

Returns:

Object[] - index 0 - String[] - SQL representation of function calls to analyze tables and indexes (array of SQL commands for each table the update statistics will be processed) - index 1 - Boolean flag signaling if the autocommit when executing these statements should be true or false

getSQLCountFunctionCall

java.lang.String getSQLCountFunctionCall()

Get string which can be used in SQL queries to retrieve record count.

Returns:

String - SQL representation of function call to get record count

hasSelectListRangeSupport

boolean hasSelectListRangeSupport()

Find out if database allows us to support rows limitation. This means that database has to provide a way how to construct EFFICIENT SQL which allows us to retrieve items starting from row X and ending at row Y.

Returns:

boolean - true if it is possible to support row limitation

isCallableStatement

boolean isCallableStatement(java.lang.String strQuery)

Test if the specified query invokes stored procedure or if it is just a regular prepared statement.

Parameters:

strQuery - - query to test

Returns:

boolean - true if query invokes stored procedure false otherwise

insertAndFetchGeneratedValues

void insertAndFetchGeneratedValues(java.sql.Connection dbConnection,
                                   java.sql.PreparedStatement insertStatement,
                                   boolean bIsInDomain,
                                   java.lang.String strTableName,
                                   int iIndex,
                                   BasicDataObject data)
                                   throws java.sql.SQLException,
                                          OSSException

Insert the data, fetch from the database id and generated creation and optionally modification timestamps for the newly created data object. Note: Since the caller created the prepared (or callable) statement, the caller is responsible for its closing.

Parameters:

dbConnection - - connection to use to access the database

insertStatement - - statement used to insert the data. This can be CallableStatement if stored procedure is used.

bIsInDomain - - are the data objects maintained in domains

strTableName - - name of the table where the data are being inserted

iIndex - - 1 based index of the next parameter value of which can be set on the statement (last parameter set by caller + 1)

data - - data object to update with the fetched values

Throws:

java.sql.SQLException - - an error has occured

OSSException - - an error has occured

updatedAndFetchGeneratedValues

void updatedAndFetchGeneratedValues(java.lang.String strDataName,
                                    java.sql.Connection dbConnection,
                                    java.sql.PreparedStatement updateStatement,
                                    boolean bIsInDomain,
                                    java.lang.String strTableName,
                                    int iIndex,
                                    ModifiableDataObject data)
                                    throws java.sql.SQLException,
                                           OSSException

Update the data, check for errors and fetch from the database generated modification timestamps for the updated data object. Note: Since the caller created the prepared statement, the caller is responsible for its closing.

Parameters:

strDataName - - name of the data object

dbConnection - - connection to use to access the datavase

updateStatement - - statement to update data in the database. This can be CallableStatement if stored procedure is used.

bIsInDomain - - are the data objects maintained in domains

strTableName - - name of the table

iIndex - - 1 based index of the next parameter value of which can be set on the statement (last parameter set by caller + 1)

data - - data object to update

Throws:

java.sql.SQLException - - an error has occured

OSSException - - an error has occured