net.sf.basedb.core.dbengine
Interface DbEngine

All Known Implementing Classes:

AbstractDbEngine, DefaultDbEngine, MySQLEngine, PostgresDbEngine

public interface DbEngine

Information about database-specific options that are not covered by the Hibernate Dialect objects.

Version:

2.0

Author:

nicklas

See Also:

EngineFactory.createEngine(Dialect)

Last modified

$Date: 2010-09-27 14:53:33 +0200 (Mon, 27 Sep 2010) $

Method Summary

String	abs(String value) Get the function call that takes the absolute of a value.
boolean	analyzeAfterBatchOperation() If TRUE, a batcher that inserts, updates or delets a lot of rows in a table should execute the SQL returned by getAnalyzeTableSql(String, String, String) for that table.
boolean	caseInsensitiveComparison() If the database does case sensitive or case insensitive string comparison in expressions.
String	castToDate(String value) Get a function that casts a date/timestamp to a date (eg. no time should be included in the result).
boolean	checkForInvalidNumberOperation() If we need to check for invalid arguments to numerical functions to avoid exceptions from the database.
String	exp(String value) Get the function call that calculates the exponential of a value.
String	getAnalyzeTableSql(String catalog, String schema, String table) Generate SQL to update the index statistics for a table.
String	getCaseSensitiveVarchar(int length) Generate a column declaration that creates a case-sensitive variable-length string column type.
String	getCreateIndexSql(String catalog, String schema, String table, String name, Set<String> columns, boolean unique) Generate SQL to create an index.
String	getDropIndexSql(String catalog, String schema, String table, String name, boolean unique) Generate SQL to drop an index.
String	getOptimizeTableSql(String catalog, String schema, String table) Generate SQL to optimize a table.
String	inspectSchemaGenerationSQL(String sql, org.hibernate.dialect.Dialect dialect, boolean update) Let the DbEninge inspect a schema generation sql statment and possible modify it before it is sent to the database.
boolean	isValidColumnName(String columnName) Check if a given string is valid to be used as a column name in the current database.
boolean	isValidTableName(String tableName) Check if a given string is valid to be used as a table name in the current database.
String	ln(String value) Get the function call that takes the natural logarithm of a value.
String	makeSafeCreateTable(String sql, String catalog, String schema, String table) Create a "safe" CREATE TABLE query string that will not fail if the table already exists.
String	power(String base, String exponent) Get the function call that calculates base raised to the power of exponent For example: POW(base, value)
String	rlike(String value, String regexp) Get a function/expression that matches the left value against the right value which should be a regular expression.
boolean	selectOrderByColumnsIfDistinct() If the database requires that columns appearing in the ORDER BY part of the query must also be part of the SELECT list when using the DISTINCT keyword.
boolean	supportColumnAliasInGroupBy() If the current database supports column aliases in the group by part of a query or not.
boolean	supportColumnAliasInHaving() If the current database supports column aliases in the order by part of a query or not.
boolean	supportColumnAliasInOrderBy() If the current database supports column aliases in the order by part of a query or not.
boolean	supportsColumnAliasInWhere() If the current database supports column aliases in the where part of a query or not.
boolean	useThetaJoin() If the database uses theta join or ansi join.

Method Detail

useThetaJoin

boolean useThetaJoin()

If the database uses theta join or ansi join.

Returns:

TRUE for theta join, FALSE for ansi join

getCreateIndexSql

String getCreateIndexSql(String catalog,
                         String schema,
                         String table,
                         String name,
                         Set<String> columns,
                         boolean unique)

Generate SQL to create an index.

Parameters:

catalog - The name of the catalog (database) where the table is located, or null if it is located in the current catalog

schema - The name of the schema where the table is located, or null if is located in the current schema

table - The name of the table

name - The name of the index to be created

columns - The name of the columns in the index

unique - If the index must contain unique values or not

Returns:

The SQL to execute

getDropIndexSql

String getDropIndexSql(String catalog,
                       String schema,
                       String table,
                       String name,
                       boolean unique)

Generate SQL to drop an index.

Parameters:

catalog - The name of the catalog (database) where the table is located, or null if it is located in the current catalog

schema - The name of the schema where the table is located, or null if is located in the current schema

table - The name of the table

name - The name of the index

unique - If the index contains unique values or not

Returns:

The SQL to execute

analyzeAfterBatchOperation

boolean analyzeAfterBatchOperation()

If TRUE, a batcher that inserts, updates or delets a lot of rows in a table should execute the SQL returned by getAnalyzeTableSql(String, String, String) for that table.

Postgres, for example, almost always require that an analysis is run since subsequent queries otherwise may take a long time to execute if indexes can't be used properly.

getOptimizeTableSql

String getOptimizeTableSql(String catalog,
                           String schema,
                           String table)

Generate SQL to optimize a table. The meaning of this may depend on the actual database used. Typical operations include updating index statistics, removing unused records, etc. Here are some example:

MySQL: OPTIMIZE TABLE <table>
Postgres: VACCUUM <table>

NOTE! The SQL returned by this method may impact the performance on the database. It is only intended to be executed when there is a need to clean up the database. How often this is needed depends on the database.

Parameters:

catalog - The name of the catalog (database) where the table is located, or null if it is located in the current catalog

schema - The name of the schema where the table is located, or null if is located in the current schema

table - The name of the table to optimize

Returns:

The SQL to execute

See Also:

getAnalyzeTableSql(String, String, String)

getAnalyzeTableSql

String getAnalyzeTableSql(String catalog,
                          String schema,
                          String table)

Generate SQL to update the index statistics for a table. Here are some example:

MySQL: ANALYZE TABLE <table>
Postgres: ANALYZE <table>

NOTE! The SQL returned by this method must be able to run within a transaction and from multiple transactions on the same table at the same time. If no such SQL statement exists null should be returned.

Parameters:

catalog - The name of the catalog (database) where the table is located, or null if it is located in the current catalog

schema - The name of the schema where the table is located, or null if is located in the current schema

table - The name of the table to analyze

Returns:

The SQL to execute, or null if not supported

See Also:

getOptimizeTableSql(String, String, String)

makeSafeCreateTable

String makeSafeCreateTable(String sql,
                           String catalog,
                           String schema,
                           String table)

Create a "safe" CREATE TABLE query string that will not fail if the table already exists. Implementors should inject proper SQL code in a way that is supported in the underlying database. The MySQL engine, for example, replaces CREATE TABLE with CREATE TABLE IF NOT EXISTS. If the underlying database doesn't support this kind of check the original SQL should be returned umodified.

Parameters:

sql - The original SQL

catalog - The name of the catalog (database) where the table is being create, or null if it is located in the current catalog

schema - The name of the schema where the table is being created, or null if is located in the current schema

table - The name of the table that is being created

Returns:

The modified or unmodified SQL statement

Since:

2.6

caseInsensitiveComparison

boolean caseInsensitiveComparison()

If the database does case sensitive or case insensitive string comparison in expressions.

Returns:

FALSE if comparisons are case sensitive (ABC != abc), TRUE if they are case insensitive (ABC = abc)

Since:

2.4

supportsColumnAliasInWhere

boolean supportsColumnAliasInWhere()

If the current database supports column aliases in the where part of a query or not. For example: SELECT tbl.blah as foo, ... FROM Table tbl WHERE foo = 2

If not supported the entire expression will be used again.

Returns:

TRUE if column aliases are supported, FALSE otherwise

supportColumnAliasInOrderBy

boolean supportColumnAliasInOrderBy()

If the current database supports column aliases in the order by part of a query or not. For example: SELECT tbl.blah as foo, ... FROM Table tbl ORDER BY foo

If not supported the entire expression will be used again.

Returns:

TRUE if column aliases are supported, FALSE otherwise

supportColumnAliasInGroupBy

boolean supportColumnAliasInGroupBy()

If the current database supports column aliases in the group by part of a query or not. For example: SELECT tbl.blah as foo, ... FROM Table tbl GROUP BY foo

If not supported the entire expression will be used again.

Returns:

TRUE if column aliases are supported, FALSE otherwise

supportColumnAliasInHaving

boolean supportColumnAliasInHaving()

If the current database supports column aliases in the order by part of a query or not. For example: SELECT count(tbl.blah) as foo, ... FROM Table tbl GROUP BY ... HAVING foo = 2

If not supported the entire expression will be used again.

Returns:

TRUE if column aliases are supported, FALSE otherwise

selectOrderByColumnsIfDistinct

boolean selectOrderByColumnsIfDistinct()

If the database requires that columns appearing in the ORDER BY part of the query must also be part of the SELECT list when using the DISTINCT keyword.

Returns:

TRUE if order by columns must be selected, FALSE otherwise

checkForInvalidNumberOperation

boolean checkForInvalidNumberOperation()

If we need to check for invalid arguments to numerical functions to avoid exceptions from the database. Postgres, for example, throws exceptions if trying to divide by zero, while MySQL returns null. To get the same behavior we need to add a CASE...WHEN statement to the query for Postgres. Example:

CASE WHEN denominator = 0 THEN null ELSE numerator / denominator

Returns:

TRUE if we need to check the numbers, FALSE otherwise

ln

String ln(String value)

Get the function call that takes the natural logarithm of a value. For example: LN(value)

Parameters:

value - The value to take the logarithm of

Returns:

The function call that calculates the logartihm

Throws:

UnsupportedOperationException - If the database doesn't support logarithms

abs

String abs(String value)

Get the function call that takes the absolute of a value. For example: ABS(value)

Parameters:

value - The value to use in the calculation

Returns:

The function call that calculates the absolute value

Throws:

UnsupportedOperationException - If the database doesn't support this function

exp

String exp(String value)

Get the function call that calculates the exponential of a value. For example: EXP(value)

Parameters:

value - The value to use in the calculation

Returns:

The function call that calculates the exponential

Throws:

UnsupportedOperationException - If the database doesn't support this function

power

String power(String base,
             String exponent)

Get the function call that calculates base raised to the power of exponent For example: POW(base, value)

Parameters:

base - The base in the expression

exponent - The exponent in the expression

Returns:

The function call that calculates the power

Throws:

UnsupportedOperationException - If the database doesn't support this function

rlike

String rlike(String value,
             String regexp)

Get a function/expression that matches the left value against the right value which should be a regular expression. If the database doesn't support regular expressions, the returned expression should use equality testing.

Parameters:

value - The left value

regexp - The regular expression as a string

Returns:

The function call/expression that matches the value agains the regular expression

Since:

2.8

castToDate

String castToDate(String value)

Get a function that casts a date/timestamp to a date (eg. no time should be included in the result).

Parameters:

value - The value to cast

Returns:

An expression that casts the value to a date

Since:

2.16

isValidTableName

boolean isValidTableName(String tableName)

Check if a given string is valid to be used as a table name in the current database.

Parameters:

tableName - The string to check

Returns:

TRUE if the name is valid, FALSE if not

Since:

2.4

isValidColumnName

boolean isValidColumnName(String columnName)

Check if a given string is valid to be used as a column name in the current database.

Parameters:

columnName - The string to check

Returns:

TRUE if the name is valid, FALSE if not

Since:

2.4

getCaseSensitiveVarchar

String getCaseSensitiveVarchar(int length)

Generate a column declaration that creates a case-sensitive variable-length string column type. If the database engine already treats strings in a case-sensitive way, it is safe to return null from this method. MySQL is case-insensitive by default. To get a case-sensitive column we can use: varchar(length) CHARACTER SET utf8 COLLATE utf8_bin

Parameters:

length - The maximum length that needs to be stored in the column

Returns:

The SQL snippet that creates the column, or null to let Hibernate use the default SQL

Since:

2.9

inspectSchemaGenerationSQL

String inspectSchemaGenerationSQL(String sql,
                                  org.hibernate.dialect.Dialect dialect,
                                  boolean update)

Let the DbEninge inspect a schema generation sql statment and possible modify it before it is sent to the database. This method is called from the SchemaGenerator class when creating or updating a database.

Parameters:

sql - The original SQL statment as generated by Hibernate

dialect - The Hibernate dialect currently in use

update - TRUE if we are updating an existing database, FALSE if we are creating a new one

Returns:

The SQL statement which may have been modified or null to skip executing the statment

Since:

2.16