org.dspace.storage.rdbms

Class DatabaseManager

java.lang.Object

org.dspace.storage.rdbms.DatabaseManager

public class DatabaseManager
extends java.lang.Object

Executes SQL queries.

Version:

$Revision$

Author:

Peter Breton, Jim Downing

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DBMS_H2
static java.lang.String	DBMS_ORACLE
static java.lang.String	DBMS_POSTGRES The static variables which represent the DBMS keyword

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DatabaseManager() Protected Constructor to prevent instantiation except by derived classes.

Method Summary

Methods

Modifier and Type	Method and Description
static void	applyOffsetAndLimit(java.lang.StringBuffer query, java.util.List<java.io.Serializable> params, int offset, int limit)
static TableRow	create(Context context, java.lang.String table) Create a new row in the given table, and assigns a unique id.
static int	delete(Context context, java.lang.String table, int id) Delete a table row via its primary key.
static int	delete(Context context, TableRow row) Delete row from the RDBMS.
static int	deleteByValue(Context context, java.lang.String table, java.lang.String column, java.lang.Object value) Delete all table rows with the given value.
static TableRow	find(Context context, java.lang.String table, int id) Find a table row by its primary key.
static TableRow	findByUnique(Context context, java.lang.String table, java.lang.String column, java.lang.Object value) Find a table row by a unique value.
protected static java.lang.String	findDbKeyword(java.sql.DatabaseMetaData meta) Return the "DbKeyword" for a specific database name.
static void	freeConnection(java.sql.Connection c) Release resources associated with this connection.
static java.sql.Connection	getConnection() Obtain an RDBMS connection.
static javax.sql.DataSource	getDataSource()
static java.lang.String	getDbKeyword() What is the string that we use to name the DBMS brand?
static java.lang.String	getDbName() What is the name of our DBMS?
protected static java.lang.String	getPrimaryKeyColumn(Context context, java.lang.String table) Return the name of the primary key column in the given table.
static java.lang.String	getPrimaryKeyColumn(Context context, TableRow row) Return the name of the primary key column.
protected static javax.sql.DataSource	initDataSource() Initialize just the DataSource for the DatabaseManager.
static void	insert(Context context, TableRow row) Insert a table row into the RDBMS.
static boolean	isOracle()
protected static void	loadParameters(java.sql.PreparedStatement statement, java.lang.Object[] parameters) Iterate over the given parameters and add them to the given prepared statement.
static TableRowIterator	query(Context context, java.lang.String query, java.lang.Object... parameters) Return an iterator with the results of the query.
static TableRow	querySingle(Context context, java.lang.String query, java.lang.Object... parameters) Return the single row result to this query, or null if no result.
static TableRow	querySingleTable(Context context, java.lang.String table, java.lang.String query, java.lang.Object... parameters) Return the single row result to this query, or null if no result.
static TableRowIterator	queryTable(Context context, java.lang.String table, java.lang.String query, java.lang.Object... parameters) Return an iterator with the results of the query.
static TableRow	row(Context context, java.lang.String table) Create a table row object that can be passed into the insert method, not commonly used unless the table has a referential integrity constraint.
static TableRow	row(java.lang.String table)
static void	setConstraintDeferred(Context context, java.lang.String constraintName) Set the constraint check to deferred (commit time)
static void	setConstraintImmediate(Context context, java.lang.String constraintName) Set the constraint check to immediate (every query)
static void	shutdown() Provide a means for a (web) application to cleanly terminate the connection pool.
static int	update(Context context, TableRow row) Update changes to the RDBMS.
static int	updateQuery(Context context, java.lang.String query, java.lang.Object... parameters) Execute an update, insert or delete query.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DBMS_POSTGRES

public static final java.lang.String DBMS_POSTGRES

The static variables which represent the DBMS keyword

See Also:

Constant Field Values

DBMS_ORACLE

public static final java.lang.String DBMS_ORACLE

See Also:

Constant Field Values

DBMS_H2

public static final java.lang.String DBMS_H2

See Also:

Constant Field Values

Constructor Detail

DatabaseManager

protected DatabaseManager()

Protected Constructor to prevent instantiation except by derived classes.

Method Detail

isOracle

public static boolean isOracle()

setConstraintDeferred

public static void setConstraintDeferred(Context context,
                         java.lang.String constraintName)
                                  throws java.sql.SQLException

Set the constraint check to deferred (commit time)

Parameters:

context - The context object

constraintName - the constraint name to deferred

Throws:

java.sql.SQLException

setConstraintImmediate

public static void setConstraintImmediate(Context context,
                          java.lang.String constraintName)
                                   throws java.sql.SQLException

Set the constraint check to immediate (every query)

Parameters:

context - The context object

constraintName - the constraint name to check immediately after every query

Throws:

java.sql.SQLException

queryTable

public static TableRowIterator queryTable(Context context,
                          java.lang.String table,
                          java.lang.String query,
                          java.lang.Object... parameters)
                                   throws java.sql.SQLException

Return an iterator with the results of the query. The table parameter indicates the type of result. If table is null, the column names are read from the ResultSetMetaData.

Parameters:

context - The context object

table - The name of the table which results

query - The SQL query

parameters - A set of SQL parameters to be included in query. The order of the parameters must correspond to the order of their reference within the query.

Returns:

A TableRowIterator with the results of the query

Throws:

java.sql.SQLException - If a database error occurs

query

public static TableRowIterator query(Context context,
                     java.lang.String query,
                     java.lang.Object... parameters)
                              throws java.sql.SQLException

Return an iterator with the results of the query.

Parameters:

context - The context object

query - The SQL query

parameters - A set of SQL parameters to be included in query. The order of the parameters must correspond to the order of their reference within the query.

Returns:

A TableRowIterator with the results of the query

Throws:

java.sql.SQLException - If a database error occurs

querySingle

public static TableRow querySingle(Context context,
                   java.lang.String query,
                   java.lang.Object... parameters)
                            throws java.sql.SQLException

Return the single row result to this query, or null if no result. If more than one row results, only the first is returned.

Parameters:

context - Current DSpace context

query - The SQL query

parameters - A set of SQL parameters to be included in query. The order of the parameters must correspond to the order of their reference within the query.

Returns:

A TableRow object, or null if no result

Throws:

java.sql.SQLException - If a database error occurs

querySingleTable

public static TableRow querySingleTable(Context context,
                        java.lang.String table,
                        java.lang.String query,
                        java.lang.Object... parameters)
                                 throws java.sql.SQLException

Return the single row result to this query, or null if no result. If more than one row results, only the first is returned.

Parameters:

context - Current DSpace context

table - The name of the table which results

query - The SQL query

parameters - A set of SQL parameters to be included in query. The order of the parameters must correspond to the order of their reference within the query.

Returns:

A TableRow object, or null if no result

Throws:

java.sql.SQLException - If a database error occurs

updateQuery

public static int updateQuery(Context context,
              java.lang.String query,
              java.lang.Object... parameters)
                       throws java.sql.SQLException

Execute an update, insert or delete query. Returns the number of rows affected by the query.

Parameters:

context - Current DSpace context

query - The SQL query to execute

parameters - A set of SQL parameters to be included in query. The order of the parameters must correspond to the order of their reference within the query.

Returns:

The number of rows affected by the query.

Throws:

java.sql.SQLException - If a database error occurs

create

public static TableRow create(Context context,
              java.lang.String table)
                       throws java.sql.SQLException

Create a new row in the given table, and assigns a unique id.

Parameters:

context - Current DSpace context

table - The RDBMS table in which to create the new row

Returns:

The newly created row

Throws:

java.sql.SQLException

find

public static TableRow find(Context context,
            java.lang.String table,
            int id)
                     throws java.sql.SQLException

Find a table row by its primary key. Returns the row, or null if no row with that primary key value exists.

Parameters:

context - Current DSpace context

table - The table in which to find the row

id - The primary key value

Returns:

The row resulting from the query, or null if no row with that primary key value exists.

Throws:

java.sql.SQLException - If a database error occurs

findByUnique

public static TableRow findByUnique(Context context,
                    java.lang.String table,
                    java.lang.String column,
                    java.lang.Object value)
                             throws java.sql.SQLException

Find a table row by a unique value. Returns the row, or null if no row with that primary key value exists. If multiple rows with the value exist, one is returned.

Parameters:

context - Current DSpace context

table - The table to use to find the object

column - The name of the unique column

value - The value of the unique column

Returns:

The row resulting from the query, or null if no row with that value exists.

Throws:

java.sql.SQLException - If a database error occurs

delete

public static int delete(Context context,
         java.lang.String table,
         int id)
                  throws java.sql.SQLException

Delete a table row via its primary key. Returns the number of rows deleted.

Parameters:

context - Current DSpace context

table - The table to delete from

id - The primary key value

Returns:

The number of rows deleted

Throws:

java.sql.SQLException - If a database error occurs

deleteByValue

public static int deleteByValue(Context context,
                java.lang.String table,
                java.lang.String column,
                java.lang.Object value)
                         throws java.sql.SQLException

Delete all table rows with the given value. Returns the number of rows deleted.

Parameters:

context - Current DSpace context

table - The table to delete from

column - The name of the column

value - The value of the column

Returns:

The number of rows deleted

Throws:

java.sql.SQLException - If a database error occurs

getConnection

public static java.sql.Connection getConnection()
                                         throws java.sql.SQLException

Obtain an RDBMS connection.

Returns:

A new database connection.

Throws:

java.sql.SQLException - If a database error occurs, or a connection cannot be obtained.

getDataSource

public static javax.sql.DataSource getDataSource()

freeConnection

public static void freeConnection(java.sql.Connection c)

Release resources associated with this connection.

Parameters:

c - The connection to release

row

public static TableRow row(Context context,
           java.lang.String table)
                    throws java.sql.SQLException

Create a table row object that can be passed into the insert method, not commonly used unless the table has a referential integrity constraint.

Parameters:

table - The RDBMS table in which to create the new row

Returns:

The newly created row

Throws:

java.sql.SQLException

row

public static TableRow row(java.lang.String table)
                    throws java.sql.SQLException

Throws:

java.sql.SQLException

insert

public static void insert(Context context,
          TableRow row)
                   throws java.sql.SQLException

Insert a table row into the RDBMS.

Parameters:

context - Current DSpace context

row - The row to insert

Throws:

java.sql.SQLException - If a database error occurs

update

public static int update(Context context,
         TableRow row)
                  throws java.sql.SQLException

Update changes to the RDBMS. Note that if the update fails, the values in the row will NOT be reverted.

Parameters:

context - Current DSpace context

row - The row to update

Returns:

The number of rows affected (1 or 0)

Throws:

java.sql.SQLException - If a database error occurs

delete

public static int delete(Context context,
         TableRow row)
                  throws java.sql.SQLException

Delete row from the RDBMS.

Parameters:

context - Current DSpace context

row - The row to delete

Returns:

The number of rows affected (1 or 0)

Throws:

java.sql.SQLException - If a database error occurs

getPrimaryKeyColumn

public static java.lang.String getPrimaryKeyColumn(Context context,
                                   TableRow row)
                                            throws java.sql.SQLException

Return the name of the primary key column. We assume there's only one primary key per table; if there are more, only the first one will be returned.

Parameters:

row - The TableRow to return the primary key for.

Returns:

The name of the primary key column, or null if the row has no primary key.

Throws:

java.sql.SQLException - If a database error occurs

getPrimaryKeyColumn

protected static java.lang.String getPrimaryKeyColumn(Context context,
                                   java.lang.String table)
                                               throws java.sql.SQLException

Return the name of the primary key column in the given table. We assume there's only one primary key per table; if there are more, only the first one will be returned.

Parameters:

table - The name of the RDBMS table

Returns:

The name of the primary key column, or null if the table has no primary key.

Throws:

java.sql.SQLException - If a database error occurs

shutdown

public static void shutdown()
                     throws java.sql.SQLException

Provide a means for a (web) application to cleanly terminate the connection pool.

Throws:

java.sql.SQLException

initDataSource

protected static javax.sql.DataSource initDataSource()
                                              throws java.sql.SQLException

Initialize just the DataSource for the DatabaseManager.

While this is normally called via initialize() to create the globally shared DataSource, it also may be called individually just to test the Database Connection settings. This second use case often needs to avoid a full initialization/migration of the Database, which takes much longer and may not be necessary just for testing a basic connection. See, for example, DatabaseUtils.main().

Returns:

initialized DataSource, or null if could not be initialized

Throws:

java.sql.SQLException - if an initialization error occurs

findDbKeyword

protected static java.lang.String findDbKeyword(java.sql.DatabaseMetaData meta)
                                         throws java.sql.SQLException

Return the "DbKeyword" for a specific database name.

This is mostly a utility method for initialize(), but also comes in handy when you want basic info about the Database but *don't* want to actually fully initialize the DatabaseManager (as it will also run all pending DB migrations)

Parameters:

meta - the DatabaseMetaData

Returns:

DB Keyword for this database, or null if not found

Throws:

java.sql.SQLException - if an initialization error occurs

getDbName

public static java.lang.String getDbName()

What is the name of our DBMS?

Returns:

name returned by the DBMS driver.

getDbKeyword

public static java.lang.String getDbKeyword()

What is the string that we use to name the DBMS brand?

This will return one of: DatabaseManager.DBMS_POSTGRES, DatabaseManager.DBMS_ORACLE, or DatabaseManager.DBMS_H2

Returns:

a normalized "keyword" for the DBMS brand: postgres, oracle, h2.

loadParameters

protected static void loadParameters(java.sql.PreparedStatement statement,
                  java.lang.Object[] parameters)
                              throws java.sql.SQLException

Iterate over the given parameters and add them to the given prepared statement. Only a select number of datatypes are supported by the JDBC driver.

Parameters:

statement - The unparameterized statement.

parameters - The parameters to be set on the statement.

Throws:

java.sql.SQLException

applyOffsetAndLimit

public static void applyOffsetAndLimit(java.lang.StringBuffer query,
                       java.util.List<java.io.Serializable> params,
                       int offset,
                       int limit)