org.apache.empire.db
Class DBDatabase

java.lang.Object
  extended by org.apache.empire.commons.ErrorObject
      extended by org.apache.empire.db.DBObject
          extended by org.apache.empire.db.DBDatabase
All Implemented Interfaces:
ErrorInfo
Direct Known Subclasses:
OracleSYSDatabase

public abstract class DBDatabase
extends DBObject

This abstract class is the applicaton's interface for a particular database schema.

It provides access to the various database objects such als tables, views and relations.

It also provides methods to execute DQL and DML SQL-commands.


Nested Class Summary
static class DBDatabase.DBSystemDate
          This class represents the database systems current date and time.
 
Field Summary
static java.lang.String EMPTY_STRING
           
static DBDatabase.DBSystemDate SYSDATE
           
 
Constructor Summary
DBDatabase()
          Constructs a new DBDatabase object set the variable 'schema' = null.
DBDatabase(java.lang.String schema)
          Constructs a new DBDatabase object and sets the specified schema object.
DBDatabase(java.lang.String schema, java.lang.String linkName)
          Constructs a new DBDatabase object and sets the specified schema object.
 
Method Summary
 boolean addRelation(DBRelation.DBReference reference)
          Adds a foreign key relation to the database.
 boolean addRelation(DBRelation.DBReference ref1, DBRelation.DBReference ref2)
          Add a foreign key relation to the database.
 boolean addReleation(java.lang.String name, DBRelation.DBReference[] references)
          Adds a foreign key relation to the database.
 boolean addTable(DBTable table)
          Adds a DBTable object to list of database tables.
 boolean addView(DBView view)
          Adds a DBView object to list of database views.
 void appendQualifiedName(java.lang.StringBuilder buf, java.lang.String name, boolean quoteName)
          Adds a full qualified object name including schema prefix and database link postfix (if any).
 void close(java.sql.Connection conn)
          closes this database object by detaching it from the driver this is a shortcut for calling getDriver().closeDatabase(db, conn)
 void closeResultSet(java.sql.ResultSet rset)
          Convenience function for closing a JDBC Resultset
Use it instead of rset.close() and stmt.close()
 void closeStatement(java.sql.Statement stmt)
          Convenience function for closing a JDBC Resultset
Use it instead of stmt.close()
 boolean commit(java.sql.Connection conn)
          Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection.
 DBCommand createCommand()
          Creates a new Command object for this database
 java.sql.ResultSet executeQuery(java.lang.String sqlCmd, java.lang.Object[] sqlParams, boolean scrollable, java.sql.Connection conn)
          Executes a select SQL-Statement and returns a resulset containing the query results.
 int executeSQL(java.lang.String sqlCmd, java.sql.Connection conn)
          Executes an update, insert or delete SQL-Statement.
 int executeSQL(java.lang.String sqlCmd, java.lang.Object[] sqlParams, java.sql.Connection conn)
          Executes an update, insert or delete SQL-Statement.
 boolean getCreateDDLScript(DBDatabaseDriver driver, DBSQLScript script)
          Creates a DDL Script for creating all database objects on the target database.
 DBDatabase getDatabase()
          Returns the database object to which this object belongs to.
 DBDatabaseDriver getDriver()
          Returns the driver for this database.
 java.lang.String getLinkName()
          Returns the database link name.
 java.lang.Object getNextSequenceValue(java.lang.String seqName, java.sql.Connection conn)
           
 java.lang.String getQualifiedName(java.lang.String name)
          Deprecated. 
 java.util.List<DBRelation> getRelations()
          Returns the tables which has been defined in the database.
 java.lang.String getSchema()
          Returns the schema for SQL statements.
 java.lang.String getSchemaPrefix()
          Returns the schema-prefix for SQL statements e.g.
 DBValueExpr getSystemDateExpr()
          Creates and returns a value object for the database systems current date and time.
 DBTable getTable(java.lang.String name)
          Finds a DBTable object by name.
 java.util.List<DBTable> getTables()
          Returns the tables which has been defined in the database.
 java.sql.Timestamp getUpdateTimestamp(java.sql.Connection conn)
          Returns a timestamp that is used for record updates.
 DBValueExpr getValueExpr(boolean value)
          Creates and returns a value object for the given boolean value.
 DBValueExpr getValueExpr(int value)
          Creates and returns a value object for the given integer value.
 DBValueExpr getValueExpr(long value)
          Creates and returns a value object for the given long value.
 DBValueExpr getValueExpr(java.lang.Object value, DataType dataType)
          Creates and returns a value object for the given value.
 DBValueExpr getValueExpr(java.lang.String value)
          Creates and returns a value object for the given string value.
 DBView getView(java.lang.String name)
          Finds a DBView object by name.
 java.util.List<DBView> getViews()
          Returns the tables which has been defined in the database.
 boolean isOpen()
          Indicates whether the database has been opened.
 boolean open(DBDatabaseDriver driver, java.sql.Connection conn)
          Sets the database driver for this database.
 java.util.List<java.lang.Object[]> queryObjectList(java.lang.String sqlCmd, java.sql.Connection conn)
          Returns a list Object-Arrays holding the result of a query.
 Options queryOptionList(java.lang.String sqlCmd, java.sql.Connection conn)
          Returns a list of key value pairs from an sql query.
<T> java.util.List<T>
querySimpleList(java.lang.Class<T> c, java.lang.String sqlCmd, java.sql.Connection conn)
          Returns a one dimensional array from an sql query.
 java.util.List<java.lang.Object> querySimpleList(java.lang.String sqlCmd, java.sql.Connection conn)
          Returns a one dimensional array from an sql query.
 double querySingleDouble(java.lang.String sqlCmd, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as a double.
 double querySingleDouble(java.lang.String sqlCmd, double defVal, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as a double.
 int querySingleInt(java.lang.String sqlCmd, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as an int.
 int querySingleInt(java.lang.String sqlCmd, int defVal, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as an int.
 long querySingleLong(java.lang.String sqlCmd, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as a long.
 long querySingleLong(java.lang.String sqlCmd, long defVal, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as a long.
 java.lang.String querySingleString(java.lang.String sqlCmd, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as a string.
 java.lang.String querySingleString(java.lang.String sqlCmd, java.lang.String defVal, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as a string.
 java.lang.Object querySingleValue(java.lang.String sqlCmd, java.sql.Connection conn)
          Returns the value of the first row/column of a sql-query as an object.
 boolean rollback(java.sql.Connection conn)
          Discards all changes made since the previous commit/rollback and releases any database locks currently held by this Connection.
 boolean setLinkName(java.lang.String linkName)
          Sets the name of the database link used to identify objects.
 boolean setSchema(java.lang.String schema)
          Sets the schema for SQL statements.
 
Methods inherited from class org.apache.empire.commons.ErrorObject
clearError, getErrorMessage, getErrorParams, getErrorSource, getErrorType, getMessage, hasError, isExceptionsEnabled, setExceptionsEnabled
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SYSDATE

public static final DBDatabase.DBSystemDate SYSDATE

EMPTY_STRING

public static final java.lang.String EMPTY_STRING
See Also:
Constant Field Values
Constructor Detail

DBDatabase

public DBDatabase()
Constructs a new DBDatabase object set the variable 'schema' = null.


DBDatabase

public DBDatabase(java.lang.String schema)
Constructs a new DBDatabase object and sets the specified schema object.

Parameters:
schema - the database schema

DBDatabase

public DBDatabase(java.lang.String schema,
                  java.lang.String linkName)
Constructs a new DBDatabase object and sets the specified schema object.

Parameters:
schema - the database schema
linkName - the database link name
Method Detail

getDriver

public DBDatabaseDriver getDriver()
Returns the driver for this database.

Returns:
Returns the driver for this database

open

public boolean open(DBDatabaseDriver driver,
                    java.sql.Connection conn)
Sets the database driver for this database.
------ DO NOT CALL DIRECTLY! -------
This function is called internally by DBDatabaseDriver:openDatabase()


close

public void close(java.sql.Connection conn)
closes this database object by detaching it from the driver this is a shortcut for calling getDriver().closeDatabase(db, conn)


getCreateDDLScript

public boolean getCreateDDLScript(DBDatabaseDriver driver,
                                  DBSQLScript script)
Creates a DDL Script for creating all database objects on the target database.
This function may be called even if the database has not been previously opened.

Once the database is open you can use getDriver().getDLLCommand() to create, alter or delete other database objects

Parameters:
driver - The driver for which to create a DDL Script
Returns:
the DLL script for creating the entire database schema

getDatabase

public DBDatabase getDatabase()
Description copied from class: DBObject
Returns the database object to which this object belongs to. For the database object itself this function will return the this pointer.

Specified by:
getDatabase in class DBObject
Returns:
the database object
See Also:
DBObject.getDatabase()

getSchema

public java.lang.String getSchema()
Returns the schema for SQL statements.

Returns:
the schema

setSchema

public boolean setSchema(java.lang.String schema)
Sets the schema for SQL statements.


getSchemaPrefix

public java.lang.String getSchemaPrefix()
Returns the schema-prefix for SQL statements e.g. "SCHEMA." or empty string if no schema is defined.

Returns:
the schema-prefix

getLinkName

public java.lang.String getLinkName()
Returns the database link name.

Returns:
the name of the database link

setLinkName

public boolean setLinkName(java.lang.String linkName)
Sets the name of the database link used to identify objects.

Parameters:
linkName - the database link name

getQualifiedName

@Deprecated
public java.lang.String getQualifiedName(java.lang.String name)
Deprecated. 

Returns the full qualified object name including schema prefix and database link postfix (if any).

Parameters:
name - the object's name
Returns:
the qualified object name

appendQualifiedName

public void appendQualifiedName(java.lang.StringBuilder buf,
                                java.lang.String name,
                                boolean quoteName)
Adds a full qualified object name including schema prefix and database link postfix (if any). to the string buffer suppield

Parameters:
buf - the string buffer to which to append the qualified object name
name - the object's name

getSystemDateExpr

public DBValueExpr getSystemDateExpr()
Creates and returns a value object for the database systems current date and time.

Returns:
a DBValueExpr object

getValueExpr

public DBValueExpr getValueExpr(java.lang.String value)
Creates and returns a value object for the given string value.

Parameters:
value - the String value
Returns:
the new DBValueExpr object

getValueExpr

public DBValueExpr getValueExpr(boolean value)
Creates and returns a value object for the given boolean value.

Parameters:
value - the Boolean value
Returns:
the new DBValueExpr object

getValueExpr

public DBValueExpr getValueExpr(int value)
Creates and returns a value object for the given integer value.

Parameters:
value - the int value
Returns:
the new DBValueExpr object

getValueExpr

public DBValueExpr getValueExpr(long value)
Creates and returns a value object for the given long value.

Parameters:
value - the long value
Returns:
the new DBValueExpr object

getValueExpr

public DBValueExpr getValueExpr(java.lang.Object value,
                                DataType dataType)
Creates and returns a value object for the given value.

Parameters:
value - the value
dataType - the database systems data type used for this value
Returns:
the new DBValueExpr object

addTable

public boolean addTable(DBTable table)
Adds a DBTable object to list of database tables.
There is usually no need to call this function directly since it is internally called from the DBTable's constructor.

Parameters:
table - the DBTable object
Returns:
true if successful

getTables

public java.util.List<DBTable> getTables()
Returns the tables which has been defined in the database.

Returns:
db tables.

getTable

public DBTable getTable(java.lang.String name)
Finds a DBTable object by name.

Parameters:
name - the name of the table
Returns:
the located DBTable object

addRelation

public final boolean addRelation(DBRelation.DBReference reference)
Adds a foreign key relation to the database.

Parameters:
reference - a reference for a source and target column pair
Returns:
true if the relations was successfully created.

addRelation

public final boolean addRelation(DBRelation.DBReference ref1,
                                 DBRelation.DBReference ref2)
Add a foreign key relation to the database.

Parameters:
ref1 - a reference for a source and target column pair
ref2 - a reference for a source and target column pair
Returns:
true if the relations was successfully created.

addReleation

public boolean addReleation(java.lang.String name,
                            DBRelation.DBReference[] references)
Adds a foreign key relation to the database.

Parameters:
references - a list of source and target column pairs
Returns:
true if the relations was successfully created.

getRelations

public java.util.List<DBRelation> getRelations()
Returns the tables which has been defined in the database.

Returns:
db tables.

addView

public boolean addView(DBView view)
Adds a DBView object to list of database views.
There is usually no need to call this function directly since it is internally called from the DBView's constructor.

Parameters:
view - the DBView object
Returns:
true if successful

getViews

public java.util.List<DBView> getViews()
Returns the tables which has been defined in the database.

Returns:
db tables.

getView

public DBView getView(java.lang.String name)
Finds a DBView object by name.

Parameters:
name - the name of the view
Returns:
the located DBTable object

isOpen

public boolean isOpen()
Indicates whether the database has been opened.

Returns:
The name of the encoding or null if a single byte encoding is used.

createCommand

public DBCommand createCommand()
Creates a new Command object for this database

Returns:
the command obejct.

getUpdateTimestamp

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

Returns:
the current date and time.

getNextSequenceValue

public java.lang.Object getNextSequenceValue(java.lang.String seqName,
                                             java.sql.Connection conn)

querySingleValue

public java.lang.Object querySingleValue(java.lang.String sqlCmd,
                                         java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as an object.

Parameters:
sqlCmd - the SQL-Command
conn - a valid connection to the database.
Returns:
the first column in the current row as a Java object
Throws:
java.sql.SQLException - if a database access error occurs

querySingleInt

public int querySingleInt(java.lang.String sqlCmd,
                          int defVal,
                          java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as an int.

Parameters:
sqlCmd - the SQL statement
defVal - the default value if no value was returned by the database
conn - a valid connection to the database.
Returns:
the result as a int value, if no result the int value 0

querySingleInt

public final int querySingleInt(java.lang.String sqlCmd,
                                java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as an int.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
the result as a int value, if no result the int value 0

querySingleLong

public long querySingleLong(java.lang.String sqlCmd,
                            long defVal,
                            java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as a long.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
the result as a long value, if no result the long value 0

querySingleLong

public final long querySingleLong(java.lang.String sqlCmd,
                                  java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as a long.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
the result as a long value, if no result the long value 0

querySingleDouble

public double querySingleDouble(java.lang.String sqlCmd,
                                double defVal,
                                java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as a double.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
the result as a long value, if no result the long value 0

querySingleDouble

public final double querySingleDouble(java.lang.String sqlCmd,
                                      java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as a double.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
the result as a long value, if no result the long value 0

querySingleString

public java.lang.String querySingleString(java.lang.String sqlCmd,
                                          java.lang.String defVal,
                                          java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as a string.

Parameters:
sqlCmd - the SQL statement
defVal - the default value if no value was returned by the database
conn - a valid connection to the database.
Returns:
the result as a String object, if no result a emtpy String

querySingleString

public final java.lang.String querySingleString(java.lang.String sqlCmd,
                                                java.sql.Connection conn)
Returns the value of the first row/column of a sql-query as a string.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
the result as a String object, if no result a emtpy String

querySimpleList

public <T> java.util.List<T> querySimpleList(java.lang.Class<T> c,
                                             java.lang.String sqlCmd,
                                             java.sql.Connection conn)
Returns a one dimensional array from an sql query. The array is filled with the values of the first column.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
a list of the values of the first column of an sql query

querySimpleList

public java.util.List<java.lang.Object> querySimpleList(java.lang.String sqlCmd,
                                                        java.sql.Connection conn)
Returns a one dimensional array from an sql query. The array is filled with the values of the first column.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
a list of values of type Object

queryOptionList

public Options queryOptionList(java.lang.String sqlCmd,
                               java.sql.Connection conn)
Returns a list of key value pairs from an sql query. The opton list is filled with the values of the first and second column.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
an Options object containing a set a of values and their corresponding names

queryObjectList

public java.util.List<java.lang.Object[]> queryObjectList(java.lang.String sqlCmd,
                                                          java.sql.Connection conn)
Returns a list Object-Arrays holding the result of a query. This function should only be used for small lists.

Parameters:
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
a list of object arrays

executeSQL

public int executeSQL(java.lang.String sqlCmd,
                      java.lang.Object[] sqlParams,
                      java.sql.Connection conn)
Executes an update, insert or delete SQL-Statement.
We recommend to use a DBCommand object in order to build the sqlCmd.

Parameters:
sqlCmd - the SQL-Command
sqlParams - a list of objects to replace sql parameters
conn - a valid connection to the database.
Returns:
the row count for insert, update or delete or 0 for SQL statements that return nothing

executeSQL

public final int executeSQL(java.lang.String sqlCmd,
                            java.sql.Connection conn)
Executes an update, insert or delete SQL-Statement.
We recommend to use a DBCommand object in order to build the sqlCmd.

Parameters:
sqlCmd - the SQL-Command
conn - a valid connection to the database.
Returns:
the row count for insert, update or delete or 0 for SQL statements that return nothing

executeQuery

public java.sql.ResultSet executeQuery(java.lang.String sqlCmd,
                                       java.lang.Object[] sqlParams,
                                       boolean scrollable,
                                       java.sql.Connection conn)
Executes a select SQL-Statement and returns a resulset containing the query results.
This function returns a JDBC ResultSet.
Insteam of using this function directly you should use a DBReader object instead.

Parameters:
sqlCmd - the SQL-Command
sqlParams - a list of parameters for parameter queries (may depend on driver)
scrollable - true if the reader should be scrollable or false if not
conn - a valid connection to the database.
Returns:
the JDBC ResutSet

commit

public boolean commit(java.sql.Connection conn)
Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection.

Parameters:
conn - a valid database connection
Returns:
true if successful
Throws:
java.sql.SQLException - if a database access error occurs

rollback

public boolean rollback(java.sql.Connection conn)
Discards all changes made since the previous commit/rollback and releases any database locks currently held by this Connection.

Parameters:
conn - a valid database connection
Returns:
true if successful
Throws:
java.sql.SQLException - if a database access error occurs

closeStatement

public void closeStatement(java.sql.Statement stmt)
Convenience function for closing a JDBC Resultset
Use it instead of stmt.close()

Parameters:
stmt - a Statement object

closeResultSet

public void closeResultSet(java.sql.ResultSet rset)
Convenience function for closing a JDBC Resultset
Use it instead of rset.close() and stmt.close()

Parameters:
rset - a ResultSet object
Throws:
java.sql.SQLException - if a database access error occurs