edu.udo.cs.miningmart.db
Class DbCore

java.lang.Object
  extended byedu.udo.cs.miningmart.db.DbCore
Direct Known Subclasses:
DbCoreOracle, DbCorePostgres

public abstract class DbCore
extends java.lang.Object

Abstract superclass class to encapsulate most of the directly database related information. Subclasses realise the access to different DBMS. The only class referencing subclasses of DbCore is DB. However, the class is public because it provides static methods to deal with different DBMS systems.

Version:
$Id: DbCore.java,v 1.6 2006/04/11 14:10:16 euler Exp $
Author:
Martin Scholz

Field Summary
static java.lang.String DBMS_ORACLE
          Public constant to refer to the Database Management System (DBMS) Oracle.
static java.lang.String DBMS_POSTGRES
          Public constant to refer to the Database Management System (DBMS) PostgreSQL.
 
Constructor Summary
DbCore(java.lang.String url, java.lang.String dbName, java.lang.String user, java.lang.String passwd, M4InterfaceContext cal, boolean refersToM4Schema)
          The constructor of this class establishes a new database connection.
 
Method Summary
 void commitTransactions()
          Commit the last transactions in the M4 database.
 void createSQLFunction(java.lang.String myFunction)
          Create a function in the database by using the given function definition.
 java.lang.String createSqlIndex(java.lang.String tableName, java.lang.String[] attributes)
          Creates a database index for the given table and set of attributes.
 void createSQLView(Columnset cs, boolean materialize)
          Create the generated sql definition for a new view within the database, or materialize the view as a table, if this is preferrable.
abstract  boolean dropRelation(java.lang.String tableName)
          Try to drop the table or view with the given name, if it exists.
 void executeDBProcedure(java.lang.String procedureName, java.lang.String[] parameters)
          Method to execute a stored procedure residing in the according schema.
 java.lang.String executeSingleValueSqlRead(java.lang.String query)
           
 java.lang.Long executeSingleValueSqlReadL(java.lang.String query)
           
protected  java.lang.Long executeSingleValueSqlReadL(java.lang.String query, java.sql.Statement stmt)
           
 java.sql.ResultSet executeSqlRead(java.lang.String query)
          Method to comfortably read from the database.
 void executeSqlWrite(java.lang.String query)
          Method to comfortably write to the database.
 void finalize()
          Closes the database connections.
static java.lang.String findDBMS(java.lang.String url)
          Use this method to decide about the Database Management System (DBMS) which is to be used.
abstract  java.lang.String getAttributeForColumnNames()
          Abstract method to be implemented by the subclasses.
abstract  java.lang.String getAttributeForColumnTypes()
          Abstract method to be implemented by the subclasses.
 Print getCasePrintObject()
           
abstract  java.lang.String getDatatypeName(java.lang.String m4RelDatatypeName, int size)
          This method returns the DBMS-dependent name of the datatype which the current DBMS uses to realize the given M4-Relational Datatype.
abstract  short getDbms()
          Indicates the DBMS used.
abstract  java.lang.String getM4DatatypeName(java.lang.String dbmsDatatypeName)
          This method returns the M4-Relational Datatype that corresponds to the given DBMS-dependent name of a datatype.
protected abstract  long getNextM4SequenceValue(java.sql.Statement stmt)
           
abstract  java.util.Collection getPrimaryKeyColumnNames(java.lang.String dbObjectName)
          Returns a Collection with the names of the DB columns that belong to the given table or view and form its primary key, if such a key is declared by SQL constraints in the DB.
abstract  java.lang.String getSelectStringAllColumnsForDbObject(java.lang.String dbObjectName)
          Abstract method to be implemented by the subclasses.
abstract  java.lang.String getSelectStringAllTables()
          Abstract method to be implemented by the subclasses.
abstract  java.lang.String getSelectStringAllViews()
          Abstract method to be implemented by the subclasses.
abstract  java.lang.String getSelectStringColumnDataTypes(java.lang.String dbObjectName, java.lang.String owner, java.lang.String columnName)
          This method returns the DBMS-dependent SQL command that returns the name of the datatype of the given column in the given table or view (which is owned by the given owner).
abstract  java.lang.String getTableOrViewType(java.lang.String dbObjectName)
          Returns one of the TYPE_... constants in the class edu.udo.cs.miningmart.m4.Columnset, or null if the given String is neither a table or view.
abstract  java.util.Map getTablesReferencedBy(java.lang.String dbObjectName)
          Returns a Map that maps every column of the given table to the name of the table that it references as a foreign key, or to null if the column does not act as a foreign key.
abstract  java.lang.String getTestQuery()
           
abstract  java.lang.String getUniqueRowIdentifier()
          Abstract method to be implemented by the subclasses.
 boolean hasOnlyForeignKeyColumns(java.lang.String dbObjectName)
          Returns TRUE iff the given table/view has ONLY columns that act as foreign keys to other tables.
protected abstract  void registerJDBC_Driver()
          This method must be implemented by subclasses in order to use other JDBC drivers (for other DBMS, for example).
 void rollback()
          Roll back the last transactions (since the last commit) in the database.
protected abstract  void switchAutocommitOff(java.sql.Connection con)
          Since the transaction mechanism may be different for different DBMS, use this method to implement the Autocommit handling.
abstract  boolean tableExists(java.lang.String tableName)
          Returns TRUE if a table (not a view) with the given name exists in the database.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DBMS_ORACLE

public static java.lang.String DBMS_ORACLE
Public constant to refer to the Database Management System (DBMS) Oracle.


DBMS_POSTGRES

public static java.lang.String DBMS_POSTGRES
Public constant to refer to the Database Management System (DBMS) PostgreSQL.

Constructor Detail

DbCore

public DbCore(java.lang.String url,
              java.lang.String dbName,
              java.lang.String user,
              java.lang.String passwd,
              M4InterfaceContext cal,
              boolean refersToM4Schema)
       throws java.sql.SQLException
The constructor of this class establishes a new database connection. Autocommit is set to false, so transaction management must be done individually by the database functions.

Parameters:
url - Prefix of the database url
dbName - name of the database
user - name of the database user
passwd - password for the database user
cal - the CompilerAccessLogic of the current thread. It is just needed in order to reach the appropriate Print-object for writing debug messages
refersToM4Schema - is true iff the connection refers to the M4 schema. Useful to decide whether triggers need to be switched off etc.
Throws:
java.sql.SQLException
Method Detail

findDBMS

public static java.lang.String findDBMS(java.lang.String url)
Use this method to decide about the Database Management System (DBMS) which is to be used. This method is given the DB connection URL (consisting of driver and location) and returns one of the public constants of this class whose name starts with "DBMS_". Currently, this method uses the driver name to decide about the DBMS.

Parameters:
url - The DB connection URL
Returns:
One of the public String constants of this class.

getCasePrintObject

public Print getCasePrintObject()

finalize

public void finalize()
              throws java.sql.SQLException
Closes the database connections. If the database is no longer used this Finalization method closes the database connection. Currently, I guess a java exit is an acceptable disconnect as well. If not we have to register a addShutdownHook in Class Runtime

Throws:
java.sql.SQLException

getDbms

public abstract short getDbms()
Indicates the DBMS used.


registerJDBC_Driver

protected abstract void registerJDBC_Driver()
                                     throws java.sql.SQLException
This method must be implemented by subclasses in order to use other JDBC drivers (for other DBMS, for example).

Throws:
java.sql.SQLException

switchAutocommitOff

protected abstract void switchAutocommitOff(java.sql.Connection con)
                                     throws java.sql.SQLException
Since the transaction mechanism may be different for different DBMS, use this method to implement the Autocommit handling.

Throws:
java.sql.SQLException

commitTransactions

public void commitTransactions()
                        throws java.sql.SQLException
Commit the last transactions in the M4 database.

Throws:
java.sql.SQLException

rollback

public void rollback()
              throws java.sql.SQLException
Roll back the last transactions (since the last commit) in the database.

Throws:
java.sql.SQLException

executeSqlWrite

public void executeSqlWrite(java.lang.String query)
                     throws java.sql.SQLException,
                            DbConnectionClosed
Method to comfortably write to the database. If possible automatic batching is applied.

Parameters:
query - an SQL query to be executed. This has to be a write operation to the database, or an SQL string to execute a procedure in the according schema.
Throws:
java.sql.SQLException
DbConnectionClosed

createSQLView

public void createSQLView(Columnset cs,
                          boolean materialize)
                   throws java.sql.SQLException,
                          DbConnectionClosed
Create the generated sql definition for a new view within the database, or materialize the view as a table, if this is preferrable.

Throws:
java.sql.SQLException
DbConnectionClosed

createSQLFunction

public void createSQLFunction(java.lang.String myFunction)
                       throws java.sql.SQLException,
                              DbConnectionClosed
Create a function in the database by using the given function definition.

Parameters:
myFunction - a function definition for a SQL function
Throws:
java.sql.SQLException
DbConnectionClosed

createSqlIndex

public java.lang.String createSqlIndex(java.lang.String tableName,
                                       java.lang.String[] attributes)
                                throws java.sql.SQLException,
                                       DbConnectionClosed
Creates a database index for the given table and set of attributes.

Parameters:
tableName - the table to create an index on
attributes - an array of attribute names, specifying for which attributes an index should be created
Returns:
the name of the index or null.
Throws:
java.sql.SQLException
DbConnectionClosed

executeSqlRead

public java.sql.ResultSet executeSqlRead(java.lang.String query)
                                  throws java.sql.SQLException,
                                         DbConnectionClosed
Method to comfortably read from the database.

Parameters:
query - an SQL query to be executed. This has to be a read operation on the database.
Returns:
the corresponding ResultSet
Throws:
java.sql.SQLException
DbConnectionClosed

executeSingleValueSqlReadL

protected java.lang.Long executeSingleValueSqlReadL(java.lang.String query,
                                                    java.sql.Statement stmt)
                                             throws java.sql.SQLException
Parameters:
query - an SQL query to be executed. This has to be a read operation yielding a single (numeric) value, which is convertable to datatype long.
stmt - the Statement to be used to execute the query
Returns:
the result as a String, or null, if no value was returned.
Throws:
java.sql.SQLException

executeSingleValueSqlReadL

public java.lang.Long executeSingleValueSqlReadL(java.lang.String query)
                                          throws java.sql.SQLException,
                                                 DbConnectionClosed
Throws:
java.sql.SQLException
DbConnectionClosed
See Also:
In contrast to that method, this method creates and then closes its own Statement.

executeSingleValueSqlRead

public java.lang.String executeSingleValueSqlRead(java.lang.String query)
                                           throws java.sql.SQLException,
                                                  DbConnectionClosed
Throws:
java.sql.SQLException
DbConnectionClosed
See Also:
In contrast to that method, this method creates and then closes its own Statement.

getNextM4SequenceValue

protected abstract long getNextM4SequenceValue(java.sql.Statement stmt)
                                        throws M4Exception
Parameters:
stmt - the Statement to be used to execute the query
Returns:
the value returned by the sequence (installed in the M4 schema).
Throws:
M4Exception - if for some reason the sequence does not return a value

executeDBProcedure

public void executeDBProcedure(java.lang.String procedureName,
                               java.lang.String[] parameters)
                        throws java.sql.SQLException,
                               DbConnectionClosed,
                               M4CompilerError
Method to execute a stored procedure residing in the according schema.

Parameters:
procedureName - the name of the stored procedure in the database
parameters - the parameters to be passed to the stored procedure. In SQL code these parameters are comma separated.
Throws:
java.sql.SQLException
DbConnectionClosed
M4CompilerError

getSelectStringAllTables

public abstract java.lang.String getSelectStringAllTables()
Abstract method to be implemented by the subclasses. Returns an SQL String that selects the names of all tables from the current schema. This is DBMS-dependent.

Returns:
An SQL String

getSelectStringAllViews

public abstract java.lang.String getSelectStringAllViews()
Abstract method to be implemented by the subclasses. Returns an SQL String that selects the names of all views from the current schema. This is DBMS-dependent.

Returns:
An SQL String

tableExists

public abstract boolean tableExists(java.lang.String tableName)
                             throws M4Exception
Returns TRUE if a table (not a view) with the given name exists in the database.

Parameters:
tableName - the table name
Returns:
TRUE or FALSE
Throws:
M4Exception

getSelectStringAllColumnsForDbObject

public abstract java.lang.String getSelectStringAllColumnsForDbObject(java.lang.String dbObjectName)
Abstract method to be implemented by the subclasses. Returns the SQL String that selects all column names and types for the given Table or View name from the business data schema. This is DBMS-dependent.

Parameters:
dbObjectName - Name of a table or view in the business data schema
Returns:
An SQL String

getAttributeForColumnNames

public abstract java.lang.String getAttributeForColumnNames()
Abstract method to be implemented by the subclasses. Returns the name of the column that contains the column names. This is DBMS-dependent.

Returns:
the name of the column that contains the column names.

getAttributeForColumnTypes

public abstract java.lang.String getAttributeForColumnTypes()
Abstract method to be implemented by the subclasses. Returns the name of the column that contains the column types. This is DBMS-dependent.

Returns:
the name of the column that contains the column types.

getUniqueRowIdentifier

public abstract java.lang.String getUniqueRowIdentifier()
Abstract method to be implemented by the subclasses. Returns a String that can be used to uniquely identify table rows in SQL-Statements. This is DBMS-dependent.

Returns:
the unique row identifier name

getTablesReferencedBy

public abstract java.util.Map getTablesReferencedBy(java.lang.String dbObjectName)
                                             throws java.sql.SQLException,
                                                    DbConnectionClosed
Returns a Map that maps every column of the given table to the name of the table that it references as a foreign key, or to null if the column does not act as a foreign key. The Map uses only Strings.

Parameters:
dbObjectName - the given table name
Returns:
a Map whose keys and values are Strings
Throws:
java.sql.SQLException
DbConnectionClosed

hasOnlyForeignKeyColumns

public boolean hasOnlyForeignKeyColumns(java.lang.String dbObjectName)
                                 throws java.sql.SQLException,
                                        DbConnectionClosed
Returns TRUE iff the given table/view has ONLY columns that act as foreign keys to other tables.

Parameters:
dbObjectName - name of given table/view
Returns:
a boolean value
Throws:
java.sql.SQLException
DbConnectionClosed

getPrimaryKeyColumnNames

public abstract java.util.Collection getPrimaryKeyColumnNames(java.lang.String dbObjectName)
                                                       throws java.sql.SQLException,
                                                              DbConnectionClosed
Returns a Collection with the names of the DB columns that belong to the given table or view and form its primary key, if such a key is declared by SQL constraints in the DB. Otherwise null is returned.

Parameters:
dbObjectName - the name of the given table or view
Returns:
a Collection of Strings
Throws:
java.sql.SQLException
DbConnectionClosed

getTableOrViewType

public abstract java.lang.String getTableOrViewType(java.lang.String dbObjectName)
                                             throws java.sql.SQLException,
                                                    DbConnectionClosed
Returns one of the TYPE_... constants in the class edu.udo.cs.miningmart.m4.Columnset, or null if the given String is neither a table or view.

Parameters:
dbObjectName - name of a table or view
Returns:
a String with the type information
Throws:
java.sql.SQLException
DbConnectionClosed

getDatatypeName

public abstract java.lang.String getDatatypeName(java.lang.String m4RelDatatypeName,
                                                 int size)
This method returns the DBMS-dependent name of the datatype which the current DBMS uses to realize the given M4-Relational Datatype.

Parameters:
m4RelDatatypeName - name of the M4 Relational Datatype
size - A size to be returned with the datatype, if the DBMS allows that. For example, if the M4 Relational Datatype is NUMBER and length is 10, then the return value will be the String "NUMBER(10)" if the DBMS is Oracle. If this length is not positive, the datatype will be returned without a size, in the example: "NUMBER". The DBMS may not allow lengths at all, in which case also the datatype without a size is returned.
Returns:
A DBMS-dependent string that contains a datatype name.

getM4DatatypeName

public abstract java.lang.String getM4DatatypeName(java.lang.String dbmsDatatypeName)
This method returns the M4-Relational Datatype that corresponds to the given DBMS-dependent name of a datatype.

Parameters:
dbmsDatatypeName - the name of the datatype in the underlying DBMS
Returns:
the corresponding M4 Relational Datatype

getSelectStringColumnDataTypes

public abstract java.lang.String getSelectStringColumnDataTypes(java.lang.String dbObjectName,
                                                                java.lang.String owner,
                                                                java.lang.String columnName)
This method returns the DBMS-dependent SQL command that returns the name of the datatype of the given column in the given table or view (which is owned by the given owner).

Parameters:
dbObjectName - Name of a table or view in the business data schema
owner - Name of the owner of the table or view
columnName - Name of the column whose datatype is returned
Returns:
the DBMS-dependent name of the datatype of the column with the given name

dropRelation

public abstract boolean dropRelation(java.lang.String tableName)
                              throws M4Exception
Try to drop the table or view with the given name, if it exists. Returns TRUE iff the table had existed, FALSE otherwise.

Parameters:
tableName - the name of the table to be dropped
Returns:
TRUE iff the table had existed before it was removed, FALSE if nothing was done.
Throws:
M4Exception

getTestQuery

public abstract java.lang.String getTestQuery()
Returns:
a String that can be used as a query to test the DB connection.


Copyright © 2001-2005