org.apache.empire.db
Class DBDatabaseDriver

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

public abstract class DBDatabaseDriver
extends ErrorObject
implements java.io.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.
 
Nested classes/interfaces inherited from class org.apache.empire.commons.ErrorObject
ErrorObject.ObjectErrorInfo
 
Field Summary
protected  boolean ddlColumnDefaults
           
protected static java.lang.String[] GENERAL_SQL_KEYWORDS
           
protected static char[] ILLEGAL_NAME_CHARS
           
protected static org.slf4j.Logger log
           
protected  java.util.Set<java.lang.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 appendElementName(java.lang.StringBuilder sql, java.lang.String name)
          Appends a table, view or column name to an SQL phrase.
 void appendElementName(java.lang.StringBuilder sql, java.lang.String name, boolean useQuotes)
          Appends a table, view or column name to an SQL phrase.
protected  void appendTextValue(java.lang.StringBuilder buf, java.lang.String value)
          this helper function doubles up single quotes for SQL
protected  boolean attachDatabase(DBDatabase db, java.sql.Connection conn)
          Called when a database is opened
 boolean checkDatabase(DBDatabase db, java.lang.String owner, java.sql.Connection conn)
          Checks the database whether or not it is consistent with the description.
protected  void close(java.sql.Statement stmt)
           
abstract  DBCommand createCommand(DBDatabase db)
          This function creates a DBCommand derived object this database
protected  void detachDatabase(DBDatabase db, java.sql.Connection conn)
          Called when a database is closed
protected  boolean detectQuoteName(java.lang.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"
 java.sql.ResultSet executeQuery(java.lang.String sqlCmd, java.lang.Object[] sqlParams, boolean scrollable, java.sql.Connection conn)
           
 int executeSQL(java.lang.String sqlCmd, java.lang.Object[] sqlParams, java.sql.Connection conn, DBDatabaseDriver.DBSetGenKeys genKeys)
          Executes the select, update or delete SQL-Command with a Statement object.
 java.lang.String extractErrorMessage(java.sql.SQLException e)
          Extracts native error message of an sqlExeption.
 java.lang.Object getColumnAutoValue(DBDatabase db, DBTableColumn column, java.sql.Connection conn)
          Returns an auto-generated value for a particular column
abstract  java.lang.String getConvertPhrase(DataType destType, DataType srcType, java.lang.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.
protected  java.lang.String getDateTimeString(java.lang.Object value, int sqlTemplate, int sqlPattern, int sqlCurrentDate)
           
 boolean getDDLScript(DBCmdType type, DBObject dbo, DBSQLScript script)
          Gets a SQL command for creating, modifying or deleting objects in the database (tables, columns, constraints, etc.)
abstract  java.lang.Object getNextSequenceValue(DBDatabase db, java.lang.String SeqName, int minValue, java.sql.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).
 java.lang.Object getResultValue(java.sql.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.
abstract  java.lang.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.
 java.sql.Timestamp getUpdateTimestamp(java.sql.Connection conn)
          Returns a timestamp that is used for record updates.
 java.lang.String getValueString(java.lang.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(java.sql.PreparedStatement pstmt, java.lang.Object[] sqlParams)
          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
 
Methods inherited from class org.apache.empire.commons.ErrorObject
clearError, clearErrorInfo, error, error, error, error, error, getErrorInfo, getErrorMessage, getErrorParams, getErrorSource, getErrorType, getMessage, hasError, internalSetError, isExceptionsEnabled, setExceptionsEnabled, success
 
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

log

protected static final org.slf4j.Logger log

ddlColumnDefaults

protected boolean ddlColumnDefaults

ILLEGAL_NAME_CHARS

protected static final char[] ILLEGAL_NAME_CHARS

GENERAL_SQL_KEYWORDS

protected static final java.lang.String[] GENERAL_SQL_KEYWORDS

reservedSQLKeywords

protected final java.util.Set<java.lang.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

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(java.lang.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(java.lang.StringBuilder sql,
                              java.lang.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(java.lang.StringBuilder sql,
                                    java.lang.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 java.lang.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 java.lang.String getConvertPhrase(DataType destType,
                                                  DataType srcType,
                                                  java.lang.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 java.lang.Object getNextSequenceValue(DBDatabase db,
                                                      java.lang.String SeqName,
                                                      int minValue,
                                                      java.sql.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 java.lang.Object getColumnAutoValue(DBDatabase db,
                                           DBTableColumn column,
                                           java.sql.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(java.sql.PreparedStatement pstmt,
                                java.lang.Object[] sqlParams)
                         throws java.sql.SQLException
Prepares an sql statement by setting the supplied objects as parameters.

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

extractErrorMessage

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

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

getResultValue

public java.lang.Object getResultValue(java.sql.ResultSet rset,
                                       int columnIndex,
                                       DataType dataType)
                                throws java.sql.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:
java.sql.SQLException - if a database access error occurs

executeSQL

public int executeSQL(java.lang.String sqlCmd,
                      java.lang.Object[] sqlParams,
                      java.sql.Connection conn,
                      DBDatabaseDriver.DBSetGenKeys genKeys)
               throws java.sql.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:
java.sql.SQLException - if a database access error occurs

executeQuery

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

close

protected void close(java.sql.Statement stmt)

getDateTimeString

protected java.lang.String getDateTimeString(java.lang.Object value,
                                             int sqlTemplate,
                                             int sqlPattern,
                                             int sqlCurrentDate)

getValueString

public final java.lang.String getValueString(java.lang.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

attachDatabase

protected boolean attachDatabase(DBDatabase db,
                                 java.sql.Connection conn)
Called when a database is opened


detachDatabase

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


checkDatabase

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

Parameters:
db - the database
owner - the owner
conn - the connection
Returns:
true if it is consistent with the description

getDDLScript

public boolean getDDLScript(DBCmdType type,
                            DBObject dbo,
                            DBSQLScript script)
Gets a SQL command for creating, modifying or deleting objects in the database (tables, columns, constraints, etc.)

Parameters:
type - the command type
dbo - the databse object
script - the script to complete
Returns:
true on succes

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 java.sql.Timestamp getUpdateTimestamp(java.sql.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.

appendTextValue

protected void appendTextValue(java.lang.StringBuilder buf,
                               java.lang.String value)
this helper function doubles up single quotes for SQL



Copyright © 2008-2011 Apache Software Foundation. All Rights Reserved.