org.apache.empire.db
Class DBDatabase

java.lang.Object
  extended by org.apache.empire.db.DBObject
      extended by org.apache.empire.db.DBDatabase
All Implemented Interfaces:
Serializable
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.

See Also:
Serialized Form

Nested Class Summary
static class DBDatabase.DBSystemDate
          This class represents the database systems current date and time.
 
Field Summary
protected  DBDatabaseDriver driver
           
static String EMPTY_STRING
           
protected  String linkName
           
protected  List<DBRelation> relations
           
protected  String schema
          the database schema *
static DBDatabase.DBSystemDate SYSDATE
           
protected  List<DBTable> tables
           
protected  List<DBView> views
           
 
Constructor Summary
DBDatabase()
          Constructs a new DBDatabase object set the variable 'schema' = null.
DBDatabase(String schema)
          Constructs a new DBDatabase object and sets the specified schema object.
DBDatabase(String schema, String linkName)
          Constructs a new DBDatabase object and sets the specified schema object.
 
Method Summary
 void addRelation(DBRelation.DBReference reference)
          Adds a foreign key relation to the database.
 void addRelation(DBRelation.DBReference ref1, DBRelation.DBReference ref2)
          Add a foreign key relation to the database.
 void addRelation(String name, DBRelation.DBReference[] references)
          Adds a foreign key relation to the database.
 void 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.
 void 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.
 void appendQualifiedName(StringBuilder buf, String name, boolean quoteName)
          Adds a full qualified object name including schema prefix and database link postfix (if any).
protected  void checkOpen()
           
 void close(Connection conn)
          closes this database object by detaching it from the driver this is a shortcut for calling getDriver().closeDatabase(db, conn)
 void closeResultSet(ResultSet rset)
          Convenience function for closing a JDBC Resultset
Use it instead of rset.close() and stmt.close()
 void closeStatement(Statement stmt)
          Convenience function for closing a JDBC Resultset
Use it instead of stmt.close()
 void commit(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
 ResultSet executeQuery(String sqlCmd, Object[] sqlParams, boolean scrollable, Connection conn)
          Executes a select SQL-Statement and returns a resultset containing the query results.
This function returns a JDBC ResultSet.
Instead of using this function directly you should use a DBReader object instead.
 int executeSQL(String sqlCmd, Connection conn)
          Executes an update, insert or delete SQL-Statement.
We recommend to use a DBCommand object in order to build the sqlCmd.
 int executeSQL(String sqlCmd, Object[] sqlParams, Connection conn)
           
 int executeSQL(String sqlCmd, Object[] sqlParams, Connection conn, DBDatabaseDriver.DBSetGenKeys setGenKeys)
          Executes an update, insert or delete SQL-Statement.
We recommend to use a DBCommand object in order to build the sqlCmd.
 void 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.
 DBDatabase getDatabase()
          Returns the database object to which this object belongs to.
 DBDatabaseDriver getDriver()
          Returns the driver for this database.
 String getLinkName()
          Returns the database link name.
 Object getNextSequenceValue(String seqName, Connection conn)
           
 String getQualifiedName(String name)
          Deprecated. 
 DBRelation getRelation(String relationName)
          Returns the relation of a given name
 List<DBRelation> getRelations()
          Returns the relations which have been defined in the database.
 String getSchema()
          Returns the schema for SQL statements.
 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(String name)
          Finds a DBTable object by name.
 List<DBTable> getTables()
          Returns the tables which have been defined in the database.
 Timestamp getUpdateTimestamp(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(Object value, DataType dataType)
          Creates and returns a value object for the given value.
 DBValueExpr getValueExpr(String value)
          Creates and returns a value object for the given string value.
 DBView getView(String name)
          Finds a DBView object by name.
 List<DBView> getViews()
          Returns the views which have been defined in the database.
 boolean isOpen()
          Indicates whether the database has been opened.
 boolean isPreparedStatementsEnabled()
          return whether prepared statements are preferred over normal statements (Default is false) Note: This will only apply for update and insert commands as well as for read operations on a DBRecord.
 void open(DBDatabaseDriver driver, Connection conn)
          Sets the database driver for this database.
 List<Object[]> queryObjectList(String sqlCmd, Connection conn)
          Returns the result of a query as a list Object-Arrays This function should only be used for small lists.
 int queryObjectList(String sqlCmd, Connection conn, Collection<Object[]> result)
          Adds the result of a query to a given collection.
The individual rows will be added as an array of objects (object[])
 Options queryOptionList(String sqlCmd, Connection conn)
          Returns a list of key value pairs from an sql query.
<T> List<T>
querySimpleList(Class<T> c, String sqlCmd, Connection conn)
          Returns a one dimensional array from an sql query.
<T> int
querySimpleList(Class<T> c, String sqlCmd, Connection conn, Collection<T> result)
          Adds the first column of a query result to a collection.
 List<Object> querySimpleList(String sqlCmd, Connection conn)
          Returns a one dimensional array from an sql query.
 double querySingleDouble(String sqlCmd, Connection conn)
          Returns the value of the first row/column of a sql-query as a double.
 double querySingleDouble(String sqlCmd, double defVal, Connection conn)
          Returns the value of the first row/column of a sql-query as a double.
 int querySingleInt(String sqlCmd, Connection conn)
          Returns the value of the first row/column of a sql-query as an int.
 int querySingleInt(String sqlCmd, int defVal, Connection conn)
          Returns the value of the first row/column of a sql-query as an int.
 long querySingleLong(String sqlCmd, Connection conn)
          Returns the value of the first row/column of a sql-query as a long.
 long querySingleLong(String sqlCmd, long defVal, Connection conn)
          Returns the value of the first row/column of a sql-query as a long.
 String querySingleString(String sqlCmd, Connection conn)
          Returns the value of the first row/column of a sql-query as a string.
 String querySingleString(String sqlCmd, String defVal, Connection conn)
          Returns the value of the first row/column of a sql-query as a string.
 Object querySingleValue(String sqlCmd, Connection conn)
          Returns the value of the first row/column of a sql-query as an object.
 void rollback(Connection conn)
          Discards all changes made since the previous commit/rollback and releases any database locks currently held by this Connection.
 void setLinkName(String linkName)
          Sets the name of the database link used to identify objects.
 void setPreparedStatementsEnabled(boolean preparedStatementsEnabled)
          enables or disables the use of prepared statements for update and insert commands as well as for read operations on a DBRecord.
 void setSchema(String schema)
          Sets the schema for SQL statements.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SYSDATE

public static final DBDatabase.DBSystemDate SYSDATE

EMPTY_STRING

public static final String EMPTY_STRING
See Also:
Constant Field Values

schema

protected String schema
the database schema *


linkName

protected String linkName

tables

protected List<DBTable> tables

relations

protected List<DBRelation> relations

views

protected List<DBView> views

driver

protected DBDatabaseDriver driver
Constructor Detail

DBDatabase

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


DBDatabase

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

Parameters:
schema - the database schema

DBDatabase

public DBDatabase(String schema,
                  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

isPreparedStatementsEnabled

public boolean isPreparedStatementsEnabled()
return whether prepared statements are preferred over normal statements (Default is false) Note: This will only apply for update and insert commands as well as for read operations on a DBRecord. For custom SQL commands parameters must be explicitly declared using cmd.addCmdParam();

Returns:
true if prepared Statements are enabled or false if not

setPreparedStatementsEnabled

public void setPreparedStatementsEnabled(boolean preparedStatementsEnabled)
enables or disables the use of prepared statements for update and insert commands as well as for read operations on a DBRecord. Note: For custom SQL commands parameters must be explicitly declared using cmd.addCmdParam();

Parameters:
preparedStatementsEnabled -

open

public void open(DBDatabaseDriver driver,
                 Connection conn)
Sets the database driver for this database. This will set up the connection for use.

Parameters:
driver - the database driver
conn - the connection

close

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

Parameters:
conn - the connection to close

getCreateDDLScript

public void 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
script - the script object that will be completed

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 String getSchema()
Returns the schema for SQL statements.

Returns:
the schema

setSchema

public void setSchema(String schema)
Sets the schema for SQL statements.

Parameters:
schema - the schema to set

getSchemaPrefix

public 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 String getLinkName()
Returns the database link name.

Returns:
the name of the database link

setLinkName

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

Parameters:
linkName - the database link name

getQualifiedName

@Deprecated
public String getQualifiedName(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(StringBuilder buf,
                                String name,
                                boolean quoteName)
Adds a full qualified object name including schema prefix and database link postfix (if any). to the string buffer supplied

Parameters:
buf - the string buffer to which to append the qualified object name
name - the object's name
quoteName - use quotes or not

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(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(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 void 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

getTables

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

Returns:
db tables.

getTable

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

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

addRelation

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

Parameters:
reference - a reference for a source and target column pair

addRelation

public final void 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

addRelation

public void addRelation(String name,
                        DBRelation.DBReference[] references)
Adds a foreign key relation to the database.

Parameters:
name - the relation name
references - a list of source and target column pairs

getRelations

public List<DBRelation> getRelations()
Returns the relations which have been defined in the database.

Returns:
db relations.

getRelation

public DBRelation getRelation(String relationName)
Returns the relation of a given name

Returns:
db the relation of the given name

addView

public void 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

getViews

public List<DBView> getViews()
Returns the views which have been defined in the database.

Returns:
db views.

getView

public DBView getView(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.

checkOpen

protected void checkOpen()

createCommand

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

Returns:
the command object.

getUpdateTimestamp

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

Parameters:
conn - the connection
Returns:
the current date and time.

getNextSequenceValue

public Object getNextSequenceValue(String seqName,
                                   Connection conn)

querySingleValue

public Object querySingleValue(String sqlCmd,
                               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 or null if there was no value

querySingleInt

public int querySingleInt(String sqlCmd,
                          int defVal,
                          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(String sqlCmd,
                                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(String sqlCmd,
                            long defVal,
                            Connection conn)
Returns the value of the first row/column of a sql-query as a long.

Parameters:
sqlCmd - the SQL statement
defVal - the default value
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(String sqlCmd,
                                  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(String sqlCmd,
                                double defVal,
                                Connection conn)
Returns the value of the first row/column of a sql-query as a double.

Parameters:
sqlCmd - the SQL statement
defVal - the default value
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(String sqlCmd,
                                      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 String querySingleString(String sqlCmd,
                                String defVal,
                                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 String querySingleString(String sqlCmd,
                                      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> int querySimpleList(Class<T> c,
                               String sqlCmd,
                               Connection conn,
                               Collection<T> result)
Adds the first column of a query result to a collection.

Type Parameters:
T - the type for the list
Parameters:
c - the class type for the list
sqlCmd - the SQL statement
conn - a valid connection to the database.
Returns:
the number of elements that have been added to the collection or -1 if an error occurred

querySimpleList

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

Type Parameters:
T - the type for the list
Parameters:
c - the class type for the list
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 List<Object> querySimpleList(String sqlCmd,
                                    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(String sqlCmd,
                               Connection conn)
Returns a list of key value pairs from an sql query. The option 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 int queryObjectList(String sqlCmd,
                           Connection conn,
                           Collection<Object[]> result)
Adds the result of a query to a given collection.
The individual rows will be added as an array of objects (object[])

This function should only be used for small lists. Otherwise a DBReader should be used!

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

queryObjectList

public List<Object[]> queryObjectList(String sqlCmd,
                                      Connection conn)
Returns the result of a query as a list Object-Arrays 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(String sqlCmd,
                      Object[] sqlParams,
                      Connection conn,
                      DBDatabaseDriver.DBSetGenKeys setGenKeys)
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.
setGenKeys - object to set the generated keys for
Returns:
the row count for insert, update or delete or 0 for SQL statements that return nothing

executeSQL

public final int executeSQL(String sqlCmd,
                            Object[] sqlParams,
                            Connection conn)

executeSQL

public final int executeSQL(String sqlCmd,
                            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 ResultSet executeQuery(String sqlCmd,
                              Object[] sqlParams,
                              boolean scrollable,
                              Connection conn)
Executes a select SQL-Statement and returns a resultset containing the query results.
This function returns a JDBC ResultSet.
Instead 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 void commit(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

rollback

public void rollback(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

closeStatement

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

Parameters:
stmt - a Statement object

closeResultSet

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

Parameters:
rset - a ResultSet object


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