org.apache.empire.db
Class DBDatabaseDriver

java.lang.Object
  extended by org.apache.empire.db.DBDatabaseDriver
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
DBDatabaseDriverDerby, DBDatabaseDriverH2, DBDatabaseDriverHSql, DBDatabaseDriverMSSQL, DBDatabaseDriverMySQL, DBDatabaseDriverOracle, DBDatabaseDriverPostgreSQL, DBDatabaseDriverSQLite

public abstract class DBDatabaseDriver
extends Object
implements Serializable

The DBDatabaseDriver class is an abstract base class for all database drivers. Its purpose is to handle everything that is - or might be - database vendor specific.

See Also:
Serialized Form

Nested Class Summary
static class DBDatabaseDriver.DBSeqTable
          This class is used to emulate sequences by using a sequence table.
static interface DBDatabaseDriver.DBSetGenKeys
          This interface is used to set the auto generated keys when executing insert statements.
 
Field Summary
protected  boolean ddlColumnDefaults
           
protected static String[] GENERAL_SQL_KEYWORDS
           
protected static char[] ILLEGAL_NAME_CHARS
           
protected  Set<String> reservedSQLKeywords
           
static int SQL_BOOLEAN_FALSE
           
static int SQL_BOOLEAN_TRUE
           
static int SQL_CONCAT_EXPR
           
static int SQL_CURRENT_DATE
           
static int SQL_CURRENT_DATETIME
           
static int SQL_DATABASE_LINK
           
static int SQL_DATE_PATTERN
           
static int SQL_DATE_TEMPLATE
           
static int SQL_DATETIME_PATTERN
           
static int SQL_DATETIME_TEMPLATE
           
static int SQL_FUNC_ABS
           
static int SQL_FUNC_AVG
           
static int SQL_FUNC_CEILING
           
static int SQL_FUNC_COALESCE
           
static int SQL_FUNC_DAY
           
static int SQL_FUNC_DECODE
           
static int SQL_FUNC_DECODE_ELSE
           
static int SQL_FUNC_DECODE_PART
           
static int SQL_FUNC_DECODE_SEP
           
static int SQL_FUNC_ESCAPE
           
static int SQL_FUNC_FLOOR
           
static int SQL_FUNC_LENGTH
           
static int SQL_FUNC_LOWER
           
static int SQL_FUNC_LTRIM
           
static int SQL_FUNC_MAX
           
static int SQL_FUNC_MIN
           
static int SQL_FUNC_MONTH
           
static int SQL_FUNC_REPLACE
           
static int SQL_FUNC_REVERSE
           
static int SQL_FUNC_ROUND
           
static int SQL_FUNC_RTRIM
           
static int SQL_FUNC_STRINDEX
           
static int SQL_FUNC_STRINDEXFROM
           
static int SQL_FUNC_SUBSTRING
           
static int SQL_FUNC_SUBSTRINGEX
           
static int SQL_FUNC_SUM
           
static int SQL_FUNC_TRIM
           
static int SQL_FUNC_TRUNC
           
static int SQL_FUNC_UPPER
           
static int SQL_FUNC_YEAR
           
static int SQL_NULL_VALUE
           
static int SQL_PARAMETER
           
static int SQL_QUOTES_CLOSE
           
static int SQL_QUOTES_OPEN
           
static int SQL_RENAME_COLUMN
           
static int SQL_RENAME_TABLE
           
 
Constructor Summary
DBDatabaseDriver()
          Constructor
 
Method Summary
 void addEnableRelationStmt(DBRelation r, boolean enable, DBSQLScript script)
          Appends a statement to enable or disable a foreign key relation.
The default is to drop or create the relation Override this method to provide different behavior for your database.
protected  void addStatementParam(PreparedStatement pstmt, int paramIndex, Object value, Connection conn)
          Adds a statement parameter to a prepared statement
 void appendElementName(StringBuilder sql, String name)
          Appends a table, view or column name to an SQL phrase.
 void appendElementName(StringBuilder sql, String name, boolean useQuotes)
          Appends a table, view or column name to an SQL phrase.
protected  void appendSQLTextValue(StringBuilder buf, String value)
          this helper function doubles up single quotes for SQL
protected  void attachDatabase(DBDatabase db, Connection conn)
          Called when a database is opened
 void checkDatabase(DBDatabase db, String owner, Connection conn)
          Checks the database whether or not it is consistent with the description.
protected  void close(Statement stmt)
           
 DBCommandExpr createCombinedCommand(DBCommandExpr left, String keyWord, DBCommandExpr right)
          This function gives the driver a chance to provide a custom implementation for a combined command such as UNION or INTERSECT
abstract  DBCommand createCommand(DBDatabase db)
          This function creates a DBCommand derived object this database
protected  void detachDatabase(DBDatabase db, Connection conn)
          Called when a database is closed
protected  boolean detectQuoteName(String name)
          Detects whether a table or column name needs to be quoted or not
By default all reserved SQL keywords as well as names containing a "-", "/", "+" or " " require quoting.
Overrides this function to add database specific keywords like "user" or "count"
 ResultSet executeQuery(String sqlCmd, Object[] sqlParams, boolean scrollable, Connection conn)
           
 int executeSQL(String sqlCmd, Object[] sqlParams, Connection conn, DBDatabaseDriver.DBSetGenKeys genKeys)
          Executes the select, update or delete SQL-Command with a Statement object.
 String extractErrorMessage(SQLException e)
          Extracts native error message of an sqlExeption.
 Object getColumnAutoValue(DBDatabase db, DBTableColumn column, Connection conn)
          Returns an auto-generated value for a particular column
abstract  String getConvertPhrase(DataType destType, DataType srcType, Object format)
          Returns a data type convertion phrase template for this driver
The returned template must contain a '?' which will be replaced by a column expression.
 void getDDLScript(DBCmdType type, DBObject dbo, DBSQLScript script)
          Appends the required DLL commands to create, drop or alter an object to the supplied DBDQLScript.
abstract  Object getNextSequenceValue(DBDatabase db, String SeqName, int minValue, Connection conn)
          Returns the next value of a named sequence The numbers are used for fields of type DBExpr.DT_AUTOINC.
If a driver supports this function it must return true for isSupported(DBDriverFeature.SEQUENCES).
 Object getResultValue(ResultSet rset, int columnIndex, DataType dataType)
           Reads a single column value from the given JDBC ResultSet and returns a value object of desired data type.
See DBExpr.getValueClass(DataType) for java class type mapping.
protected  String getSQLDateTimeString(Object value, int sqlTemplate, int sqlPattern, int sqlCurrentDate)
          encodes a Date value for an SQL command string.
protected  String getSQLNumberString(Object value, DataType type)
          encodes a numeric value for an SQL command string.
abstract  String getSQLPhrase(int phrase)
          Returns an sql phrase template for this database system.
Templates for sql function expressions must contain a '?' character which will be replaced by the current column expression.
If other parameters are necessary the template must contain placeholders like {0}, {1} etc.
protected  String getSQLTextString(DataType type, Object value)
          encodes Text values for an SQL command string.
 Timestamp getUpdateTimestamp(Connection conn)
          Returns a timestamp that is used for record updates.
 String getValueString(Object value, DataType type)
          Creates a sql string for a given value.
 boolean isDDLColumnDefaults()
           
abstract  boolean isSupported(DBDriverFeature type)
          Returns whether or not a particular feature is supported by this driver
protected  void prepareStatement(PreparedStatement pstmt, Object[] sqlParams, Connection conn)
          Prepares an sql statement by setting the supplied objects as parameters.
 void setDDLColumnDefaults(boolean ddlColumnDefaults)
          Set true if column default values should be included in DDL Statements
protected  boolean stringToBoolean(String value)
          this function converts a string containing a boolean expression to a boolean.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SQL_NULL_VALUE

public static final int SQL_NULL_VALUE
See Also:
Constant Field Values

SQL_PARAMETER

public static final int SQL_PARAMETER
See Also:
Constant Field Values

SQL_RENAME_TABLE

public static final int SQL_RENAME_TABLE
See Also:
Constant Field Values

SQL_RENAME_COLUMN

public static final int SQL_RENAME_COLUMN
See Also:
Constant Field Values

SQL_DATABASE_LINK

public static final int SQL_DATABASE_LINK
See Also:
Constant Field Values

SQL_QUOTES_OPEN

public static final int SQL_QUOTES_OPEN
See Also:
Constant Field Values

SQL_QUOTES_CLOSE

public static final int SQL_QUOTES_CLOSE
See Also:
Constant Field Values

SQL_CONCAT_EXPR

public static final int SQL_CONCAT_EXPR
See Also:
Constant Field Values

SQL_BOOLEAN_TRUE

public static final int SQL_BOOLEAN_TRUE
See Also:
Constant Field Values

SQL_BOOLEAN_FALSE

public static final int SQL_BOOLEAN_FALSE
See Also:
Constant Field Values

SQL_CURRENT_DATE

public static final int SQL_CURRENT_DATE
See Also:
Constant Field Values

SQL_DATE_PATTERN

public static final int SQL_DATE_PATTERN
See Also:
Constant Field Values

SQL_DATE_TEMPLATE

public static final int SQL_DATE_TEMPLATE
See Also:
Constant Field Values

SQL_CURRENT_DATETIME

public static final int SQL_CURRENT_DATETIME
See Also:
Constant Field Values

SQL_DATETIME_PATTERN

public static final int SQL_DATETIME_PATTERN
See Also:
Constant Field Values

SQL_DATETIME_TEMPLATE

public static final int SQL_DATETIME_TEMPLATE
See Also:
Constant Field Values

SQL_FUNC_COALESCE

public static final int SQL_FUNC_COALESCE
See Also:
Constant Field Values

SQL_FUNC_SUBSTRING

public static final int SQL_FUNC_SUBSTRING
See Also:
Constant Field Values

SQL_FUNC_SUBSTRINGEX

public static final int SQL_FUNC_SUBSTRINGEX
See Also:
Constant Field Values

SQL_FUNC_REPLACE

public static final int SQL_FUNC_REPLACE
See Also:
Constant Field Values

SQL_FUNC_REVERSE

public static final int SQL_FUNC_REVERSE
See Also:
Constant Field Values

SQL_FUNC_STRINDEX

public static final int SQL_FUNC_STRINDEX
See Also:
Constant Field Values

SQL_FUNC_STRINDEXFROM

public static final int SQL_FUNC_STRINDEXFROM
See Also:
Constant Field Values

SQL_FUNC_LENGTH

public static final int SQL_FUNC_LENGTH
See Also:
Constant Field Values

SQL_FUNC_UPPER

public static final int SQL_FUNC_UPPER
See Also:
Constant Field Values

SQL_FUNC_LOWER

public static final int SQL_FUNC_LOWER
See Also:
Constant Field Values

SQL_FUNC_TRIM

public static final int SQL_FUNC_TRIM
See Also:
Constant Field Values

SQL_FUNC_LTRIM

public static final int SQL_FUNC_LTRIM
See Also:
Constant Field Values

SQL_FUNC_RTRIM

public static final int SQL_FUNC_RTRIM
See Also:
Constant Field Values

SQL_FUNC_ESCAPE

public static final int SQL_FUNC_ESCAPE
See Also:
Constant Field Values

SQL_FUNC_ABS

public static final int SQL_FUNC_ABS
See Also:
Constant Field Values

SQL_FUNC_ROUND

public static final int SQL_FUNC_ROUND
See Also:
Constant Field Values

SQL_FUNC_TRUNC

public static final int SQL_FUNC_TRUNC
See Also:
Constant Field Values

SQL_FUNC_FLOOR

public static final int SQL_FUNC_FLOOR
See Also:
Constant Field Values

SQL_FUNC_CEILING

public static final int SQL_FUNC_CEILING
See Also:
Constant Field Values

SQL_FUNC_DAY

public static final int SQL_FUNC_DAY
See Also:
Constant Field Values

SQL_FUNC_MONTH

public static final int SQL_FUNC_MONTH
See Also:
Constant Field Values

SQL_FUNC_YEAR

public static final int SQL_FUNC_YEAR
See Also:
Constant Field Values

SQL_FUNC_SUM

public static final int SQL_FUNC_SUM
See Also:
Constant Field Values

SQL_FUNC_MAX

public static final int SQL_FUNC_MAX
See Also:
Constant Field Values

SQL_FUNC_MIN

public static final int SQL_FUNC_MIN
See Also:
Constant Field Values

SQL_FUNC_AVG

public static final int SQL_FUNC_AVG
See Also:
Constant Field Values

SQL_FUNC_DECODE

public static final int SQL_FUNC_DECODE
See Also:
Constant Field Values

SQL_FUNC_DECODE_SEP

public static final int SQL_FUNC_DECODE_SEP
See Also:
Constant Field Values

SQL_FUNC_DECODE_PART

public static final int SQL_FUNC_DECODE_PART
See Also:
Constant Field Values

SQL_FUNC_DECODE_ELSE

public static final int SQL_FUNC_DECODE_ELSE
See Also:
Constant Field Values

ddlColumnDefaults

protected boolean ddlColumnDefaults

ILLEGAL_NAME_CHARS

protected static final char[] ILLEGAL_NAME_CHARS

GENERAL_SQL_KEYWORDS

protected static final String[] GENERAL_SQL_KEYWORDS

reservedSQLKeywords

protected final Set<String> reservedSQLKeywords
Constructor Detail

DBDatabaseDriver

public DBDatabaseDriver()
Constructor

Method Detail

createCommand

public abstract DBCommand createCommand(DBDatabase db)
This function creates a DBCommand derived object this database

Parameters:
db - the database for which to create a command object for
Returns:
a DBCommand object

createCombinedCommand

public DBCommandExpr createCombinedCommand(DBCommandExpr left,
                                           String keyWord,
                                           DBCommandExpr right)
This function gives the driver a chance to provide a custom implementation for a combined command such as UNION or INTERSECT

Parameters:
left - the left command
keyWord - the key word (either "UNION" or "INTERSECT")
left - the right command
Returns:
a DBCommandExpr object

isSupported

public abstract boolean isSupported(DBDriverFeature type)
Returns whether or not a particular feature is supported by this driver

Parameters:
type - type of requested feature. @see DBDriverFeature
Returns:
true if the features is supported or false otherwise

detectQuoteName

protected boolean detectQuoteName(String name)
Detects whether a table or column name needs to be quoted or not
By default all reserved SQL keywords as well as names containing a "-", "/", "+" or " " require quoting.
Overrides this function to add database specific keywords like "user" or "count"


appendElementName

public void appendElementName(StringBuilder sql,
                              String name,
                              boolean useQuotes)
Appends a table, view or column name to an SQL phrase.

Parameters:
sql - the StringBuilder containing the SQL phrase.
name - the name of the object (table, view or column)
useQuotes - use quotes or not

appendElementName

public final void appendElementName(StringBuilder sql,
                                    String name)
Appends a table, view or column name to an SQL phrase.

Parameters:
sql - the StringBuilder containing the SQL phrase.
name - the name of the object (table, view or column)

getSQLPhrase

public abstract String getSQLPhrase(int phrase)
Returns an sql phrase template for this database system.
Templates for sql function expressions must contain a '?' character which will be replaced by the current column expression.
If other parameters are necessary the template must contain placeholders like {0}, {1} etc.

Parameters:
phrase - the identifier of the phrase
Returns:
the phrase template

getConvertPhrase

public abstract String getConvertPhrase(DataType destType,
                                        DataType srcType,
                                        Object format)
Returns a data type convertion phrase template for this driver
The returned template must contain a '?' which will be replaced by a column expression.

Parameters:
destType - the target data type
srcType - the source data type
format - additional formatting information (optional)
Returns:
the data conversion phrase template

getNextSequenceValue

public abstract Object getNextSequenceValue(DBDatabase db,
                                            String SeqName,
                                            int minValue,
                                            Connection conn)
Returns the next value of a named sequence The numbers are used for fields of type DBExpr.DT_AUTOINC.
If a driver supports this function it must return true for isSupported(DBDriverFeature.SEQUENCES).

Parameters:
db - the database
SeqName - the name of the sequence
minValue - the minimum value of the sequence
conn - a valid database connection
Returns:
a new unique sequence value or null if an error occurred

getColumnAutoValue

public Object getColumnAutoValue(DBDatabase db,
                                 DBTableColumn column,
                                 Connection conn)
Returns an auto-generated value for a particular column

Parameters:
db - the database
column - the column for which a value is required
conn - a valid database connection
Returns:
the auto-generated value

prepareStatement

protected void prepareStatement(PreparedStatement pstmt,
                                Object[] sqlParams,
                                Connection conn)
                         throws SQLException
Prepares an sql statement by setting the supplied objects as parameters.

Parameters:
pstmt - the prepared statement
sqlParams - list of objects
Throws:
SQLException

addStatementParam

protected void addStatementParam(PreparedStatement pstmt,
                                 int paramIndex,
                                 Object value,
                                 Connection conn)
                          throws SQLException
Adds a statement parameter to a prepared statement

Parameters:
pstmt - the prepared statement
paramIndex - the parameter index
value - the parameter value
conn - the connection
Throws:
SQLException

extractErrorMessage

public String extractErrorMessage(SQLException e)
Extracts native error message of an sqlExeption.

Parameters:
e - the SQLException
Returns:
the error message of the database

getResultValue

public Object getResultValue(ResultSet rset,
                             int columnIndex,
                             DataType dataType)
                      throws SQLException

Reads a single column value from the given JDBC ResultSet and returns a value object of desired data type.
See DBExpr.getValueClass(DataType) for java class type mapping.

This gives the driver the opportunity to change the value i.e. to simulate missing data types with other types.

Parameters:
rset - the sql Resultset with the current data row
columnIndex - one based column Index of the desired column
dataType - the required data type
Returns:
the value of the Column
Throws:
SQLException - if a database access error occurs

executeSQL

public int executeSQL(String sqlCmd,
                      Object[] sqlParams,
                      Connection conn,
                      DBDatabaseDriver.DBSetGenKeys genKeys)
               throws SQLException
Executes the select, update or delete SQL-Command with a Statement object.

Parameters:
sqlCmd - the SQL-Command
sqlParams - array of sql command parameters used for prepared statements (Optional).
conn - a valid connection to the database.
genKeys - allows to set the auto generated key of a record (INSERT statements only)
Returns:
the row count for insert, update or delete or 0 for SQL statements that return nothing
Throws:
SQLException - if a database access error occurs

executeQuery

public ResultSet executeQuery(String sqlCmd,
                              Object[] sqlParams,
                              boolean scrollable,
                              Connection conn)
                       throws SQLException
Throws:
SQLException

close

protected void close(Statement stmt)

getValueString

public String getValueString(Object value,
                             DataType type)
Creates a sql string for a given value. Text will be enclosed in single quotes and existing single quotes will be doubled. Empty strings are treated as null. Syntax of Date, Datetime and Boolean values are vendor specific.

Parameters:
value - the value which is inserted to the new String
type - the sql data type of the supplied value
Returns:
the sql string representing this value

getSQLNumberString

protected String getSQLNumberString(Object value,
                                    DataType type)
encodes a numeric value for an SQL command string.

Parameters:
value - the numeric value
type - the number data type
Returns:
the string reprentation of the number

getSQLDateTimeString

protected String getSQLDateTimeString(Object value,
                                      int sqlTemplate,
                                      int sqlPattern,
                                      int sqlCurrentDate)
encodes a Date value for an SQL command string.

Parameters:
value -
sqlTemplate -
sqlPattern -
sqlCurrentDate -
Returns:

getSQLTextString

protected String getSQLTextString(DataType type,
                                  Object value)
encodes Text values for an SQL command string.

Parameters:
type - date type (can only be TEXT, CHAR, CLOB and UNIQUEID)
value - the text to be encoded
Returns:
the encoded sql value

appendSQLTextValue

protected void appendSQLTextValue(StringBuilder buf,
                                  String value)
this helper function doubles up single quotes for SQL


stringToBoolean

protected boolean stringToBoolean(String value)
this function converts a string containing a boolean expression to a boolean.

Parameters:
value - the string containing a boolean expression
Returns:
true if the string contains either "true", "y" or "1" or false otherwise

attachDatabase

protected void attachDatabase(DBDatabase db,
                              Connection conn)
Called when a database is opened


detachDatabase

protected void detachDatabase(DBDatabase db,
                              Connection conn)
Called when a database is closed


checkDatabase

public void checkDatabase(DBDatabase db,
                          String owner,
                          Connection conn)
Checks the database whether or not it is consistent with the description.

Parameters:
db - the database
owner - the owner
conn - the connection

getDDLScript

public void getDDLScript(DBCmdType type,
                         DBObject dbo,
                         DBSQLScript script)
Appends the required DLL commands to create, drop or alter an object to the supplied DBDQLScript.

Parameters:
type - operation to perform (CREATE, DROP, ALTER)
dbo - the object for which to perform the operation (DBDatabase, DBTable, DBView, DBColumn, DBRelation)
script - the script to which to add the DDL command(s)

addEnableRelationStmt

public void addEnableRelationStmt(DBRelation r,
                                  boolean enable,
                                  DBSQLScript script)
Appends a statement to enable or disable a foreign key relation.
The default is to drop or create the relation Override this method to provide different behavior for your database.

Parameters:
r - the foreign key relation which should be enabled or disabled
enable - true to enable the relation or false to disable
script - the script to which to add the DDL command(s)

isDDLColumnDefaults

public boolean isDDLColumnDefaults()
Returns:
true if column default values are created with dll statements or false if not

setDDLColumnDefaults

public void setDDLColumnDefaults(boolean ddlColumnDefaults)
Set true if column default values should be included in DDL Statements

Parameters:
ddlColumnDefaults - true if dll statements should include column default values or false if not

getUpdateTimestamp

public Timestamp getUpdateTimestamp(Connection conn)
Returns a timestamp that is used for record updates.

Parameters:
conn - the connection that might be used
Returns:
the current date and time.


Copyright © 2008–2014 Apache Software Foundation. All rights reserved.