org.rhq.core.db

Class DatabaseType

java.lang.Object

org.rhq.core.db.DatabaseType

Direct Known Subclasses:

H2DatabaseType, OracleDatabaseType, PostgresqlDatabaseType, SQLServerDatabaseType

public abstract class DatabaseType
extends Object

A vendor-specific database with some vendor-specific method implementations in order to do things necessary for each individual type of database. This abstract class provides some default implementations; vendor-specific subclasses are free to override their behavior.

Author:

John Mazzitelli

Constructor Summary

Constructors

Constructor and Description
DatabaseType()

Method Summary

Methods

Modifier and Type	Method and Description
void	addColumn(Connection conn, String table, String column, String generic_column, Object precision) Adds a column to a table.
abstract void	alterColumn(Connection conn, String table, String column, String generic_column_type, String default_value, String precision, Boolean nullable, Boolean reindex) Alters an existing column.
boolean	checkColumnExists(Connection conn, String table, String column) Check to see if a column exists in a table.
boolean	checkTableExists(Connection conn, String table) Determines if the given table exists in the database.
void	closeConnection(Connection c) Close a database connection.
void	closeJDBCObjects(Connection c, Statement s, ResultSet rs) Close a connection, statement, and result set in one method call.
void	closeResultSet(ResultSet rs) Close a database result set.
void	closeStatement(Statement s) Close a database statement.
int	countRows(int num_rows_already_read, ResultSet result_set) Counts the number of rows in a result set.
void	createSequence(Connection conn, String name, String initial, String increment, String seqIdCacheSize) Creates a sequence with the given name.
void	deleteColumn(Connection conn, String table, String column) Deletes a column.
void	dropSequence(Connection conn, String sequence_name) Drops the sequence with the given name.
void	dropTable(Connection conn, String table) Drops a table.
List<Object[]>	executeSelectSql(Connection conn, String sql) Executes the given SQL on the given connection.
void	executeSql(Connection conn, List<String> sql_list) Executes each SQL string in the list.
void	executeSql(Connection conn, String sql) Executes the given SQL on the given connection.
String	getBooleanValue(boolean bool) Get the value for a boolean as a string as required for the specific database.
String	getDBTypeFromGenericType(String generic_type) Given a generic type, this will return an analogous type that is specific to this database.
String	getEscapeCharacter() Provides the value to be used for the ESCAPE character in string literals.
abstract String	getHibernateDialect() Return the hibernate dialect, that can be used in <property name="hibernate.dialect" value="" / > expressions within persistence.xml
Integer	getInteger(Object number) Get the Integer representation of the number type supplied by the db vendor for an integer field value.
String	getLimitClause(int limit) Return vendor-specific row limit clause to be appended to a native SQL SELECT statement.
Long	getLong(Object number) Get the Long representation of the number type supplied by the db vendor for a long field value.
abstract String	getName() Returns a vendor-specific, version-specific database name.
abstract int	getNextSequenceValue(Connection conn, String table, String key) A utility that returns the next value of a sequence.
String	getSequenceInsertValue(Connection conn, String sequenceName) A utility that returns the string for sequence use in an Insert statement
abstract int	getSequenceValue(Connection conn, String table, String key) A utility that returns the last value of a sequence.
String	getString(String varchar, int maxLength) Different vendors have different rules regarding varchar/varchar2 string storage.
abstract String	getVendor() Returns a vendor-specific database name.
abstract String	getVersion() Returns the version number of the database, as a String.
void	insert(Connection conn, String table, String insert_cmd) Inserts data into a table.
abstract boolean	isTableNotFoundException(SQLException e) Determines if the given SQL exception was caused by a "table not found" error.
boolean	matches(String vendor, String version) Returns true if this database type's vendor and version match those of the given vendor and given version strings.
abstract void	reindexTable(Connection conn, String table) Reindexes the given table.
void	setBooleanValue(boolean bool, PreparedStatement ps, int idx) Fill out a PreparedStatement correctly with a boolean.
boolean	supportsSelfReferringCascade() Most vendors support foreign keys to itself that in fact perform cascade delete.
String	toString()
void	update(Connection conn, String table, String column, String where, String value, int jdbc_type_int) Updates data in a particular column.
void	updateColumn(Connection conn, String table, String column, String modify_cmd) Updates a column by altering its attributes.

Methods inherited from class java.lang.Object

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

Constructor Detail

DatabaseType

public DatabaseType()

Method Detail

getName

public abstract String getName()

Returns a vendor-specific, version-specific database name. This is the name used in the ANT tasks and XML files when needing to specify a specific type of database. You can define database-specific typemaps for a specific version of the vendor's databases if this vendor/version-unique name is used in the mapping.

Returns:

name of database, which is also version specific

getVendor

public abstract String getVendor()

Returns a vendor-specific database name. This is the name of the database, without specifying a specific version. For example, this can return "oracle" for the database types that represent Oracle8, Oracle9 and Oracle10. You can define database-specific typemaps across all versions of the vendor's databases if this vendor name is used in the mapping.

Returns:

name of database vendor

getVersion

public abstract String getVersion()

Returns the version number of the database, as a String.

Returns:

database version

getHibernateDialect

public abstract String getHibernateDialect()

Return the hibernate dialect, that can be used in <property name="hibernate.dialect" value="" / > expressions within persistence.xml

Returns:

classname of the hibernate dialect

toString

public String toString()

Overrides:

toString in class Object

See Also:

Object.toString()

matches

public boolean matches(String vendor,
              String version)

Returns true if this database type's vendor and version match those of the given vendor and given version strings. If either the vendor or version strings do not match, false is returned. If either vendor or version is null, that argument is ignored and not compared. If you just want to compare vendor strings, for example, pass in a null version string. When comparing the strings, the comparision will be case-insensitive.

Parameters:

vendor -

version -

Returns:

true if the given vendor and version match this database type

getDBTypeFromGenericType

public String getDBTypeFromGenericType(String generic_type)

Given a generic type, this will return an analogous type that is specific to this database.

Parameters:

generic_type - a generic type name

Returns:

a database specific type name

closeConnection

public void closeConnection(Connection c)

Close a database connection. No exception is thrown if it fails, but a warning is logged.

Parameters:

c - The connection to close (may be null)

closeStatement

public void closeStatement(Statement s)

Close a database statement. No exception is thrown if it fails, but a warning is logged.

Parameters:

s - The statement to close (may be null)

closeResultSet

public void closeResultSet(ResultSet rs)

Close a database result set. No exception is thrown if it fails, but a warning is logged.

Parameters:

rs - The result set to close (may be null)

closeJDBCObjects

public void closeJDBCObjects(Connection c,
                    Statement s,
                    ResultSet rs)

Close a connection, statement, and result set in one method call. You can pass null for any argument to ignore it. No exception is thrown if any close fails, but warnings will be logged.

Parameters:

c - The connection to close.

s - The statement set to close.

rs - The result set to close.

countRows

public int countRows(int num_rows_already_read,
            ResultSet result_set)
              throws SQLException

Counts the number of rows in a result set.

Parameters:

num_rows_already_read -

result_set -

Returns:

number of rows currently in the row set, plus the num_rows_already_read

Throws:

SQLException

checkColumnExists

public boolean checkColumnExists(Connection conn,
                        String table,
                        String column)
                          throws SQLException

Check to see if a column exists in a table.

Parameters:

conn - The DB connection to use.

table - The table to check.

column - The column to look for. This is done in a case-insensitive manner.

Returns:

true if the column exists in the table, false otherwise

Throws:

SQLException

getBooleanValue

public String getBooleanValue(boolean bool)

Get the value for a boolean as a string as required for the specific database.

Parameters:

bool - the boolean value to be converted to the DB string version of the boolean

Returns:

the appropriate boolean string for the specific database

getInteger

public Integer getInteger(Object number)

Get the Integer representation of the number type supplied by the db vendor for an integer field value. The default implementation simply applies a cast to the passed in number and is appropriate for DB types that support a native integer field type (like Postgres). Other db types should override this method (like Oracle).

Parameters:

number -

Returns:

getLong

public Long getLong(Object number)

Get the Long representation of the number type supplied by the db vendor for a long field value. The default implementation simply applies a cast to the passed in number and is appropriate for DB types that support a native long field type. Other db types should override this method (like Oracle).

Parameters:

number -

Returns:

getString

public String getString(String varchar,
               int maxLength)

Different vendors have different rules regarding varchar/varchar2 string storage. In particular, Oracle has a hard limit of 4000 bytes (not characters, bytes). Make sure we trim to maxLength (in characters) while also meeting vendor-specific constraints.

Parameters:

varchar - The String to be stored as a varchar/varchar2

maxLength - max length of the DB field, in characters.

Returns:

The string, safe for storage to the DB field

setBooleanValue

public void setBooleanValue(boolean bool,
                   PreparedStatement ps,
                   int idx)
                     throws SQLException

Fill out a PreparedStatement correctly with a boolean.

Parameters:

bool - the boolean you want

ps - the prepapred statement where the boolean will be stored

idx - the index that corresponds to the boolean parameter in the statement

Throws:

SQLException

checkTableExists

public boolean checkTableExists(Connection conn,
                       String table)
                         throws Exception

Determines if the given table exists in the database. Note that if the table does not exist a call to this method will cause an underlying SQLException, which will invalidate the current transaction.

Parameters:

conn - connection to the database where the table to check is

table - the table to check for existence

Returns:

true if the table exists in the database, false if the table does not exist AND the implementation determined the information WITHOUT generating an SQLException (meaning the transaction has not been invalidated. Otherwise, throws an exception which should be handled.

Throws:

IllegalStateException - if the check generated an expected "table does not exist SQLException (note, the exception invalidates the transaction).

Exception - if the table check failed for a reason other than a "table does not exist" error.

updateColumn

public void updateColumn(Connection conn,
                String table,
                String column,
                String modify_cmd)
                  throws SQLException

Updates a column by altering its attributes. The modify_cmd is used as part of the ALTER SQL command; e.g.:

 ALTER TABLE table MODIFY ( column modify_cmd )
 

Parameters:

conn -

table -

column -

modify_cmd -

Throws:

SQLException

dropTable

public void dropTable(Connection conn,
             String table)
               throws SQLException

Drops a table.

Parameters:

conn -

table -

Throws:

SQLException

deleteColumn

public void deleteColumn(Connection conn,
                String table,
                String column)
                  throws SQLException

Deletes a column.

Parameters:

conn -

table -

column -

Throws:

SQLException

executeSelectSql

public List<Object[]> executeSelectSql(Connection conn,
                              String sql)
                                throws SQLException

Executes the given SQL on the given connection. Use this method if you want to return the raw results for further processing. This is especially useful when used in conjunction with SST_JavaTask.

Parameters:

conn - the connection to the database that will execute the SQL

sql - the actual SQL to execute

Throws:

SQLException

executeSql

public void executeSql(Connection conn,
              String sql)
                throws SQLException

Executes the given SQL on the given connection. Use this method if you don't care about what the results are, you just want to execute the SQL and know if it was successful or not.

Parameters:

conn - the connection to the database that will execute the SQL

sql - the actual SQL to execute

Throws:

SQLException

executeSql

public void executeSql(Connection conn,
              List<String> sql_list)
                throws SQLException

Executes each SQL string in the list.

Parameters:

conn -

sql_list - the list of SQL strings, each item is assumed to be a standalone and complete SQL statement

Throws:

SQLException

See Also:

executeSql(Connection, String)

dropSequence

public void dropSequence(Connection conn,
                String sequence_name)
                  throws SQLException

Drops the sequence with the given name.

Parameters:

conn -

sequence_name -

Throws:

SQLException

insert

public void insert(Connection conn,
          String table,
          String insert_cmd)
            throws SQLException

Inserts data into a table. The insert_cmd is the SQL that appears after the INSERT INTO table.

Parameters:

conn -

table -

insert_cmd -

Throws:

SQLException

update

public void update(Connection conn,
          String table,
          String column,
          String where,
          String value,
          int jdbc_type_int)
            throws SQLException

Updates data in a particular column. The jdbc_type_int is the column's JDBC type as defined in Types. The where clause is optional and may be null; if it is non-null, it does not include the actual WHERE keyword.

Parameters:

conn -

table -

column -

where -

value -

jdbc_type_int -

Throws:

SQLException

addColumn

public void addColumn(Connection conn,
             String table,
             String column,
             String generic_column,
             Object precision)
               throws SQLException

Adds a column to a table. The column type name is a generic type name.

Parameters:

conn - the connection to the database

table - the table where the column is to be added

column - the new column name

generic_column - the generic column type name

precision - if the column type can take a precision, this can be non-null

Throws:

SQLException

isTableNotFoundException

public abstract boolean isTableNotFoundException(SQLException e)

Determines if the given SQL exception was caused by a "table not found" error.

Parameters:

e - the SQL exception that occurred

Returns:

true if the given exception is the database's "table not found" exception.

getSequenceValue

public abstract int getSequenceValue(Connection conn,
                   String table,
                   String key)
                              throws SQLException

A utility that returns the last value of a sequence. This is useful for when you need the value of a primary key for a row that you just inserted.

Parameters:

conn - The connection to use to get the sequence value.

table - The table where the sequence is defined.

key - The column on which the sequence is defined.

Returns:

the last value of a sequence

Throws:

SQLException

getNextSequenceValue

public abstract int getNextSequenceValue(Connection conn,
                       String table,
                       String key)
                                  throws SQLException

A utility that returns the next value of a sequence.

Parameters:

conn - The connection to use to get the sequence value.

table - The table where the sequence is defined.

key - The column on which the sequence is defined.

Returns:

the last value of a sequence

Throws:

SQLException

getSequenceInsertValue

public String getSequenceInsertValue(Connection conn,
                            String sequenceName)

A utility that returns the string for sequence use in an Insert statement

Parameters:

conn - The connection to use to get the sequence value.

sequenceName - The sequence name for the table.

Returns:

the sequence generating string

Throws:

SQLException

createSequence

public void createSequence(Connection conn,
                  String name,
                  String initial,
                  String increment,
                  String seqIdCacheSize)
                    throws SQLException

Creates a sequence with the given name. Its initial value is specified along with its increment (both are specified as Strings).

Parameters:

conn -

name -

initial -

increment -

seqIdCacheSize -

Throws:

SQLException

alterColumn

public abstract void alterColumn(Connection conn,
               String table,
               String column,
               String generic_column_type,
               String default_value,
               String precision,
               Boolean nullable,
               Boolean reindex)
                          throws SQLException

Alters an existing column. You can optionally alter the column's type, the default value, precision, and nullability. You can also optionally reindex the table.

Parameters:

conn - connection to the database

table - the name of the table where the column exists

column - the name of the column to alter

generic_column_type - the new generic type of the column

default_value - the new default value

precision - the new precision of the column

nullable - the new nullable value (if true, it's value can now be NULL)

reindex - if true, and the DB supports it, the table will be reindexed

Throws:

SQLException

reindexTable

public abstract void reindexTable(Connection conn,
                String table)
                           throws SQLException

Reindexes the given table.

Parameters:

conn -

table -

Throws:

SQLException

getEscapeCharacter

public String getEscapeCharacter()

Provides the value to be used for the ESCAPE character in string literals. The SQL standard is a single character, typically '\', but not every dbType conforms to the standard. To override the db default set the rhq.server.database.escape-character system property.

Returns:

If set, the value of rhq.server.database.escape-character, otherwise the db default.

supportsSelfReferringCascade

public boolean supportsSelfReferringCascade()

Most vendors support foreign keys to itself that in fact perform cascade delete. But some do not and that currently affects our data model. (see rhq_config_property in content-schema.xml).

Returns:

true unless overriden to return false.

getLimitClause

public String getLimitClause(int limit)

Return vendor-specific row limit clause to be appended to a native SQL SELECT statement. This does not support OFFSET and therefore is not useful for paging, only for limiting the result set in a native way. For predictable results it is usually desirable to use an ORDER BY in conjunction with limit.

Parameters:

limit -

Returns:

the limit clause