| java.lang.Object
 org.griphyn.vdl.dbdriver.DatabaseDriver
All known Subclasses: org.griphyn.vdl.dbdriver.Postgres, org.griphyn.vdl.dbdriver.SQLServer2000, org.griphyn.vdl.dbdriver.MySQL, org.griphyn.vdl.dbdriver.Oracle, org.griphyn.vdl.dbdriver.SQLite,
| DatabaseDriver | | abstract public class DatabaseDriver (Code) | | This common database interface that defines basic functionalities
for interacting with backend SQL database. The implementation
usually requires specific attention to the details between different
databases, as each does things slightly different. The API provides
a functionality that is independent of the schemas to be used.
The schema classes implement all their database access in terms of
this database driver classes.
The separation of database driver and schema lowers the implementation
cost, as only N driver and M schemas need to be implemented, instead
of N x M schema-specific database-specific drivers.
author:
Jens-S. Vöckler
author:
Yong Zhao
version:
$Revision: 50 $
See Also: org.griphyn.vdl.dbschema |
| Field Summary | |
| protected Connection | m_connection
This variable keeps the JDBC handle for the database connection. | | protected Map | m_prepared
This list stores the prepared statements by their position.
The constructor will initialize it. |
| Method Summary | |
| public boolean | addPreparedStatement(String id, String statement)
Inserts a new prepared statement into the list of prepared
statements. | | protected boolean | addPreparedStatement(String id, String statement, boolean autoGeneratedKeys)
Inserts a new prepared statement into the list of prepared
statements. | | public ResultSet | backdoor(String query)
Drills a hole into the nice database driver abstraction to the JDBC3
level. | | abstract public boolean | cachingMakesSense()
Determines, if the backend is expensive, and results should be cached. | | public void | cancelPreparedStatement(String id)
Cancels and resets all previous values of a prepared statement. | | public void | clearWarnings()
Clears all warnings reported for this database driver. | | public void | commit()
Commits the latest changes to the database. | | protected boolean | connect(String driver, String url, Properties info, Set tables)
Establishes a connection to the specified database. | | abstract public boolean | connect(String url, Properties info, Set tables)
Establish a connection to your database. | | public int | delete(String table, Map columns)
Removes all rows that match the provided keyset from a table.
Parameters:
table - is the name of the table to remove values from
Parameters:
columns - is a set of column names and their associatedvalues to select the removed columns. | | public void | disconnect()
Close an established database connection. | | public void | driverMatch()
Determines, if the JDBC driver is the right one for the database we
talk to. | | protected void | finalize()
Closes an open connection to the database whenever this object
is destroyed. | | public PreparedStatement | getPreparedStatement(String id)
Obtains a reference to a prepared statement to be used from
the caller. | | public SQLWarning | getWarnings()
Retrieves the first warning reported by calls on this Connection
object. | | public long | insert(String table, Map keycolumns, Map columns)
Inserts a row in one given database table.
Parameters:
table - is the name of the table to insert into.
Parameters:
keycolumns - is a set of primary keys and their associated values.For special tables, the primary key set may be nullor empty (e.g. | | public boolean | insertPreparedStatement(String id, String statement)
Inserts a new prepared statement into the list of prepared
statements. | | public static DatabaseDriver | loadDriver(String dbDriverName, String propertyPrefix, Object[] arguments)
Instantiates the appropriate child according to property values.
This method is a factory. | | public static DatabaseDriver | loadDriver(String propertyPrefix)
Convenience method instantiates the appropriate child according to
property values. | | abstract public boolean | preferString()
Predicate to tell the schema, if using a string instead of number
will result in the speedier index scans instead of sequential scans. | | public String | quote(String s)
Quotes a string that may contain special SQL characters.
Parameters:
s - is the raw string. | | public void | removePreparedStatement(String id)
Explicitely requests a prepared id to be destroyed and its resources
freed. | | public void | rollback()
Rolls back the latest changes to the database. | | public ResultSet | select(List select, String table, Map where, String order)
Selects any rows in one or more colums from one or more tables
restricted by some condition, possibly ordered. | | public ResultSet | select(List select, String table, Map where, Map operator, String order)
Selects any rows in one or more colums from one or more tables
restricted by some condition that allows operators. | | abstract public long | sequence1(String name)
Obtains the next value from a sequence. | | abstract public long | sequence2(Statement s, String name, int pos)
Obtains the sequence value for the current statement. | | public int | update(String table, Map keycolumns, Map columns)
Updates matching rows in one given database table.
Parameters:
table - is the name of the table to insert into.
Parameters:
keycolumns - is a set of primary keys and their associated values.For special tables, the primary key set may be nullor empty (e.g. |
| m_connection | | protected Connection m_connection(Code) | | This variable keeps the JDBC handle for the database connection.
|
| m_prepared | | protected Map m_prepared(Code) | | This list stores the prepared statements by their position.
The constructor will initialize it. Explicit destruction can
be requested per statement.
|
| DatabaseDriver | | public DatabaseDriver()(Code) | | Default constructor. As the constructor will do nothing, please use
the connect method to obtain a database connection. This is the
constructor that will be invoked when dynamically loading a driver.
See Also: DatabaseDriver.connect(String,Properties,Set) |
| addPreparedStatement | | protected boolean addPreparedStatement(String id, String statement, boolean autoGeneratedKeys) throws SQLException(Code) | | Inserts a new prepared statement into the list of prepared
statements. If the id is already taken, it will be
rejected. This method can only be used with JDBC drivers
that support auto-increment columns. It might fail with JDBC
drivers that do not support auto-increment columns, depending
on the driver's implementation.
Parameters:
id - is the id into which to parse the statement
Parameters:
statement - is the before-parsing statement string
Parameters:
autoGeneratedKeys - is true, if the statement should reservespace to return autoinc columns, false, if the statement does nothave any such keys. true, if the statement was parsed and added at the id,false, if the id was already taken. The statement is not parsedin that case.
exception:
SQLException - may be thrown by parsing the statement.
See Also: DatabaseDriver.removePreparedStatement(String)
See Also: DatabaseDriver.getPreparedStatement(String)
See Also: DatabaseDriver.cancelPreparedStatement(String) |
| backdoor | | public ResultSet backdoor(String query) throws SQLException(Code) | | Drills a hole into the nice database driver abstraction to the JDBC3
level. Use with caution.
Parameters:
query - is an SQL query statement.
exception:
SQLException - if something goes wrong during the query |
| cachingMakesSense | | abstract public boolean cachingMakesSense()(Code) | | Determines, if the backend is expensive, and results should be cached.
Ideally, this will move transparently into the backend itself.
true if caching is advisable, false for no caching. |
| clearWarnings | | public void clearWarnings() throws SQLException(Code) | | Clears all warnings reported for this database driver. After a call
to this method, the internal warnings are cleared until the next one
occurs.
|
| commit | | public void commit() throws SQLException(Code) | | Commits the latest changes to the database.
exception:
SQLException - is propagated from the commit. |
| connect | | protected boolean connect(String driver, String url, Properties info, Set tables) throws SQLException, ClassNotFoundException(Code) | | Establishes a connection to the specified database. The parameters
will often be ignored or abused for different purposes on different
backends. It is assumed that the connection is not in auto-commit
mode, and explicit commits must be issued.
Essentially, the deriving class will overwrite their connect method
to fill in the appropriate driver, and otherwise just call this
method.
Parameters:
driver - is the Java class name of the database driver package
Parameters:
url - the contact string to database, or schema location
Parameters:
info - additional parameters, usually username and password
Parameters:
tables - is a set of all table names in the schema. Theexistence of all tables will be checked to verifythat the schema is active in the database. true if the connection succeeded, false otherwise. Usually,false is returned, if the any of the tables or sequences is missing.
See Also: DatabaseDriver.connect(String,Properties,Set)
See Also: org.griphyn.vdl.util.ChimeraProperties.getDatabaseDriverName
See Also: org.griphyn.vdl.util.ChimeraProperties.getDatabaseURL
See Also: org.griphyn.vdl.util.ChimeraProperties.getDatabaseDriverProperties if the driver is incapable of establishing a connection. |
| connect | | abstract public boolean connect(String url, Properties info, Set tables) throws SQLException, ClassNotFoundException(Code) | | Establish a connection to your database. The parameters will often
be ignored or abused for different purposes on different backends.
It is assumed that the connection is not in auto-commit mode, and
explicit commits must be issued.
Parameters:
url - the contact string to database, or schema location
Parameters:
info - additional parameters, usually username and password
Parameters:
tables - is a set of all table names in the schema. Theexistence of all tables will be checked to verifythat the schema is active in the database. true if the connection succeeded, false otherwise. Usually,false is returned, if the any of the tables or sequences is missing. if the driver is incapable of establishing a connection. |
| delete | | public int delete(String table, Map columns) throws SQLException(Code) | | Removes all rows that match the provided keyset from a table.
Parameters:
table - is the name of the table to remove values from
Parameters:
columns - is a set of column names and their associatedvalues to select the removed columns. The mapmay be null to remove all rows in a table. the number of rows removed. if something goes wrong while removing the values. |
| disconnect | | public void disconnect() throws SQLException(Code) | | Close an established database connection.
if the driver threw up on the data. |
| driverMatch | | public void driverMatch() throws SQLException(Code) | | Determines, if the JDBC driver is the right one for the database we
talk to. Throws an exception if not.
|
| finalize | | protected void finalize() throws Throwable(Code) | | Closes an open connection to the database whenever this object
is destroyed. This is still not foolproof.
|
| insert | | public long insert(String table, Map keycolumns, Map columns) throws SQLException(Code) | | Inserts a row in one given database table.
Parameters:
table - is the name of the table to insert into.
Parameters:
keycolumns - is a set of primary keys and their associated values.For special tables, the primary key set may be nullor empty (e.g. a table without primary keys).
Parameters:
columns - is a set of regular keys and their associated values. the number of rows affected. if something goes wrong while inserting the values. |
| loadDriver | | public static DatabaseDriver loadDriver(String dbDriverName, String propertyPrefix, Object[] arguments) throws ClassNotFoundException, IOException, NoSuchMethodException, InstantiationException, IllegalAccessException, InvocationTargetException, SQLException(Code) | | Instantiates the appropriate child according to property values.
This method is a factory. Currently, drivers may be instantiated
multiple times.
Parameters:
dbDriverName - is the name of the class that conforms tothe DatabaseDriver API. This class will be dynamically loaded.The passed value should not be null.
Parameters:
propertyPrefix - is the property prefix string to use.
Parameters:
arguments - are arguments to the constructor of the driverto load. Please use "new Object[0]" for the argumentless defaultconstructor.
exception:
ClassNotFoundException - if the driver for the databasecannot be loaded. You might want to check your CLASSPATH, too.
exception:
NoSuchMethodException - if the driver's constructor interfacedoes not comply with the database driver API.
exception:
InstantiationException - if the driver class is an abstractclass instead of a concrete implementation.
exception:
IllegalAccessException - if the constructor for the driverclass it not publicly accessible to this package.
exception:
InvocationTargetException - if the constructor of the driverthrows an exception while being dynamically loaded.
exception:
SQLException - if the driver for the database can beloaded, but faults when initially accessing the database
See Also: org.griphyn.vdl.util.ChimeraProperties.getDatabaseDriverName |
| loadDriver | | public static DatabaseDriver loadDriver(String propertyPrefix) throws ClassNotFoundException, IOException, NoSuchMethodException, InstantiationException, IllegalAccessException, InvocationTargetException, SQLException(Code) | | Convenience method instantiates the appropriate child according to
property values. Effectively, the following abbreviation is called:
loadDriver( null, propertyPrefix, new Object[0] );
Parameters:
propertyPrefix - is the property prefix string to use.
exception:
ClassNotFoundException - if the driver for the databasecannot be loaded. You might want to check your CLASSPATH, too.
exception:
NoSuchMethodException - if the driver's constructor interfacedoes not comply with the database driver API.
exception:
InstantiationException - if the driver class is an abstractclass instead of a concrete implementation.
exception:
IllegalAccessException - if the constructor for the driverclass it not publicly accessible to this package.
exception:
InvocationTargetException - if the constructor of the driverthrows an exception while being dynamically loaded.
exception:
SQLException - if the driver for the database can beloaded, but faults when initially accessing the database
See Also: DatabaseDriver.loadDriver(String,String,Object[]) |
| preferString | | abstract public boolean preferString()(Code) | | Predicate to tell the schema, if using a string instead of number
will result in the speedier index scans instead of sequential scans.
PostGreSQL has this problem, but using strings in the place of
integers may not be universally portable.
true, if using strings instead of integers and bigintswill yield better performance. |
| quote | | public String quote(String s)(Code) | | Quotes a string that may contain special SQL characters.
Parameters:
s - is the raw string. the quoted string, which may be just the input string. |
| rollback | | public void rollback() throws SQLException(Code) | | Rolls back the latest changes to the database. Some databases may
be incapable of rolling back.
exception:
SQLException - is propagated from the rollback operation. |
| select | | public ResultSet select(List select, String table, Map where, String order) throws SQLException(Code) | | Selects any rows in one or more colums from one or more tables
restricted by some condition, possibly ordered.
Parameters:
select - is the ordered set of column names to select, orsimply a one-value list with an asterisk.
Parameters:
table - is the name of the table to select from.
Parameters:
where - is a collection of column names and values they must equal.
Parameters:
order - is an optional ordering string. |
| select | | public ResultSet select(List select, String table, Map where, Map operator, String order) throws SQLException(Code) | | Selects any rows in one or more colums from one or more tables
restricted by some condition that allows operators. Permissable
operators include =, <>, >, >=, <, <=, like, etc.
possibly ordered.
Parameters:
select - is the ordered set of column names to select, orsimply a one-value list with an asterisk.
Parameters:
table - is the name of the table to select from.
Parameters:
where - is a collection of column names and values
Parameters:
operator - is a collection of column names and operatorsif no entry is found for the name, then use '=' as default
Parameters:
order - is an optional ordering string. |
| sequence1 | | abstract public long sequence1(String name) throws SQLException(Code) | | Obtains the next value from a sequence. JDBC drivers which allow
explicit access to sequence generator will return a valid value
in this function. All other JDBC drivers should return -1.
Parameters:
name - is the name of the sequence. the next sequence number. if something goes wrong while fetching the new value. |
| sequence2 | | abstract public long sequence2(Statement s, String name, int pos) throws SQLException(Code) | | Obtains the sequence value for the current statement. JDBC driver
that permit insertion of NULL into auto-increment value should use
this method to return the inserted ID value via the statements
getGeneratedKeys(). Other JDBC drivers should treat return the
parametric id.
Parameters:
s - is a statment or prepared statement
Parameters:
name - is the name of the sequence.
Parameters:
pos - is the column number of the auto-increment column. the next sequence number. if something goes wrong while fetching the new value. |
| update | | public int update(String table, Map keycolumns, Map columns) throws SQLException(Code) | | Updates matching rows in one given database table.
Parameters:
table - is the name of the table to insert into.
Parameters:
keycolumns - is a set of primary keys and their associated values.For special tables, the primary key set may be nullor empty (e.g. a table without primary keys).
Parameters:
columns - is a set of regular keys and their associated values. the number of rows affected if something goes wrong while updating the values. |
|
|